feat: warn when @refs outlive the session snapshot they came from

Refs are positional indexes into the latest stored session tree; any
selector-based command's resolution capture silently reshuffles them
(#1076). Track an honest marker on the daemon session
(snapshotRefsStale): set wherever the stored snapshot is replaced by a
response that does not hand the new refs to the client, cleared only
where the client demonstrably receives them (snapshot responses, find
ref outputs). Commands consuming @ref arguments while the marker is set
(press/click/longpress/fill/get/wait) attach a warning and still
execute — the geometric guards keep catching detectable drift.

Closes #1076

Author: thymikee

src/daemon/handlers/__tests__/find.test.ts

@@ -730,3 +730,30 @@ test('handleFindCommands wait captures fresh snapshots while polling', async ()
   }
   expect(mockDispatch).toHaveBeenCalledTimes(2);
 });
+
+test('handleFindCommands click re-issues a fresh ref and clears the stale-refs marker (#1076)', async () => {
+  const sessionName = 'default';
+  const session = makeSession(sessionName);
+  // As set by an earlier selector-resolution capture that replaced the tree.
+  session.snapshotRefsStale = true;
+
+  const { response, session: storedSession } = await runFindClickScenario({
+    positionals: ['Increment', 'click'],
+    nodes: [
+      {
+        index: 0,
+        type: 'Button',
+        label: 'Increment',
+        hittable: true,
+        rect: { x: 50, y: 0, width: 100, height: 100 },
+        depth: 0,
+      },
+    ],
+    session,
+  });
+
+  expect(response.ok).toBe(true);
+  // The response returns a ref minted from the freshly stored snapshot, so
+  // the marker clears before the internal click @ref sub-invocation runs.
+  expect(storedSession.snapshotRefsStale).toBe(false);
+});

src/daemon/handlers/__tests__/interaction.test.ts

@@ -6,6 +6,7 @@ import type { CommandFlags } from '../../../core/dispatch.ts';
 import { attachRefs, type SnapshotBackend } from '../../../kernel/snapshot.ts';
 import { AppError } from '../../../kernel/errors.ts';
 import { buildSnapshotState } from '../snapshot-capture.ts';
+import { setSessionSnapshot, STALE_SNAPSHOT_REFS_WARNING } from '../../session-snapshot.ts';
 import { makeSessionStore } from '../../../__tests__/test-utils/store-factory.ts';
 import {
   makeIosSession,
@@ -106,7 +107,9 @@ async function emulateCaptureSnapshotForSession(
     contextFromFlags(effectiveFlags, session.appBundleId, session.trace?.outPath),
   )) as { nodes?: never[]; truncated?: boolean; backend?: SnapshotBackend };
   const snapshot = buildSnapshotState(snapshotData ?? {}, effectiveFlags);
-  session.snapshot = snapshot;
+  // Mirror the real captureSnapshotForSession: session snapshot writes go
+  // through setSessionSnapshot so snapshotRefsStale tracking (#1076) applies.
+  setSessionSnapshot(session, snapshot);
   sessionStore.set(session.name, session);
   return snapshot;
 }
@@ -3101,3 +3104,210 @@ test('is reports Android permission dialog blocker when app content assertion fa
     });
   }
 });
