fix: preserve ranked Maestro replay suggestions

Author: thymikee

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

@@ -7,12 +7,18 @@ vi.mock('../../../core/dispatch.ts', async (importOriginal) => {
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { buildTypedMaestroFailureReportProjection } from '../session-replay-maestro-failure.ts';
+import {
+  buildTypedMaestroFailureReportProjection,
+  buildTypedMaestroFailureResponse,
+} from '../session-replay-maestro-failure.ts';
 import { runReplayScriptFile } from '../session-replay-runtime.ts';
 import { SessionStore } from '../../session-store.ts';
 import { dispatchCommand } from '../../../core/dispatch.ts';
 import { makeIosSession } from '../../../__tests__/test-utils/session-factories.ts';
 import { baseReplayRequest as baseReq } from './session-replay-runtime.fixtures.ts';
+import type { MaestroCommand } from '../../../compat/maestro/program-ir.ts';
+import type { MaestroReplayPlan } from '../../../compat/maestro/replay-plan-types.ts';
+import type { SnapshotNode } from '../../../kernel/snapshot.ts';
 
 const mockDispatchCommand = vi.mocked(dispatchCommand);
 
@@ -21,6 +27,54 @@ beforeEach(() => {
   mockDispatchCommand.mockResolvedValue({});
 });
 
+function makeMaestroPlan(): MaestroReplayPlan {
+  return {
+    kind: 'maestroReplayPlan',
+    platform: 'ios',
+    initialStaticEnv: {},
+    steps: [],
+    total: 1,
+    digest: 'typed-maestro-test-plan',
+    compatibility: {
+      staticallyExecutedControls: 0,
+      staticallySkippedControls: 0,
+    },
+  };
+}
+
+async function buildFailureResponse(
+  command: MaestroCommand,
+  nodes: SnapshotNode[],
+): Promise<Extract<Awaited<ReturnType<typeof buildTypedMaestroFailureResponse>>, { ok: false }>> {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-maestro-suggestions-'));
+  const sessionName = 'default';
+  const sessionStore = new SessionStore(path.join(root, 'sessions'));
+  sessionStore.set(sessionName, makeIosSession(sessionName));
+  mockDispatchCommand.mockResolvedValue({ nodes, truncated: false, backend: 'xctest' });
+  const response = await buildTypedMaestroFailureResponse({
+    error: { code: 'COMMAND_FAILED', message: 'typed Maestro action failed' },
+    event: {
+      command,
+      source: command.source,
+      generation: 0,
+      stepIndex: 1,
+      stepTotal: 1,
+      durationMs: 12,
+      error: new Error('typed Maestro action failed'),
+      artifactPaths: [],
+      expandedVariables: {},
+    },
+    plan: makeMaestroPlan(),
+    replayPath: path.join(root, 'flow.yaml'),
+    req: baseReq({ flags: { replayBackend: 'maestro', platform: 'ios' } }),
+    sessionName,
+    sessionStore,
+    logPath: path.join(root, 'daemon.log'),
+  });
+  if (response.ok) throw new Error('expected typed Maestro failure response');
+  return response;
+}
+
 test('typed Maestro failure projection is report-only and preserves authored provenance', () => {
   const command = {
     kind: 'tapOn' as const,
@@ -221,3 +275,140 @@ test('typed Maestro nested scopes scrub failure values after unwind and keep ret
     }),
   ]);
 });
