@@ -106,6 +106,18 @@ test('help workflow preserves known device workaround guidance', async () => {
   assert.match(result.stdout, /Avoid broad restore-key fallbacks/);
 });
 
+test('help workflow documents the selector disambiguation policy (#1037)', async () => {
+  const result = await runCliCapture(['help', 'workflow']);
+  assert.equal(result.code, 0);
+  assert.equal(result.calls.length, 0);
+  assert.match(result.stdout, /does not fail by default/);
+  assert.match(result.stdout, /deepest node first/);
+  assert.match(result.stdout, /then smallest on-screen area/);
+  assert.match(result.stdout, /Selector did not resolve uniquely/);
+  assert.match(result.stdout, /replay and replay-heal apply the same depth-then-area policy/);
+  assert.match(result.stdout, /targetHittable: false/);
+});
+
 test('help unknown command prints error plus global usage and skips daemon dispatch', async () => {
   const result = await runCliCapture(['help', 'not-a-command']);
   assert.equal(result.code, 1);
 
@@ -189,6 +189,8 @@ Selectors:
     agent-device press 'id="submit-order"'
     agent-device is visible 'label="Online"'
     agent-device get text 'id="quantity-value"'
+  Ambiguous selector disambiguation: a selector on an interactive command (press/click/fill/focus/longpress/scroll/swipe/pinch) that matches multiple elements does not fail by default. It auto-resolves deepest node first (largest depth in the tree), then smallest on-screen area; only an exact tie on both depth and area fails with "Selector did not resolve uniquely". replay and replay-heal apply the same depth-then-area policy for touch/fill/get-text, so recorded flows and live commands pick the same candidate. This exists because short/reused labels (tab + header + button with the same text, or a duplicated list-row label) are common in real apps; add id="..." or a longer/more specific text to force a different match instead of assuming ambiguous selectors always fail.
+  Selector match can still land on a non-interactive node (for example an off-screen map annotation that exact-matches text= while the real control has a longer label). Success responses for press/fill/click/ref targets carry targetHittable: false and a hint when the resolved element reports hittable: false, since the tap may have had no visible effect; treat that as a signal to verify with a snapshot or re-target by @ref/longer text, not as a command failure.
 
 Text entry:
   fill replaces; type appends to focused field.
 
@@ -234,6 +234,60 @@ test('runtime click keeps non-button semantic targets at their own center', asyn
   assert.equal(result.node?.label, 'Account');
 });
 
+test('runtime press surfaces targetHittable and a hint when the final tap node is non-hittable (#1037)', async () => {
+  const calls: Point[] = [];
+  const device = createInteractionDevice(nonHittableCellSnapshot(), {
+    tap: async (_context, point) => {
+      calls.push(point);
+    },
+  });
+
+  const result = await device.interactions.press(ref('@e2'), { session: 'default' });
+
+  // Press still proceeds and reports success — non-hittable is informational only.
+  assert.deepEqual(calls, [{ x: 70, y: 30 }]);
+  assert.equal(result.kind, 'ref');
+  assert.equal(result.node?.label, 'Account');
+  assert.equal(result.targetHittable, false);
+  assert.match(result.hint ?? '', /hittable: false/);
+  assert.match(result.hint ?? '', /@ref/);
+});
+
+test('runtime press omits targetHittable and hint when the resolved node is hittable', async () => {
+  const device = createInteractionDevice(selectorSnapshot(), {
+    tap: async () => {},
+  });
+
+  const result = await device.interactions.press(selector('label=Continue'), {
+    session: 'default',
+  });
+
+  assert.equal(result.kind, 'selector');
+  assert.equal(result.targetHittable, undefined);
+  assert.equal(result.hint, undefined);
+});
+
+test('runtime fill surfaces targetHittable and a hint for a non-hittable selector match (Maps pin case, #1037)', async () => {
+  const calls: Array<{ point: Point; text: string }> = [];
+  const device = createInteractionDevice(mapPinAnnotationSnapshot(), {
+    fill: async (_context, point, text) => {
+      calls.push({ point, text });
+    },
+  });
+
+  const result = await device.interactions.fill(
+    selector('text="Anthropic - Headquarters"'),
+    'ignored',
+    { session: 'default' },
+  );
+
+  assert.equal(result.kind, 'selector');
+  assert.equal(result.node?.label, 'Anthropic - Headquarters');
+  assert.equal(result.targetHittable, false);
+  assert.match(result.hint ?? '', /hittable: false/);
+  assert.deepEqual(calls, [{ point: { x: 192, y: 461 }, text: 'ignored' }]);
+});
+
 test('runtime click still promotes non-touchable nodes to hittable ancestors', async () => {
   const calls: Point[] = [];
   const device = createInteractionDevice(nonTouchableGroupSnapshot(), {
@@ -1092,6 +1146,31 @@ function nonHittableCellSnapshot(): SnapshotState {
   ]);
 }
 
+// Mirrors the #1037 Maps repro: a non-hittable map-pin annotation exact-matches
+// `text="Anthropic - Headquarters"` while the real, longer-labeled row is a
+// separate node. Fill/press must still proceed against the unique match (no
+// stricter resolution) but should flag it as likely non-actionable.
+function mapPinAnnotationSnapshot(): SnapshotState {
+  return makeSnapshotState([
+    {
+      index: 0,
+      depth: 0,
+      type: 'Other',
+      label: 'Anthropic - Headquarters',
+      rect: { x: 177, y: 446, width: 30, height: 30 },
+      hittable: false,
+    },
+    {
+      index: 1,
+      depth: 1,
+      type: 'Button',
+      label: 'Anthropic - Headquarters, 548 Market St',
+      rect: { x: 0, y: 786, width: 390, height: 60 },
+      hittable: false,
+    },
+  ]);
+}
+
 function nonTouchableGroupSnapshot(): SnapshotState {
   return makeSnapshotState([
     {
 
@@ -93,6 +93,7 @@ async function resolveRefInteractionTarget(
       action: params.action === 'fill' ? 'fill' : 'click',
     }),
     refLabel: resolveRefLabel(node, capture.snapshot.nodes),
+    ...describeNonHittableTarget(node, params.action),
   };
 }
 
@@ -159,6 +160,26 @@ async function resolveSelectorInteractionTarget(
       action: params.action === 'fill' ? 'fill' : 'click',
     }),
     refLabel: resolveRefLabel(node, capture.snapshot.nodes),
+    ...describeNonHittableTarget(node, params.action),
+  };
+}
+
+/**
+ * iOS AX `hittable` flags are unreliable on deep React Native trees (see #1037:
+ * a map-pin annotation exact-matched a longer recents row label and reported tap
+ * success while doing nothing visible). We deliberately do NOT fail or filter on
+ * this signal — that would break selectors that only ever resolve to nodes the
+ * platform marks non-hittable. Instead, surface it so the caller can notice a
+ * likely no-op tap and re-target with a ref or a more specific selector/longer text.
+ */
+function describeNonHittableTarget(
+  node: SnapshotNode,
+  action: InteractionAction,
+): { targetHittable?: boolean; hint?: string } {
+  if (node.hittable !== false) return {};
+  return {
+    targetHittable: false,
+    hint: `The resolved element reports hittable: false, so this ${action} may have had no visible effect. Verify with a snapshot, or prefer a @ref or a longer/more specific selector to target the intended element.`,
   };
 }
 
 
@@ -43,6 +43,8 @@ export type ResolvedInteractionTarget =
       node?: SnapshotNode;
       selectorChain?: string[];
       refLabel?: string;
+      targetHittable?: boolean;
+      hint?: string;
     }
   | {
       kind: 'selector';
@@ -51,6 +53,8 @@ export type ResolvedInteractionTarget =
       node: SnapshotNode;
       selectorChain: string[];
       refLabel?: string;
+      targetHittable?: boolean;
+      hint?: string;
     };
 
 export type PressCommandResult = ResolvedInteractionTarget & {
 
@@ -1739,6 +1739,9 @@ test('press @ref promotes a non-hittable node to its hittable ancestor before ta
     expect(response.data?.ref).toBe('e2');
     expect(response.data?.x).toBe(180);
     expect(response.data?.y).toBe(136);
+    // Promotion landed on a hittable ancestor, so there is nothing to flag.
+    expect(response.data?.targetHittable).toBeUndefined();
+    expect(response.data?.hint).toBeUndefined();
   }
   expect(mockDispatch).toHaveBeenCalledTimes(1);
   expect(mockDispatch.mock.calls[0]?.[1]).toBe('press');
@@ -1798,6 +1801,12 @@ test('press @ref does not promote to a full-screen hittable ancestor', async ()
   if (response?.ok) {
     expect(response.data?.x).toBe(201);
     expect(response.data?.y).toBe(319);
+    // #1037: the press still proceeds against the non-hittable node (no stricter
+    // resolution), but the daemon response flags it so agents can react instead
+    // of assuming the tap had a visible effect.
+    expect(response.data?.targetHittable).toBe(false);
+    expect(typeof response.data?.hint).toBe('string');
+    expect(response.data?.hint as string).toMatch(/hittable: false/);
   }
   expect(mockDispatch).toHaveBeenCalledTimes(1);
   expect(mockDispatch.mock.calls[0]?.[2]).toEqual(['201', '319']);
 
@@ -132,13 +132,17 @@ export function interactionResultExtra(
       ref: stripAtPrefix(result.target?.kind === 'ref' ? result.target.ref : undefined),
       refLabel: result.refLabel,
       selectorChain: result.selectorChain,
+      targetHittable: result.targetHittable,
+      hint: result.hint,
     };
   }
   if (result.kind === 'selector') {
     return {
       selector: result.target?.kind === 'selector' ? result.target.selector : undefined,
       selectorChain: result.selectorChain,
       refLabel: result.refLabel,
+      targetHittable: result.targetHittable,
+      hint: result.hint,
     };
   }
   return {};
 
@@ -140,6 +140,8 @@ function interactionResultSchema(extra: InteractionExtra = {}): JsonSchema {
       node: snapshotNodeSchema,
       selectorChain: stringArraySchema,
       refLabel: stringSchema(),
+      targetHittable: booleanSchema(),
+      hint: stringSchema(),
       ...extraProperties,
     },
     ['kind', 'target', ...extraRequired],
@@ -152,6 +154,8 @@ function interactionResultSchema(extra: InteractionExtra = {}): JsonSchema {
       node: snapshotNodeSchema,
       selectorChain: stringArraySchema,
       refLabel: stringSchema(),
+      targetHittable: booleanSchema(),
+      hint: stringSchema(),
       ...extraProperties,
     },
     ['kind', 'point', 'target', 'node', 'selectorChain', ...extraRequired],