test: restore daemon composition wait branch coverage

Author: thymikee

packages/daemon/package.json

@@ -164,10 +164,6 @@
       "types": "./src/core/session-store.ts",
       "default": "./src/core/session-store.ts"
     },
-    "./testing/snapshot-interactor-capture": {
-      "types": "./src/core/snapshot-interactor-capture.ts",
-      "default": "./src/core/snapshot-interactor-capture.ts"
-    },
     "./testing/web-session-names": {
       "types": "./src/sessions/web-session-names.ts",
       "default": "./src/sessions/web-session-names.ts"

packages/daemon/src/execution/wait-runtime.test.ts

@@ -342,6 +342,31 @@ test('a text wait returns a native owner hit without capturing a snapshot', asyn
   expect(harness.captureSnapshot).not.toHaveBeenCalled();
 });
 
+test('the native text reading runs in the same runner context as the capture', async () => {
+  let nativeReads = 0;
+  const harness = waitRuntimeHarness({
+    findText: available,
+    findTextAnswers: () => nativeReads++ > 0,
+    nodesPerPoll: [[{ index: 0, depth: 0, type: 'Button', label: 'Checkout', hittable: true }]],
+  });
+
+  const { response } = await runWait(['text', 'Ready', '4000'], harness, [], {
+    debug: true,
+    iosXctestrunFile: '/tmp/override.xctestrun',
+    iosXctestDerivedDataPath: '/tmp/derived',
+  });
+
+  expect(response.ok).toBe(true);
+  const captureExecution = harness.captureSnapshot.mock.calls[0]?.[0]?.execution;
+  const findTextExecution = harness.findText.mock.calls[0]?.[0]?.execution;
+  expect(captureExecution).toMatchObject({
+    requestId: 'wait-runtime-test',
+    iosXctestrunFile: '/tmp/override.xctestrun',
+    iosXctestDerivedDataPath: '/tmp/derived',
+  });
+  expect(findTextExecution).toEqual(captureExecution);
+});
+
 test('native text failure cannot hide a canonical capture failure', async () => {
   const harness = waitRuntimeHarness({ findText: available });
   harness.findText.mockRejectedValueOnce(new Error('native observation failed'));
@@ -375,6 +400,20 @@ test('a selector wait binds the capture use once and polls through the bound ope
   expect(harness.bindDevice).toHaveBeenCalledWith(harness.device, waitWithoutActiveAppUse);
 });
 
+test('an unavailable conditional native reading preserves the capture-backed wait path', async () => {
+  const harness = waitRuntimeHarness({
+    nodesPerPoll: [[{ index: 0, depth: 0, type: 'Button', label: 'Ready', hittable: true }]],
+  });
+
+  const { response } = await runWait(['text', 'Ready'], harness);
+
+  expect(response).toMatchObject({ ok: true, data: { text: 'Ready' } });
+  expect(harness.inspectFacts).toHaveBeenCalledTimes(1);
+  expect(harness.bindDevice).toHaveBeenCalledTimes(1);
+  expect(harness.findText).not.toHaveBeenCalled();
+  expect(harness.captureSnapshot).toHaveBeenCalledTimes(1);
+});
+
 test('a @ref wait binds the capture use once and polls through the bound operation', async () => {
   const harness = waitRuntimeHarness();
 

src/commands/interaction/runtime/settle-generic-surface.test.ts

@@ -0,0 +1,112 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import type { SnapshotState } from '@agent-device/kernel/snapshot';
+import { makeSnapshotState } from '@agent-device/selectors/snapshot-geometry-fixtures';
+import { surfaceScopedNodes } from '@agent-device/capture-kit/snapshot-baseline';
+import {
+  buttonSnapshot,
+  createSettleDevice,
+  welcomeSnapshot,
+} from './__tests__/settle-device-fixtures.ts';
+import { settleObservationCommand } from './settle.ts';
+
+const SHEET_BUNDLE_ID = 'com.apple.SafariViewService';
+
+function signInSheetSnapshot(): SnapshotState {
+  return {
+    ...makeSnapshotState(
+      ['Continue', 'Sign in with Example', 'Email', 'Password', 'Cancel'].map((label, index) => ({
+        index,
+        depth: 0,
+        type: 'Button',
+        label,
+        rect: { x: 10, y: 20 + index * 50, width: 200, height: 40 },
+        hittable: true,
+      })),
+    ),
+    iosSystemSurfaceBundleId: SHEET_BUNDLE_ID,
+  };
+}
+
+async function genericSettle(baseline: SnapshotState, after: SnapshotState) {
+  const device = createSettleDevice({
+    stored: baseline,
+    captureSnapshot: () => ({ snapshot: after }),
+  });
+  const settle = await settleObservationCommand(device, {
+    session: 'default',
+    baseline: surfaceScopedNodes(baseline),
+    quietMs: 25,
+    timeoutMs: 5_000,
+  });
+  return { device, settle };
+}
+
+const app = welcomeSnapshot();
+const sheet = signInSheetSnapshot();
+
+for (const route of ['scroll', 'back'] as const) {
+  for (const transition of [
+    { name: 'app-to-sheet', baseline: app, after: sheet, from: 'app', to: SHEET_BUNDLE_ID },
+    { name: 'sheet-to-app', baseline: sheet, after: app, from: SHEET_BUNDLE_ID, to: 'app' },
+  ]) {
+    test(`targetless ${route} settle discloses the ${transition.name} surface change`, async () => {
+      const { device, settle } = await genericSettle(transition.baseline, transition.after);
+
+      assert.equal(settle.settled, true);
+      assert.equal(settle.surfaceChange?.from, transition.from);
+      assert.equal(settle.surfaceChange?.to, transition.to);
+      assert.ok(settle.surfaceChange?.disclosure);
+      assert.equal(settle.diff, undefined);
+      assert.equal(settle.tail, undefined);
+      assert.match(settle.hint ?? '', /different surfaces/);
+      assert.match(settle.hint ?? '', /take a snapshot/i);
+      const stored = (await device.sessions.get('default')) as { snapshot?: SnapshotState };
+      assert.equal(
+        stored.snapshot?.iosSystemSurfaceBundleId,
+        transition.after.iosSystemSurfaceBundleId,
+      );
+    });
+  }
+}
+
+function presentedSheetBaseline(nodeCount: number): SnapshotState {
+  return {
+    ...makeSnapshotState(
+      Array.from({ length: nodeCount }, (_, index) => ({
+        index,
+        depth: 0,
+        type: 'Button',
+        label: `Sheet action ${index}`,
+      })),
+    ),
+    presentedSurface: 'presented',
+  };
+}
+
+for (const [flavour, nodeCount] of [
+  ['interactive', 4],
+  ['full', 6],
+] as const) {
+  test(`targetless back settle confirms a dismissed sheet from the ${flavour} baseline`, async () => {
+    const { settle } = await genericSettle(presentedSheetBaseline(nodeCount), welcomeSnapshot());
+
+    assert.equal(settle.settled, true);
+    assert.ok(settle.waitedMs >= 1_500, `confirmation ended after ${settle.waitedMs}ms`);
+  });
+}
+
+test('targetless back settle keeps the plain window when the baseline presented nothing', async () => {
+  const absent = { ...buttonSnapshot(), presentedSurface: 'absent' as const };
+  const { settle } = await genericSettle(absent, welcomeSnapshot());
+
+  assert.equal(settle.settled, true);
+  assert.ok(settle.waitedMs < 1_500, `plain window ended after ${settle.waitedMs}ms`);
+});
+
+test('targetless back settle confirms a broad replacement when the baseline fact is unknown', async () => {
+  const { settle } = await genericSettle(buttonSnapshot(), welcomeSnapshot());
+
+  assert.equal(settle.settled, true);
+  assert.ok(settle.waitedMs >= 1_500, `confirmation ended after ${settle.waitedMs}ms`);
+});

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

@@ -1,12 +1,17 @@
 import assert from 'node:assert/strict';
-import { test } from 'vitest';
-import type { AgentDeviceBackend, BackendSnapshotResult } from '@agent-device/contracts/backend';
+import { test, vi } from 'vitest';
+import type {
+  AgentDeviceBackend,
+  BackendCommandContext,
+  BackendSnapshotResult,
+} from '@agent-device/contracts/backend';
 import { createLocalArtifactAdapter } from '../../../io.ts';
 import { createAgentDevice } from '../../../runtime.ts';
 import { localCommandPolicy } from '@agent-device/contracts/command-policy';
 import { makeSnapshotState } from '@agent-device/selectors/snapshot-geometry-fixtures';
 import { createFakeClock } from './__tests__/test-utils/index.ts';
 import { AppError } from '@agent-device/kernel/errors';
+import { WAIT_REASONS } from '@agent-device/contracts/wait';
 import { createMemorySessionStore } from '../../../command-runtime/runtime-factory.ts';
 
 const SELECTOR = 'label="Removed"';
@@ -52,6 +57,36 @@ function absentDevice(
   });
 }
 
+function cancelledAbsentDevice(params: {
+  firstSnapshot?: BackendSnapshotResult;
+  cancellation: AppError;
+}) {
+  let captures = 0;
+  const captureSnapshot = vi.fn(async (context: BackendCommandContext) => {
+    captures += 1;
+    if (captures === 1 && params.firstSnapshot) return params.firstSnapshot;
+    const signal = context.signal;
+    if (!signal) throw new Error('the wait deadline never reached the capture');
+    return await new Promise<never>((_resolve, reject) => {
+      const cancel = () => reject(params.cancellation);
+      if (signal.aborted) cancel();
+      else signal.addEventListener('abort', cancel, { once: true });
+    });
+  });
+  const clock = { now: () => 0, sleep: async (_durationMs: number) => {} };
+  const device = createAgentDevice({
+    backend: {
+      platform: 'ios',
+      captureSnapshot,
+    } satisfies AgentDeviceBackend,
+    artifacts: createLocalArtifactAdapter(),
+    sessions: createMemorySessionStore([{ name: 'default' }]),
+    policy: localCommandPolicy(),
+    clock,
+  });
+  return { device, captureSnapshot };
+}
+
 async function waitAbsent(device: ReturnType<typeof createAgentDevice>, timeoutMs = 1000) {
   return await device.selectors.wait({
     session: 'default',
@@ -222,3 +257,129 @@ test('wait absent preserves a final Android unreadable diagnostic when no valid
     return true;
   });
 });
+
+test('strict wait absent reports capture-stalled when every capture stalls', async () => {
+  vi.useFakeTimers();
+  try {
+    const { device, captureSnapshot } = cancelledAbsentDevice({
+      cancellation: new AppError('COMMAND_FAILED', 'capture cancelled'),
+    });
+    const pending = waitAbsent(device, 20);
+    const failure = assert.rejects(pending, (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.details?.reason, WAIT_REASONS.captureStalled);
+      assert.equal(error.details?.captureStalled, true);
+      assert.equal(error.details?.readableCaptures, 0);
+      return true;
+    });
+
+    await vi.advanceTimersByTimeAsync(20);
+    await failure;
+    assert.equal(captureSnapshot.mock.calls.length, 1);
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test('strict wait absent keeps target-present evidence when a steady-state capture is cancelled', async () => {
+  vi.useFakeTimers();
+  try {
+    const { device, captureSnapshot } = cancelledAbsentDevice({
+      firstSnapshot: snapshot('Removed'),
+      cancellation: new AppError('COMMAND_FAILED', 'capture cancelled'),
+    });
+    const pending = waitAbsent(device, 20);
+    const failure = assert.rejects(pending, (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.details?.reason, WAIT_REASONS.targetPresent);
+      assert.equal(error.details?.readableCaptures, 1);
+      assert.equal(error.details?.readinessPhase, undefined);
+      return true;
+    });
+
+    await vi.advanceTimersByTimeAsync(20);
+    await failure;
+    assert.equal(captureSnapshot.mock.calls.length, 2);
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test('strict wait absent preserves runner-restart exhaustion over an earlier present capture', async () => {
+  vi.useFakeTimers();
+  try {
+    const { device, captureSnapshot } = cancelledAbsentDevice({
+      firstSnapshot: snapshot('Removed'),
+      cancellation: new AppError('COMMAND_FAILED', 'request cancelled', {
+        runnerRestarted: true,
+        runnerRestartReason: 'runner_readiness_preflight_failed_before_command_send',
+      }),
+    });
+    const pending = waitAbsent(device, 20);
+    const failure = assert.rejects(pending, (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.details?.reason, WAIT_REASONS.runnerRestartExhausted);
+      assert.equal(error.details?.runnerRestarted, true);
+      assert.equal(error.details?.readableCaptures, 1);
+      assert.equal(error.details?.captureStalled, undefined);
+      return true;
+    });
+
+    await vi.advanceTimersByTimeAsync(20);
+    await failure;
+    assert.equal(captureSnapshot.mock.calls.length, 2);
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test('strict wait absent keeps runner-restart exhaustion as the deadline reason', async () => {
+  vi.useFakeTimers();
+  try {
+    const { device, captureSnapshot } = cancelledAbsentDevice({
+      cancellation: new AppError('COMMAND_FAILED', 'request cancelled', {
+        runnerRestarted: true,
+        runnerRestartReason: 'runner_readiness_preflight_failed_before_command_send',
+      }),
+    });
+    const pending = waitAbsent(device, 20);
+    const failure = assert.rejects(pending, (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.details?.reason, WAIT_REASONS.runnerRestartExhausted);
+      assert.equal(error.details?.readableCaptures, 0);
+      return true;
+    });
+
+    await vi.advanceTimersByTimeAsync(20);
+    await failure;
+    assert.equal(captureSnapshot.mock.calls.length, 1);
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test('strict wait absent preserves readiness exhaustion over an earlier present capture', async () => {
+  vi.useFakeTimers();
+  try {
+    const { device, captureSnapshot } = cancelledAbsentDevice({
+      firstSnapshot: snapshot('Removed'),
+      cancellation: new AppError('COMMAND_FAILED', 'request cancelled', {
+        readinessPhase: 'target-discovery',
+      }),
+    });
+    const pending = waitAbsent(device, 20);
+    const failure = assert.rejects(pending, (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.details?.reason, WAIT_REASONS.readinessExhausted);
+      assert.equal(error.details?.readinessPhase, 'target-discovery');
+      assert.equal(error.details?.readableCaptures, 1);
+      return true;
+    });
+
+    await vi.advanceTimersByTimeAsync(20);
+    await failure;
+    assert.equal(captureSnapshot.mock.calls.length, 2);
+  } finally {
+    vi.useRealTimers();
+  }
+});