+
+test('typed Maestro suggestions rank visible childOf candidates and exclude out-of-scope nodes', async () => {
+  const command = {
+    kind: 'tapOn' as const,
+    source: { path: '/flows/actions.yaml', line: 4 },
+    target: { space: 'target' as const, selector: { text: 'save.*' } },
+    childOf: { id: 'actions' },
+  } satisfies Extract<MaestroCommand, { kind: 'tapOn' }>;
+  const response = await buildFailureResponse(command, [
+    {
+      ref: 'e1',
+      index: 0,
+      type: 'Application',
+      rect: { x: 0, y: 0, width: 402, height: 874 },
+    },
+    {
+      ref: 'e2',
+      index: 1,
+      parentIndex: 0,
+      identifier: 'actions',
+      type: 'View',
+      rect: { x: 0, y: 0, width: 402, height: 300 },
+    },
+    {
+      ref: 'e3',
+      index: 2,
+      parentIndex: 1,
+      identifier: 'save-primary',
+      label: 'Primary',
+      type: 'Button',
+      rect: { x: 16, y: 40, width: 140, height: 44 },
+      hittable: true,
+    },
+    {
+      ref: 'e4',
+      index: 3,
+      parentIndex: 1,
+      identifier: 'secondary',
+      label: 'Save secondary',
+      type: 'Button',
+      rect: { x: 16, y: 96, width: 140, height: 44 },
+      hittable: true,
+    },
+    {
+      ref: 'e5',
+      index: 4,
+      parentIndex: 0,
+      identifier: 'save-outside',
+      label: 'Save outside',
+      type: 'Button',
+      rect: { x: 16, y: 152, width: 140, height: 44 },
+      hittable: true,
+    },
+    {
+      ref: 'e6',
+      index: 5,
+      parentIndex: 1,
+      identifier: 'save-hidden',
+      label: 'Save hidden',
+      type: 'Button',
+      rect: { x: 16, y: 208, width: 140, height: 0 },
+      hittable: false,
+    },
+  ]);
+  const divergence = response.error.details?.divergence as {
+    suggestionCount: number;
+    suggestions: Array<{ selector: string; basis: string }>;
+  };
+
+  expect(divergence.suggestions).toHaveLength(2);
+  expect(divergence.suggestions.map(({ basis }) => basis)).toEqual(['id', 'label']);
+  expect(divergence.suggestions[0]?.selector).toContain('save-primary');
+  expect(divergence.suggestions[1]?.selector).toContain('Save secondary');
+  expect(divergence.suggestionCount).toBe(2);
+});
+
+test('typed Maestro text matching an identifier reports id basis', async () => {
+  const command = {
+    kind: 'tapOn' as const,
+    source: { path: '/flows/actions.yaml', line: 4 },
+    target: { space: 'target' as const, selector: { text: 'accessibility-save' } },
+  } satisfies Extract<MaestroCommand, { kind: 'tapOn' }>;
+  const response = await buildFailureResponse(command, [
+    {
+      ref: 'e1',
+      index: 0,
+      type: 'Application',
+      rect: { x: 0, y: 0, width: 402, height: 874 },
+    },
+    {
+      ref: 'e2',
+      index: 1,
+      parentIndex: 0,
+      identifier: 'accessibility-save',
+      type: 'Button',
+      rect: { x: 16, y: 40, width: 140, height: 44 },
+      hittable: true,
+    },
+  ]);
+  const divergence = response.error.details?.divergence as {
+    suggestions: Array<{ basis: string }>;
+  };
+
+  expect(divergence.suggestions).toEqual([expect.objectContaining({ basis: 'id' })]);
+});
+
+test('typed Maestro suggestions retain total count before the five-entry cap', async () => {
+  const command = {
+    kind: 'tapOn' as const,
+    source: { path: '/flows/actions.yaml', line: 4 },
+    target: { space: 'target' as const, selector: { label: 'Save' } },
+  } satisfies Extract<MaestroCommand, { kind: 'tapOn' }>;
+  const response = await buildFailureResponse(command, [
+    {
+      ref: 'e1',
+      index: 0,
+      type: 'Application',
+      rect: { x: 0, y: 0, width: 402, height: 874 },
+    },
+    ...Array.from({ length: 6 }, (_, offset) => ({
+      ref: `e${offset + 2}`,
+      index: offset + 1,
+      parentIndex: 0,
+      label: 'Save',
+      type: 'Button',
+      rect: { x: 16, y: 40 + offset * 50, width: 140, height: 44 },
+      hittable: true,
+    })),
+  ]);
+  const divergence = response.error.details?.divergence as {
+    suggestionCount: number;
+    suggestions: unknown[];
+  };
+
+  expect(divergence.suggestionCount).toBe(6);
+  expect(divergence.suggestions).toHaveLength(5);
+});

src/daemon/handlers/session-replay-maestro-failure.ts

@@ -3,9 +3,18 @@ import { formatMaestroCommandProgress } from '../../compat/maestro/progress.ts';
 import type { MaestroCommand, MaestroSelector } from '../../compat/maestro/program-ir.ts';
 import { evaluateMaestroReplayResume } from '../../compat/maestro/replay-plan.ts';
 import type { MaestroReplayPlan } from '../../compat/maestro/replay-plan-types.ts';
-import { resolveMaestroTargetFromSnapshot } from '../../compat/maestro/runtime-targets.ts';
+import { findMaestroTypedSelectorMatches } from '../../compat/maestro/runtime-target-matching.ts';
+import {
+  filterVisibleMaestroMatches,
+  matchesMaestroTypedSelector,
+} from '../../compat/maestro/runtime-target-policy.ts';
+import { normalizeMaestroSnapshotMatches } from '../../compat/maestro/runtime-target-ranking.ts';
 import type { DaemonError } from '../../kernel/contracts.ts';
 import type { SnapshotNode } from '../../kernel/snapshot.ts';
