fix: tighten Android freshness baselines

Author: thymikee

src/daemon/android-snapshot-freshness.ts

@@ -9,22 +9,32 @@ export type AndroidSnapshotFreshness = {
   action: string;
   markedAt: number;
   baselineCount: number;
-  baselineSignatures: string[];
+  baselineSignatures?: string[];
+  routeComparable: boolean;
 };
 
 export type AndroidFreshnessCaptureMeta = {
   action: string;
   retryCount: number;
   staleAfterRetries: boolean;
+  reason?: 'empty-interactive' | 'sharp-drop' | 'stuck-route';
 };
 
-export function markAndroidSnapshotFreshness(session: SessionState, action: string): void {
+export function markAndroidSnapshotFreshness(
+  session: SessionState,
+  action: string,
+  baseline = session.snapshot,
+): void {
   if (session.device.platform !== 'android') return;
+  const routeComparable = baseline?.comparisonSafe === true;
   session.androidSnapshotFreshness = {
     action,
     markedAt: Date.now(),
-    baselineCount: session.snapshot?.nodes.length ?? 0,
-    baselineSignatures: buildSnapshotSignatures(session.snapshot?.nodes ?? []),
+    baselineCount: baseline?.nodes.length ?? 0,
+    baselineSignatures: routeComparable
+      ? buildSnapshotSignatures(baseline?.nodes ?? [])
+      : undefined,
+    routeComparable,
   };
 }
 
@@ -74,9 +84,12 @@ export function isLikelyStaleSnapshotDrop(previousCount: number, currentCount: n
 }
 
 export function isLikelySnapshotStuckOnPreviousRoute(
-  previousSignatures: string[],
+  previousSignatures: string[] | undefined,
   currentNodes: SnapshotState['nodes'],
 ): boolean {
+  if (!previousSignatures || previousSignatures.length === 0) {
+    return false;
+  }
   const total = Math.max(previousSignatures.length, currentNodes.length);
   if (total < 12) {
     return false;

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

@@ -319,12 +319,14 @@ test('handleFindCommands wait bypasses snapshot cache while Android freshness re
     nodes: baselineNodes,
     createdAt: Date.now(),
     backend: 'android',
+    comparisonSafe: true,
   };
   session.androidSnapshotFreshness = {
     action: 'press',
     markedAt: Date.now(),
     baselineCount: baselineNodes.length,
     baselineSignatures: buildSnapshotSignatures(baselineNodes),
+    routeComparable: true,
   };
 
   mockDispatch

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

@@ -69,7 +69,7 @@ async function emulateCaptureSnapshotForSession(
     effectiveFlags.out,
     contextFromFlags(effectiveFlags, session.appBundleId, session.trace?.outPath),
   )) as { nodes?: never[]; truncated?: boolean; backend?: 'xctest' | 'android' | 'macos-helper' };
-  const snapshot = buildSnapshotState(snapshotData ?? {}, effectiveFlags.snapshotRaw);
+  const snapshot = buildSnapshotState(snapshotData ?? {}, effectiveFlags);
   session.snapshot = snapshot;
   sessionStore.set(session.name, session);
   return snapshot;

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

@@ -78,6 +78,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { handleSessionCommands } from '../session.ts';
+import { buildSnapshotSignatures } from '../../android-snapshot-freshness.ts';
 import {
   retainMaterializedPaths,
   cleanupRetainedMaterializedPathsForSession,
@@ -2624,6 +2625,63 @@ test('open intent target on existing Android session clears stale package contex
   expect(dispatchedContext?.appBundleId).toBe(undefined);
 });
 
+test('open on existing Android session preserves a comparable freshness baseline', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-open-freshness';
+  const baselineNodes = Array.from({ length: 14 }, (_, index) => ({
+    ref: `e${index + 1}`,
+    index,
+    depth: 0,
+    type: 'android.widget.TextView',
+    label: `Inbox row ${index + 1}`,
+  }));
+  sessionStore.set(sessionName, {
+    ...makeSession(sessionName, {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Pixel Emulator',
+      kind: 'emulator',
+      booted: true,
+    }),
+    appBundleId: 'com.example.old',
+    appName: 'Old App',
+    snapshot: {
+      nodes: baselineNodes,
+      createdAt: Date.now(),
+      backend: 'android',
+      comparisonSafe: true,
+    },
+  });
+
+  mockDispatch.mockResolvedValue({});
+  mockResolveAndroidPackage.mockResolvedValue('com.android.settings');
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'open',
+      positionals: ['settings'],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  expect(response?.ok).toBe(true);
+  const updated = sessionStore.get(sessionName);
+  expect(updated?.snapshot).toBeUndefined();
+  expect(updated?.androidSnapshotFreshness).toEqual({
+    action: 'open',
+    markedAt: expect.any(Number),
+    baselineCount: baselineNodes.length,
+    baselineSignatures: buildSnapshotSignatures(baselineNodes),
+    routeComparable: true,
+  });
+});
+
 test('open --relaunch closes and reopens active session app', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'android-session';

src/daemon/handlers/__tests__/snapshot-handler.test.ts

@@ -213,12 +213,14 @@ test('snapshot automatically retries stale Android trees after recent navigation
     nodes: baselineNodes,
     createdAt: Date.now(),
     backend: 'android',
+    comparisonSafe: true,
   };
   session.androidSnapshotFreshness = {
     action: 'press',
     markedAt: Date.now(),
     baselineCount: baselineNodes.length,
     baselineSignatures: buildSnapshotSignatures(baselineNodes),
+    routeComparable: true,
   };
   sessionStore.set(sessionName, session);
 
@@ -283,12 +285,14 @@ test('snapshot warns when Android freshness retries still return the previous ro
     nodes: baselineNodes,
     createdAt: Date.now(),
     backend: 'android',
+    comparisonSafe: true,
   };
   session.androidSnapshotFreshness = {
     action: 'press',
     markedAt: Date.now(),
     baselineCount: baselineNodes.length,
     baselineSignatures: buildSnapshotSignatures(baselineNodes),
+    routeComparable: true,
   };
   sessionStore.set(sessionName, session);
 
@@ -343,12 +347,14 @@ test('diff snapshot carries stale-tree warnings for recent Android presses', asy
     nodes: baselineNodes,
     createdAt: Date.now(),
     backend: 'android',
+    comparisonSafe: true,
   };
   session.androidSnapshotFreshness = {
     action: 'press',
     markedAt: Date.now(),
     baselineCount: baselineNodes.length,
     baselineSignatures: buildSnapshotSignatures(baselineNodes),
+    routeComparable: true,
   };
   sessionStore.set(sessionName, session);
 
@@ -403,12 +409,14 @@ test('wait text on Android uses freshness-aware capture instead of one-shot snap
     nodes: baselineNodes,
     createdAt: Date.now(),
     backend: 'android',
+    comparisonSafe: true,
   };
   session.androidSnapshotFreshness = {
     action: 'press',
     markedAt: Date.now(),
     baselineCount: baselineNodes.length,
     baselineSignatures: buildSnapshotSignatures(baselineNodes),
+    routeComparable: true,
   };
   sessionStore.set(sessionName, session);
 

src/daemon/handlers/find.ts

@@ -11,10 +11,7 @@ import { parseTimeout } from './parse-utils.ts';
 import { readTextForNode } from './interaction-read.ts';
 import { captureSnapshot } from './snapshot-capture.ts';
 import { errorResponse } from './response.ts';
-import {
-  getActiveAndroidSnapshotFreshness,
-  markAndroidSnapshotFreshness,
-} from '../android-snapshot-freshness.ts';
+import { getActiveAndroidSnapshotFreshness } from '../android-snapshot-freshness.ts';
 
 type FindContext = {
   req: DaemonRequest;
@@ -263,7 +260,6 @@ async function handleFindClick(ctx: FindContext, match: ResolvedMatch): Promise<
     matchData.y = matchCoords.y;
   }
   if (session) {
-    markAndroidSnapshotFreshness(session, 'click');
     sessionStore.recordAction(session, {
       command,
       positionals: req.positionals ?? [],

src/daemon/handlers/session-open.ts

@@ -157,6 +157,9 @@ async function completeOpenCommand(params: {
     };
   }
 
+  if (existingSession) {
+    markAndroidSnapshotFreshness(existingSession, 'open', existingSession.snapshot);
+  }
   const nextSession = buildNextOpenSession({
     existingSession,
     sessionName,
@@ -186,7 +189,6 @@ async function completeOpenCommand(params: {
     runtime: req.runtime !== undefined ? runtime : undefined,
     result: openResult,
   });
-  markAndroidSnapshotFreshness(nextSession, 'open');
   sessionStore.set(sessionName, nextSession);
   return { ok: true, data: openResult };
 }

src/daemon/handlers/snapshot-capture.ts

@@ -37,6 +37,8 @@ type SnapshotData = {
   analysis?: AndroidSnapshotAnalysis;
 };
 
+type AndroidFreshnessReason = 'empty-interactive' | 'sharp-drop' | 'stuck-route';
+
 export async function captureSnapshot(params: CaptureSnapshotParams): Promise<{
   snapshot: SnapshotState;
   analysis?: AndroidSnapshotAnalysis;
@@ -49,7 +51,7 @@ export async function captureSnapshot(params: CaptureSnapshotParams): Promise<{
   const data = await captureSnapshotData(params);
   clearAndroidSnapshotFreshness(params.session);
   return {
-    snapshot: buildSnapshotState(data, params.flags?.snapshotRaw),
+    snapshot: buildSnapshotState(data, params.flags),
     analysis: data.analysis,
   };
 }
@@ -85,30 +87,31 @@ async function captureAndroidFreshnessAwareSnapshot(
   freshness?: AndroidFreshnessCaptureMeta;
 }> {
   let latest = await captureSnapshotAttempt(params);
-  let suspicious = isSuspiciousAndroidFreshnessCapture(latest, freshness, params.flags);
+  let suspiciousReason = getAndroidFreshnessReason(latest, freshness, params.flags);
   let retryCount = 0;
 
   for (const delayMs of ANDROID_FRESHNESS_RETRY_DELAYS_MS) {
-    if (!suspicious) break;
+    if (!suspiciousReason) break;
     await new Promise((resolve) => setTimeout(resolve, delayMs));
     latest = await captureSnapshotAttempt(params);
     retryCount += 1;
-    suspicious = isSuspiciousAndroidFreshnessCapture(latest, freshness, params.flags);
+    suspiciousReason = getAndroidFreshnessReason(latest, freshness, params.flags);
   }
 
-  if (!suspicious) {
+  if (!suspiciousReason) {
     clearAndroidSnapshotFreshness(params.session);
   }
 
   return {
     snapshot: latest.snapshot,
     analysis: latest.data.analysis,
     freshness:
-      retryCount > 0 || suspicious
+      retryCount > 0 || Boolean(suspiciousReason)
         ? {
             action: freshness.action,
             retryCount,
-            staleAfterRetries: suspicious,
+            staleAfterRetries: Boolean(suspiciousReason),
+            reason: suspiciousReason ?? undefined,
           }
         : undefined,
   };
@@ -120,15 +123,15 @@ async function captureSnapshotAttempt(
   const data = await captureSnapshotData(params);
   return {
     data,
-    snapshot: buildSnapshotState(data, params.flags?.snapshotRaw),
+    snapshot: buildSnapshotState(data, params.flags),
   };
 }
 
-function isSuspiciousAndroidFreshnessCapture(
+function getAndroidFreshnessReason(
   attempt: { data: SnapshotData; snapshot: SnapshotState },
   freshness: NonNullable<SessionState['androidSnapshotFreshness']>,
   flags: CommandFlags | undefined,
-): boolean {
+): AndroidFreshnessReason | null {
   const interactiveOnly = flags?.snapshotInteractiveOnly === true;
   const analysis = attempt.data.analysis;
 
@@ -138,17 +141,18 @@ function isSuspiciousAndroidFreshnessCapture(
     analysis &&
     analysis.rawNodeCount >= 12
   ) {
-    return true;
+    return 'empty-interactive';
   }
 
   if (isLikelyStaleSnapshotDrop(freshness.baselineCount, attempt.snapshot.nodes.length)) {
-    return !hasMeaningfulSnapshotContent(attempt.snapshot);
+    return !hasMeaningfulSnapshotContent(attempt.snapshot) ? 'sharp-drop' : null;
   }
 
-  return (
+  return freshness.routeComparable &&
     isNavigationSensitiveAction(freshness.action) &&
     isLikelySnapshotStuckOnPreviousRoute(freshness.baselineSignatures, attempt.snapshot.nodes)
-  );
+    ? 'stuck-route'
+    : null;
 }
 
 function hasMeaningfulSnapshotContent(snapshot: SnapshotState): boolean {
@@ -167,15 +171,28 @@ export function buildSnapshotState(
     truncated?: boolean;
     backend?: 'xctest' | 'android' | 'macos-helper';
   },
-  snapshotRaw: boolean | undefined,
+  flags:
+    | (Pick<
+        CommandFlags,
+        'snapshotCompact' | 'snapshotDepth' | 'snapshotInteractiveOnly' | 'snapshotRaw'
+      > &
+        Partial<Pick<CommandFlags, 'snapshotScope'>>)
+    | undefined,
 ): SnapshotState {
   const rawNodes = data?.nodes ?? [];
+  const snapshotRaw = flags?.snapshotRaw;
   const nodes = attachRefs(snapshotRaw ? rawNodes : pruneGroupNodes(rawNodes));
   return {
     nodes,
     truncated: data?.truncated,
     createdAt: Date.now(),
     backend: data?.backend,
+    comparisonSafe:
+      data?.backend === 'android' &&
+      flags?.snapshotInteractiveOnly !== true &&
+      flags?.snapshotCompact !== true &&
+      typeof flags?.snapshotDepth !== 'number' &&
+      !flags?.snapshotScope,
   };
 }