fix(#2682): disclose only the repair a request paid for

Adversarial review findings on #2693:

- A cache hit is not a repair. Selector reads may answer from the tree an earlier command stored
  (`reusableLastSnapshot`, `reusableSessionSnapshot`), and stamping the disclosure off that consumed
  tree told a command "the session app was not foreground when THIS command arrived" when it never
  looked. The repair now travels on its own per-request proof, filled only by a capture the request
  actually took, first fact wins; the #2438 surface disclosure keeps reading the consumed tree, which
  is what the response actually describes.
- The snapshot route read the stored snapshot unconditionally, including on a failure response. It now
  binds the fact to its own capture inside `execute`, so a snapshot that failed before capturing
  inherits nothing.
- Docs said a command that consumed no capture "stays silent", which reads as "no repair happened".
  That is ADR 0012's category wearing a disclaimer: the runner may well have activated and the
  interaction projection drops the stamp. The docs now say silence proves nothing and point at #2694.
- `sessions.md` still claimed iOS `appstate` worked; the appstate pointer, the `bundle_changed`
  definition, and the missing `missing_after_wait` / `interaction_foreground_guard` reasons are fixed,
  and the identity rename lands here too (`otherActiveApplicationPid`).

Author: thymikee

packages/kernel/src/snapshot.ts

@@ -445,14 +445,15 @@ export type IosTargetActivationPriorState = (typeof IOS_TARGET_ACTIVATION_PRIOR_
 /**
  * Foreground repair the Apple runner performed while serving one command (#2682). `priorState` is
  * the session app's state BEFORE the runner activated it, so the fact describes what was repaired
- * rather than what the repair produced. `foregroundPid` is present only when exactly one
- * application other than the session app had an active accessibility session at that moment: the
- * private AX client the runner reads resolves pids and answers no bundle id for an arbitrary app.
+ * rather than what the repair produced. `otherActiveApplicationPid` is present only when exactly one
+ * application other than the session app held an active accessibility session at that moment: a
+ * liveness claim and nothing more, since the private AX client reports no ordering of
+ * `activeApplications`, resolves pids only, and answers no bundle id for an arbitrary app.
  */
 export type IosTargetActivation = Readonly<{
   reason: IosTargetActivationReason;
   priorState: IosTargetActivationPriorState;
-  foregroundPid?: number;
+  otherActiveApplicationPid?: number;
 }>;
 
 export type SnapshotState = {

src/commands/capture/output.test.ts

@@ -2,6 +2,7 @@ import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import { attachRefs, type RawSnapshotNode } from '@agent-device/kernel/snapshot';
 import type { CaptureSnapshotResult } from '@agent-device/contracts/client';
+import { iosTargetActivationDisclosure } from '@agent-device/contracts/ios-target-activation';
 import { snapshotCliOutput } from './output.ts';
 
 function buildResult(raw: RawSnapshotNode[]): CaptureSnapshotResult {
@@ -101,21 +102,16 @@ test('snapshot output presents the materialized fallback screenshot path', async
  * never has to parse the sentence.
  */
 test('a repaired capture renders the disclosure and keeps the structured fact', async () => {
+  const fact = {
+    reason: 'stale_target',
+    priorState: 'runningBackground',
+    otherActiveApplicationPid: 4562,
+  } as const;
   const output = await snapshotCliOutput({
     result: {
       ...buildResult(REPEATED_CHAIN),
-      warnings: [
-        'The session app was not foreground when this command arrived (another app (pid 4562) held ' +
-          'it, prior state runningBackground), so the runner activated it before answering (reason ' +
-          'stale_target). Any capture taken earlier in this session described another app (pid 4562), ' +
-          'not the session app. Re-capture now that the session app answers, or drive the other app ' +
-          'in its own session.',
-      ],
-      targetActivation: {
-        reason: 'stale_target',
-        priorState: 'runningBackground',
-        foregroundPid: 4562,
-      },
+      warnings: [iosTargetActivationDisclosure(fact)],
+      targetActivation: fact,
     } as CaptureSnapshotResult,
   });
 
@@ -124,6 +120,6 @@ test('a repaired capture renders the disclosure and keeps the structured fact',
   assert.deepEqual((output.jsonData as { targetActivation?: unknown }).targetActivation, {
     reason: 'stale_target',
     priorState: 'runningBackground',
-    foregroundPid: 4562,
+    otherActiveApplicationPid: 4562,
   });
 });

src/daemon/__tests__/capture-disclosure-target-activation.test.ts

@@ -8,7 +8,7 @@ import type { DaemonResponse } from '../daemon-request.ts';
 const FACT: IosTargetActivation = {
   reason: 'stale_target',
   priorState: 'runningBackground',
-  foregroundPid: 4562,
+  otherActiveApplicationPid: 4562,
 };
 
 function okResponse(data: Record<string, unknown>): DaemonResponse {
@@ -63,15 +63,39 @@ test('a capture with no repair leaves the response byte-identical', () => {
   assert.deepEqual(response, untouched);
 });
 
+/**
+ * A failure carries the sentence in `error.details.hint`. That carrier is exactly where a route could
+ * cheaply borrow the previous command's repair off the stored snapshot and blame it on this request,
+ * so the repair travels only on the request's own proof (#2682).
+ */
+test('a failure does not borrow a repair the stored snapshot happens to carry', () => {
+  const failed: DaemonResponse = {
+    ok: false,
+    error: { code: 'COMMAND_FAILED', message: 'snapshot failed' } as never,
+  };
+
+  const response = withCaptureDisclosures({
+    response: failed,
+    consumedTree: { targetActivation: FACT },
+    activationProof: {},
+  });
+
+  assert.equal(response, failed);
+});
+
 /**
  * The two carriers are pre-existing: the surface disclosure extends `data.warning`, the capture's
  * own warnings arrive as `data.warnings` (#2438 predates the array). A response can therefore carry
  * both, and each disclosure must survive in the carrier it belongs to.
  */
 test('surface and foreground disclosures ride one response together', () => {
-  const response = withCaptureDisclosures(okResponse({ nodes: [] }), {
-    iosSystemSurfaceBundleId: 'com.apple.SafariViewService',
-    targetActivation: FACT,
+  const response = withCaptureDisclosures({
+    response: okResponse({ nodes: [] }),
+    consumedTree: {
+      iosSystemSurfaceBundleId: 'com.apple.SafariViewService',
+      targetActivation: FACT,
+    },
+    activationProof: { state: { targetActivation: FACT } },
   });
   const data = dataOf(response);
   assert.match(String(data.warning), /system web sign-in sheet/);

src/daemon/__tests__/selector-capture-runtime.test.ts

@@ -3,7 +3,10 @@ import type {
   CaptureSnapshotInput,
   SnapshotResult,
 } from '@agent-device/contracts/snapshot-runtime';
-import { buildSnapshotPresentationKey } from '@agent-device/kernel/snapshot';
+import { buildSnapshotPresentationKey, type SnapshotState } from '@agent-device/kernel/snapshot';
+import type { IosTargetActivation } from '@agent-device/contracts/ios-target-activation';
+import type { DaemonResponse } from '../daemon-request.ts';
+import { type RequestActivationProof, withCaptureDisclosures } from '../capture-disclosure.ts';
 import { makeIosSession } from '../../__tests__/test-utils/session-factories.ts';
 import { makeSessionStore } from '../../__tests__/test-utils/store-factory.ts';
 import { createSelectorCaptureRuntime } from '../selector-capture-runtime.ts';
@@ -191,6 +194,122 @@ test('sparse verdict recovery retries with query scope and stores recovered snap
   });
 });
 
+const REPAIR: IosTargetActivation = {
+  reason: 'stale_target',
+  priorState: 'runningBackground',
+  otherActiveApplicationPid: 4562,
+};
+
+function proofRuntime(params: {
+  sessionName: string;
+  storedSnapshot?: SnapshotState;
+  capturedTargetActivation?: IosTargetActivation;
+}) {
+  const sessionStore = makeSessionStore('agent-device-selector-capture-');
+  const session = makeIosSession(
+    params.sessionName,
+    params.storedSnapshot ? { snapshot: params.storedSnapshot } : {},
+  );
+  sessionStore.set(params.sessionName, session);
+  boundCapture.mockResolvedValue({
+    backend: 'xctest',
+    producer: 'apple-runner',
+    nodes: [{ index: 0, type: 'Button', label: 'Captured' }],
+    ...(params.capturedTargetActivation
+      ? { targetActivation: params.capturedTargetActivation }
+      : {}),
+  } as never);
+  const consumedSnapshot: { state?: SnapshotState } = {};
+  const activationProof: RequestActivationProof = {};
+  const runtime = createSelectorCaptureRuntime({
+    device: session.device,
+    session,
+    sessionStore,
+    sessionName: params.sessionName,
+    consumedSnapshot,
+    activationProof,
+    capture: boundCapture,
+    req: {
+      token: 't',
+      session: params.sessionName,
+      command: 'get',
+      positionals: [],
+      flags: {},
+    },
+  });
+  return { runtime, consumedSnapshot, activationProof };
+}
+
+/**
+ * A selector read answered from the tree an earlier command stored performed no device work, so it
+ * owns no foreground repair (#2682). The stored tree may still be disclosed as the surface the
+ * response describes (#2438); the repair sentence is a claim about THIS command and would be
+ * fabricated here.
+ */
+test('a session-snapshot cache hit consumes a repaired tree without earning the repair proof', async () => {
+  const holders = proofRuntime({
+    sessionName: 'selector-cache-hit-repair-proof',
+    storedSnapshot: {
+      createdAt: Date.now(),
+      presentationKey: buildSnapshotPresentationKey({}),
+      nodes: [{ ref: 'e1', index: 0, type: 'Button', label: 'Stored' }],
+      targetActivation: REPAIR,
+    },
+  });
+
+  await holders.runtime.capture({ flags: {}, cache: { useSessionSnapshot: true } });
+
+  expect(boundCapture).not.toHaveBeenCalled();
+  expect(holders.consumedSnapshot.state?.targetActivation).toEqual(REPAIR);
+  expect(holders.activationProof.state).toBeUndefined();
+
+  const response = withCaptureDisclosures({
+    response: { ok: true, data: { nodes: [] } } as DaemonResponse,
+    consumedTree: holders.consumedSnapshot.state,
+    activationProof: holders.activationProof,
+  });
+  expect(response.ok).toBe(true);
+  if (response.ok) {
+    expect(response.data?.targetActivation).toBeUndefined();
+    expect(response.data?.warnings).toBeUndefined();
+  }
+});
+
+test('a capture the request took itself earns the repair proof', async () => {
+  const holders = proofRuntime({
+    sessionName: 'selector-fresh-capture-repair-proof',
+    capturedTargetActivation: REPAIR,
+  });
+
+  await holders.runtime.capture({ flags: {}, cache: { useSessionSnapshot: true } });
+
+  expect(boundCapture).toHaveBeenCalledTimes(1);
+  expect(holders.activationProof.state?.targetActivation).toEqual(REPAIR);
+});
+
+/**
+ * A poll or a recovery re-capture inside one request can answer from an already-foreground app while
+ * an earlier capture in that same request reported the repair. The later fact-less tree must not
+ * erase the disclosure the request earned (#2682).
+ */
+test('a later fact-less capture does not erase an earlier repair proof', async () => {
+  const holders = proofRuntime({
+    sessionName: 'selector-second-capture-keeps-proof',
+    capturedTargetActivation: REPAIR,
+  });
+
+  await holders.runtime.capture({ flags: {}, cache: { forceFresh: true } });
+  boundCapture.mockResolvedValue({
+    backend: 'xctest',
+    producer: 'apple-runner',
+    nodes: [{ index: 0, type: 'Button', label: 'Quiet' }],
+  } as never);
+  await holders.runtime.capture({ flags: {}, cache: { forceFresh: true } });
+
+  expect(boundCapture).toHaveBeenCalledTimes(2);
+  expect(holders.activationProof.state?.targetActivation).toEqual(REPAIR);
+});
+
 function makeCaptureRuntime(sessionName: string) {
   const sessionStore = makeSessionStore('agent-device-selector-capture-');
   const session = makeIosSession(sessionName);

src/daemon/__tests__/snapshot-runtime-target-activation.test.ts

@@ -0,0 +1,80 @@
+import path from 'node:path';
+import { beforeEach, expect, test, vi } from 'vitest';
+import { iosTargetActivationDisclosure } from '@agent-device/contracts/ios-target-activation';
+import type { IosTargetActivation } from '@agent-device/kernel/snapshot';
+import { makeIosSession } from '../../__tests__/test-utils/session-factories.ts';
+import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
+import { SessionStore } from '../session-store.ts';
+import { handleSnapshotCommands } from '../handlers/snapshot.ts';
+import { legacyDispatchCapture } from './legacy-snapshot-capture-fixture.ts';
+import { snapshotRuntimeFixture } from './snapshot-runtime-fixture.ts';
+
+vi.mock('../snapshot-interactor-capture.ts', async () => {
+  const fixture = await import('./legacy-snapshot-capture-fixture.ts');
+  return { captureSnapshotWithInteractor: fixture.captureSnapshotThroughLegacyDispatchFixture };
+});
+
+const REPAIR: IosTargetActivation = {
+  reason: 'stale_target',
+  priorState: 'runningBackground',
+  otherActiveApplicationPid: 4562,
+};
+
+beforeEach(() => {
+  legacyDispatchCapture.mockReset();
+});
+
+test('a snapshot that captured a repaired tree discloses the repair it paid for', async () => {
+  const input = scenario({});
+  legacyDispatchCapture.mockResolvedValue({
+    backend: 'xctest',
+    truncated: false,
+    targetActivation: REPAIR,
+    nodes: [
+      {
+        index: 0,
+        depth: 0,
+        type: 'Button',
+        label: 'Continue',
+        rect: { x: 0, y: 0, width: 100, height: 44 },
+        hittable: true,
+      },
+    ],
+  });
+
+  const response = await dispatchSnapshot(input);
+
+  expect(response.ok).toBe(true);
+  if (response.ok) {
+    expect(response.data?.targetActivation).toEqual(REPAIR);
+    expect(response.data?.warnings).toContain(iosTargetActivationDisclosure(REPAIR));
+  }
+});
+
+function scenario(params: { storedRepair?: boolean }) {
+  const root = mkdtempForTestSync('agent-device-snapshot-target-activation');
+  const sessionName = 'default';
+  const sessionStore = new SessionStore(path.join(root, 'sessions'));
+  const session = makeIosSession(sessionName, { appBundleId: 'com.example.app' });
+  if (params.storedRepair) {
+    session.snapshot = {
+      createdAt: Date.now(),
+      nodes: [{ ref: 'e1', index: 0, type: 'Button', label: 'Earlier' }],
+      targetActivation: REPAIR,
+    };
+  }
+  sessionStore.set(sessionName, session);
+  return { sessionStore, sessionName, logPath: path.join(root, 'daemon.log') };
+}
+
+async function dispatchSnapshot(input: ReturnType<typeof scenario>) {
+  const response = await handleSnapshotCommands({
+    req: { command: 'snapshot', positionals: [], token: 't', session: input.sessionName },
+    sessionName: input.sessionName,
+    logPath: input.logPath,
+    sessionStore: input.sessionStore,
+    ...snapshotRuntimeFixture(),
+  });
+  if (!response) throw new Error('snapshot route did not answer');
+  return response;
+}

src/daemon/capture-disclosure.ts

@@ -10,6 +10,20 @@ export type CaptureProvenance = Pick<
   'systemSurfaceOnly' | 'iosSystemSurfaceBundleId' | 'targetActivation'
 >;
 
+/**
+ * The foreground repair THIS request paid for, filled by the capture path only when the request
+ * actually captured a tree (#2682).
+ *
+ * Separate from the consumed tree on purpose. A selector read may answer from a cached or stored
+ * tree — that tree still describes the surface the response is about, which is what #2438 discloses
+ * — but a cache hit performed no device work, so it can own no repair. Stamping the repair off the
+ * consumed tree would tell a command "you found the session app out of foreground" when it never
+ * looked, which is a fabricated observation rather than a disclosure.
+ */
+export type RequestActivationProof = {
+  state?: CaptureProvenance;
+};
+
 /**
  * Append the occluding-system-surface disclosure to a selector-route response whose consumed
  * snapshot was a system surface: an Android notification shade / quick settings, or an iOS in-place
@@ -51,12 +65,22 @@ export function withTargetActivationDisclosure(
   return { ...response, data };
 }
 
-/** Every capture-provenance disclosure a consumed tree owes its response (#2438, #2682). */
-export function withCaptureDisclosures(
-  response: DaemonResponse,
-  snapshot: CaptureProvenance | undefined,
-): DaemonResponse {
-  return withTargetActivationDisclosure(withSystemSurfaceDisclosure(response, snapshot), snapshot);
+/**
+ * Every capture-provenance disclosure a response owes, from the two different things a capture can
+ * prove: what the answered tree describes (#2438 — cache tiers included, because the surface is
+ * still on screen) and what this request's own capture found (#2682 — cache hits excluded, because
+ * a request that captured nothing repaired nothing).
+ */
+export function withCaptureDisclosures(params: {
+  response: DaemonResponse;
+  consumedTree: CaptureProvenance | undefined;
+  activationProof?: RequestActivationProof;
+}): DaemonResponse {
+  const { response, consumedTree, activationProof } = params;
+  return withTargetActivationDisclosure(
+    withSystemSurfaceDisclosure(response, consumedTree),
+    activationProof?.state,
+  );
 }
 
 function responseWarnings(value: unknown): string[] {

src/daemon/interaction/internal/__tests__/interaction-target-activation-disclosure.test.ts

@@ -12,7 +12,7 @@ import { contextFromFlags, makeSession } from './interaction-touch-fixtures.ts';
 const FACT: IosTargetActivation = {
   reason: 'stale_target',
   priorState: 'runningBackground',
-  foregroundPid: 4562,
+  otherActiveApplicationPid: 4562,
 };
 
 function capturedTree(params: {