fix(is): answer the review pass on #3340

- Eager-closure budget: the daemon entry gained one static edge for the new
  failure-door module. The gate names its own fix -- give the code a home in a
  module the closure already evaluates -- so the builders move into
  selector-read-shared.ts (the strict reads' existing shared-failure home) and
  the standalone module is deleted. No baseline touched, no lazy import bolted
  onto an error path.
- Contract fields are now written AFTER caller details, so no caller spread
  order can clobber them; both strict rows prove they report the matched
  alternative as details.selector for the same capture.
- The ambiguity hint no longer echoes the selector into a single-quoted
  find command (label="It's here" broke the outer quoting).
- The text-echo collapse gains the reportage clause: every non-reporter
  candidate must be the accessibility element the platform reports for the
  reporter (isReportedAccessibilityElement). Same label + same frame with an
  authored (view-backed) descendant stays ambiguous -- the closest-negative
  fixture pins exactly that. The offset-rect fixture gains the live RN roles
  so the rect is the only differing fact.
- The 5-candidate cap moves to kernel/errors as ELEMENT_MATCH_CANDIDATE_LIMIT
  beside the ElementMatchCandidateDetails type the surfaces read; all three
  producers (acting refusal, find refusal, read door) consume it. The shared-
  shape comment now names what is actually shared.
- Help/docs: 'Uniqueness-based reads' replaces internal 'nominating reads';
  ref guidance scoped to ref-taking commands (is rejects refs); the RN pair
  bullet qualified as the observed iOS accessibility shape.

Author: thymikee

packages/kernel/src/errors.ts

@@ -161,6 +161,14 @@ export type NormalizedError = {
   details?: ErrorWireDetails;
 };
 
+/**
+ * How many candidate lines an `AMBIGUOUS_MATCH` producer puts on the wire.
+ * Owned beside the detail type every surface reads (`readErrorCandidateViews`
+ * computes the "+N more" marker from `matches - candidates.length`), so the
+ * producers' caps cannot drift from each other or from the renderers.
+ */
+export const ELEMENT_MATCH_CANDIDATE_LIMIT = 5;
+
 export type ElementMatchCandidateDetails = {
   candidates: string[];
   matches: number;

packages/selectors/src/interaction-targeting.fixtures.ts

@@ -365,14 +365,17 @@ export const RN_TEXT_ECHO_DISTINCT_SUBTREE_NODES: RawSnapshotNode[] = [
 /**
  * The other closest negative: one ancestry chain whose descendant repeats the
  * ancestor's label at a DIFFERENT rect — two runs of the same words, which is two
- * elements the caller still has to choose between.
+ * elements the caller still has to choose between. Roles mirror the live RN pair
+ * so the rect is the ONLY fact that differs from the collapsing positive.
  */
 export const RN_TEXT_ECHO_OFFSET_RECT_NODES: RawSnapshotNode[] = [
   {
     index: 0,
     depth: 1,
     parentIndex: 2,
     type: 'XCUIElementTypeStaticText',
+    role: 'RCTParagraphComponentView',
+    subrole: 'UIView',
     label: 'Catalog scroll: top',
     rect: { x: 18, y: 168, width: 350, height: 17 },
     enabled: true,
@@ -383,6 +386,8 @@ export const RN_TEXT_ECHO_OFFSET_RECT_NODES: RawSnapshotNode[] = [
     depth: 2,
     parentIndex: 0,
     type: 'XCUIElementTypeStaticText',
+    role: 'RCTAccessibilityElement',
+    subrole: 'UIAccessibilityElement',
     label: 'Catalog scroll: top',
     rect: { x: 18, y: 420, width: 350, height: 17 },
     enabled: true,
@@ -397,3 +402,47 @@ export const RN_TEXT_ECHO_OFFSET_RECT_NODES: RawSnapshotNode[] = [
     hittable: true,
   },
 ];
+
+/**
+ * The reportage negative: one ancestry chain with the identical label at the
+ * identical rect — the shape geometry cannot distinguish — where the descendant
+ * is an AUTHORED element (a nested `<Text>` or a `<View>` carrying the same
+ * accessibilityLabel, view-backed role/subrole), not the accessibility element
+ * the platform reports for the reporter. Same frame, same label, two authored
+ * elements: the collapse rule's `isReportedAccessibilityElement` clause keeps
+ * this ambiguous.
+ */
+export const RN_TEXT_ECHO_AUTHORED_CHILD_NODES: RawSnapshotNode[] = [
+  {
+    index: 0,
+    depth: 1,
+    parentIndex: 2,
+    type: 'XCUIElementTypeStaticText',
+    role: 'RCTParagraphComponentView',
+    subrole: 'UIView',
+    label: 'Catalog scroll: top',
+    rect: { x: 18, y: 168, width: 350, height: 17 },
+    enabled: true,
+    hittable: true,
+  },
+  {
+    index: 1,
+    depth: 2,
+    parentIndex: 0,
+    type: 'RCTParagraphComponentView',
+    role: 'RCTParagraphComponentView',
+    subrole: 'UIView',
+    label: 'Catalog scroll: top',
+    rect: { x: 18, y: 168, width: 350, height: 17 },
+    enabled: true,
+    hittable: true,
+  },
+  {
+    index: 2,
+    depth: 0,
+    type: 'XCUIElementTypeApplication',
+    rect: { x: 0, y: 0, width: 386, height: 678 },
+    enabled: true,
+    hittable: true,
+  },
+];

packages/selectors/src/interaction-targeting.ts

@@ -145,6 +145,23 @@ function resolveUnverifiedWrapperControlWithIndex(
     : null;
 }
 
+/**
+ * The mirror half of the RN pair is not a view the app authored: it is the
+ * synthetic element the platform reports for the reporter's accessibility
+ * subtree, and it carries that reportage in its role/subrole
+ * (`RCTAccessibilityElement` / `UIAccessibilityElement`, measured live via
+ * `snapshot --raw`). Requiring it on every non-reporter candidate is what
+ * distinguishes "one element the platform reported twice" from "two authored
+ * elements that happen to share a label and a frame" — geometry cannot tell
+ * those apart, only the reportage can. An authored child (a nested `<Text>`
+ * styled to the same label at the same place, a `<View>` carrying the same
+ * accessibilityLabel) has view-backed role/subrole and keeps the refusal.
+ */
+function isReportedAccessibilityElement(node: SnapshotNode): boolean {
+  const roles = [node.type, node.role, node.subrole].map((value) => normalizeType(value ?? ''));
+  return roles.some((role) => role.includes('accessibilityelement'));
+}
+
 /**
  * The React Native text shape, captured live from the fixture Catalog screen: a
  * `RCTParagraphComponentView` reporting the accessibility label (and the app's
@@ -166,6 +183,10 @@ function resolveUnverifiedWrapperControlWithIndex(
  * - identical non-empty labels and rects agreeing within wrapper slack — a nested
  *   `<Text>` that repeats a word at its own position is a second run of text, not
  *   a mirror, and a distinct rect proves it;
+ * - every non-reporter candidate is a reported accessibility element (above) —
+ *   same label AND same frame is exactly the case where geometry cannot
+ *   distinguish a mirror from a second authored element, so the reportage is
+ *   required and an authored same-frame child stays ambiguous;
  * - no candidate is a semantic touch target — a button labelled like its own static
  *   text is two roles the caller still has to choose between (that shape is the
  *   wrapper rule above's job, through the hittability door it keeps);
@@ -189,6 +210,7 @@ function resolveTextEchoReporterWithIndex(
   if (!reporterRect) return null;
   const mirrorsOneReporter = candidates.every(
     (candidate) =>
+      (candidate === reporter || isReportedAccessibilityElement(candidate)) &&
       candidate.label?.trim() === reporterLabel &&
       agreesWithinWrapperSlack(normalizeRect(candidate.rect), reporterRect),
   );

packages/selectors/src/selector-pipeline.test.ts

@@ -5,6 +5,7 @@ import { SELECTOR_RESOLUTION_POLICIES } from '@agent-device/selectors';
 import { makeSnapshotState } from './snapshot-geometry.fixtures.ts';
 import {
   ELEMENT14_DISTINCT_SUBTREE_NODES,
+  RN_TEXT_ECHO_AUTHORED_CHILD_NODES,
   RN_TEXT_ECHO_DISTINCT_SUBTREE_NODES,
   RN_TEXT_ECHO_NODES,
   RN_TEXT_ECHO_OFFSET_RECT_NODES,
@@ -355,8 +356,8 @@ test('the uniqueness rows collapse React Native text reported twice', async () =
 
 /**
  * Each negative changes exactly ONE structural fact of the pair above while every
- * label and rect still matches, so a rule reading the description rather than the
- * structure would answer and these tests would notice.
+ * label and rect still matches (or the ancestry breaks), so a rule reading the
+ * description rather than the structure would answer and these tests would notice.
  */
 test('the uniqueness rows refuse a text pair that is not one reporter and its mirror', async () => {
   const cases = [
@@ -370,6 +371,14 @@ test('the uniqueness rows refuse a text pair that is not one reporter and its mi
       nodesOf(RN_TEXT_ECHO_OFFSET_RECT_NODES),
       RN_TEXT_ECHO_SELECTOR,
     ],
+    [
+      // Same label AND same frame — the case geometry cannot decide. The
+      // descendant is authored (view-backed roles), not the platform's
+      // reported accessibility element, so the pair stays two elements.
+      'same label at the same frame with an authored descendant',
+      nodesOf(RN_TEXT_ECHO_AUTHORED_CHILD_NODES),
+      RN_TEXT_ECHO_SELECTOR,
+    ],
   ] as const;
   for (const [name, nodes, selector] of cases) {
     for (const row of ['readUnique', 'cropTarget'] as const) {

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

@@ -82,6 +82,39 @@ test('is reports the ambiguity it refuses as an ambiguity, not an absence (readU
   assert.deepEqual(details?.candidates, ['@e2 [button] "Save"', '@e3 [button] "Save"']);
 });
 
+/**
+ * Both rows share one door, so `details.selector` must name the MATCHED
+ * alternative for both, never the caller's authored expression. `is` passes
+ * its authored selector among its details; a spread order that let caller
+ * details win would make `is` report the whole expression while `get attrs`
+ * reported the alternative — same door, two shapes (#2870 review).
+ */
+test('both strict rows report the matched alternative as details.selector, not the authored expression', async () => {
+  const AUTHORED = 'label="Nowhere" || label="Save"';
+  const device = createSelectorDevice(ambiguousSelectorReadSnapshot());
+
+  const errors = await Promise.all([
+    device.selectors.is({ session: 'default', predicate: 'visible', selector: AUTHORED }).then(
+      () => null,
+      (error: unknown) => error as AppError,
+    ),
+    device.selectors.getAttrs(selector(AUTHORED), { session: 'default' }).then(
+      () => null,
+      (error: unknown) => error as AppError,
+    ),
+  ]);
+
+  for (const error of errors) {
+    assert.ok(error instanceof AppError);
+    assert.equal(error.code, 'AMBIGUOUS_MATCH');
+    assert.equal(
+      (error.details as { selector?: string } | undefined)?.selector,
+      'label="Save"',
+      'details.selector names the alternative that matched twice',
+    );
+  }
+});
+
 /**
  * The closest negative to the pair above: a selector that matches NOTHING still
  * reports proof of absence. The two failures carry different typed reasons and

src/commands/interaction/runtime/selector-action-resolution.ts

@@ -1,4 +1,4 @@
-import { AppError } from '@agent-device/kernel/errors';
+import { AppError, ELEMENT_MATCH_CANDIDATE_LIMIT } from '@agent-device/kernel/errors';
 import type { Platform, PublicPlatform } from '@agent-device/kernel/device';
 import type { SnapshotNode } from '@agent-device/kernel/snapshot';
 import type { SelectorResolution } from '@agent-device/selectors';
@@ -7,8 +7,6 @@ import { listSelectorPipelineMatches } from '@agent-device/selectors/selector-pi
 import type { ActingPipelinePolicy } from '@agent-device/selectors/selector-pipeline-policy';
 import { formatSnapshotLine } from '@agent-device/capture-kit/snapshot-lines';
 
-const AMBIGUOUS_ACTION_CANDIDATE_LIMIT = 5;
-
 /**
  * How an acting row narrows its candidate set: wrapper duplicates may collapse
  * through structural/actionable equivalence; matches in distinct branches are
@@ -51,7 +49,7 @@ export function resolveActionSelector(
         selector: list.selector,
         matches: classification.candidates.length,
         candidates: classification.candidates
-          .slice(0, AMBIGUOUS_ACTION_CANDIDATE_LIMIT)
+          .slice(0, ELEMENT_MATCH_CANDIDATE_LIMIT)
           .map((candidate) => formatSnapshotLine(candidate, 0, false)),
       },
     );

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

@@ -22,6 +22,7 @@ import {
   type CapturedSnapshot,
   type SelectorSnapshotOptions,
   captureSelectorSnapshot,
+  observationReadFailure,
 } from './selector-read-shared.ts';
 import { deriveSelectorCapturePolicy } from './selector-capture-policy.ts';
 import { absenceCaptureOptionRefusal } from '@agent-device/selectors/absence-observation';
@@ -30,7 +31,6 @@ import {
   absenceUnreadableError,
 } from '@agent-device/selectors/absence-observation-errors';
 import { resolveAbsenceObservation } from '@agent-device/selectors/absence-observation-resolution';
-import { observationReadFailure } from './selector-observation-failure.ts';
 
 export type IsCommandOptions = CommandContext &
   SelectorSnapshotOptions & {