Skip to content

Commit 6cb160a

Browse files
authored
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
1 parent 29ac8e6 commit 6cb160a

6 files changed

Lines changed: 213 additions & 37 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,17 @@
22

33
## Unreleased
44

5+
- Fixed (ios): `fold half-open` no longer reports a pose the hinge never held. The command accepted
6+
the requested category as the answer whenever its four-read budget happened to end on a
7+
`half-open` angle, so a hinge still sweeping from 180° toward 0° — which passes through every
8+
half-open angle on the way — came back as a settled Book pose. An angle inside that open interval
9+
proves the category and nothing else, so `half-open` now requires two consecutive readings that
10+
both fall inside it and agree within 0.5°; a pair straddling the 179° boundary is two poses, not
11+
one hinge at rest. A budget ending on an unsettled angle fails with `COMMAND_FAILED` and
12+
`details.reason: "fold-pose-unsettled"`, carrying `requestedPose`, `observedPose`,
13+
`hingeAngleDegrees` and the previous reading, and says the hinge was observed half-open and did
14+
not settle rather than claiming it never got there. `fold-pose-unverified` still covers a budget
15+
that ends on another pose. Supersedes ADR 0025's budget-end exception (#2730).
516
- Fixed (macos): `press` and `click` on the `frontmost-app`, `desktop`, and `menubar` surfaces post
617
clicks the way a trackpad does. The helper posted the release in the same tick as the press, so
718
AppKit dropped it and controls never activated; each press is now held (`--hold-ms`, 60 ms by

‎docs/adr/0025-foldable-apple-panels.md‎

Lines changed: 53 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,9 @@
22

33
## Status
44

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.
78

89
An iPhone Duo carries two integrated panels — Apple's **outer display** and **inner display** —
910
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
2021
| Device has one integrated panel | Keep the pre-panel behavior exactly: no display flag, no pose, unchanged scale probe |
2122
| 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 |
2223
| 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 |
2426
| An external display is attached | It is not a panel: it never makes the device multi-screen and never produces a pose |
2527
| CoreDevice cannot answer | Return an unresolved inventory and keep the single-panel capture path; a missing host feature is not a capture failure |
2628

@@ -98,15 +100,18 @@ the read-back is. The pieces, each of which was checked on the shipping 27.1 too
98100
| 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 |
99101
| 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 |
100102

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.
110115

111116
Requirements the command states in its own errors: Accessibility permission for the host
112117
(`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
115120
pressed (`single-panel-device`), and the leaf fact refuses physical devices and every non-iPhone
116121
simulator OS.
117122

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
138+
`COMMAND_FAILED`, `details.reason: "fold-pose-unsettled"`, `requestedPose`, `observedPose`,
139+
`hingeAngleDegrees` and the previous reading, and says the hinge was observed half-open and did not
140+
settle — never that it failed to reach half-open, which its own observed pose refutes.
141+
`fold-pose-unverified` stays for a budget ending on another pose, and keeps classifying from that
142+
final sample alone: a hinge that passed through `half-open` on its way to the end stop is refused as
143+
unverified, because the pose it ended in is not the one that was asked for.
144+
The attempt count, the per-read timeout, cancellation, and the open/closed end-stop
145+
rule are unchanged: an unsettled fold costs the same four hinge streams it always did.
146+
118147
## Pose is derived from panel power, and official control does not exist
119148

120149
Apple ships fold state as an **app-side, read-only** API: `UIHinge.status`
@@ -218,6 +247,14 @@ and text sent with `type` is found again by `find text` — hit testing and read
218247
lit panel. A ref issued before the fold is refused afterwards as an expired frame rather than
219248
replayed at the new point size, which is the pose-change rule working as designed.
220249

250+
Half-open pose under the amended settle rule, on a booted iPhone Duo (iOS 27.1) at this PR's head:
251+
`fold open` reported 180° on its end-stop reading, and `fold half-open` from that open pose reported
252+
130° naming `LCD-1` at `669x951pt`. The hinge was travelling when the press landed and still came to
253+
rest inside the interval, so requiring a settled pair did not lose the Book preset. A
254+
`devicectl device motion hinge-angle` stream read afterwards reported `Angle:130,0° Velocity:+0,0°/s`
255+
— the hinge is where the pair rule said it was. The run's session was closed and its daemon stopped
256+
afterwards.
257+
221258
## Accepted evidence gaps
222259

223260
- **Runner screenshot fallback.** `XCUIScreen.main` is hardcoded in the runner's `screenshot`
@@ -232,6 +269,10 @@ replayed at the new point size, which is the pose-change rule working as designe
232269
against a changed value.
233270
- **Pose control on a second Device Hub instance.** `fold` drives the first `DeviceHub` process in
234271
the process table. Two Xcodes each running a Device Hub is not a state this was verified in.
272+
- **A hinge that settles slowly.** Four reads is twenty seconds of streams, and a Duo that needs
273+
longer to come to rest inside `half-open` is now refused where the superseded rule would have
274+
reported a pose. Every Duo run observed for this change settled inside the budget; no simulator
275+
that needs longer was seen, so the budget stays as it is rather than growing on a hypothesis.
235276
- **Physical foldables.** Device Hub poses simulators only; the leaf fact refuses a physical device,
236277
and the hinge stream on one was not exercised.
237278

‎packages/platform-apple/src/foldable/pose.test.ts‎

Lines changed: 89 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -127,26 +127,61 @@ test('maps half-open onto the Book preset and reports it only once the hinge has
127127
expect(mockHinge).toHaveBeenCalledTimes(3);
128128
});
129129

130-
test('reports half-open when the budget ends on it even though the hinge never came to rest', async () => {
131-
mockInventory
132-
.mockResolvedValueOnce(duoInventory('inner'))
133-
.mockResolvedValueOnce(duoInventory('inner'));
130+
test('refuses half-open when the hinge was observed there but never came to rest', async () => {
131+
mockInventory.mockResolvedValueOnce(duoInventory('inner'));
134132
mockHinge
135133
.mockResolvedValueOnce(170)
136134
.mockResolvedValueOnce(150)
137135
.mockResolvedValueOnce(120)
138136
.mockResolvedValueOnce(90);
139137

140-
// A refusal must never name the pose that was requested: every one of these reads is
141-
// half-open, so the last one is the answer, not a failure that cites it.
142-
await expect(setAppleFoldPose(duo, 'half-open')).resolves.toMatchObject({
143-
pose: 'half-open',
144-
hingeAngleDegrees: 90,
138+
// Every read classifies as half-open, so the requested category was observed; what is missing is
139+
// a hinge that stopped.
140+
const failure = await setAppleFoldPose(duo, 'half-open').catch((error: unknown) => error);
141+
expect(failure).toMatchObject({
142+
code: 'COMMAND_FAILED',
143+
details: expect.objectContaining({
144+
reason: 'fold-pose-unsettled',
145+
requestedPose: 'half-open',
146+
observedPose: 'half-open',
147+
hingeAngleDegrees: 90,
148+
previousHingeAngleDegrees: 120,
149+
}),
150+
});
151+
// The observed pose refutes a claim that the pose was never reached, so the refusal may only say
152+
// the hinge did not come to rest inside it.
153+
expect((failure as Error).message).toContain('did not settle');
154+
expect((failure as Error).message).not.toContain('did not reach');
155+
expect(mockHinge).toHaveBeenCalledTimes(4);
156+
// A refused pose never reaches the capture-path panel read.
157+
expect(mockInventory).toHaveBeenCalledTimes(1);
158+
});
159+
160+
test('refuses half-open when consecutive readings only straddle the open boundary', async () => {
161+
mockInventory.mockResolvedValueOnce(duoInventory('inner'));
162+
// 179° is `open` and 178.8° is `half-open`, yet they differ by 0.2°. Numerical proximity across a
163+
// category boundary is not two readings of a hinge that came to rest inside the requested pose.
164+
mockHinge
165+
.mockResolvedValueOnce(180)
166+
.mockResolvedValueOnce(180)
167+
.mockResolvedValueOnce(179)
168+
.mockResolvedValueOnce(178.8);
169+
170+
await expect(setAppleFoldPose(duo, 'half-open')).rejects.toMatchObject({
171+
code: 'COMMAND_FAILED',
172+
details: expect.objectContaining({
173+
reason: 'fold-pose-unsettled',
174+
requestedPose: 'half-open',
175+
observedPose: 'half-open',
176+
hingeAngleDegrees: 178.8,
177+
previousHingeAngleDegrees: 179,
178+
}),
145179
});
146180
expect(mockHinge).toHaveBeenCalledTimes(4);
181+
expect(mockInventory).toHaveBeenCalledTimes(1);
147182
});
148183

149-
test('refuses half-open only when the last reading is some other pose', async () => {
184+
test('refuses half-open as unverified when the last reading is another pose', async () => {
150185
mockInventory.mockResolvedValueOnce(duoInventory('inner'));
151186
mockHinge
152187
.mockResolvedValueOnce(170)
@@ -155,12 +190,15 @@ test('refuses half-open only when the last reading is some other pose', async ()
155190
.mockResolvedValueOnce(180);
156191

157192
await expect(setAppleFoldPose(duo, 'half-open')).rejects.toMatchObject({
193+
code: 'COMMAND_FAILED',
158194
details: expect.objectContaining({
159195
reason: 'fold-pose-unverified',
196+
requestedPose: 'half-open',
160197
observedPose: 'open',
161198
hingeAngleDegrees: 180,
162199
}),
163200
});
201+
expect(mockInventory).toHaveBeenCalledTimes(1);
164202
});
165203

166204
test('refuses the pose when the hinge never reaches it, naming what CoreDevice still reports', async () => {
@@ -179,6 +217,47 @@ test('refuses the pose when the hinge never reaches it, naming what CoreDevice s
179217
expect(mockHinge).toHaveBeenCalledTimes(4);
180218
});
181219

220+
test('reports closed on one reading at the end stop, without waiting for a second one', async () => {
221+
mockInventory
222+
.mockResolvedValueOnce(duoInventory('outer'))
223+
.mockResolvedValueOnce(duoInventory('outer'));
224+
// 95.7° is the hinge mid-sweep toward closed; 0.4° is the end stop, and an end stop needs no
225+
// confirmation. Routing `closed` through the half-open settle rule would want another read.
226+
mockHinge.mockResolvedValueOnce(95.7).mockResolvedValueOnce(0.4);
227+
228+
await expect(setAppleFoldPose(duo, 'closed')).resolves.toMatchObject({
229+
pose: 'closed',
230+
hingeAngleDegrees: 0.4,
231+
});
232+
expect(mockHinge).toHaveBeenCalledTimes(2);
233+
});
234+
235+
test('refuses before reading the hinge at all when the request is already cancelled', async () => {
236+
const controller = new AbortController();
237+
controller.abort(new DOMException('request cancelled', 'AbortError'));
238+
mockInventory.mockResolvedValueOnce(duoInventory('inner'));
239+
240+
await expect(
241+
setAppleFoldPose(duo, 'half-open', { signal: controller.signal }),
242+
).rejects.toMatchObject({ name: 'AbortError' });
243+
expect(mockHinge).not.toHaveBeenCalled();
244+
});
245+
246+
test('propagates a cancellation raised by a hinge read and stops polling', async () => {
247+
const controller = new AbortController();
248+
mockInventory.mockResolvedValueOnce(duoInventory('inner'));
249+
mockHinge.mockImplementation(async () => {
250+
const cancelled = new DOMException('request cancelled', 'AbortError');
251+
controller.abort(cancelled);
252+
throw cancelled;
253+
});
254+
255+
await expect(
256+
setAppleFoldPose(duo, 'half-open', { signal: controller.signal }),
257+
).rejects.toMatchObject({ name: 'AbortError' });
258+
expect(mockHinge).toHaveBeenCalledTimes(1);
259+
});
260+
182261
test('refuses a single-panel simulator before pressing anything', async () => {
183262
mockInventory.mockResolvedValueOnce(buildInventory([panel({})]));
184263

0 commit comments

Comments
 (0)