fix(daemon): print ambiguity candidates only when they can be issued (ADR 0014)

The review's P1: updateSessionSnapshot deliberately skips storing a
sparse-quality capture, so candidates minted from that tree were issued
against the PREVIOUS stored tree's generation -- the same wrong-node
bind the issuance rule exists to prevent, arriving through the sparse
path. issueSettleRefs already carries the opposite ruling beside the
same primitive: what was not stored issues nothing. The second
implementation of the rule had dropped that guard.

Printing and issuing become one decision at the rule, keyed on the
typed fact the surfaces already read: the candidate bodies may only be
authorized when the capture the failing request consumed IS the tree
the session stores under the generation being frozen (node identity --
the command layer stores an annotation copy of the same array). A
sparse/unstored capture, a retired or sessionless ref, or a session
with no generation now degrades to the count-only refusal: truthful
matches count, no candidate refs, and a hint that cannot advertise an
affordance the frame could not honor. An advertised-but-unusable ref is
worse than no list.

Both consumer seams hand the rule the capture their request consumed:
the selector routes pass the capture runtime's consumedSnapshot slot
through toDaemonResponse's issuance parameter, and the touch runtime
owns a per-dispatch consumedCapture slot filled where its own captures
land. Runner-native refusals (direct iOS) carry no candidate shape and
pass through untouched.

The unit door previously over-claimed a sessionless assertion it never
made; it now pins retired-ref, sessionless, no-generation, and
unstored-capture refusals separately, and the reviewer's end-to-end
sequence gains its sparse twin. commands.md scopes the predicate claim
to the uniqueness rows (exists/absent never resolve one element) and
documents the count-only form.

Author: thymikee

src/daemon/__tests__/selector-runtime-ambiguity-issuance.test.ts

@@ -174,3 +174,62 @@ test('a plain candidate ref from the ambiguity refusal is refused, not silently
   }
   expect(mockTapPoint).not.toHaveBeenCalled();
 });
+
+/**
+ * The P1 the review caught (cubic + coordinator): the capture runtime
+ * DELIBERATELY does not store a sparse-quality capture
+ * (`selector-capture-runtime.ts` `updateSessionSnapshot`: sparse verdicts skip
+ * the store, exactly as `issueSettleRefs` documents for the settle path). So
+ * candidates minted from that never-stored tree cannot be issued against the
+ * PREVIOUS stored tree's generation — a printed `@ref` would resolve against
+ * the older tree, the same wrong-node bind this rule exists to prevent.
+ * Printing and issuing are ONE decision: when the consumed capture was not
+ * stored, the refusal keeps its truthful count and prints no candidate refs.
+ */
+test('an ambiguous is on a sparse capture prints no candidates and issues nothing', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'is-ambiguity-sparse';
+  // A stored frame from an earlier command, as in the reviewer's sequence.
+  const session = makeStaleRefSession(sessionName);
+  session.device = IOS_SIMULATOR;
+  sessionStore.publish(sessionName, session);
+  const storedNodes = session.snapshot!.nodes;
+
+  // The ambiguous two-button tree, but delivered with a SPARSE quality
+  // verdict: the capture runtime refuses to store it, so the session keeps
+  // describing the older tree. `is` itself does not gate on the verdict; the
+  // readUnique door is reached on this tree. (The verdict's `backend` is the
+  // acquisition backend vocabulary, not the producer.)
+  const sparseCapture = () => ({
+    ...ambiguousFullCapture(),
+    quality: {
+      state: 'sparse' as const,
+      backend: 'tree' as const,
+      reasonCode: 'sparse-tree' as const,
+    },
+  });
+  const fixture = selectorCaptureFixture({ snapshot: sparseCapture });
+  const response = await dispatchIsViaRuntime({
+    req: isRequest(sessionName, ['visible', 'label="Deploy"']),
+    sessionName,
+    sessionStore,
+    inspectFacts: fixture.inspectFacts,
+    bindDevice: fixture.bindDevice,
+  });
+
+  expect(response?.ok).toBe(false);
+  if (!response || response.ok) throw new Error('expected the ambiguity refusal');
+  // Still the truth: two nodes matched and the read refuses to choose.
+  expect(response.error.code).toBe('AMBIGUOUS_MATCH');
+  expect(response.error.details?.matches).toBe(2);
+  // But nothing issuable, so nothing printable: no candidate refs, no epoch,
+  // and no hint advertising an affordance the frame cannot honor.
+  expect(response.error.details?.candidates).toBeUndefined();
+  expect(response.error.details?.refsGeneration).toBeUndefined();
+  expect(String(response.error.details?.hint)).not.toMatch(/printed candidate/);
+  // The store still describes the tree it did — the sparse capture replaced
+  // nothing — and the pre-existing complete frame from the earlier snapshot
+  // was left alone rather than reissued over a tree that was never stored.
+  expect(session.snapshot!.nodes).toBe(storedNodes);
+  expect(refFrameScope(session)).toBe('all');
+});

