Skip to content

Commit 9fefab0

Browse files
committed
fix(daemon): let a settle that proved rest record the tree that proved it (#3471)
Removing the session-snapshot preference took the baseline back to the tree the action started from, and that broke a contract the repository already encodes: a press following a converged `--settle` spends a tap and nothing else (test/integration/provider-scenarios/settle-observation. test.ts asserts the runner transcript directly). A settled press is the case the screening exists to answer cheaply — re-observing a surface the settle already proved quiet is the round trip `--settle` was built to remove. The provenance problem the review found stays fixed. Instead of inferring "newer" from a differing node array, the finalizer forwards the action's own settle observation and the marker reads the one field that carries the fact: `diff`, which the runtime attaches only when the loop converged AND stored its settled tree as the session snapshot within one surface. `settled` alone is not that fact — a sparse capture is refused by the store and a cross-surface transition withholds the diff, and in both cases the session's newest tree belongs to some earlier capture. Everything that is not a stored settled tree keeps the acted-through tree: a timed-out loop, a lone `--verify` capture, a freshness capture, a `@ref` frame.
1 parent bc5c09d commit 9fefab0

4 files changed

Lines changed: 117 additions & 15 deletions

File tree

‎src/daemon/__tests__/moving-target-baseline.test.ts‎

Lines changed: 75 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import assert from 'node:assert/strict';
22
import { test } from 'vitest';
3-
import type { SurfaceScopedNodes } from '@agent-device/contracts/interaction';
3+
import type { SettleObservation, SurfaceScopedNodes } from '@agent-device/contracts/interaction';
44
import { makeSnapshotState } from '@agent-device/selectors/snapshot-geometry-fixtures';
55
import {
66
markDeferredInteractionOutcome,
@@ -208,6 +208,80 @@ test('a gesture takes the surface over from a press, rather than joining it', ()
208208
assert.equal(movingTargetBaseline(session), undefined);
209209
});
210210

211+
/** A `--settle` observation. `diff` is the field that means "converged AND stored". */
212+
function settleMark(params: { settled: boolean; diff: boolean }): SettleObservation {
213+
return {
214+
settled: params.settled,
215+
waitedMs: 120,
216+
captures: 3,
217+
quietMs: 50,
218+
timeoutMs: 1_000,
219+
...(params.diff
220+
? { diff: { summary: { additions: 1, removals: 0, unchanged: 4 }, lines: [] } }
221+
: {}),
222+
};
223+
}
224+
225+
test('a settle that stored its settled tree records that tree, not the tree the press started from', () => {
226+
// The loop stopped because two reads agreed, and the tree it published became the session
227+
// snapshot. That tree IS the resting surface, and the follow-up press is contractually supposed to
228+
// spend a tap and nothing else (test/integration/provider-scenarios/settle-observation.test.ts);
229+
// screening it against the pre-action tree re-observes a surface the settle already proved quiet.
230+
const session = makeSession('android');
231+
const settled = appTree('Settled');
232+
session.snapshot = settled;
233+
234+
markDeferredInteractionOutcome({
235+
session,
236+
command: 'press',
237+
positionals: ['label="Slide target"'],
238+
flags: undefined,
239+
preActionTree: { nodes: appTree('Pre-action').nodes },
240+
settle: settleMark({ settled: true, diff: true }),
241+
});
242+
243+
assert.equal(movingTargetBaseline(session)?.tree.nodes, settled.nodes);
244+
});
245+
246+
test('a settle that timed out keeps the acted-through tree', () => {
247+
// The loop ran out its budget without two reads agreeing, so the newest capture says nothing about
248+
// rest — recording it would turn an unsettled surface into evidence of quiet.
249+
const session = makeSession('android');
250+
session.snapshot = appTree('Still changing');
251+
const actedThrough = appTree('Pre-action');
252+
253+
markDeferredInteractionOutcome({
254+
session,
255+
command: 'press',
256+
positionals: ['label="Slide target"'],
257+
flags: undefined,
258+
preActionTree: { nodes: actedThrough.nodes },
259+
settle: settleMark({ settled: false, diff: false }),
260+
});
261+
262+
assert.equal(movingTargetBaseline(session)?.tree.nodes, actedThrough.nodes);
263+
});
264+
265+
test('a converged settle that stored nothing keeps the acted-through tree', () => {
266+
// `settled: true` is not the whole claim: a sparse capture is refused by the store and a
267+
// cross-surface transition (#2438) withholds the diff, leaving whatever an earlier capture
268+
// published. Only the stored settled tree may carry a rest claim.
269+
const session = makeSession('android');
270+
session.snapshot = appTree('Published by some earlier capture');
271+
const actedThrough = appTree('Pre-action');
272+
273+
markDeferredInteractionOutcome({
274+
session,
275+
command: 'press',
276+
positionals: ['label="Slide target"'],
277+
flags: undefined,
278+
preActionTree: { nodes: actedThrough.nodes },
279+
settle: settleMark({ settled: true, diff: false }),
280+
});
281+
282+
assert.equal(movingTargetBaseline(session)?.tree.nodes, actedThrough.nodes);
283+
});
284+
211285
test('the trigger is wider than the guard on purpose: any command that acted through a tree records it', () => {
212286
// The ADR 0011 `targetStability` cells scope which commands the GATE refuses to dispatch blind
213287
// (press, click). This marker answers a different question — did a mutation just leave a surface

‎src/daemon/deferred-interaction-outcome.ts‎

Lines changed: 30 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import type { CommandFlags } from '@agent-device/contracts/command';
2-
import type { SurfaceScopedNodes } from '@agent-device/contracts/interaction';
2+
import type { SettleObservation, SurfaceScopedNodes } from '@agent-device/contracts/interaction';
33
import type { PostOpenObservation } from '@agent-device/contracts/application-lifecycle-runtime';
44
import type { SnapshotCaptureAnnotations } from '@agent-device/contracts/capture';
55
import { isApplePlatform, isMobilePlatform } from '@agent-device/kernel/device';
@@ -64,6 +64,12 @@ export type DeferredInteractionOutcomeMark = {
6464
* moving-target baseline; absent for the routes that dispatch without a daemon tree.
6565
*/
6666
preActionTree?: SurfaceScopedNodes | undefined;
67+
/**
68+
* The action's own `--settle` observation, when it ran one (#3471). Its `diff` is the load-bearing
69+
* field: the runtime attaches it only when the loop converged AND stored its settled tree within
70+
* one surface, which is exactly when that published tree may stand as the baseline.
71+
*/
72+
settle?: SettleObservation | undefined;
6773
};
6874

6975
export function markDeferredInteractionOutcome(
@@ -77,6 +83,7 @@ export function markDeferredInteractionOutcome(
7783
flags,
7884
androidFreshnessBaseline,
7985
preActionTree,
86+
settle,
8087
} = params;
8188
if (isNavigationSensitiveAction(action)) {
8289
markAndroidSnapshotFreshness(session, action, androidFreshnessBaseline ?? session.snapshot);
@@ -91,7 +98,18 @@ export function markDeferredInteractionOutcome(
9198
// #1542/#1600 unsettled-tree check the scroll bought.
9299
if (markSurfaceStabilization(session, action, positionals, flags)) return;
93100
if (pendingSurfaceStabilization(session)) return;
94-
markMovingTargetBaseline(session, preActionTree);
101+
markMovingTargetBaseline(session, preActionTree, settle?.diff !== undefined);
102+
}
103+
104+
/** Narrows a published capture to the shape a baseline keeps, so a stored tree never smuggles in more. */
105+
function movingTargetRestTree(snapshot: SnapshotState | undefined): SurfaceScopedNodes | undefined {
106+
if (!snapshot) return undefined;
107+
return {
108+
nodes: snapshot.nodes,
109+
...(snapshot.iosSystemSurfaceBundleId
110+
? { surfaceBundleId: snapshot.iosSystemSurfaceBundleId }
111+
: {}),
112+
};
95113
}
96114

97115
/** Whether this mutation left an unsettled surface for the capture side to steady. */
@@ -143,27 +161,26 @@ function markSurfaceStabilization(
143161
* tap, `back`, an app open) leave the session idle: the ordinary navigate-then-tap step pays the
144162
* gate nothing.
145163
*
146-
* The baseline is that tree and never the session's current snapshot. A `--settle` or `--verify`
147-
* press does publish a post-action observation, and it would be the better account of where the
148-
* surface came to rest — but nothing here can tell a post-action capture from a freshness capture or
149-
* a `@ref` press's authorized frame, since all three reach `session.snapshot` as a different node
150-
* array from the one the action resolved against. Inferring "newer" from array identity would
151-
* attribute to this action a surface it may never have looked at, which is the exact thing this
152-
* marker forbids. A settled press therefore leaves the next press owed a re-observation rather than
153-
* answered from a tree of unknown provenance: the cost lands on one extra pair of captures inside the
154-
* window, never on a rest judgement made against the wrong surface.
164+
* `restProved` switches the tree to the session's published one, and is set only when the action's
165+
* own settle loop converged AND stored its settled tree. Everything else keeps the pre-action tree:
166+
* the session's snapshot may hold a freshness capture, a `@ref` press's authorized frame, or a lone
167+
* `--verify` capture, and none of those proves rest. Inferring it from a snapshot that merely
168+
* differs from the tree the action resolved against would attribute to this action a surface it may
169+
* never have looked at — the substitution this marker exists to prevent.
155170
*/
156171
function markMovingTargetBaseline(
157172
session: SessionState,
158173
preActionTree: SurfaceScopedNodes | undefined,
174+
restProved: boolean,
159175
): void {
160-
if (!preActionTree || preActionTree.nodes.length === 0) {
176+
const tree = restProved ? movingTargetRestTree(session.snapshot) : preActionTree;
177+
if (!tree || tree.nodes.length === 0) {
161178
retireMovingTargetBaseline(session);
162179
return;
163180
}
164181
session.deferredSurface = {
165182
kind: 'recheck',
166-
baseline: { finishedAt: Date.now(), tree: preActionTree },
183+
baseline: { finishedAt: Date.now(), tree },
167184
};
168185
}
169186

‎src/daemon/interaction/internal/interaction-common.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import type { CommandFlags } from '@agent-device/contracts/command';
2-
import type { SurfaceScopedNodes } from '@agent-device/contracts/interaction';
2+
import type { SettleObservation, SurfaceScopedNodes } from '@agent-device/contracts/interaction';
33
import type { SnapshotState } from '@agent-device/kernel/snapshot';
44
import type { DaemonResponse } from '../../daemon-request.ts';
55
import { stripInternalInteractionFlags } from '../../deferred-interaction-outcome.ts';
@@ -34,6 +34,11 @@ export function finalizeTouchInteraction(params: {
3434
* baseline. Absent for the dispatches that acted without a daemon tree.
3535
*/
3636
preActionTree?: SurfaceScopedNodes | undefined;
37+
/**
38+
* The action's own `--settle` observation, forwarded to the deferred-outcome marker, which reads
39+
* the settled-tree signal from it (#3471).
40+
*/
41+
settle?: SettleObservation | undefined;
3742
}): DaemonResponse {
3843
const {
3944
operations,
@@ -49,6 +54,7 @@ export function finalizeTouchInteraction(params: {
4954
actionFinishedAt,
5055
androidFreshnessBaseline,
5156
preActionTree,
57+
settle,
5258
} = params;
5359
const actionFlags = stripInternalInteractionFlags(flags);
5460
const [parameterizedResult, parameterizedResponseData] = parameterizeFillPayloads({
@@ -81,6 +87,7 @@ export function finalizeTouchInteraction(params: {
8187
flags,
8288
androidFreshnessBaseline,
8389
preActionTree,
90+
settle,
8491
});
8592
operations.recordGestureVisualization(
8693
actionCommand,

‎src/daemon/interaction/internal/interaction-touch-runtime.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,10 @@ export async function dispatchRuntimeInteraction<
126126
actionFinishedAt,
127127
androidFreshnessBaseline: options.androidFreshnessBaseline,
128128
preActionTree: runtimeResult.preAction,
129+
// The action's own settle observation, so the baseline can be the tree that proved rest
130+
// instead of the tree the action started from. Without it the follow-up press re-observes a
131+
// surface the settle already proved quiet — the round trip `--settle` exists to remove.
132+
...(runtimeResult.settle ? { settle: runtimeResult.settle } : {}),
129133
});
130134
} catch (error) {
131135
const appError = publishAmbiguousMatchCandidateRefs(

0 commit comments

Comments
 (0)