fix: guard the AMBIGUOUS_MATCH candidate renderer against device-domain shapes

Review on #1602 (P2): formatAmbiguousMatchCandidateLines ran for every
normalized error and stringified details.candidates unconditionally,
but device-domain AMBIGUOUS_MATCH/APP_NOT_INSTALLED errors
(findBootedAppleSimulatorWithApp, src/core/dispatch-resolve.ts) reuse
that key for { id, name } device objects with no `matches` field —
CLI and MCP would have printed "Candidates: [object Object]" for
those. The renderer now requires numeric details.matches AND every
candidate to be a string before rendering anything, restricting it to
buildAmbiguousMatchError's element-match shape; unrecognized shapes
render nothing, same as before this feature existed. Added regression
tests against the exact device-error shape on both text surfaces.

Also unexports AMBIGUOUS_MATCH_CANDIDATE_LIMIT (fallow flagged it as
an unused production export) — it has no consumer outside find.ts.

Author: thymikee

src/daemon/handlers/find.ts

@@ -547,7 +547,9 @@ function publicFindFlags(flags: DaemonRequest['flags']): Record<string, unknown>
 // label/identifier. Capped at AMBIGUOUS_MATCH_CANDIDATE_LIMIT to bound the
 // error payload — `matches` (the true total) is what a "+N more" marker is
 // computed from at render time (src/utils/output.ts, src/mcp/tool-error.ts).
-export const AMBIGUOUS_MATCH_CANDIDATE_LIMIT = 5;
+// Module-local: no consumer outside this file needs the raw cap, only the
+// already-capped `candidates` array on the response.
+const AMBIGUOUS_MATCH_CANDIDATE_LIMIT = 5;
 
 // Exported as the single AMBIGUOUS_MATCH producer so the help-benchmark
 // sample parity test renders the exact error this handler returns; a message

src/mcp/__tests__/tool-error.test.ts

@@ -37,3 +37,26 @@ test('formatToolErrorText omits the candidates block for non-ambiguous errors',
 
   assert.equal(text.includes('Candidates:'), false);
 });
+
+// P2 review on #1597: device-domain AMBIGUOUS_MATCH (findBootedAppleSimulatorWithApp,
+// src/core/dispatch-resolve.ts) reuses `details.candidates` for `{ id, name }`
+// device objects with no `matches` field — must never render as
+// "Candidates:\n  [object Object]" on the MCP text path either.
+test('formatToolErrorText renders device-domain candidate objects as nothing, never [object Object]', () => {
+  const err = new AppError(
+    'AMBIGUOUS_MATCH',
+    'Multiple booted iOS simulators have com.example.app installed',
+    {
+      appTarget: 'com.example.app',
+      candidates: [
+        { id: 'SIM-001', name: 'iPhone 17 Pro' },
+        { id: 'SIM-002', name: 'iPhone 17' },
+      ],
+    },
+  );
+
+  const text = formatToolErrorText(normalizeToolError(err));
+
+  assert.equal(text.includes('[object Object]'), false);
+  assert.equal(text.includes('Candidates:'), false);
+});

src/utils/__tests__/output.test.ts

@@ -1786,6 +1786,48 @@ test('formatAmbiguousMatchCandidateLines returns nothing when details carry no c
   assert.deepEqual(formatAmbiguousMatchCandidateLines({ candidates: [] }), []);
 });
 
+// P2 review on #1597: `details.candidates` is not unique to the find
+// handler's element-match shape. The device-domain resolver
+// (findBootedAppleSimulatorWithApp, src/core/dispatch-resolve.ts) reuses the
+// same key for `{ id, name }` device objects on both AMBIGUOUS_MATCH and
+// APP_NOT_INSTALLED, and never sets `details.matches` — this must render
+// nothing (its behavior before this renderer existed), never
+// "Candidates:\n  [object Object]".
+test('printHumanError renders device-domain candidate objects as nothing, never [object Object]', () => {
+  const deviceCandidates = [
+    { id: 'SIM-001', name: 'iPhone 17 Pro' },
+    { id: 'SIM-002', name: 'iPhone 17' },
+  ];
+
+  const ambiguousDeviceErr = new AppError(
+    'AMBIGUOUS_MATCH',
+    'Multiple booted iOS simulators have com.example.app installed',
+    { appTarget: 'com.example.app', candidates: deviceCandidates },
+  );
+  const ambiguousOutput = captureStderr(() => printHumanError(ambiguousDeviceErr));
+  assert.equal(ambiguousOutput.includes('[object Object]'), false);
+  assert.equal(ambiguousOutput.includes('Candidates:'), false);
+
+  const notInstalledErr = new AppError(
+    'APP_NOT_INSTALLED',
+    'No booted iOS simulator has com.example.app installed',
+    { appTarget: 'com.example.app', candidates: deviceCandidates },
+  );
+  const notInstalledOutput = captureStderr(() => printHumanError(notInstalledErr));
+  assert.equal(notInstalledOutput.includes('[object Object]'), false);
+  assert.equal(notInstalledOutput.includes('Candidates:'), false);
+
+  // The formatter itself, not just the CLI render, must reject this shape —
+  // both the missing `matches` and the object-shaped entries disqualify it.
+  assert.deepEqual(
+    formatAmbiguousMatchCandidateLines({
+      appTarget: 'com.example.app',
+      candidates: deviceCandidates,
+    }),
+    [],
+  );
+});
+
 test('printHumanError shows an unavailable screen reason and omitted suggestions hint', () => {
   const err = new AppError('REPLAY_DIVERGENCE', 'Replay failed at step 1', {
     divergence: {

src/utils/output.ts

@@ -70,16 +70,28 @@ export function printHumanError(
 // AMBIGUOUS_MATCH_CANDIDATE_LIMIT by buildAmbiguousMatchError,
 // src/daemon/handlers/find.ts) and `details.matches` (the true total) to
 // compute the "+N more" marker for whatever the cap omitted.
+//
+// `details.candidates` is NOT unique to that one producer: the device-domain
+// AMBIGUOUS_MATCH/APP_NOT_INSTALLED resolvers (findBootedAppleSimulatorWithApp,
+// src/core/dispatch-resolve.ts) reuse the same key for `{ id, name }` device
+// objects, and never set `details.matches` at all. Both guards below —
+// numeric `matches` and every candidate being a pre-rendered string — must
+// hold together, or this renders "[object Object]" for that shape instead of
+// silently rendering nothing (its prior, pre-#1597 behavior).
 export function formatAmbiguousMatchCandidateLines(
   details: Record<string, unknown> | undefined,
 ): string[] {
   const candidates = details?.candidates;
   if (!Array.isArray(candidates) || candidates.length === 0) return [];
-  const totalMatches = typeof details?.matches === 'number' ? details.matches : candidates.length;
+  if (typeof details?.matches !== 'number') return [];
+  if (!candidates.every((candidate): candidate is string => typeof candidate === 'string')) {
+    return [];
+  }
+  const totalMatches = details.matches;
   const remaining = totalMatches - candidates.length;
   return [
     'Candidates:',
-    ...candidates.map((candidate) => `  ${String(candidate)}`),
+    ...candidates.map((candidate) => `  ${candidate}`),
     ...(remaining > 0 ? [`  +${remaining} more`] : []),
   ];
 }