fix: preserve wait absent restart diagnostics

Author: thymikee

packages/maestro/src/internal/__tests__/export-label-projection.test.ts

@@ -41,12 +41,20 @@ test('keeps compound selectors that include label as hard export errors', () =>
 });
 
 test('does not export strict wait absent as Maestro notVisible', () => {
-  expect(() =>
+  let thrown: unknown;
+  try {
     exportReplayActionsToMaestro([action('wait', ['absent', 'label="Removed"', '1000'])], {
       resolveSelector: (expression) =>
         projectSelectorExpression(expression, MAESTRO_SELECTOR_PROJECTION),
-    }),
-  ).toThrow(/wait absent.*unsupported|strict.*absence|notVisible/i);
+    });
+  } catch (error) {
+    thrown = error;
+  }
+
+  expect(thrown).toBeInstanceOf(AppError);
+  if (!(thrown instanceof AppError)) return;
+  expect(thrown.message).toMatch(/unsupported|strict absence/i);
+  expect(thrown.message).not.toMatch(/notVisible/i);
 });
 
 function action(command: string, positionals: string[]): SessionAction {

src/__tests__/command-doc-coverage.test.ts

@@ -184,6 +184,13 @@ describe('command reference doc coverage', () => {
     );
   });
 
+  test('commands.md publishes the wait absence unreadable-observation reason', () => {
+    assert.match(
+      markdown,
+      /`?predicate_failed`? means strict `wait absent` could not prove absence because no valid capture arrived/,
+    );
+  });
+
   test('no stale waivers', () => {
     assert.deepEqual(
       findStaleUndocumentedWaivers(

src/cli-schema/cli-help-topics.test.ts

@@ -185,6 +185,10 @@ test('usageForCommand resolves workflow help topic', async () => {
   );
   assert.match(help, /open -> snapshot -i -> settle -> verify -> close loop/);
   assert.match(help, /type never takes --settle/);
+  assert.match(help, /snapshot\/get\/is\/find answer read-only questions/);
+  assert.match(help, /--settle confirms local UI quieted/);
+  assert.match(help, /wait text "Expected result" or wait <selector> instead of polling/);
+  assert.match(help, /strict disappearance uses wait absent <selector>/);
   assert.match(
     help,
     /Chain confident consecutive steps with &&: press 'label="Search"' --settle && fill 'label="Search"' "query" --settle/,
@@ -235,6 +239,10 @@ test('usageForCommand resolves workflow help topic', async () => {
   assert.match(help, /Wait failure contract:/);
   assert.match(help, /wait_target_absent: a readable capture ran and found no match/);
   assert.match(help, /wait_target_present: wait absent timed out with matches/);
+  assert.match(
+    help,
+    /predicate_failed: wait absent had no valid capture; final observation\/diagnostic is preserved/,
+  );
   assert.match(help, /wait_capture_stalled: no readable capture finished before the deadline/);
   assert.match(help, /wait_deadline_exceeded: a later capture used the remaining budget/);
   assert.match(help, /wait_landmark_identity_mismatch: a replay destination guard/);

src/cli-schema/cli-help.ts

@@ -54,9 +54,10 @@ const EXAMPLE_LINES = [
 ] as const;
 
 const WAIT_FAILURE_CONTRACT = `Wait failure contract:
-  Read the verdict from error.details.reason in --json, not the message text.
+  Read error.details.reason in --json, not the message text.
   wait_target_absent: a readable capture ran and found no match.
   wait_target_present: wait absent timed out with matches; details include matches and firstMatch.
+  predicate_failed: wait absent had no valid capture; final observation/diagnostic is preserved.
   wait_capture_stalled: no readable capture finished before the deadline -- retriable.
   wait_deadline_exceeded: a later capture used the remaining budget after an earlier readable one.
   wait_landmark_identity_mismatch: a replay destination guard found the selector but not the recorded identity.
@@ -129,10 +130,10 @@ Focused compatibility request: ${MAESTRO_COMPATIBILITY_ISSUE_URL}`,
     summary: 'Normal agent-device bootstrap, exploration, and validation loop',
     body: `agent-device help workflow
 
-Command shapes, refs, selectors, waits, recovery, and platform limits for the default open -> snapshot -i -> settle -> verify -> close loop.
+Command shapes, refs, selectors, waits, recovery, and platform limits for open -> snapshot -i -> settle -> verify -> close loop.
 
 Command shape:
-  Command lines only -- no prose, numbering, fences, pipes, or grep/head/tail/jq on agent-device output; raw output carries the refs/hints the next step needs. Subcommand first, then positionals, then flags: agent-device open com.example.app --session checkout --platform android --relaunch
+  Command lines only -- no prose, numbering, fences, pipes, or grep/head/tail/jq; raw output carries refs/hints for the next step. Order: subcommand, positionals, flags: agent-device open com.example.app --session checkout --platform android --relaunch
   Chain confident consecutive steps with &&: press 'label="Search"' --settle && fill 'label="Search"' "query" --settle. Fall back to one command at a time when a step is uncertain (ambiguous match, network-backed result, unseen screen).
   Refs look like @e12; use the exact ref from the latest snapshot -i, never a placeholder (@ref, @eN, @Label_Name). Pin with ~s<n> (press @e12~s4); iOS rejects a stale pinned ref -- refresh with snapshot -i or use a selector.
   close = agent-device close. App back is back; system back is back --system. Taps are press/click. type never takes --settle: run type, then diff snapshot to verify. Known flow: batch --steps-file ./steps.json (help batch).
@@ -145,11 +146,11 @@ Bootstrap:
   Apple CI: prepare ios-runner after boot/install, before replay/test (help prepare). Remote/cloud: connect -> open -> commands -> close -> disconnect (help remote). Reusable scripts, secret-safe fills, replay repair: help scripting.
 
 Snapshots and refs:
-  snapshot reads visible state; snapshot -i gets current interactive refs only -- the fast path before an interaction. Default text is agent-facing and token-efficient; --raw/--json only for the full provider tree.
+  snapshot reads visible state; snapshot -i gets current interactive refs only -- fast path before interaction. Default text is token-efficient; --raw/--json for full provider tree.
   Legend: @e12 [button] label="Add to cart" enabled hittable -> press @e12. [off-screen below] -> scroll down (a hint, not a ref).
   Refs stay valid until you press/click/fill/type/scroll/back/wait-for-async-UI, or otherwise change app state; open/--relaunch clears the stored snapshot outright.
-  Prefer --settle and continue from its settled diff when it shows the next target; refresh with snapshot -i only when you did not settle, it reported not settled, or its output lacks what you need. A known selector/label after a mutation is often enough, since interaction commands refresh state internally.
-  Truncated preview: snapshot -s @e12 (the current concrete ref), not get text. Missing target in a list: scroll down/up (not bottom/top unless the task wants the edge), then snapshot -i. TV/D-pad focus: help tv.
+  Prefer --settle and its diff when it shows next target; refresh with snapshot -i only when you did not settle, it reported not settled, or output lacks what you need. A known selector/label after a mutation is often enough, since interaction commands refresh state internally.
+  Truncated preview: snapshot -s @e12 (the current concrete ref), not get text. Missing list target: scroll down/up then snapshot -i. TV/D-pad focus: help tv.
 
 Selectors:
   id="field-email", label="Allow", role=button label="Search" -- not bare role keys (button="Search"); no CSS selectors/--selector/--text/raw x-y when refs/selectors exist.
@@ -168,7 +169,7 @@ Session ordering:
 
 Read-only and waits:
 ${WAIT_FAILURE_CONTRACT}
-  Use wait text/selector for delayed results; use wait absent <selector> for strict disappearance.
+  snapshot/get/is/find answer read-only questions; snapshot -i is for refs. --settle confirms local UI quieted; delayed results use wait text "Expected result" or wait <selector> instead of polling; strict disappearance uses wait absent <selector>.
   wait stable [quietMs] [timeoutMs] (defaults 500/10000) is the fallback for open/relaunch/navigation, or an intentionally-unsettled mutation -- not after a --settle whose diff already shows the change. Ambiguous find: add --first or --last.
 
 Navigation:

src/commands/interaction/runtime/selector-read.test.ts

@@ -351,8 +351,8 @@ test('runtime selector convenience methods use explicit target helpers', async (
 // mid-transition Android helper content verdicts) instead of aborting the
 // wait — the live-validated destination-guard gap from #1349's PR review.
 // (#1349's own in-loop landmark identity verification tests — the
-// `target.recordedLandmark` cases — moved to `selector-wait.test.ts`, the
-// 1:1 topology location for `selector-wait.ts`; #1478 P5 step 2 cell 7.)
+// `target.recordedLandmark` cases — moved to `wait-selector.test.ts`, the
+// 1:1 topology location for `wait-selector.ts`; #1478 P5 step 2 cell 7.)
 // ---------------------------------------------------------------------------
 
 function landmarkScreen(parentLabel: string) {

src/commands/interaction/runtime/wait-absent.ts

@@ -87,6 +87,16 @@ export async function waitForAbsent<Runtime extends SelectorWaitRuntime>(
     await polling.sleepUntilNextPoll();
   }
 
+  // A runner restart is the authoritative deadline cause even when an earlier
+  // readable poll saw the target. Returning stale target-present evidence would
+  // hide the retriable restart and make callers stop retrying the wrong reason.
+  if (deadline === 'runner-restart-exhausted') {
+    throw waitTimeoutError(
+      `wait absent timed out for selector: ${selectorExpression}`,
+      polling,
+      deadline,
+    );
+  }
   if (present) throw waitTargetPresentError(selectorExpression, present, polling.failureEvidence());
   throw waitTimeoutError(
     `wait absent timed out for selector: ${selectorExpression}`,

…nteraction/runtime/selector-wait.test.ts …nteraction/runtime/wait-selector.test.tssrc/commands/interaction/runtime/selector-wait.test.ts renamed to src/commands/interaction/runtime/wait-selector.test.ts src/commands/interaction/runtime/selector-wait.test.ts renamed to src/commands/interaction/runtime/wait-selector.test.ts

@@ -8,11 +8,7 @@ import {
   localCommandPolicy,
 } from '../../../runtime.ts';
 import { makeSnapshotState } from '../../../__tests__/test-utils/snapshot-builders.ts';
-import {
-  createFakeClock,
-  createSelectorDevice,
-  selectorReadSnapshot,
-} from './__tests__/test-utils/index.ts';
+import { createFakeClock } from './__tests__/test-utils/index.ts';
 import { computeTargetEvidence } from '../../../daemon/session-target-evidence.ts';
 import { WAIT_LANDMARK_MISMATCH_REASON } from '@agent-device/contracts/replay';
 import { AppError } from '@agent-device/kernel/errors';
@@ -52,36 +48,9 @@ test('runtime focused selector waits against a full snapshot', async () => {
   assert.equal(captureOptions?.interactiveOnly, false);
 });
 
-// A text wait has exactly one source of truth: the polled capture. The backend `findText` seam
-// that short-circuited it on Apple was wait's second platform-execution path and retired with
-// wait's ADR 0019 cutover, so the tree answer is the only answer — in both directions.
-test('runtime wait resolves text from the polled snapshot', async () => {
-  const device = createSelectorDevice(selectorReadSnapshot(), { now: 10 });
-
-  const result = await device.selectors.wait({
-    session: 'default',
-    target: { kind: 'text', text: 'Continue', timeoutMs: 100 },
-  });
-
-  assert.deepEqual(result, { kind: 'text', text: 'Continue', waitedMs: 0 });
-});
-
-test('runtime wait times out on text the polled snapshot does not carry', async () => {
-  const device = createSelectorDevice(selectorReadSnapshot(), { clock: createFakeClock() });
-
-  await assert.rejects(
-    async () =>
-      await device.selectors.wait({
-        session: 'default',
-        target: { kind: 'text', text: 'Ready', timeoutMs: 100 },
-      }),
-    (error: Error) => error.message.includes('wait timed out for text: Ready'),
-  );
-});
-
 // ---------------------------------------------------------------------------
 // #1349 (relocated from `selector-read.test.ts` — this is the 1:1 topology
-// location for `selector-wait.ts`, and #1478 P5 step 2 cell 7's pin):
+// location for `wait-selector.ts`, and #1478 P5 step 2 cell 7's pin):
 // wait's in-loop landmark identity verification, threaded as
 // `target.recordedLandmark`. Polling semantics are preserved — a
 // same-selector impostor never aborts the wait; only the deadline turns

…ion/runtime/selector-wait-stable.test.ts …/interaction/runtime/wait-stable.test.tssrc/commands/interaction/runtime/selector-wait-stable.test.ts renamed to src/commands/interaction/runtime/wait-stable.test.ts src/commands/interaction/runtime/selector-wait-stable.test.ts renamed to src/commands/interaction/runtime/wait-stable.test.ts

@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import {
+  createFakeClock,
+  createSelectorDevice,
+  selectorReadSnapshot,
+} from './__tests__/test-utils/index.ts';
+
+// A text wait has exactly one source of truth: the polled capture. The backend `findText` seam
+// that short-circuited it on Apple was wait's second platform-execution path and retired with
+// wait's ADR 0019 cutover, so the tree answer is the only answer — in both directions.
+test('runtime wait resolves text from the polled snapshot', async () => {
+  const device = createSelectorDevice(selectorReadSnapshot(), { now: 10 });
+
+  const result = await device.selectors.wait({
+    session: 'default',
+    target: { kind: 'text', text: 'Continue', timeoutMs: 100 },
+  });
+
+  assert.deepEqual(result, { kind: 'text', text: 'Continue', waitedMs: 0 });
+});
+
+test('runtime wait times out on text the polled snapshot does not carry', async () => {
+  const device = createSelectorDevice(selectorReadSnapshot(), { clock: createFakeClock() });
+
+  await assert.rejects(
+    async () =>
+      await device.selectors.wait({
+        session: 'default',
+        target: { kind: 'text', text: 'Ready', timeoutMs: 100 },
+      }),
+    (error: Error) => error.message.includes('wait timed out for text: Ready'),
+  );
+});

src/commands/interaction/runtime/wait-text.test.ts

@@ -2,7 +2,8 @@ import { test, expect, vi, beforeEach } from 'vitest';
 import { legacyDispatchCapture } from './legacy-snapshot-capture-fixture.ts';
 import { handleFindCommands } from '../interaction/index.ts';
 import { getRuntimeBindings } from './interaction-get-runtime-fixture.ts';
-import { dispatchFindReadOnlyViaRuntime, dispatchWaitViaRuntime } from '../selector-runtime.ts';
+import { dispatchFindReadOnlyViaRuntime } from '../selector-runtime.ts';
+import { dispatchWaitViaRuntime } from '../wait-runtime.ts';
 import type { DaemonRequest, DaemonResponse } from '../types.ts';
 import { ANDROID_SYSTEM_SURFACE_DISCLOSURE } from '../../core/android-system-surface-disclosure.ts';
 import { snapshotRuntimeFixture } from './snapshot-runtime-fixture.ts';