+
+// --- Stale @ref warnings (#1076) ---
+
+function makeTwoButtonNodes() {
+  return [
+    {
+      index: 0,
+      type: 'Application',
+      rect: { x: 0, y: 0, width: 390, height: 844 },
+    },
+    {
+      index: 1,
+      parentIndex: 0,
+      type: 'XCUIElementTypeButton',
+      label: 'Continue',
+      rect: { x: 10, y: 20, width: 100, height: 40 },
+      enabled: true,
+      hittable: true,
+    },
+    {
+      index: 2,
+      parentIndex: 0,
+      type: 'XCUIElementTypeButton',
+      label: 'Cancel',
+      rect: { x: 10, y: 80, width: 100, height: 40 },
+      enabled: true,
+      hittable: true,
+    },
+  ];
+}
+
+function makeStaleRefSession(sessionName: string): SessionState {
+  const session = makeSession(sessionName);
+  session.snapshot = {
+    nodes: attachRefs(makeTwoButtonNodes() as never),
+    createdAt: Date.now(),
+    backend: 'xctest',
+  };
+  // As if the snapshot command just returned these refs to the client.
+  session.snapshotRefsStale = false;
+  return session;
+}
+
+async function runInteraction(
+  sessionStore: SessionStore,
+  sessionName: string,
+  command: string,
+  positionals: string[],
+  flags: Record<string, unknown> = {},
+) {
+  return await handleInteractionCommands({
+    req: { token: 't', session: sessionName, command, positionals, flags },
+    sessionName,
+    sessionStore,
+    contextFromFlags,
+  });
+}
+
+test('press selector then press @ref warns that refs outlived the stored snapshot', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'stale-ref-warns';
+  const session = makeStaleRefSession(sessionName);
+  sessionStore.set(sessionName, session);
+  mockDispatch.mockImplementation(async (_device, command) =>
+    command === 'snapshot' ? { nodes: makeTwoButtonNodes(), backend: 'xctest' } : {},
+  );
+
+  // Selector press: its resolution capture replaces the stored snapshot
+  // without handing the new refs back to the client.
+  const selectorPress = await runInteraction(sessionStore, sessionName, 'press', [
+    'label=Continue',
+  ]);
+  if (!selectorPress?.ok) {
+    throw new Error(`selector press failed: ${JSON.stringify(selectorPress)}`);
+  }
+  expect(selectorPress.data?.warning).toBeUndefined();
+  expect(sessionStore.get(sessionName)?.snapshotRefsStale).toBe(true);
+
+  const refPress = await runInteraction(sessionStore, sessionName, 'press', ['@e1']);
+  expect(refPress?.ok).toBe(true);
+  if (refPress?.ok) {
+    expect(refPress.data?.warning).toBe(STALE_SNAPSHOT_REFS_WARNING);
+  }
+});
+
+test('press @ref directly after refs were issued does not warn', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'fresh-ref-no-warning';
+  const session = makeStaleRefSession(sessionName);
+  sessionStore.set(sessionName, session);
+
+  const response = await runInteraction(sessionStore, sessionName, 'press', ['@e1']);
+  expect(response?.ok).toBe(true);
+  if (response?.ok) {
+    expect(response.data?.warning).toBeUndefined();
+  }
+});
+
+test('re-issuing refs clears the stale marker so press @ref does not warn', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'reissued-refs-no-warning';
+  const session = makeStaleRefSession(sessionName);
+  sessionStore.set(sessionName, session);
+  mockDispatch.mockImplementation(async (_device, command) =>
+    command === 'snapshot' ? { nodes: makeTwoButtonNodes(), backend: 'xctest' } : {},
+  );
+
+  const selectorPress = await runInteraction(sessionStore, sessionName, 'press', [
+    'label=Continue',
+  ]);
+  expect(selectorPress?.ok).toBe(true);
+  expect(sessionStore.get(sessionName)?.snapshotRefsStale).toBe(true);
+
+  // Simulate the snapshot command re-issuing refs (its handler clears the
+  // marker through buildNextSnapshotSession; covered in snapshot-handler tests).
+  const stored = sessionStore.get(sessionName)!;
+  stored.snapshotRefsStale = false;
+  sessionStore.set(sessionName, stored);
+
+  const refPress = await runInteraction(sessionStore, sessionName, 'press', ['@e1']);
+  expect(refPress?.ok).toBe(true);
+  if (refPress?.ok) {
+    expect(refPress.data?.warning).toBeUndefined();
+  }
+});
+
+test('fill @ref warns while refs are stale', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'stale-ref-fill';
+  const session = makeStaleRefSession(sessionName);
+  session.snapshot = {
+    nodes: attachRefs([
+      {
+        index: 0,
+        type: 'XCUIElementTypeTextField',
+        label: 'Email',
+        rect: { x: 10, y: 20, width: 200, height: 40 },
+        enabled: true,
+        hittable: true,
+      },
+    ]),
+    createdAt: Date.now(),
+    backend: 'xctest',
+  };
+  session.snapshotRefsStale = true;
+  sessionStore.set(sessionName, session);
+
+  const response = await runInteraction(sessionStore, sessionName, 'fill', [
+    '@e1',
+    'hello@example.com',
+  ]);
+  expect(response?.ok).toBe(true);
+  if (response?.ok) {
+    expect(response.data?.warning).toBe(STALE_SNAPSHOT_REFS_WARNING);
+  }
+});
+
+test('get text @ref warns while refs are stale', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'stale-ref-get-text';
+  const session = makeStaleRefSession(sessionName);
+  session.snapshotRefsStale = true;
+  sessionStore.set(sessionName, session);
+  mockDispatch.mockRejectedValue(
+    new Error('dispatch should not be called for snapshot-derived get text'),
+  );
+
+  const response = await runInteraction(sessionStore, sessionName, 'get', ['text', '@e1']);
+  expect(response?.ok).toBe(true);
+  if (response?.ok) {
+    expect(response.data?.warning).toBe(STALE_SNAPSHOT_REFS_WARNING);
+    expect(response.data?.ref).toBe('e1');
+  }
+});
+
+test('stale-ref warning appends to an existing interaction warning', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'stale-ref-appends';
+  const session = makeStaleRefSession(sessionName);
+  session.snapshot = {
+    nodes: attachRefs([
+      {
+        index: 0,
+        // Non-fillable type produces the runtime fill warning the stale-ref
+        // warning must append to, not replace.
+        type: 'XCUIElementTypeStaticText',
+        label: 'Read-only',
+        rect: { x: 10, y: 20, width: 200, height: 40 },
+        enabled: true,
+        hittable: true,
+      },
+    ]),
+    createdAt: Date.now(),
+    backend: 'xctest',
+  };
+  session.snapshotRefsStale = true;
+  sessionStore.set(sessionName, session);
+
+  const response = await runInteraction(sessionStore, sessionName, 'fill', ['@e1', 'nope']);
+  expect(response?.ok).toBe(true);
+  if (response?.ok) {
+    const warning = String(response.data?.warning ?? '');
+    expect(warning).toContain('attempting fill anyway');
+    expect(warning).toContain(STALE_SNAPSHOT_REFS_WARNING);
+    expect(warning.endsWith(STALE_SNAPSHOT_REFS_WARNING)).toBe(true);
+  }
+});