+import {
+  buildSnapshotNodeByIndex,
+  isDescendantOfSnapshotNode,
+} from '../../snapshot/snapshot-processing.ts';
 import {
   REPLAY_DIVERGENCE_SUGGESTION_LIMIT,
   createReplayDivergenceSanitizer,
@@ -192,17 +201,57 @@ function collectTypedMaestroSuggestions(params: {
   const query = typedSuggestionQuery(params.command);
   if (!query || (params.platform !== 'android' && params.platform !== 'ios')) return [];
   const snapshot = { createdAt: Date.now(), nodes: params.nodes };
-  const resolution = resolveMaestroTargetFromSnapshot(snapshot, query, params.platform);
-  if (!resolution.ok) return [];
-  return [
-    buildReplayDivergenceSuggestionForNode({
-      node: resolution.node,
-      session: params.session,
-      action: params.action,
-      basis: suggestionBasis(query.selector),
-      sanitize: params.sanitize,
-    }),
-  ];
+  const candidates = collectTypedMaestroCandidates(snapshot, query, params.platform);
+  const byNode = new Map<number, { node: SnapshotNode; basis: TypedSuggestionBasis }>();
+  for (const node of candidates) {
+    const basis = suggestionBasis(query.selector, node);
+    const existing = byNode.get(node.index);
+    if (!existing || typedSuggestionBasisRank(basis) < typedSuggestionBasisRank(existing.basis)) {
+      byNode.set(node.index, { node, basis });
+    }
+  }
+  return [...byNode.values()]
+    .sort(
+      (left, right) =>
+        typedSuggestionBasisRank(left.basis) - typedSuggestionBasisRank(right.basis) ||
+        left.node.index - right.node.index,
+    )
+    .map(({ node, basis }) =>
+      buildReplayDivergenceSuggestionForNode({
+        node,
+        session: params.session,
+        action: params.action,
+        basis,
+        sanitize: params.sanitize,
+      }),
+    );
+}
+
+type TypedSuggestionBasis = 'id' | 'label' | 'other';
+
+function collectTypedMaestroCandidates(
+  snapshot: { nodes: SnapshotNode[]; createdAt: number },
+  query: TypedSuggestionQuery,
+  platform: Extract<MaestroReplayPlan['platform'], 'android' | 'ios'>,
+): SnapshotNode[] {
+  let matches = findMaestroTypedSelectorMatches(snapshot, query.selector);
+  if (query.childOf) {
+    const parents = findMaestroTypedSelectorMatches(snapshot, query.childOf);
+    if (parents.length === 0) return [];
+    const nodeByIndex = buildSnapshotNodeByIndex(snapshot.nodes);
+    matches = matches.filter((node) =>
+      parents.some((parent) =>
+        isDescendantOfSnapshotNode(snapshot.nodes, node, parent, nodeByIndex),
+      ),
+    );
+  }
+
+  const visible = filterVisibleMaestroMatches({
+    nodes: snapshot.nodes,
+    matches,
+    platform,
+  });
+  return normalizeMaestroSnapshotMatches(snapshot.nodes, visible.matches, query.selector, platform);
 }
 
 type TypedSuggestionQuery = {
@@ -275,12 +324,27 @@ function observationSuggestion(command: ObservationCommand): TypedSuggestionQuer
   }
 }
 
-function suggestionBasis(selector: MaestroSelector): 'id' | 'label' | 'other' {
+function suggestionBasis(selector: MaestroSelector, node: SnapshotNode): TypedSuggestionBasis {
   if (selector.id !== undefined) return 'id';
+  if (
+    selector.text !== undefined &&
+    matchesMaestroTypedSelector(
+      { ...node, label: undefined, value: undefined },
+      { text: selector.text },
+    )
+  ) {
+    return 'id';
+  }
   if (selector.text !== undefined || selector.label !== undefined) return 'label';
   return 'other';
 }
 
+function typedSuggestionBasisRank(basis: TypedSuggestionBasis): number {
+  if (basis === 'id') return 0;
+  if (basis === 'label') return 2;
+  return 3;
+}
+
 function reportCommandForCapture(command: string): string {
   if (command === 'tapOn' || command === 'doubleTapOn') return 'click';
   if (command === 'longPressOn') return 'longpress';