fix(snapshot): one-shot recovered warning for internally armed penalties

The deferred-capture suppression assumed the capture that armed the
XCTest-channel penalty already rendered the full 'overly complex or slow
accessibility tree' warning. Internal captures (selector resolution,
settle observation loops, system-modal probes) can arm the penalty
without any user-facing render, leaving the next public snapshot with
only the structured verdict and no CLI warning line.

The runner cannot tell user-facing from internal captures, so the daemon
now holds a per-session one-shot latch (snapshot-quality-latch.ts)
applied at the snapshot/diff response seam: a genuine recovered render
sets it silently, the first public 'deferred' verdict without the latch
re-renders the full warning once and sets it, a healthy public verdict
clears it (the penalty window is over), and an app switch supersedes it.
Internal observation responses (observationOnly) neither consume nor
clear the latch.

Follow-up to PR #1587 review (non-blocking hardening).

Author: thymikee

src/daemon/__tests__/snapshot-quality-latch.test.ts

@@ -0,0 +1,248 @@
+import os from 'node:os';
+import path from 'node:path';
+import { expect, test, vi } from 'vitest';
+import type { SnapshotQualityVerdict } from '@agent-device/kernel/snapshot';
+import { makeIosSession } from '../../__tests__/test-utils/session-factories.ts';
+import {
+  recoveredSnapshotQualityWarning,
+  renderSnapshotQualityWarnings,
+} from '../../snapshot/snapshot-quality.ts';
+import {
+  applyRecoveredWarningLatch,
+  resolveRecoveredWarningLatch,
+} from '../snapshot-quality-latch.ts';
+import { dispatchSnapshotViaRuntime } from '../snapshot-runtime.ts';
+import { SessionStore } from '../session-store.ts';
+import type { SessionState } from '../types.ts';
+
+const dispatchCommandMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../../core/dispatch.ts', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../core/dispatch.ts')>();
+  return {
+    ...actual,
+    dispatchCommand: dispatchCommandMock,
+  };
+});
+
+const FULL_WARNING = recoveredSnapshotQualityWarning('private-ax');
+
+function deferredVerdict(): SnapshotQualityVerdict {
+  return {
+    state: 'recovered',
+    backend: 'private-ax',
+    reason: 'XCTest-backed snapshot tiers were deferred after recent slow accessibility work',
+    reasonCode: 'deferred',
+  };
+}
+
+function genuineRecoveredVerdict(): SnapshotQualityVerdict {
+  return {
+    state: 'recovered',
+    backend: 'private-ax',
+    reason: 'iOS XCTest snapshot failed while serializing the accessibility tree',
+    reasonCode: 'ax-rejected',
+  };
+}
+
+test('the injected warning is the exact line a genuine recovery renders', () => {
+  // The latch exists to restore the warning an internal arming capture never rendered;
+  // wording drift between the two paths would defeat one-shot deduplication.
+  expect(renderSnapshotQualityWarnings(genuineRecoveredVerdict(), [])).toEqual([FULL_WARNING]);
+});
+
+test('resolveRecoveredWarningLatch transitions', () => {
+  const app = 'com.example.app';
+
+  // First deferred verdict with no latch held: inject once and hold the latch.
+  const first = resolveRecoveredWarningLatch({
+    verdict: deferredVerdict(),
+    appBundleId: app,
+    latch: undefined,
+  });
+  expect(first.warning).toBe(FULL_WARNING);
+  expect(first.latch).toEqual({ appBundleId: app });
+
+  // Held latch: further deferred verdicts stay quiet.
+  const repeat = resolveRecoveredWarningLatch({
+    verdict: deferredVerdict(),
+    appBundleId: app,
+    latch: first.latch,
+  });
+  expect(repeat.warning).toBeUndefined();
+  expect(repeat.latch).toEqual({ appBundleId: app });
+
+  // A genuine recovery renders through the runtime, so it sets the latch silently.
+  const genuine = resolveRecoveredWarningLatch({
+    verdict: genuineRecoveredVerdict(),
+    appBundleId: app,
+    latch: undefined,
+  });
+  expect(genuine.warning).toBeUndefined();
+  expect(genuine.latch).toEqual({ appBundleId: app });
+
+  // Healthy ends the penalty window; the next arming warns again.
+  const healthy = resolveRecoveredWarningLatch({
+    verdict: { state: 'healthy', backend: 'tree' },
+    appBundleId: app,
+    latch: first.latch,
+  });
+  expect(healthy.latch).toBeUndefined();
+
+  // Sparse and verdict-less captures carry no penalty signal either way.
+  const sparse = resolveRecoveredWarningLatch({
+    verdict: { state: 'sparse', backend: 'private-ax' },
+    appBundleId: app,
+    latch: first.latch,
+  });
+  expect(sparse.warning).toBeUndefined();
+  expect(sparse.latch).toEqual({ appBundleId: app });
+  const absent = resolveRecoveredWarningLatch({
+    verdict: undefined,
+    appBundleId: app,
+    latch: first.latch,
+  });
+  expect(absent.warning).toBeUndefined();
+  expect(absent.latch).toEqual({ appBundleId: app });
+
+  // The runner clears its penalty on app switch, so a latch held for another
+  // app never suppresses the new app's first deferred verdict.
+  const switched = resolveRecoveredWarningLatch({
+    verdict: deferredVerdict(),
+    appBundleId: 'com.example.other',
+    latch: first.latch,
+  });
+  expect(switched.warning).toBe(FULL_WARNING);
+  expect(switched.latch).toEqual({ appBundleId: 'com.example.other' });
+});
+
+test('internal observation responses neither consume nor clear the latch', () => {
+  const session = makeIosSession('default', { appBundleId: 'com.example.app' });
+
+  const internal = applyRecoveredWarningLatch({
+    session,
+    data: { snapshotQuality: deferredVerdict() },
+    internalObservation: true,
+  });
+  expect(internal.warnings).toBeUndefined();
+  expect(session.recoveredSnapshotWarningLatch).toBeUndefined();
+
+  session.recoveredSnapshotWarningLatch = { appBundleId: 'com.example.app' };
+  applyRecoveredWarningLatch({
+    session,
+    data: { snapshotQuality: { state: 'healthy', backend: 'tree' } },
+    internalObservation: true,
+  });
+  expect(session.recoveredSnapshotWarningLatch).toEqual({ appBundleId: 'com.example.app' });
+});
+
+test('sessionless responses pass through unchanged', () => {
+  const data = { snapshotQuality: deferredVerdict() };
+  expect(
+    applyRecoveredWarningLatch({ session: undefined, data, internalObservation: false }),
+  ).toBe(data);
+});
+
+function scenario() {
+  const root = path.join(os.tmpdir(), `agent-device-quality-latch-${crypto.randomUUID()}`);
+  const sessionStore = new SessionStore(path.join(root, 'sessions'));
+  const sessionName = 'default';
+  const session = makeIosSession(sessionName, { appBundleId: 'com.example.app' });
+  sessionStore.set(sessionName, session);
+  return { sessionStore, sessionName, logPath: path.join(root, 'daemon.log') };
+}
+
+function seedCapture(verdict: SnapshotQualityVerdict) {
+  dispatchCommandMock.mockResolvedValue({
+    backend: 'xctest',
+    truncated: false,
+    quality: verdict,
+    nodes: [
+      {
+        index: 0,
+        depth: 0,
+        type: 'Button',
+        label: 'Continue',
+        rect: { x: 0, y: 0, width: 100, height: 44 },
+        hittable: true,
+      },
+    ],
+  });
+}
+
+async function dispatchPublicSnapshot(input: ReturnType<typeof scenario>) {
+  return await dispatchSnapshotViaRuntime({
+    req: { command: 'snapshot', positionals: [], token: 't', session: input.sessionName },
+    sessionName: input.sessionName,
+    logPath: input.logPath,
+    sessionStore: input.sessionStore,
+  });
+}
+
+function responseWarnings(response: Awaited<ReturnType<typeof dispatchSnapshotViaRuntime>>) {
+  if (!response.ok) throw new Error('expected ok response');
+  return (response.data?.warnings ?? []) as string[];
+}
+
+function storedLatch(input: ReturnType<typeof scenario>): SessionState['recoveredSnapshotWarningLatch'] {
+  return input.sessionStore.get(input.sessionName)?.recoveredSnapshotWarningLatch;
+}
+
+test('an internally armed penalty warns once on the first public deferred snapshot', async () => {
+  const input = scenario();
+  seedCapture(deferredVerdict());
+
+  // The internal capture that armed the penalty (settle observation, selector
+  // resolution) rendered nothing; without the latch the deferred suppression
+  // would hide the warning from the user entirely.
+  const internal = await dispatchSnapshotViaRuntime({
+    req: {
+      command: 'snapshot',
+      positionals: [],
+      token: 't',
+      session: input.sessionName,
+      internal: { observationOnly: true },
+    },
+    sessionName: input.sessionName,
+    logPath: input.logPath,
+    sessionStore: input.sessionStore,
+  });
+  expect(responseWarnings(internal)).not.toContain(FULL_WARNING);
+  expect(storedLatch(input)).toBeUndefined();
+
+  const first = await dispatchPublicSnapshot(input);
+  expect(responseWarnings(first).filter((line) => line === FULL_WARNING)).toHaveLength(1);
+  expect(storedLatch(input)).toEqual({ appBundleId: 'com.example.app' });
+
+  const second = await dispatchPublicSnapshot(input);
+  expect(responseWarnings(second)).not.toContain(FULL_WARNING);
+});
+
+test('a healthy public capture re-arms the one-shot warning', async () => {
+  const input = scenario();
+  seedCapture(deferredVerdict());
+  await dispatchPublicSnapshot(input);
+  expect(storedLatch(input)).toEqual({ appBundleId: 'com.example.app' });
+
+  seedCapture({ state: 'healthy', backend: 'tree' });
+  const healthy = await dispatchPublicSnapshot(input);
+  expect(responseWarnings(healthy)).not.toContain(FULL_WARNING);
+  expect(storedLatch(input)).toBeUndefined();
+
+  seedCapture(deferredVerdict());
+  const rearmed = await dispatchPublicSnapshot(input);
+  expect(responseWarnings(rearmed).filter((line) => line === FULL_WARNING)).toHaveLength(1);
+});
+
+test('a genuine recovered render keeps later deferred captures quiet without doubling', async () => {
+  const input = scenario();
+  seedCapture(genuineRecoveredVerdict());
+
+  const genuine = await dispatchPublicSnapshot(input);
+  expect(responseWarnings(genuine).filter((line) => line === FULL_WARNING)).toHaveLength(1);
+  expect(storedLatch(input)).toEqual({ appBundleId: 'com.example.app' });
+
+  seedCapture(deferredVerdict());
+  const deferred = await dispatchPublicSnapshot(input);
+  expect(responseWarnings(deferred)).not.toContain(FULL_WARNING);
+});