src/daemon/handlers/__tests__/snapshot-handler.test.ts

@@ -402,6 +402,54 @@ test('snapshot on iOS runs when the session tracks an app', async () => {
   );
 });
 
+test('snapshot clears the stale-refs marker; diff leaves client refs stale (#1076)', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-stale-refs-marker';
+  const session = makeSession(sessionName, androidDevice);
+  session.snapshot = {
+    nodes: [{ ref: 'e1', index: 0, depth: 0, type: 'android.widget.Button', label: 'Old' }],
+    createdAt: Date.now(),
+    backend: 'android',
+  };
+  // As set by a selector-resolution capture that replaced the stored tree.
+  session.snapshotRefsStale = true;
+  sessionStore.set(sessionName, session);
+  mockDispatch.mockResolvedValue({
+    nodes: [{ index: 0, depth: 0, type: 'android.widget.Button', label: 'Fresh' }],
+    truncated: false,
+    backend: 'android',
+  });
+
+  const snapshotResponse = await handleSnapshotCommands({
+    req: { token: 't', session: sessionName, command: 'snapshot', positionals: [], flags: {} },
+    sessionName,
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+  });
+
+  // The snapshot response hands every stored node's ref to the client.
+  expect(snapshotResponse?.ok).toBe(true);
+  expect(sessionStore.get(sessionName)?.snapshotRefsStale).toBe(false);
+
+  const diffResponse = await handleSnapshotCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'diff',
+      positionals: ['snapshot'],
+      flags: {},
+    },
+    sessionName,
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+  });
+
+  // diff replaces the stored tree but only returns a summary, so the refs the
+  // client holds go stale again.
+  expect(diffResponse?.ok).toBe(true);
+  expect(sessionStore.get(sessionName)?.snapshotRefsStale).toBe(true);
+});
+
 test('snapshot surfaces filtered-to-zero Android guidance for interactive snapshots', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'android-empty-interactive';

src/daemon/handlers/find.ts

@@ -23,6 +23,7 @@ import { errorResponse, noActiveSessionError } from './response.ts';
 import { recordSessionAction } from './handler-utils.ts';
 import { stripInternalInteractionFlags } from '../interaction-outcome-policy.ts';
 import { dispatchFindReadOnlyViaRuntime } from '../selector-runtime.ts';
+import { markSessionSnapshotRefsIssued } from '../session-snapshot.ts';
 import { createSelectorCaptureRuntime } from '../selector-capture-runtime.ts';
 import {
   isSparseSnapshotQualityVerdict,
@@ -156,6 +157,15 @@ export async function handleFindCommands(params: {
   const ref = `@${resolvedNode.ref}`;
   const actionFlags = { ...(req.flags ?? {}), noRecord: true };
   const match: ResolvedMatch = { node, resolvedNode, ref, nodes, actionFlags };
+  if (session) {
+    // #1076 clear choke point: every action below returns `match.ref`, minted
+    // from the snapshot the capture runtime just stored, so the client leaves
+    // with a ref that matches the stored tree. Clearing here also keeps the
+    // internal `click/fill @ref` sub-invocations from attaching a spurious
+    // stale-refs warning to the find response.
+    markSessionSnapshotRefsIssued(session);
+    sessionStore.set(sessionName, session);
+  }
 
   const actionHandlers: Record<string, () => Promise<DaemonResponse | null>> = {
     exists: () => handleFindExists(ctx),

src/daemon/handlers/interaction-touch-response.ts

@@ -5,6 +5,7 @@ import type {
   PressCommandResult,
 } from '../../contracts/interaction.ts';
 import { successText } from '../../utils/success-text.ts';
+import { STALE_SNAPSHOT_REFS_WARNING } from '../session-snapshot.ts';
 import { interactionResultExtra, stripAtPrefix } from './interaction-touch-targets.ts';
 
 /**
@@ -55,6 +56,13 @@ export function buildInteractionResponseData(params: {
    * button tags for click, selector/maestro details for the direct path.
    */
   extra?: Record<string, unknown>;
+  /**
+   * The command consumed an `@ref` argument while the session's stored
+   * snapshot had been replaced without re-issuing refs to the client
+   * (`session.snapshotRefsStale`, #1076). Appends
+   * STALE_SNAPSHOT_REFS_WARNING to the response warning.
+   */
+  staleRefs?: boolean;
 }): InteractionResponsePayloads {
   const { source, referenceFrame, extra } = params;
   if (source.kind === 'runner-payload') {
@@ -89,13 +97,27 @@ export function buildInteractionResponseData(params: {
           ...interactionResultExtra(result),
         }
       : visualization;
-  if ('warning' in result && result.warning) {
-    visualization.warning = result.warning;
-    responseData.warning = result.warning;
+  const warning = composeResponseWarning(
+    'warning' in result ? result.warning : undefined,
+    params.staleRefs,
+  );
+  if (warning) {
+    visualization.warning = warning;
+    responseData.warning = warning;
   }
   return { result: visualization, responseData };
 }
 
+function composeResponseWarning(
+  resultWarning: string | undefined,
+  staleRefs: boolean | undefined,
+): string | undefined {
+  if (staleRefs !== true) return resultWarning;
+  return resultWarning
+    ? `${resultWarning} ${STALE_SNAPSHOT_REFS_WARNING}`
+    : STALE_SNAPSHOT_REFS_WARNING;
+}
+
 function buildTouchVisualizationResult(params: {
   data: Record<string, unknown> | undefined;
   fallbackX?: number;