fix(android): bound the scroll-hint dumpsys probe and skip it in wait polling (#1270) (#1288)

* fix(android): bound the scroll-hint dumpsys probe and skip it in wait polling (#1270)

deriveScrollableContentHintsIfNeeded's dumpsys activity top probe ran
with an 8s timeout equal to a whole wait/get budget, and measured
latency ranges from 37ms to ~5.9s under contention. Cap it at 1.5s so
one pathological call can't starve a caller's timeout, and skip hint
derivation entirely during find ... wait polling, since a presence
check never consumes scroll hints.

The wait polling loop actually lives in
commands/interaction/runtime/selector-read.ts's waitForFindMatch
(daemon/handlers/find.ts's own handleFindWait is unreachable for wait
today — dispatchFindReadOnlyViaRuntime always intercepts read-only
find actions first), so the skip-hints option threads through that
capture path down to snapshotAndroid via the existing
flags -> contextFromFlags -> dispatchCommand -> interactor.snapshot
channel.

* fix(android): skip scroll-hint derivation in standalone wait polling too (#1270)

The issue's motivating repro — wait 'label="Battery"' 8000 — polls
waitForSelector, not the find-wait loop, and text/ref waits poll
waitForText (backend.findText -> captureWaitSnapshot on the daemon, or
the snapshotContainsText fallback). All three presence-only polling
captures now disable hidden-content-hint derivation, matching the
Android alert-wait capture which already did. Stable wait keeps full
snapshot semantics.

Adds daemon-route regressions for the exact repro shape on both the
selector-wait and text-wait routes, asserting every per-poll snapshot
dispatch carries snapshotIncludeHiddenContentHints: false.

Author: thymikee

src/backend.ts

@@ -63,6 +63,7 @@ export type BackendSnapshotResult = {
 
 export type BackendSnapshotOptions = SnapshotOptions & {
   includeRects?: boolean;
+  includeHiddenContentHints?: boolean;
   outPath?: string;
 };
 

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

@@ -51,6 +51,7 @@ export async function captureSelectorSnapshot(
     scope?: string;
     includeRects?: boolean;
     interactiveOnly?: boolean;
+    includeHiddenContentHints?: boolean;
   } = {
     updateSession: true,
   },
@@ -67,6 +68,9 @@ export async function captureSelectorSnapshot(
     scope: captureOptions.scope ?? options.scope,
     raw: options.raw,
     includeRects: captureOptions.includeRects,
+    ...(captureOptions.includeHiddenContentHints !== undefined
+      ? { includeHiddenContentHints: captureOptions.includeHiddenContentHints }
+      : {}),
   });
   const snapshot =
     result.snapshot ??

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

@@ -406,6 +406,50 @@ test('runtime find wait reports sparse snapshot verdicts on the selector-read ro
   assert.equal(session.snapshot, initialSnapshot);
 });
 
+test('runtime find wait skips hidden-content hint derivation on every poll (#1270)', async () => {
+  // A `wait`'s presence check never consumes scroll hints, so every poll must ask the capture
+  // layer to skip deriving them — otherwise a single pathological `dumpsys activity top` call
+  // can eat the whole wait budget from inside this loop.
+  const snapshot = selectorReadSnapshot();
+  const captureOptionsCalls: Array<BackendSnapshotOptions | undefined> = [];
+  let elapsed = 0;
+  const device = createAgentDevice({
+    backend: {
+      platform: 'android',
+      captureSnapshot: async (_context, options) => {
+        captureOptionsCalls.push(options);
+        return { snapshot };
+      },
+    } satisfies AgentDeviceBackend,
+    artifacts: createLocalArtifactAdapter(),
+    sessions: createMemorySessionStore([{ name: 'default', snapshot }]),
+    policy: localCommandPolicy(),
+    clock: {
+      now: () => elapsed,
+      sleep: async () => {
+        elapsed += 300;
+      },
+    },
+  });
+
+  await assert.rejects(
+    () =>
+      device.selectors.find({
+        session: 'default',
+        locator: 'text',
+        query: 'Never appears',
+        action: 'wait',
+        timeoutMs: 500,
+      }),
+    /find wait timed out/,
+  );
+
+  assert.equal(captureOptionsCalls.length >= 2, true);
+  for (const options of captureOptionsCalls) {
+    assert.equal(options?.includeHiddenContentHints, false);
+  }
+});
+
 test('runtime wait can use backend text search', async () => {
   const device = createSelectorDevice(selectorReadSnapshot(), {
     findText: true,

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

@@ -448,7 +448,12 @@ async function waitForFindMatch(
   const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const start = now(runtime);
   while (now(runtime) - start < timeout) {
-    const { match } = await findFirstLocatorMatch(runtime, options, locator);
+    // A presence check never consumes scroll hints, so every poll skips deriving them —
+    // otherwise a single pathological `dumpsys activity top` call can eat the whole wait
+    // budget from inside this loop (#1270).
+    const { match } = await findFirstLocatorMatch(runtime, options, locator, {
+      includeHiddenContentHints: false,
+    });
     if (match) return { kind: 'found', found: true, waitedMs: now(runtime) - start };
     await sleep(runtime, POLL_INTERVAL_MS);
   }
@@ -459,11 +464,13 @@ async function findFirstLocatorMatch(
   runtime: AgentDeviceRuntime,
   options: FindReadCommandOptions,
   locator: FindLocator,
+  captureOverrides?: { includeHiddenContentHints?: boolean },
 ): Promise<{ capture: CapturedSnapshot; match: SnapshotNode | undefined }> {
   const selectorChain = parseFindSelectorExpression(locator, options.query);
   const capture = await captureSelectorSnapshot(runtime, options, {
     updateSession: true,
     scope: findSnapshotScope(runtime, locator, options.query, selectorChain),
+    includeHiddenContentHints: captureOverrides?.includeHiddenContentHints,
     ...deriveSelectorCapturePolicy({ selectorChain }),
   });
   if (isSparseSnapshotQualityVerdict(capture.snapshot.snapshotQuality)) {
@@ -512,8 +519,10 @@ async function waitForSelector(
   const chain = parseSelectorChain(selectorExpression);
   const capturePolicy = deriveSelectorCapturePolicy({ selectorChain: chain });
   while (now(runtime) - start < timeout) {
+    // Presence-only poll: skip scroll-hint derivation (#1270), same as waitForFindMatch.
     const capture = await captureSelectorSnapshot(runtime, options, {
       updateSession: true,
+      includeHiddenContentHints: false,
       ...capturePolicy,
     });
     const match = findSelectorChainMatch(capture.snapshot.nodes, chain, {
@@ -549,7 +558,11 @@ async function snapshotContainsText(
   options: WaitCommandOptions,
   text: string,
 ): Promise<boolean> {
-  const capture = await captureSelectorSnapshot(runtime, options, { updateSession: true });
+  // Presence-only poll: skip scroll-hint derivation (#1270), same as waitForFindMatch.
+  const capture = await captureSelectorSnapshot(runtime, options, {
+    updateSession: true,
+    includeHiddenContentHints: false,
+  });
   return Boolean(findNodeByLabel(capture.snapshot.nodes, text));
 }
 

src/core/dispatch-context.ts

@@ -26,6 +26,7 @@ export type CommandFlags = Omit<CliFlags, DaemonExcludedCliFlag> & {
   kind?: string;
   maestro?: MaestroRuntimeFlags;
   postGestureStabilization?: boolean;
+  snapshotIncludeHiddenContentHints?: boolean;
   leaseProvider?: string;
   provider?: string;
   deviceKey?: string;
@@ -61,6 +62,7 @@ export type DispatchContext = ScreenshotDispatchFlags & {
   snapshotScope?: string;
   snapshotRaw?: boolean;
   snapshotIncludeRects?: boolean;
+  snapshotIncludeHiddenContentHints?: boolean;
   skipIosSimulatorBootCheck?: boolean;
   count?: number;
   intervalMs?: number;

src/core/dispatch.ts

@@ -636,6 +636,7 @@ async function handleSnapshotCommand(
     scope: context?.snapshotScope,
     raw: context?.snapshotRaw,
     includeRects: context?.snapshotIncludeRects,
+    includeHiddenContentHints: context?.snapshotIncludeHiddenContentHints,
     surface: context?.surface,
   });
 }

src/core/interactor-types.ts

@@ -72,6 +72,7 @@ export const MAESTRO_NON_HITTABLE_FALLBACK_MESSAGE = 'tapped via non-hittable co
 export type SnapshotOptions = BaseSnapshotOptions & {
   appBundleId?: string;
   includeRects?: boolean;
+  includeHiddenContentHints?: boolean;
   surface?: SessionSurface;
 };
 

src/core/interactors/android.ts

@@ -66,6 +66,7 @@ export function createAndroidInteractor(device: DeviceInfo): Interactor {
             depth: options?.depth,
             scope: options?.scope,
             raw: options?.raw,
+            includeHiddenContentHints: options?.includeHiddenContentHints,
             // appBundleId is present for app-backed daemon sessions; keep the helper warm there,
             // but release it after standalone device snapshots so UiAutomation is not squatted.
             helperSessionScope: options?.appBundleId ? 'daemon-session' : 'command',

src/daemon/context.ts

@@ -41,6 +41,7 @@ export function contextFromFlags(
     snapshotDepth: flags?.snapshotDepth,
     snapshotScope: flags?.snapshotScope,
     snapshotRaw: flags?.snapshotRaw,
+    snapshotIncludeHiddenContentHints: flags?.snapshotIncludeHiddenContentHints,
     ...screenshotFlagsFromOptions(flags),
     count: flags?.count,
     intervalMs: flags?.intervalMs,

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

@@ -1543,6 +1543,79 @@ test('wait selector timeout includes compact current-surface details', async ()
   }
 });
 
+test('wait selector polling skips hidden-content hint derivation on every poll (#1270)', async () => {
+  // The #1270 repro: `wait 'label="Battery"' 8000` on Android. A presence-only wait never
+  // consumes scroll hints, so every per-poll snapshot capture must disable hint derivation —
+  // otherwise a pathological `dumpsys activity top` call is charged against the wait budget.
+  const sessionName = 'android-wait-selector-skips-hints';
+  const withoutBattery = {
+    nodes: locationRequiredNodes,
+    truncated: false,
+    backend: 'android',
+    analysis: { rawNodeCount: 2, maxDepth: 0 },
+  };
+  const withBattery = {
+    nodes: [
+      {
+        index: 0,
+        depth: 0,
+        type: 'android.widget.TextView',
+        label: 'Battery',
+        rect: { x: 252, y: 780, width: 153, height: 65 },
+      },
+    ],
+    truncated: false,
+    backend: 'android',
+    analysis: { rawNodeCount: 1, maxDepth: 0 },
+  };
+  mockDispatch.mockResolvedValueOnce(withoutBattery).mockResolvedValueOnce(withBattery);
+
+  const response = await runWaitCommand(sessionName, androidDevice, ['label="Battery"', '8000']);
+
+  expect(response?.ok).toBe(true);
+  const snapshotCalls = mockDispatch.mock.calls.filter(([, command]) => command === 'snapshot');
+  expect(snapshotCalls.length).toBe(2);
+  for (const call of snapshotCalls) {
+    const context = call[4] as { snapshotIncludeHiddenContentHints?: boolean } | undefined;
+    expect(context?.snapshotIncludeHiddenContentHints).toBe(false);
+  }
+});
+
+test('wait text polling skips hidden-content hint derivation on every poll (#1270)', async () => {
+  const sessionName = 'android-wait-text-skips-hints';
+  const withoutBattery = {
+    nodes: locationRequiredNodes,
+    truncated: false,
+    backend: 'android',
+    analysis: { rawNodeCount: 2, maxDepth: 0 },
+  };
+  const withBattery = {
+    nodes: [
+      {
+        index: 0,
+        depth: 0,
+        type: 'android.widget.TextView',
+        label: 'Battery',
+        rect: { x: 252, y: 780, width: 153, height: 65 },
+      },
+    ],
+    truncated: false,
+    backend: 'android',
+    analysis: { rawNodeCount: 1, maxDepth: 0 },
+  };
+  mockDispatch.mockResolvedValueOnce(withoutBattery).mockResolvedValueOnce(withBattery);
+
+  const response = await runWaitCommand(sessionName, androidDevice, ['Battery', '8000']);
+
+  expect(response?.ok).toBe(true);
+  const snapshotCalls = mockDispatch.mock.calls.filter(([, command]) => command === 'snapshot');
+  expect(snapshotCalls.length).toBe(2);
+  for (const call of snapshotCalls) {
+    const context = call[4] as { snapshotIncludeHiddenContentHints?: boolean } | undefined;
+    expect(context?.snapshotIncludeHiddenContentHints).toBe(false);
+  }
+});
+
 test('wait timeout summary prefers content labels over chrome and identifier noise', async () => {
   const sessionName = 'ios-wait-timeout-surface-summary';
   mockRunnerCommand.mockResolvedValue({ found: false });