Skip to content

Commit b1df399

Browse files
thymikeeclaude
andcommitted
fix(fold): word the no-sample hinge read neutrally and carry its failure
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
1 parent bb187b6 commit b1df399

7 files changed

Lines changed: 21 additions & 21 deletions

File tree

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -252,7 +252,7 @@ unverified, because the pose it ended in is not the one that was asked for.
252252
The attempt count, the per-read timeout, cancellation, and the open/closed end-stop
253253
rule are unchanged: an unsettled fold costs the same four hinge streams it always did.
254254

255-
A toolchain with no `devicectl device motion` subcommand (devicectl 651.13.5, Xcode 27.1 RC build 27A9275) cannot read the hinge at all, and answers the first read with no sample. The HID command has already been delivered by then, so `fold` refuses with `fold-pose-dispatched-unverified`: sent, not confirmed, distinct from a pose the hinge contradicted. The error carries the lit panel as evidence; panel power cannot separate `half-open` from `open`, so it is never promoted to a verified pose.
255+
A first hinge read that returns no sample leaves the pose unconfirmed, whatever the cause: devicectl 651.13.5 (Xcode 27.1 RC build 27A9275) has no `device motion` subcommand, and an unreachable device prints no sample either. The HID command has already been delivered by then, so `fold` refuses with `fold-pose-dispatched-unverified`: sent, not confirmed, distinct from a pose the hinge contradicted. The read's own failure rides along as `hingeReadFailure`, so the cause is read from its stderr rather than assumed. When panel power decides a single lit panel, the error carries it as `screen` evidence; panel power cannot separate `half-open` from `open`, so it is never promoted to a verified pose. A no-sample read after an earlier sample is not this case and keeps its own reason.
256256

257257
## Pose is derived from panel power, and official control does not exist
258258

