Skip to content

Commit bc8e5eb

Browse files
thymikeeclaude
andcommitted
fix(settle): arm the dismissal confirmation on the producer's presented-surface fact
A tab switch or a push replaces the screen broadly, so main's arming charged ordinary navigation the 1.5 s confirmation floor (#3470). The settle baseline now carries the presentedSurface fact its producer stamped before projection (#3565), and the confirmation reads it: - `absent` rules the confirmation out for the run: nothing presented, no dismissal to confirm. - `presented` admits a rootless first capture after the dismissal, as a tiny baseline already did. - `unknown` or no fact keeps the parent's arming, so the fact only ever narrows the guard. Because the fact is stamped before projection, interactive and full-tree baselines of one sheet arm alike, which the node-count draft of this layer could not do. Closes #3470 Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 542fb77 commit bc8e5eb

10 files changed

Lines changed: 587 additions & 38 deletions

File tree

‎packages/command-registry/src/flag-definitions-action.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -211,7 +211,7 @@ export const ACTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
211211
min: 0,
212212
usageLabel: '--settle-quiet <ms>',
213213
usageDescription:
214-
'Settle: quiet window the UI must hold to count as settled (default 500ms; 300ms when the settled tree comes from the iOS simulator snapshot bridge). On iOS, a broad screen replacement such as a modal dismissal is confirmed for at least 1500ms whatever window is asked for, within the --timeout settle deadline',
214+
'Settle: quiet window the UI must hold to count as settled (default 500ms; 300ms when the settled tree comes from the iOS simulator snapshot bridge). On iOS, a broad screen replacement such as a modal dismissal is confirmed for at least 1500ms whatever window is asked for, within the --timeout settle deadline; one from a screen the pre-action capture read as presenting nothing, such as a tab switch, is not',
215215
projectConfig: true,
216216
recorded: false,
217217
},

‎packages/daemon/src/execution/generic-settle.ts‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,12 @@ import type { BoundContextFromFlags } from '../core/context.ts';
1717
import type { RuntimeAdmissionBindings } from '../core/request-runtime-binding.ts';
1818
import type { DaemonPlatformServices } from '../core/platform-services.ts';
1919
import { resolveSettleObservationCapture } from '../core/settle-observation-capture.ts';
20+
import { isOutdatedObservation } from '../core/ref-frame.ts';
2021
import { issueSettleRefs } from './session-snapshot.ts';
2122
import type { SessionStore } from '../core/session-store.ts';
2223
import type { DaemonRequest, DaemonResponse } from '../core/daemon-request.ts';
2324
import type { SessionRef, SessionState } from '../core/session-state.ts';
25+
import type { SnapshotState } from '@agent-device/kernel/snapshot';
2426