src/daemon/__tests__/session-snapshot.test.ts

@@ -262,12 +262,14 @@ for (const retire of [false, true]) {
 }
 
 // #2870 review: every response that prints candidate @refs must issue those
-// refs on the frame they came from. One rule, consumed by the acting refusal
+// refs on the frame they came from, and issuance is only valid against the
+// tree that generation describes. One rule, consumed by the acting refusal
 // (touch runtime) and the strict-read refusals (is / get attrs dispatch).
 test('ambiguous refusals issue their printed candidates as a partial frame', () => {
   const store = makeSessionStore();
   const session = makeSession();
-  setSessionSnapshot(session, makeSnapshot());
+  const captured = makeSnapshot();
+  setSessionSnapshot(session, captured);
   const ref = store.publish('cwd:ambiguity:default', session);
   const published = publishAmbiguousMatchCandidateRefs(
     ref,
@@ -276,28 +278,78 @@ test('ambiguous refusals issue their printed candidates as a partial frame', ()
       matches: 4,
       candidates: ['@e2 [text] "Team Standup"', '@e5 [button] "Team Standup"'],
     }),
+    // The consumed capture IS the stored tree: what the capture runtime does
+    // for every non-sparse read, node identity included.
+    captured,
   );
   expect(published.details?.refsGeneration).toBe(session.snapshotGeneration);
   expect(refFrameScope(session)).toEqual(new Set(['e2', 'e5']));
 });
 