src/daemon/snapshot-quality-latch.ts

@@ -0,0 +1,86 @@
+import type { SnapshotQualityVerdict } from '@agent-device/kernel/snapshot';
+import {
+  readSnapshotQualityVerdict,
+  recoveredSnapshotQualityWarning,
+} from '../snapshot/snapshot-quality.ts';
+import type { DaemonResponseData, SessionState } from './types.ts';
+
+type RecoveredWarningLatch = NonNullable<SessionState['recoveredSnapshotWarningLatch']>;
+
+type LatchDecision = {
+  /** Full recovered warning to prepend to the response, when the latch was not held. */
+  warning?: string;
+  latch: RecoveredWarningLatch | undefined;
+};
+
+/**
+ * One-shot warning latch for penalty-deferred captures (PR #1587 follow-up).
+ *
+ * `renderSnapshotQualityWarnings` suppresses the full recovered warning for
+ * `reasonCode: 'deferred'` on the assumption that the capture which ARMED the
+ * XCTest-channel penalty already rendered it. Internal captures (selector
+ * resolution, settle observation loops, system-modal probes) can arm the
+ * penalty without any user-facing render, and the runner cannot tell the two
+ * apart — so the daemon tracks per session whether a recovered warning actually
+ * reached this client for the currently penalized app, and re-renders it once
+ * when it has not.
+ *
+ * Transitions (evaluated only on user-facing snapshot/diff responses):
+ * - genuine `recovered` — the same response already carries the full warning
+ *   (rendered by the runtime), so the latch is set without injecting anything;
+ * - `deferred` with the latch not held for this app — inject the full warning
+ *   once and set the latch;
+ * - `healthy` — the penalty window is over; clear the latch so the next arming
+ *   renders again;
+ * - `sparse` or no verdict — no penalty signal either way; latch unchanged.
+ *
+ * The daemon cannot observe penalty arming directly (a 120s TTL held
+ * runner-side), so "penalty window" is approximated by the verdicts of public
+ * captures: as long as no public capture reports healthy, an unbroken hostile
+ * stretch of the same app warns once.
+ */
+export function resolveRecoveredWarningLatch(params: {
+  verdict: SnapshotQualityVerdict | undefined;
+  appBundleId: string | undefined;
+  latch: RecoveredWarningLatch | undefined;
+}): LatchDecision {
+  const { verdict, appBundleId, latch } = params;
+  if (!verdict) return { latch };
+  if (verdict.state === 'healthy') return { latch: undefined };
+  if (verdict.state !== 'recovered') return { latch };
+  if (verdict.reasonCode !== 'deferred') {
+    return { latch: { appBundleId } };
+  }
+  if (latch !== undefined && latch.appBundleId === appBundleId) return { latch };
+  return { warning: recoveredSnapshotQualityWarning(verdict.backend), latch: { appBundleId } };
+}
+
+/**
+ * Applies the latch to a user-facing snapshot/diff response: updates the
+ * session's latch state and prepends the full recovered warning when this is
+ * the penalty window's first user-facing render. Internal observation captures
+ * (`req.internal.observationOnly`) must pass `internalObservation: true` — they
+ * never reach the user, so they neither consume nor clear the latch.
+ */
+export function applyRecoveredWarningLatch(params: {
+  session: SessionState | undefined;
+  data: DaemonResponseData;
+  internalObservation: boolean;
+}): DaemonResponseData {
+  const { session, data, internalObservation } = params;
+  if (internalObservation || !session) return data;
+  // The snapshot command carries the capture's verdict in the response; diff
+  // publishes only warnings, so its verdict is read from the session snapshot
+  // the capture just stored.
+  const verdict =
+    readSnapshotQualityVerdict(data.snapshotQuality) ?? session.snapshot?.snapshotQuality;
+  const decision = resolveRecoveredWarningLatch({
+    verdict,
+    appBundleId: session.appBundleId,
+    latch: session.recoveredSnapshotWarningLatch,
+  });
+  session.recoveredSnapshotWarningLatch = decision.latch;
+  if (!decision.warning) return data;
+  const warnings = Array.isArray(data.warnings) ? data.warnings : [];
+  return { ...data, warnings: [decision.warning, ...warnings] };
+}