2527
/**
2628
* `--settle` on the generic daemon route (#1638): `scroll` and `back` change
@@ -84,11 +86,23 @@ export function planGenericSettleObservation(
8486
if (invalidSettleFlags) return { response: invalidSettleFlags };
8587
const settle = readSettleRequest(params.flags);
8688
if (!settle) return {};
87-
const snapshot = params.session.snapshot;
88-
const baseline = surfaceScopedNodes(snapshot);
89+
const baseline = storedTreeBaseline(params.session.snapshot);
8990
return { observe: async () => await observeSettled(params, settle, baseline) };
9091
}
9192

93+
/**
94+
* The stored tree as the settle baseline. Its presented-surface fact describes the screen when the
95+
* tree was captured, so a tree a later side effect outdated keeps its nodes for the diff but not
96+
* the fact: an `absent` read taken before a sheet was presented must not rule out the confirmation
97+
* owed to that sheet's dismissal (#3565).
98+
*/
99+
function storedTreeBaseline(snapshot: SnapshotState | undefined): SurfaceScopedNodes {
100+
const baseline = surfaceScopedNodes(snapshot);
101+
if (!snapshot || !isOutdatedObservation(snapshot)) return baseline;
102+
const { presentedSurface: _outdated, ...current } = baseline;
103+
return current;
104+
}
105+
92106
/**
93107
* Best-effort like the settle engine itself: the action already succeeded, so a
94108
* runtime that cannot even be constructed (session evicted mid-request)

‎src/__tests__/daemon-composition/generic-settle.test.ts‎

Lines changed: 84 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import { composedPlatformServicesFixture } from './platform-services-fixture.ts'
22
import { beforeEach, expect, test, vi } from 'vitest';
33
import type { CommandFlags } from '@agent-device/contracts/command';
44
import type { CommandClock } from '@agent-device/contracts/runtime-contract';
5-
import type { RawSnapshotNode } from '@agent-device/kernel/snapshot';
5+
import type { PresentedSurface, RawSnapshotNode } from '@agent-device/kernel/snapshot';
66
import {
77
APP_SURFACE,
88
iosSystemSurfaceDisclosure,
@@ -11,7 +11,16 @@ import {
1111
} from '@agent-device/contracts/ios-system-surface';
1212
import { makeIosSession } from '@agent-device/daemon/testing/__tests__/support/session-factories';
1313
import { makeSessionStore } from '@agent-device/daemon/testing/__tests__/support/store-factory';
14-
import { activateCompleteRefFrame, refFrameState } from '@agent-device/daemon/testing/ref-frame';
14+
import {
15+
PRESENTED_SHEET_FULL_NODES,
16+
PRESENTED_SHEET_INTERACTIVE_NODES,
17+
SHEET_DISMISSED_NODES,
18+
} from './presented-sheet-trees.ts';
19+
import {
20+
activateCompleteRefFrame,
21+
markSessionSnapshotOutdated,
22+
refFrameState,
23+
} from '@agent-device/daemon/testing/ref-frame';
1524
import { setSessionSnapshot } from '@agent-device/daemon/testing/session-snapshot';
1625
import type { SessionStore } from '@agent-device/daemon/testing/session-store';
1726
import type { DaemonRequest, DaemonResponse } from '@agent-device/daemon/daemon-request';
@@ -77,6 +86,7 @@ type SettlePayload = {
7786
captures: number;
7887
quietMs: number;
7988
timeoutMs: number;
89+
waitedMs: number;
8090
refsGeneration?: number;
8191
diff?: {
8292
summary: { additions: number; removals: number; unchanged: number };
@@ -115,7 +125,7 @@ async function emulateCaptureSnapshotForSession(
115125
}
116126

117127
function mockCommandDispatch(
118-
snapshots: Array<typeof BEFORE_NODES>,
128+
snapshots: RawSnapshotNode[][],
119129
producer: NonNullable<GenericSettleTree['producer']> = 'apple-runner',
120130
) {
121131
let snapshotCalls = 0;
@@ -181,6 +191,7 @@ type GenericSettleTree = {
181191
nodes: RawSnapshotNode[];
182192
systemSurface?: IosSystemSurfaceProvenance;
183193
producer?: 'apple-runner' | 'simulator-ax-bridge';
194+
presentedSurface?: PresentedSurface;
184195
};
185196

186197
function snapshotPayload(tree: GenericSettleTree) {
@@ -189,6 +200,7 @@ function snapshotPayload(tree: GenericSettleTree) {
189200
backend: 'xctest' as const,
190201
producer: tree.producer ?? ('apple-runner' as const),
191202
...(tree.systemSurface ? { systemSurface: tree.systemSurface } : {}),
203+
...(tree.presentedSurface ? { presentedSurface: tree.presentedSurface } : {}),
192204
};
193205
}
194206

@@ -556,6 +568,75 @@ test('back --settle attaches no diff across a sheet-to-app surface change and di
556568
expect(stored.snapshot?.iosSystemSurfaceBundleId).toBeUndefined();
557569
});
558570

571+
/**
572+
* `back --settle` over a sheet left on the session by a capture of one given flavour, which is how
573+
* the generic route picks its baseline (`generic-settle.ts` reads the stored tree directly). The
574+
* settle loop's budget arithmetic runs on the injected clock, so no caller waits real time.
575+
*/
576+
async function dismissSheetFromBaseline(
577+
sessionName: string,
578+
baseline: GenericSettleTree,
579+
options: { outdated?: boolean; captures?: RawSnapshotNode[][] } = {},
580+
): Promise<SettlePayload> {
581+
const sessionStore = makeSessionStore();
582+
const session = seedSession(sessionName, sessionStore, baseline);
583+
if (options.outdated) markSessionSnapshotOutdated(session);
584+
// Rootless, as the first reads after a dismissal can be: only a presented baseline arms on them.
585+
mockCommandDispatch(options.captures ?? [SHEET_DISMISSED_NODES.slice(1)]);
586+
const response = await dispatchGeneric({
587+
sessionName,
588+
sessionStore,
589+
command: 'back',
590+
flags: { settle: true, settleQuietMs: 25, timeoutMs: 30_000 },
591+
clock: fakeClock(),
592+
});
593+
return expectOkData(response).settle as SettlePayload;
594+
}
595+
596+
test('the confirmation arms for one presented sheet whichever baseline flavour the route holds', async () => {
597+
// The interactive capture projects the sheet as 4 nodes and the full read as 6, so a rule keyed on
598+
// the projection disarms on the full one. The producer's fact is stamped before projection.
599+
const interactive = await dismissSheetFromBaseline('generic-settle-dismiss-sheet-interactive', {
600+
nodes: PRESENTED_SHEET_INTERACTIVE_NODES,
601+
presentedSurface: 'presented',
602+
});
603+
const full = await dismissSheetFromBaseline('generic-settle-dismiss-sheet-full', {
604+
nodes: PRESENTED_SHEET_FULL_NODES,
605+
presentedSurface: 'presented',
606+
});
607+
608+
expect(interactive.settled).toBe(true);
609+
expect(full.settled).toBe(true);
610+
expect(interactive.waitedMs).toBeGreaterThanOrEqual(1_500);
611+
expect(full.waitedMs).toBeGreaterThanOrEqual(1_500);
612+
});
613+
614+
test('back --settle keeps the plain window when the stored tree presented nothing', async () => {
615+
// The same broad replacement, stamped `absent` by its producer: the stored tree's fact reaches
616+
// the loop, and a screen with nothing presented over it owes no dismissal confirmation (#3470).
617+
const settle = await dismissSheetFromBaseline(
618+
'generic-settle-absent',
619+
{ nodes: PRESENTED_SHEET_FULL_NODES, presentedSurface: 'absent' },
620+
{ captures: [SHEET_DISMISSED_NODES] },
621+
);
622+
623+
expect(settle.settled).toBe(true);
624+
expect(settle.waitedMs).toBeLessThan(1_500);
625+
});
626+
627+
test('back --settle keeps the confirmation when a side effect outdated an absent stored tree', async () => {
628+
// The app screen was read `absent`, then a press presented the sheet without a capture. The
629+
// stored fact predates the sheet, so it cannot rule out the confirmation its dismissal owes.
630+
const settle = await dismissSheetFromBaseline(
631+
'generic-settle-outdated-absent',
632+
{ nodes: SHEET_DISMISSED_NODES, presentedSurface: 'absent' },
633+
{ outdated: true, captures: [PRESENTED_SHEET_INTERACTIVE_NODES, SHEET_DISMISSED_NODES] },
634+
);
635+
636+
expect(settle.settled).toBe(true);
637+
expect(settle.waitedMs).toBeGreaterThanOrEqual(1_500);
638+
});
639+
559640
test('the settle observation runs after the post-gesture stabilization marker', async () => {
560641
const sessionStore = makeSessionStore();
561642
const sessionName = 'generic-settle-order';
Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
import type { RawSnapshotNode } from '@agent-device/kernel/snapshot';
2+
3+
/**
4+
* One presented iOS `pageSheet`, in the two flavours a settle baseline can arrive as, plus the app
5+
* screen a dismissal returns to. An interactive capture carries only the surface — the content
6+
* underneath is not hittable, so it drops out of the projection (4 nodes on the iPhone 18 Pro sim,
7+
* October 2026) — while a full read of the very same screen also reports the covered content (6
8+
* nodes). Arming the broad-transition confirmation must not depend on which flavour produced the
9+
* baseline, which is what the caller that reads these asserts.
10+
*/
11+
export const PRESENTED_SHEET_INTERACTIVE_NODES: RawSnapshotNode[] = [
12+
{ index: 0, type: 'Application', rect: { x: 0, y: 0, width: 390, height: 844 } },
13+
{
14+
index: 1,
15+
parentIndex: 0,
16+
type: 'StaticText',
17+
label: 'Allow notifications?',
18+
rect: { x: 10, y: 450, width: 370, height: 22 },
19+
},
20+
{
21+
index: 2,
22+
parentIndex: 0,
23+
type: 'Button',
24+
label: 'Continue',
25+
rect: { x: 10, y: 600, width: 370, height: 44 },
26+
hittable: true,
27+
},
28+
{
29+
index: 3,
30+
parentIndex: 0,
31+
type: 'Button',
32+
label: 'Cancel',
33+
rect: { x: 10, y: 660, width: 370, height: 44 },
34+
hittable: true,
35+
},
36+
];
37+
38+
export const PRESENTED_SHEET_FULL_NODES: RawSnapshotNode[] = [
39+
...PRESENTED_SHEET_INTERACTIVE_NODES,
40+
{
41+
index: 4,
42+
parentIndex: 0,
43+
type: 'Other',
44+
label: 'CoveredContent',
45+
rect: { x: 0, y: 0, width: 390, height: 440 },
46+
},
47+
{
48+
index: 5,
49+
parentIndex: 0,
50+
type: 'Button',
51+
label: 'Open settings',
52+
rect: { x: 10, y: 120, width: 370, height: 44 },
53+
},
54+
];
55+
56+
/** The app screen the sheet is dismissed from, which is what every settle capture then reads. */
57+
export const SHEET_DISMISSED_NODES: RawSnapshotNode[] = [
58+
{ index: 0, type: 'Application', rect: { x: 0, y: 0, width: 390, height: 844 } },
59+
{
60+
index: 1,
61+
parentIndex: 0,
62+
type: 'StaticText',
63+
label: 'Signed in as demo',
64+
rect: { x: 10, y: 80, width: 200, height: 22 },
65+
},
66+
{
67+
index: 2,
68+
parentIndex: 0,
69+
type: 'Button',
70+
label: 'Home',
71+
rect: { x: 10, y: 120, width: 370, height: 44 },
72+
hittable: true,
73+
},
74+
{
75+
index: 3,
76+
parentIndex: 0,
77+
type: 'TabBar',
78+
label: 'Tab Bar',
79+
rect: { x: 0, y: 800, width: 390, height: 44 },
80+
},
81+
];
Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'vitest';
3+
import type { PresentedSurface, SnapshotState } from '@agent-device/kernel/snapshot';
4+
import { ref, selector } from './selector-read-utils.ts';
5+
import { createSettleDevice } from './__tests__/settle-device-fixtures.ts';
6+
import {
7+
elementCatalogTabSnapshot,
8+
elementSettingsTabSnapshot,
9+
} from './stable-capture.fixtures.ts';
10+
11+
// Each settle route hands the loop its own baseline, and the producer's presented-surface fact has
12+
// to arrive with it (#3565): a tab switch from a screen read `absent` keeps the plain window, while
13+
// the same broad replacement without that reading still pays the confirmation floor. The tab
14+
// switch is the transition #3470 measured; budgets run on the injected clock.
15+
16+
function stamped(snapshot: SnapshotState, presentedSurface: PresentedSurface): SnapshotState {
17+
return { ...snapshot, presentedSurface };
18+
}
19+
20+
/** A press that switches from the catalog tab to the settings tab, with the given baseline fact. */
21+
function tabSwitchDevice(params: { stored: PresentedSurface; preActionCaptureFails?: boolean }) {
22+
const catalog = elementCatalogTabSnapshot();
23+
let captures = 0;
24+
return createSettleDevice({
25+
stored: stamped(catalog, params.stored),
26+
captureSnapshot: () => {
27+
captures += 1;
28+
if (captures === 1 && params.preActionCaptureFails) throw new Error('capture unavailable');
29+
return {
30+
snapshot:
31+
captures === 1
32+
? stamped(catalog, params.stored)
33+
: stamped(elementSettingsTabSnapshot(), 'absent'),
34+
};
35+
},
36+
});
37+
}
38+
39+
function settingsTabRef(): string {
40+
const node = elementCatalogTabSnapshot().nodes.find(
41+
(candidate) => candidate.label === 'Settings',
42+
);
43+
assert.ok(node?.ref);
44+
return `@${node.ref}`;
45+
}
46+
47+
const ROUTES = [
48+
['a selector press', () => selector('label=Settings')],
49+
['an @ref press', () => ref(settingsTabRef())],
50+
] as const;
51+
52+
for (const [label, target] of ROUTES) {
53+
test(`${label} carries an absent baseline into the loop: a tab switch keeps the plain window`, async () => {
54+
const device = tabSwitchDevice({ stored: 'absent' });
55+
56+
const result = await device.interactions.press(target(), { session: 'default', settle: {} });
57+
58+
assert.equal(result.settle?.settled, true);
59+
assert.ok(result.settle.waitedMs < 1_500, `paid the floor: ${result.settle.waitedMs}ms`);
60+
});
61+
62+
test(`${label} keeps the confirmation when the baseline's producer could not answer`, async () => {
63+
const device = tabSwitchDevice({ stored: 'unknown' });
64+
65+
const result = await device.interactions.press(target(), { session: 'default', settle: {} });
66+
67+
assert.equal(result.settle?.settled, true);
68+
assert.ok(result.settle.waitedMs >= 1_500, `lost the floor: ${result.settle.waitedMs}ms`);
69+
});
70+
}
71+
72+
test('a point press whose evidence capture failed does not trust the stored fact', async () => {
73+
// With no capture of its own, the baseline is the stored tree, which may predate a side effect
74+
// this layer cannot see: its `absent` must not rule the confirmation out.
75+
const device = tabSwitchDevice({ stored: 'absent', preActionCaptureFails: true });
76+
77+
const result = await device.interactions.press(
78+
{ kind: 'point', x: 300, y: 820 },
79+
{ session: 'default', settle: {} },
80+
);
81+
82+
assert.equal(result.settle?.settled, true);
83+
assert.ok(result.settle.waitedMs >= 1_500, `trusted a stored fact: ${result.settle.waitedMs}ms`);
84+
});

‎src/commands/interaction/runtime/settle.ts‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ async function settleAfterAction(
145145
...(params.quietMs === undefined ? {} : { quietMs: params.quietMs }),
146146
timeoutMs,
147147
resetBudgetOnPrivateAxRecovery: true,
148-
broadTransitionBaselineNodes: params.baseline.nodes,
148+
broadTransitionBaseline: params.baseline,
149149
});
150150
if (outcome.failure) return settleUnavailable(base, outcome.quietMs, outcome.failure.error);
151151
return await readSettledOutcome(runtime, options, params, base, outcome);
@@ -271,8 +271,17 @@ function authorizedRefBaseline(
271271
return nonEmptyBaseline(surfaceScopedNodes(session?.refFrameSnapshot));
272272
}
273273

274+
/**
275+
* The latest stored tree, for a target no capture resolved. The diff can use its nodes, but its
276+
* presented-surface fact may predate a side effect this layer cannot see, and an `absent` read
277+
* taken before a sheet was presented must not rule out the confirmation owed to that sheet's
278+
* dismissal (#3565).
279+
*/
274280
function sessionBaseline(session: CommandSessionRecord | undefined): SurfaceScopedNodes {
275-
return surfaceScopedNodes(session?.refFrameSnapshot ?? session?.snapshot);
281+
const { presentedSurface: _unverified, ...baseline } = surfaceScopedNodes(
282+
session?.refFrameSnapshot ?? session?.snapshot,
283+
);
284+
return baseline;
276285
}
277286

278287
function nonEmptyBaseline(

0 commit comments

Comments
 (0)