-test('a non-ambiguity read refusal issues nothing', () => {
+/**
+ * The P1 the review caught: the capture runtime DELIBERATELY does not store a
+ * sparse-quality capture (`updateSessionSnapshot` skips it, and `issueSettleRefs`
+ * documents the same ruling for the settle path), so candidates minted from
+ * that tree cannot be issued against the PREVIOUS stored tree's generation —
+ * a printed @ref would resolve to a different node. Printing and issuing are
+ * one decision: no stored tree, no printed candidates, and the hint drops the
+ * "act on a printed candidate" route it could not honor.
+ */
+test('a sparse capture that was never stored issues nothing and prints no candidates', () => {
   const store = makeSessionStore();
   const session = makeSession();
   setSessionSnapshot(session, makeSnapshot());
+  const ref = store.publish('cwd:ambiguity-sparse:default', session);
+  const storedNodes = session.snapshot!.nodes;
+  // The sparse capture the failing request consumed: a different tree, never
+  // stored (that skip is the capture runtime's deliberate quality ruling).
+  const sparseCapture: SnapshotState = {
+    nodes: [],
+    createdAt: Date.now(),
+    backend: 'xctest',
+    snapshotQuality: { state: 'sparse', backend: 'tree', reasonCode: 'sparse-tree' },
+  };
+  const published = publishAmbiguousMatchCandidateRefs(
+    ref,
+    store,
+    new AppError('AMBIGUOUS_MATCH', 'Selector matched 2 elements', {
+      matches: 2,
+      candidates: ['@e2 [text] "a"', '@e3 [text] "b"'],
+      hint: 'Narrow the selector with role/id/longer text, or act on a printed candidate with a command that takes refs, such as press.',
+    }),
+    sparseCapture,
+  );
+  expect(published.code).toBe('AMBIGUOUS_MATCH');
+  expect(published.details?.refsGeneration).toBeUndefined();
+  expect(published.details?.candidates).toBeUndefined();
+  // The truthful count survives; the unusable affordance does not.
+  expect(published.details?.matches).toBe(2);
+  expect(String(published.details?.hint)).not.toMatch(/printed candidate/);
+  // Nothing was issued: the frame stays untouched and the stored tree was
+  // never replaced by the sparse capture.
+  expect(session.refFrame).toBeUndefined();
+  expect(session.snapshot!.nodes).toBe(storedNodes);
+});
+
+test('a non-ambiguity read refusal issues nothing', () => {
+  const store = makeSessionStore();
+  const session = makeSession();
+  const captured = makeSnapshot();
+  setSessionSnapshot(session, captured);
   const ref = store.publish('cwd:ambiguity-none:default', session);
   const original = new AppError('COMMAND_FAILED', 'Selector did not match: label="X"');
-  const returned = publishAmbiguousMatchCandidateRefs(ref, store, original);
+  const returned = publishAmbiguousMatchCandidateRefs(ref, store, original, captured);
   expect(returned).toBe(original);
   // The ref-frame accessor defaults a never-issued frame to PRISTINE; the
   // raw slot staying unset is what "untouched" means here.
   expect(session.refFrame).toBeUndefined();
 });
 
-test('ambiguity without a live session ref (retired or sessionless route) issues nothing', () => {
+test('ambiguity on a retired session ref issues nothing and prints no candidates', () => {
   const store = makeSessionStore();
   const session = makeSession();
-  setSessionSnapshot(session, makeSnapshot());
+  const captured = makeSnapshot();
+  setSessionSnapshot(session, captured);
   const ref = store.publish('cwd:ambiguity-retired:default', session);
   store.retire(ref);
   const published = publishAmbiguousMatchCandidateRefs(
@@ -307,7 +359,57 @@ test('ambiguity without a live session ref (retired or sessionless route) issues
       matches: 2,
       candidates: ['@e2 [text] "a"', '@e3 [text] "b"'],
     }),
+    captured,
+  );
+  expect(published.details?.refsGeneration).toBeUndefined();
+  expect(published.details?.candidates).toBeUndefined();
+  expect(published.details?.matches).toBe(2);
+  expect(session.refFrame).toBeUndefined();
+});
+
+/**
+ * The sessionless shape `is` can travel (a selector route whose `lookup` found
+ * no live ref): with no session there is no generation to freeze and no frame
+ * to authorize, so the refusal must degrade to the count-only form too rather
+ * than print refs nobody can act on.
+ */
+test('ambiguity without a session ref (sessionless route) issues nothing and prints no candidates', () => {
+  const store = makeSessionStore();
+  const published = publishAmbiguousMatchCandidateRefs(
+    undefined,
+    store,
+    new AppError('AMBIGUOUS_MATCH', 'Selector matched 2 elements', {
+      matches: 2,
+      candidates: ['@e2 [text] "a"', '@e3 [text] "b"'],
+    }),
+    makeSnapshot(),
+  );
+  expect(published.code).toBe('AMBIGUOUS_MATCH');
+  expect(published.details?.refsGeneration).toBeUndefined();
+  expect(published.details?.candidates).toBeUndefined();
+  expect(published.details?.matches).toBe(2);
+});
+
+/**
+ * A session whose lifetime never stored a tree has no generation to freeze
+ * (both `setSessionSnapshot` and every capture runtime mint it on the first
+ * store). Same rule as the sparse case: nothing issuable, nothing printable.
+ */
+test('ambiguity on a session with no stored snapshot issues nothing and prints no candidates', () => {
+  const store = makeSessionStore();
+  const session = makeSession();
+  const ref = store.publish('cwd:ambiguity-nogen:default', session);
+  const published = publishAmbiguousMatchCandidateRefs(
+    ref,
+    store,
+    new AppError('AMBIGUOUS_MATCH', 'Selector matched 2 elements', {
+      matches: 2,
+      candidates: ['@e2 [text] "a"', '@e3 [text] "b"'],
+    }),
+    makeSnapshot(),
   );
   expect(published.details?.refsGeneration).toBeUndefined();
+  expect(published.details?.candidates).toBeUndefined();
+  expect(published.details?.matches).toBe(2);
   expect(session.refFrame).toBeUndefined();
 });

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

@@ -8,7 +8,7 @@ import type {
 } from '../../../backend.ts';
 import { createCommandSurfaceAgentDevice } from '../../../command-runtime/runtime-command-surface.ts';
 import { getRequestSignal } from '@agent-device/host-kit/request';
-import type { Rect } from '@agent-device/kernel/snapshot';
+import type { Rect, SnapshotState } from '@agent-device/kernel/snapshot';
 import type { DaemonCommandContext } from '../../context.ts';
 import { createDaemonRuntimePolicy } from '../../runtime-policy.ts';
 import { buildAppleRunnerRequestOptions } from '../../apple-runner-options.ts';
@@ -40,6 +40,14 @@ export function createInteractionRuntimeForRoute(
     pairedGestureViewport?: Rect;
     touchExecutor?: BoundTouchExecutor;
     gestures?: BoundGestureExecutor;
+    /**
+     * Filled with the LAST capture this request consumed. ADR 0014 ambiguity
+     * issuance is only valid against a tree the session stored under the
+     * generation it freezes, and a sparse-quality capture deliberately stores
+     * nothing — the refusal seam needs the same consumed-capture slot the
+     * selector routes carry (`consumedSnapshot`), owned per dispatch.
+     */
+    consumedCapture?: { state?: SnapshotState };
   },
 ) {
   const ref = bindInteractionSession(params).sessionRef;
@@ -58,6 +66,7 @@ export function createInteractionRuntimeForRoute(
         params.contextFromFlags,
         options,
       );
+      if (params.consumedCapture) params.consumedCapture.state = snapshot;
       return recordCaptureProof(params.captureProof, snapshot);
     },
     runtimeSessions: createDaemonRuntimeSessionStore({

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

@@ -7,6 +7,7 @@ import type {
   ResolvedInteractionTarget,
 } from '@agent-device/contracts/interaction';
 import type { GestureReferenceFrame } from '@agent-device/contracts/scroll-gesture';
+import type { SnapshotState } from '@agent-device/kernel/snapshot';
 import { asAppError, normalizeError } from '@agent-device/kernel/errors';
 import { readResolvedInteractionTarget } from '../../../core/interaction-outcome.ts';
 import { publishAmbiguousMatchCandidateRefs } from '../../session-snapshot.ts';
@@ -70,9 +71,11 @@ export async function dispatchRuntimeInteraction<
   params = bindInteractionSession(params);
   if (!params.sessionRef) return noActiveSessionError();
   const session = params.sessionStore.requireCurrent(params.sessionRef);
+  const consumedCapture: { state?: SnapshotState } = {};
   const runtime = createInteractionRuntimeForRoute({
     ...params,
     touchExecutor: options.touchExecutor,
+    consumedCapture,
   });
   const actionStartedAt = Date.now();
   try {
@@ -124,6 +127,7 @@ export async function dispatchRuntimeInteraction<
       params.sessionRef,
       params.sessionStore,
       asAppError(error),
+      consumedCapture.state,
     );
     if (isAndroidEscapeError(appError)) throw appError;
     if (appError.code === 'AMBIGUOUS_MATCH') return appErrorResponse(appError);

src/daemon/selector-runtime.ts

@@ -1,5 +1,5 @@
 import { asAppError } from '@agent-device/kernel/errors';
-import type { SnapshotNode } from '@agent-device/kernel/snapshot';
+import type { SnapshotNode, SnapshotState } from '@agent-device/kernel/snapshot';
 import { absenceCaptureOptionError } from '@agent-device/selectors/absence-observation-errors';
 import { absenceCaptureOptionRefusal } from '@agent-device/selectors/absence-observation';
 import type { DaemonRequest, DaemonResponse } from './daemon-request.ts';
@@ -186,7 +186,11 @@ export async function dispatchGetViaRuntime(
       const data = toDaemonGetData(result);
       return staleRefsWarning ? { ...data, warning: staleRefsWarning } : data;
     },
-    { ref: resolvedRuntime.ref, sessionStore: params.sessionStore },
+    {
+      ref: resolvedRuntime.ref,
+      sessionStore: params.sessionStore,
+      consumed: params.consumedSnapshot,
+    },
   );
   return withCaptureDisclosures({
     response,
@@ -255,7 +259,11 @@ export async function dispatchIsViaRuntime(
       );
       return stripSelectorChain(strippedResult);
     },
-    { ref: resolvedRuntime.ref, sessionStore: params.sessionStore },
+    {
+      ref: resolvedRuntime.ref,
+      sessionStore: params.sessionStore,
+      consumed: params.consumedSnapshot,
+    },
   );
   return withCaptureDisclosures({
     response: await maybeAndroidForegroundBlockerResponse(params, response, `is ${predicate}`),
@@ -312,18 +320,30 @@ function parseGetTarget(req: DaemonRequest):
  * `get attrs`): ADR 0014's ambiguity-issuance rule then runs before flattening,
  * so a printed candidate is admitted on the frame that listed it — the same
  * contract the acting refusal gets through the touch runtime (#2870 review).
+ * `consumed` is the capture runtime's slot for the tree THIS request consumed:
+ * issuance is only valid against a capture the session actually stored under
+ * that generation, and a sparse-quality capture deliberately stores nothing.
  * Routes that never print candidates (`wait`, read-only `find`) pass nothing
  * and keep the plain flatten.
  */
 export async function toDaemonResponse(
   task: () => Promise<Record<string, unknown>>,
-  issuance?: { ref: SessionRef | undefined; sessionStore: SessionStore },
+  issuance?: {
+    ref: SessionRef | undefined;
+    sessionStore: SessionStore;
+    consumed: { state?: SnapshotState } | undefined;
+  },
 ): Promise<DaemonResponse> {
   try {
     return { ok: true, data: await task() };
   } catch (error) {
     const appError = issuance
-      ? publishAmbiguousMatchCandidateRefs(issuance.ref, issuance.sessionStore, asAppError(error))
+      ? publishAmbiguousMatchCandidateRefs(
+          issuance.ref,
+          issuance.sessionStore,
+          asAppError(error),
+          issuance.consumed?.state,
+        )
       : asAppError(error);
     return errorResponse(appError.code, appError.message, appError.details);
   }