src/daemon/snapshot-runtime.ts

@@ -18,6 +18,7 @@ import {
   withSessionlessRunnerCleanup,
 } from './handlers/snapshot-session.ts';
 import { activateCompleteRefFrame } from './ref-frame.ts';
+import { applyRecoveredWarningLatch } from './snapshot-quality-latch.ts';
 import { createDaemonRuntimePolicy } from './runtime-policy.ts';
 import { createDaemonRuntimeSessionStore } from './runtime-session.ts';
 import { isInteractiveObservation } from './session-action-recorder.ts';
@@ -180,7 +181,11 @@ async function dispatchSnapshotRuntimeCommand(
     });
     return {
       ok: true,
-      data: result.data,
+      data: applyRecoveredWarningLatch({
+        session: sessionStore.get(sessionName),
+        data: result.data,
+        internalObservation: req.internal?.observationOnly === true,
+      }),
     };
   });
 }

src/daemon/types.ts

@@ -319,6 +319,18 @@ export type SessionState = {
    * probabilistic (seeded), NOT identity-based.
    */
   snapshotGeneration?: number;
+  /**
+   * One-shot latch: the full "overly complex or slow accessibility tree" warning has been
+   * rendered to this session's client for the app currently under the XCTest-channel
+   * penalty. Penalty-deferred verdicts (`reasonCode: 'deferred'`) suppress the repeated
+   * warning in `renderSnapshotQualityWarnings`, but internal captures (selector
+   * resolution, settle observation, system-modal probes) can arm the runner-side penalty
+   * without any user-facing render — when the latch is not held, the first public
+   * deferred verdict re-renders the warning once. Managed only through
+   * `src/daemon/snapshot-quality-latch.ts`: a genuine recovered render sets it, a healthy
+   * public verdict clears it, and an app switch supersedes it.
+   */
+  recoveredSnapshotWarningLatch?: { appBundleId?: string };
   /** Source snapshot used to resolve repeated `snapshot -s @ref` after scoped output replaces refs. */
   snapshotScopeSource?: SnapshotState;
   /**