‎packages/platform-apple/src/core/__tests__/hinge-angle.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ test('refuses a stream that printed no sample, naming the toolchain gap', async
6767
await expect(readAppleHingeAngle(IOS_TEST_SIMULATOR)).rejects.toMatchObject({
6868
code: 'COMMAND_FAILED',
6969
details: expect.objectContaining({
70-
reason: 'fold-hinge-angle-unavailable',
70+
reason: 'fold-hinge-angle-no-sample',
7171
hint: expect.stringContaining('hinge-angle'),
7272
}),
7373
});

‎packages/platform-apple/src/core/hinge-angle.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,11 @@ import { runXcrun } from './tool-provider.ts';
1212
*/
1313
const HINGE_ANGLE_SAMPLE = /Angle:\s*(-?\d+(?:[.,]\d+)?)\s*°/g;
1414

15-
/** The stream printed no sample: the toolchain has no `device motion` subcommand or it reports nothing. */
16-
export const HINGE_ANGLE_UNAVAILABLE_REASON = 'fold-hinge-angle-unavailable';
15+
/** The read returned no sample line; stderr in the details says why. */
16+
export const HINGE_ANGLE_NO_SAMPLE_REASON = 'fold-hinge-angle-no-sample';
1717

18-
const HINGE_ANGLE_UNSUPPORTED_HINT =
19-
"This Xcode/CoreDevice toolchain does not stream 'devicectl device motion hinge-angle' for this device. Foldable poses can be verified only through that stream; update Xcode to a version that ships it.";
18+
const HINGE_ANGLE_NO_SAMPLE_HINT =
19+
"'devicectl device motion hinge-angle' printed no sample, and foldable poses can be verified only through that stream. The stderr in the details names the cause, such as a devicectl without the subcommand or a device CoreDevice cannot reach.";
2020

2121
/**
2222
* Reads the hinge angle CoreDevice currently reports for one Apple device, in degrees: 0 is
@@ -59,8 +59,8 @@ export async function readAppleHingeAngle(
5959
stdout: result.stdout,
6060
stderr: result.stderr,
6161
deviceId: device.id,
62-
reason: HINGE_ANGLE_UNAVAILABLE_REASON,
63-
hint: HINGE_ANGLE_UNSUPPORTED_HINT,
62+
reason: HINGE_ANGLE_NO_SAMPLE_REASON,
63+
hint: HINGE_ANGLE_NO_SAMPLE_HINT,
6464
}),
6565
);
6666
}

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -383,13 +383,13 @@ test.each([
383383
},
384384
);
385385

386-
test('reports a dispatched but unverifiable pose when the toolchain has no hinge-angle stream', async () => {
386+
test('reports a dispatched but unverifiable pose when the first hinge read returns no sample', async () => {
387387
mockInventory
388388
.mockResolvedValueOnce(duoInventory('outer'))
389389
.mockResolvedValueOnce(duoInventory('inner'));
390390
mockHinge.mockRejectedValue(
391391
new AppError('COMMAND_FAILED', 'CoreDevice reported no hinge angle sample', {
392-
reason: 'fold-hinge-angle-unavailable',
392+
reason: 'fold-hinge-angle-no-sample',
393393
}),
394394
);
395395

@@ -418,12 +418,12 @@ test('keeps a mid-settle hinge read failure as the read failure, not a missing t
418418
mockInventory.mockResolvedValueOnce(duoInventory('inner'));
419419
mockHinge.mockResolvedValueOnce(100).mockRejectedValueOnce(
420420
new AppError('COMMAND_FAILED', 'CoreDevice reported no hinge angle sample', {
421-
reason: 'fold-hinge-angle-unavailable',
421+
reason: 'fold-hinge-angle-no-sample',
422422
}),
423423
);
424424

425425
await expect(setAppleFoldPose(duo, { pose: 'half-open' })).rejects.toMatchObject({
426-
details: expect.objectContaining({ reason: 'fold-hinge-angle-unavailable' }),
426+
details: expect.objectContaining({ reason: 'fold-hinge-angle-no-sample' }),
427427
});
428428
});
429429

@@ -435,7 +435,7 @@ test('omits the screen from the dispatched-unverified refusal when no panel is l
435435
mockInventory.mockResolvedValueOnce(duoInventory('outer')).mockResolvedValueOnce(noneLit);
436436
mockHinge.mockRejectedValue(
437437
new AppError('COMMAND_FAILED', 'CoreDevice reported no hinge angle sample', {
438-
reason: 'fold-hinge-angle-unavailable',
438+
reason: 'fold-hinge-angle-no-sample',
439439
stderr: "Unknown option '--device'",
440440
}),
441441
);

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ import {
1515
type AppleDeviceDisplay,
1616
type AppleDisplayInventory,
1717
} from '../core/display-inventory.ts';
18-
import { HINGE_ANGLE_UNAVAILABLE_REASON, readAppleHingeAngle } from '../core/hinge-angle.ts';
18+
import { HINGE_ANGLE_NO_SAMPLE_REASON, readAppleHingeAngle } from '../core/hinge-angle.ts';
1919
import { requireSimulatorDevice } from '../core/simulator.ts';
2020
import { sendSimulatorFoldPose } from './simulator-hid.ts';
2121

@@ -26,7 +26,7 @@ const INVENTORY_REQUIRED_HINT =
2626
"fold needs 'devicectl device info displays' to tell a foldable from a single-panel simulator; update Xcode to a version that ships the display-information feature.";
2727

2828
const DISPATCHED_UNVERIFIED_HINT =
29-
"The pose request was sent and the device may have followed it, but 'devicectl device motion hinge-angle' is unavailable here, so fold cannot confirm it. Take a screenshot or snapshot to see which panel is lit, or update Xcode to a version that ships the hinge-angle stream.";
29+
'The pose request was sent and the device may have followed it, but the first hinge-angle read returned no sample, so fold cannot confirm it. Take a screenshot or snapshot to see which panel is lit; hingeReadFailure names why the read failed.';
3030

3131
const POSE_UNSETTLED_HINT =
3232
'The hinge reached the requested pose and was still moving when the read budget ended. Retry the fold, then read the angle directly with xcrun devicectl device motion hinge-angle --device <udid> --session-timeout 1 --timeout 5 to see whether the simulator holds the pose.';
@@ -61,8 +61,8 @@ export async function setAppleFoldPose(
6161
};
6262
}
6363

64-
function isHingeAngleUnavailable(error: unknown): boolean {
65-
return error instanceof AppError && error.details?.reason === HINGE_ANGLE_UNAVAILABLE_REASON;
64+
function isHingeNoSample(error: unknown): boolean {
65+
return error instanceof AppError && error.details?.reason === HINGE_ANGLE_NO_SAMPLE_REASON;
6666
}
6767

6868
/**
@@ -81,7 +81,7 @@ async function dispatchedUnverifiedPoseError(
8181
const litPanel = await readLitPanel(device, signal);
8282
return new AppError(
8383
'COMMAND_FAILED',
84-
`${device.name} received the ${pose} pose request, but this toolchain cannot read the hinge angle to verify it`,
84+
`${device.name} received the ${pose} pose request, but the first hinge-angle read returned no sample to verify it`,
8585
{
8686
deviceId: device.id,
8787
requestedPose: pose,
@@ -139,7 +139,7 @@ async function awaitHingePose(
139139
try {
140140
observed = await readAppleHingeAngle(device, { signal });
141141
} catch (error) {
142-
if (observed !== undefined || !isHingeAngleUnavailable(error)) throw error;
142+
if (observed !== undefined || !isHingeNoSample(error)) throw error;
143143
throw await dispatchedUnverifiedPoseError(device, pose, signal, targetAngle, error);
144144
}
145145
if (isVerifiedHingePose(observed, previous, pose, targetAngle)) return observed;

‎src/commands/system/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -253,7 +253,7 @@ Screens are handled for you:
253253
254254
Changing the pose:
255255
agent-device fold closed | half-open | open
256-
fold sends a private HID hinge event inside the selected simulator and then reads the hinge angle back from CoreDevice until it agrees: closed is 0 degrees, open is 180, and half-open is any angle between them (requested at 130 degrees). An angle in that interval only proves the category, so half-open is reported once two consecutive readings both fall inside it and agree within 0.5 degrees. The response reports the verified pose, the hinge angle, and the panel the device now lights with its native panel point size, marked coordinateSpace "native-panel". That point size is the panel's own geometry, not the next snapshot's viewport, so it cannot place a tap: the active app window can differ (a 669x951 inner panel hosts a 951x669 window). A hinge whose last reading is some other pose fails with COMMAND_FAILED and reason fold-pose-unverified, naming the angle CoreDevice still reports; a hinge seen half-open but never at rest fails with reason fold-pose-unsettled, naming the observed and previous angles; a toolchain without the hinge-angle stream (no devicectl device motion) fails with reason fold-pose-dispatched-unverified, meaning the pose was sent but cannot be confirmed, and carries the lit panel's size as evidence, so take a screenshot or snapshot to check. A single-panel simulator fails with UNSUPPORTED_OPERATION. A simulator scoped to a non-default set with --ios-simulator-device-set is refused before any hinge is touched, with ${foldGuidance.unsupportedScope}: the HID send honors the set, but CoreDevice's display inventory and hinge-angle readback resolve a scoped simulator as not found, so the pose could not be verified. Run fold without --ios-simulator-device-set (in the default set).
256+
fold sends a private HID hinge event inside the selected simulator and then reads the hinge angle back from CoreDevice until it agrees: closed is 0 degrees, open is 180, and half-open is any angle between them (requested at 130 degrees). An angle in that interval only proves the category, so half-open is reported once two consecutive readings both fall inside it and agree within 0.5 degrees. The response reports the verified pose, the hinge angle, and the panel the device now lights with its native panel point size, marked coordinateSpace "native-panel". That point size is the panel's own geometry, not the next snapshot's viewport, so it cannot place a tap: the active app window can differ (a 669x951 inner panel hosts a 951x669 window). A hinge whose last reading is some other pose fails with COMMAND_FAILED and reason fold-pose-unverified, naming the angle CoreDevice still reports; a hinge seen half-open but never at rest fails with reason fold-pose-unsettled, naming the observed and previous angles; a first hinge-angle read that returns no sample (for example a devicectl without device motion) fails with reason fold-pose-dispatched-unverified, meaning the pose was sent but cannot be confirmed; hingeReadFailure holds the read's own failure details, and screen holds the lit panel's size when panel power decides one panel, so take a screenshot or snapshot to check. A single-panel simulator fails with UNSUPPORTED_OPERATION. A simulator scoped to a non-default set with --ios-simulator-device-set is refused before any hinge is touched, with ${foldGuidance.unsupportedScope}: the HID send honors the set, but CoreDevice's display inventory and hinge-angle readback resolve a scoped simulator as not found, so the pose could not be verified. Run fold without --ios-simulator-device-set (in the default set).
257257
Expect a fold to take 10-16 seconds: each hinge read is a five-second devicectl stream, and half-open waits for the hinge to stop moving. Re-snapshot after every fold; refs and coordinates from before it are stale, and the command's message says so.
258258
Timed motion: fold --keyframes '[{"atMs":0,"angle":0},{"atMs":5000,"angle":180}]'. Use 2–64 frames starting at 0ms, increasing integer timestamps up to 60000ms, and angles from 0 to 180. The last timestamp sets motion duration, excluding setup and verification. Equal angles hold; cancellation stops motion. See the fold examples in the command and Node API documentation for trajectories.
259259

‎website/docs/docs/commands.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ Fold a foldable device:
114114
- The iOS response names the lit panel and its size, marked `coordinateSpace: "native-panel"`. That size is not the next snapshot's viewport and cannot place a tap.
115115
- iOS only: `--keyframes` plays a timed trajectory instead of a preset, for example `fold --keyframes '[{"atMs":0,"angle":0},{"atMs":1667,"angle":160},{"atMs":3333,"angle":100},{"atMs":5000,"angle":180}]'`. Use 2–64 keyframes starting at 0ms, strictly increasing integer timestamps up to 60,000ms, and angles from 0 to 180°.
116116
- iOS needs an Xcode with the iOS simulator SDK and foldable HID support (verified on Xcode 27.1); Device Hub and Accessibility permission aren't required. The first fold builds a helper cached under `~/.agent-device/fold-helper`; failures report `fold-helper-build-failed` or `fold-hid-dispatch-failed`.
117-
- `COMMAND_FAILED` with `reason: fold-pose-unverified` means the hinge reports another pose; `fold-pose-unsettled` means it reached `half-open` but never came to rest; `fold-pose-dispatched-unverified` means the pose was sent but this Xcode has no hinge-angle stream to confirm it, so check the lit panel with a screenshot.
117+
- `COMMAND_FAILED` with `reason: fold-pose-unverified` means the hinge reports another pose; `fold-pose-unsettled` means it reached `half-open` but never came to rest; `fold-pose-dispatched-unverified` means the pose was sent but the first hinge-angle read returned no sample, so check the lit panel with a screenshot; `hingeReadFailure` holds the read's own failure.
118118
- `UNSUPPORTED_OPERATION` covers single-panel devices (`single-panel-device` on Android) and simulators in a non-default `--ios-simulator-device-set` (`unsupported-device-scope`; use the default set). Physical devices are refused.
119119
- On Android, `fold` confirms the pose from the device state the emulator commits and reports `hingeAngleDegrees` as the hinge sensor reads it: the angle the AVD profile defines for the posture, such as 0°, 90°, and 180° on the Pixel folds or 15°, 90°, and 165° on the generic 7.6in Foldable. It also dismisses the lock screen that folding to the cover display can raise. For panels, poses, and timings, see `agent-device help foldable`.
120120

0 commit comments

Comments
 (0)