You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 6cb160a
Browse filesBrowse the repository at this point in the historyBrowse files
fix(fold): require a settled hinge before reporting half-open (#2734)
`fold half-open` accepted the requested category as the answer whenever its four-read budget
happened to end on a half-open angle. A hinge travelling between the end stops passes through that
interval on every fold, so the command could report a Book pose for a hinge that was still moving
and had no intention of resting at 130 degrees.
An angle inside the open interval proves the category and nothing else, so the pose is now the hinge
*resting* there: two consecutive readings that both classify as half-open and differ by at most the
existing 0.5-degree tolerance. Numerical proximity is not agreement when a pair straddles a category
boundary, so `isSettledHalfOpenPair` tests both readings, not just their distance. `closed` and
`open` keep the end-stop rule, and the attempt count, per-read timeout, and cancellation behaviour
are untouched.
A budget that ends on an unsettled half-open angle fails with COMMAND_FAILED and
`details.reason: "fold-pose-unsettled"`, carrying requestedPose, observedPose, hingeAngleDegrees and
the previous reading, and says the hinge was observed half-open and did not settle — its own observed
pose refutes "did not reach". A budget ending on another pose keeps `fold-pose-unverified`. This
supersedes ADR 0025's budget-end exception, recorded there as an amendment with the Duo run taken
under the new rule.
Closes#2730
Copy file name to clipboardExpand all lines: docs/adr/0025-foldable-apple-panels.md
+53-12Lines changed: 53 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,8 +2,9 @@
2
2
3
3
## Status
4
4
5
-
Accepted (2026-09-20). Covers iPhone Duo (iOS 27.1, `iPhone19,4`) and any Apple device that
6
-
reports more than one integrated CoreDevice display.
5
+
Accepted (2026-09-20; the pose-settle rule amended 2026-09-21 under #2730). Covers iPhone Duo
6
+
(iOS 27.1, `iPhone19,4`) and any Apple device that reports more than one integrated CoreDevice
7
+
display.
7
8
8
9
An iPhone Duo carries two integrated panels — Apple's **outer display** and **inner display** —
9
10
and lights one of them at a time. Which one is lit is the device pose. Two independent facts
@@ -20,7 +21,8 @@ device is in**. The first is answered by an official host API; the second only b
20
21
| Device has one integrated panel | Keep the pre-panel behavior exactly: no display flag, no pose, unchanged scale probe |
21
22
| Density normalization | Use the captured panel's own `pointScale`; a runner-fallback capture keeps the scale probe because `XCUIScreen.main` may be a different panel |
22
23
| Pose must be reported | From panel power alone, report `closed`, `fully-open`, or `unknown`, and never narrower; `fold` reports the exact pose because it reads the hinge angle |
23
-
| A pose change is requested |`agent-device fold <closed\|half-open\|open>`: press the pose control in the Device Hub window through macOS accessibility, then read the hinge angle back from CoreDevice until it agrees; refuse the pose if it never does |
24
+
| A pose change is requested |`agent-device fold <closed\|half-open\|open>`: press the pose control in the Device Hub window through macOS accessibility, then read the hinge angle back from CoreDevice until it agrees — for `half-open`, until two consecutive readings agree; refuse the pose if it never does |
25
+
| The hinge reaches `half-open` but keeps moving | Refuse it as `fold-pose-unsettled` with the observed and previous angles: an angle inside the open interval is an observed category, not a pose the hinge holds |
24
26
| An external display is attached | It is not a panel: it never makes the device multi-screen and never produces a pose |
25
27
| CoreDevice cannot answer | Return an unresolved inventory and keep the single-panel capture path; a missing host feature is not a capture failure |
26
28
@@ -98,15 +100,18 @@ the read-back is. The pieces, each of which was checked on the shipping 27.1 too
98
100
| Device identity | Device Hub titles the window `<name> – iOS 27.1`, which two simulators sharing a name cannot distinguish. Its sidebar rows carry `AXIdentifier``TableRow.Device.<UDID>`, and setting `AXSelected` on a row switches the window to that device, so `fold` selects by UDID and only then presses |
99
101
| No window | A simulator booted headlessly leaves Device Hub running with no window. LaunchServices cannot address the trampolined process by bundle id (`open -b`, `NSRunningApplication.activate` do nothing), but a `kAEReopenApplication` event sent to the pid restores the device window, the same event a Dock click sends |
100
102
101
-
The rule this yields: `closed` and `open` are the hinge's end stops, so one read at the stop is
102
-
the pose; every other angle is `half-open`, including the ones the hinge sweeps through on its way
103
-
somewhere else, so `half-open` is reported once two consecutive reads agree within 0.5°, or when
104
-
the four-read budget ends while the hinge still reads `half-open` — a refusal never names the pose
105
-
that was asked for. Each read takes the last sample the five-second stream printed, so a moving
106
-
hinge is reported where it is now. The live run that fixed the settle rule read 175.1° one stream
107
-
after pressing Book and 130° two streams later. A hinge whose last reading is some other pose is
108
-
refused as `fold-pose-unverified` with the angle CoreDevice still reports; the response of a verified pose carries the angle and the lit
109
-
panel's point size, because the point size is what tells an agent its refs are stale.
103
+
The rule this yields: `closed` and `open` are the hinge's two end stops, so one read at the stop is
104
+
the pose. Every other angle is `half-open`, including the ones a hinge sweeps through on its way
105
+
somewhere else, so an angle in that open interval proves only the category — the pose is the hinge
106
+
*resting* there, which two consecutive reads show by both classifying as `half-open` and agreeing
107
+
within 0.5°. Each read takes the last sample the five-second stream printed, so a moving hinge is
108
+
reported where it is now. The run that first exposed the animation — before the amendment below —
109
+
read 175.1° one stream after pressing Book and 130° two streams later; the run recorded under the
110
+
amended rule is in "Verified on a booted Duo". A budget that ends with the hinge at some other pose is
111
+
refused as `fold-pose-unverified` with the angle CoreDevice still reports; one that ends on an
112
+
unsettled `half-open` angle is refused as `fold-pose-unsettled` (see the amendment below). The
113
+
response of a verified pose carries the angle and the lit panel's point
114
+
size, because the point size is what tells an agent its refs are stale.
110
115
111
116
Requirements the command states in its own errors: Accessibility permission for the host
112
117
(`accessibility-permission`), a running Device Hub (`fold` launches it in the background the way
@@ -115,6 +120,30 @@ the UDID (`device-hub-device-missing`). A single-panel simulator is refused befo
115
120
pressed (`single-panel-device`), and the leaf fact refuses physical devices and every non-iPhone
116
121
simulator OS.
117
122
123
+
## Amendment: an observed half-open angle is not a settled pose (issue #2730)
124
+
125
+
The rule above first ended the other way: `half-open` was also reported when the four-read budget
126
+
ran out while the hinge still read `half-open`, because a refusal was not allowed to name the pose
127
+
that was asked for. That reasoning confuses an observed category with a completed pose change.
128
+
`half-open` is an open interval, so a hinge travelling between the end stops passes through it on
129
+
every fold; four readings that each land inside the interval and never agree describe a hinge in
130
+
motion, and reporting them as a pose tells an agent the Book preset is on screen when nothing is at
131
+
rest there. The interval rule also cannot pin a value: Device Hub's Book preset measures 130° on
132
+
this iOS 27.1 Duo, which is one device's measurement, not the success condition — stability is.
133
+
134
+
So `fold half-open` succeeds only on two consecutive readings that both classify as `half-open` and
135
+
differ by at most 0.5°. Numerical proximity is not agreement when the pair straddles a category
136
+
boundary: 179° is `open` and 178.8° is `half-open` although they differ by 0.2°, and those are two
137
+
poses, not one resting hinge. A budget that ends on an unsettled `half-open` angle fails with
0 commit comments