fix: preserve android freshness baseline for optimized taps

Author: thymikee

src/daemon/android-snapshot-freshness.ts

@@ -8,6 +8,7 @@ export type { AndroidSnapshotFreshness } from './types.ts';
 // and can lag behind real transitions by up to ~2 s; 2.5 s gives a comfortable margin
 // while avoiding unnecessary retries for steady-state interactions like typing.
 const ANDROID_FRESHNESS_WINDOW_MS = 2_500;
+const ANDROID_COMPARISON_BASELINE_MAX_AGE_MS = 5_000;
 
 // Retry suspicious snapshots until this post-action deadline expires.  The delay
 // sequence stays short in the happy path; the 600 ms tail retry is opportunistic
@@ -28,21 +29,34 @@ export function markAndroidSnapshotFreshness(
   baseline = session.snapshot,
 ): void {
   if (session.device.platform !== 'android') return;
+  const comparisonBaseline = resolveAndroidComparisonBaseline(session, baseline);
   // Route-stuck recovery only makes sense against a baseline captured in a broad, comparable
   // shape. Interactive/scoped/depth-limited snapshots are still useful for users, but they are
   // too pruned to serve as a reliable "same route vs new route" baseline.
-  const routeComparable = baseline?.comparisonSafe === true;
+  const routeComparable = comparisonBaseline?.comparisonSafe === true;
   session.androidSnapshotFreshness = {
     action,
     markedAt: Date.now(),
-    baselineCount: baseline?.nodes.length ?? 0,
+    baselineCount: (comparisonBaseline ?? baseline)?.nodes.length ?? 0,
     baselineSignatures: routeComparable
-      ? buildSnapshotSignatures(baseline?.nodes ?? [])
+      ? buildSnapshotSignatures(comparisonBaseline?.nodes ?? [])
       : undefined,
     routeComparable,
   };
 }
 
+function resolveAndroidComparisonBaseline(
+  session: SessionState,
+  baseline: SnapshotState | undefined,
+): SnapshotState | undefined {
+  if (baseline?.comparisonSafe === true) return baseline;
+  const previous = session.lastComparisonSafeSnapshot;
+  if (!previous || previous.comparisonSafe !== true) return baseline;
+  return Date.now() - previous.createdAt <= ANDROID_COMPARISON_BASELINE_MAX_AGE_MS
+    ? previous
+    : baseline;
+}
+
 export function getActiveAndroidSnapshotFreshness(
   session: SessionState | undefined,
 ): AndroidSnapshotFreshness | undefined {

src/daemon/handlers/__tests__/interaction.test.ts

@@ -1446,6 +1446,72 @@ test('press @ref falls back to cached Android ref when freshness refresh fails',
   });
 });
 
+test('coordinate press preserves Android route freshness from last comparable snapshot', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-coordinate-freshness-baseline';
+  const session = makeAndroidSession(sessionName);
+  const comparableSnapshot = {
+    nodes: attachRefs([
+      {
+        index: 0,
+        type: 'android.widget.ScrollView',
+        label: 'Albums',
+        rect: { x: 0, y: 0, width: 400, height: 700 },
+      },
+      {
+        index: 1,
+        type: 'android.widget.Button',
+        label: 'Go to Contacts',
+        rect: { x: 16, y: 120, width: 160, height: 48 },
+        enabled: true,
+        hittable: true,
+      },
+    ]),
+    createdAt: Date.now(),
+    backend: 'android' as const,
+    comparisonSafe: true,
+  };
+  session.lastComparisonSafeSnapshot = comparableSnapshot;
+  session.snapshot = {
+    nodes: attachRefs([
+      {
+        index: 0,
+        type: 'android.widget.Button',
+        label: 'Go to Contacts',
+        rect: { x: 16, y: 120, width: 160, height: 48 },
+        enabled: true,
+        hittable: true,
+      },
+    ]),
+    createdAt: Date.now(),
+    backend: 'android',
+    comparisonSafe: false,
+  };
+  sessionStore.set(sessionName, session);
+  mockDispatch.mockResolvedValue({ pressed: true });
+
+  const response = await handleInteractionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'press',
+      positionals: ['96', '144'],
+      flags: {},
+    },
+    sessionName,
+    sessionStore,
+    contextFromFlags,
+  });
+
+  expect(response?.ok).toBe(true);
+  expect(sessionStore.get(sessionName)?.androidSnapshotFreshness).toMatchObject({
+    action: 'press',
+    baselineCount: 2,
+    baselineSignatures: expect.any(Array),
+    routeComparable: true,
+  });
+});
+
 test('press @ref fails when Android tap escapes to launcher', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'android-escape';

src/daemon/handlers/__tests__/session-replay.test.ts

@@ -1,6 +1,10 @@
 import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { test } from 'vitest';
 import { buildNestedReplayFlags } from '../session-replay.ts';
+import { collectReplayActionArtifactPaths } from '../session-replay-runtime.ts';
 
 test('buildNestedReplayFlags returns parent flags untouched when neither override is set', () => {
   const parent = { platform: 'android' as const, timeoutMs: 5000 };
@@ -51,3 +55,22 @@ test('buildNestedReplayFlags overrides a parent artifactsDir with the attempt-le
   });
   assert.equal(result?.artifactsDir, '/suite-root/flow/attempt-2');
 });
+
+test('collectReplayActionArtifactPaths includes failed action artifact details', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-artifacts-'));
+  const snapshotPath = path.join(root, 'failure-snapshot.txt');
+  fs.writeFileSync(snapshotPath, 'snapshot');
+
+  const paths = collectReplayActionArtifactPaths({
+    ok: false,
+    error: {
+      code: 'COMMAND_FAILED',
+      message: 'assertion failed',
+      details: {
+        artifactPaths: [snapshotPath, path.join(root, 'missing.txt')],
+      },
+    },
+  });
+
+  assert.deepEqual(paths, [snapshotPath]);
+});

src/daemon/handlers/session-replay-runtime.ts

@@ -102,6 +102,7 @@ export async function runReplayScriptFile(params: {
         collectReplayActionArtifactPaths(response).forEach((entry) => artifactPaths.add(entry));
         continue;
       }
+      collectReplayActionArtifactPaths(response).forEach((entry) => artifactPaths.add(entry));
       if (!shouldUpdate) {
         return withReplayFailureContext(response, action, index, resolved, [...artifactPaths]);
       }
@@ -129,6 +130,7 @@ export async function runReplayScriptFile(params: {
         invoke,
       });
       if (!response.ok) {
+        collectReplayActionArtifactPaths(response).forEach((entry) => artifactPaths.add(entry));
         return withReplayFailureContext(response, nextAction, index, resolved, [...artifactPaths]);
       }
       collectReplayActionArtifactPaths(response).forEach((entry) => artifactPaths.add(entry));
@@ -231,7 +233,20 @@ function withReplayFailureContext(
 
 // fallow-ignore-next-line complexity
 export function collectReplayActionArtifactPaths(response: DaemonResponse): string[] {
-  if (!response.ok || !response.data) return [];
+  if (!response.ok) {
+    const paths = response.error.details?.artifactPaths;
+    return Array.isArray(paths)
+      ? [
+          ...new Set(
+            paths.filter(
+              (candidate): candidate is string =>
+                typeof candidate === 'string' && isReplayArtifactPath(candidate),
+            ),
+          ),
+        ]
+      : [];
+  }
+  if (!response.data) return [];
   const candidates: string[] = [];
   if (typeof response.data.path === 'string') candidates.push(response.data.path);
   if (typeof response.data.outPath === 'string') candidates.push(response.data.outPath);

src/daemon/handlers/snapshot-session.ts

@@ -56,14 +56,20 @@ export function buildSnapshotSession(params: {
 }): SessionState {
   const { session, sessionName, device, snapshot, appBundleId } = params;
   if (session) {
-    return { ...session, snapshot };
+    return {
+      ...session,
+      snapshot,
+      lastComparisonSafeSnapshot:
+        snapshot?.comparisonSafe === true ? snapshot : session.lastComparisonSafeSnapshot,
+    };
   }
   return {
     name: sessionName,
     device,
     createdAt: Date.now(),
     appBundleId,
     snapshot,
+    ...(snapshot?.comparisonSafe === true ? { lastComparisonSafeSnapshot: snapshot } : {}),
     actions: [],
   };
 }

src/daemon/session-snapshot.ts

@@ -4,4 +4,7 @@ import type { SessionState } from './types.ts';
 export function setSessionSnapshot(session: SessionState, snapshot: SnapshotState): void {
   session.snapshot = snapshot;
   session.snapshotScopeSource = undefined;
+  if (snapshot.comparisonSafe === true) {
+    session.lastComparisonSafeSnapshot = snapshot;
+  }
 }

src/daemon/types.ts

@@ -211,6 +211,8 @@ export type SessionState = {
   snapshot?: SnapshotState;
   /** Source snapshot used to resolve repeated `snapshot -s @ref` after scoped output replaces refs. */
   snapshotScopeSource?: SnapshotState;
+  /** Last broad snapshot safe for Android route-freshness comparisons after interactive snapshots. */
+  lastComparisonSafeSnapshot?: SnapshotState;
   androidSnapshotFreshness?: AndroidSnapshotFreshness;
   postGestureStabilization?: PostGestureStabilization;
   pendingInteractionOutcome?: PendingInteractionOutcome;