diff --git a/packages/argent-mcp/src/auto-screenshot.ts b/packages/argent-mcp/src/auto-screenshot.ts
index 041347ef8..367043e50 100644
--- a/packages/argent-mcp/src/auto-screenshot.ts
+++ b/packages/argent-mcp/src/auto-screenshot.ts
@@ -23,6 +23,7 @@ export const AUTO_SCREENSHOT_TOOLS = new Set([
   "restart-app",
   "open-url",
   "describe",
+  "find",
   "run-sequence",
 ]);
 
@@ -46,10 +47,27 @@ export const AUTO_SCREENSHOT_DELAY_MS_BY_TOOL: Record<string, number> = {
   "rotate": 1000,
   "keyboard": 300,
   "describe": 100,
+  // `find`'s headline action is a tap (which can trigger a transition), so match
+  // gesture-tap's settle delay. Its read-only actions (exists/get-text/get-attrs/
+  // wait) don't mutate the screen, so they use the shorter describe-style delay
+  // instead — see `getAutoScreenshotDelayMs`, which keys off `args.action`.
+  "find": 1500,
 };
 
 const DEFAULT_DELAY_MS = 1400;
 
+// `find` actions that don't touch the device — their auto-screenshot doesn't need
+// the tap settle delay (it would just over-wait ~1.5s for an unchanged screen).
+// Kept in sync with the tool's ACTIONS by name (argent-mcp must not import from
+// tool-server); the default action is `tap`, so an omitted action is NOT read-only.
+const READ_ONLY_FIND_ACTIONS = new Set(["exists", "get-text", "get-attrs", "wait"]);
+
+function isReadOnlyFindAction(args: unknown): boolean {
+  if (!args || typeof args !== "object") return false;
+  const action = (args as { action?: unknown }).action;
+  return typeof action === "string" && READ_ONLY_FIND_ACTIONS.has(action);
+}
+
 // Auto-screenshot is on by default; the opt-out is the off-by-default
 // `disable-auto-screenshot` flag. `options` mirrors isFlagEnabled so tests can
 // point storage at a temp dir.
@@ -83,9 +101,12 @@ export function shouldAutoScreenshot(toolName: string): boolean {
   return canonical !== "screenshot" && AUTO_SCREENSHOT_TOOLS.has(canonical);
 }
 
-export function getAutoScreenshotDelayMs(toolName: string): number {
+export function getAutoScreenshotDelayMs(toolName: string, args?: unknown): number {
   const canonical = normalizeToolName(toolName);
-  const base = AUTO_SCREENSHOT_DELAY_MS_BY_TOOL[canonical] ?? DEFAULT_DELAY_MS;
+  const base =
+    canonical === "find" && isReadOnlyFindAction(args)
+      ? AUTO_SCREENSHOT_DELAY_MS_BY_TOOL["describe"]!
+      : (AUTO_SCREENSHOT_DELAY_MS_BY_TOOL[canonical] ?? DEFAULT_DELAY_MS);
   const envOverride = process.env.ARGENT_AUTO_SCREENSHOT_DELAY_MS;
   if (envOverride) {
     const envMs = parseInt(envOverride, 10);
diff --git a/packages/argent-mcp/src/mcp-server.ts b/packages/argent-mcp/src/mcp-server.ts
index 118241ff2..c8558a600 100644
--- a/packages/argent-mcp/src/mcp-server.ts
+++ b/packages/argent-mcp/src/mcp-server.ts
@@ -304,7 +304,7 @@ export async function startMcpServer(options: StartMcpServerOptions): Promise<vo
 
       const udid = getUdidFromArgs(params.arguments);
       if (autoScreenshotOn && udid && shouldAutoScreenshot(params.name)) {
-        const delayMs = getAutoScreenshotDelayMs(params.name);
+        const delayMs = getAutoScreenshotDelayMs(params.name, params.arguments);
         if (delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
 
         try {
diff --git a/packages/argent-mcp/test/auto-screenshot.test.ts b/packages/argent-mcp/test/auto-screenshot.test.ts
index bfbb90117..3fe410fe4 100644
--- a/packages/argent-mcp/test/auto-screenshot.test.ts
+++ b/packages/argent-mcp/test/auto-screenshot.test.ts
@@ -180,6 +180,32 @@ describe("getAutoScreenshotDelayMs", () => {
     process.env.ARGENT_AUTO_SCREENSHOT_DELAY_MS = "abc";
     expect(getAutoScreenshotDelayMs("gesture-tap")).toBe(1500);
   });
+
+  // N1: a read-only `find` shouldn't over-wait the tap settle for an unchanged
+  // screen — it uses describe's short delay, keyed off args.action.
+  it("uses the describe delay for a read-only find action", () => {
+    for (const action of ["exists", "get-text", "get-attrs", "wait"]) {
+      expect(getAutoScreenshotDelayMs("find", { action })).toBe(
+        AUTO_SCREENSHOT_DELAY_MS_BY_TOOL["describe"]
+      );
+    }
+    // normalized names work too
+    expect(getAutoScreenshotDelayMs("mcp__argent__find", { action: "exists" })).toBe(
+      AUTO_SCREENSHOT_DELAY_MS_BY_TOOL["describe"]
+    );
+  });
+
+  it("keeps the tap settle delay for a find tapping action (or omitted action → default tap)", () => {
+    expect(getAutoScreenshotDelayMs("find", { action: "tap" })).toBe(
+      AUTO_SCREENSHOT_DELAY_MS_BY_TOOL["find"]
+    );
+    expect(getAutoScreenshotDelayMs("find", { action: "fill", text: "x" })).toBe(
+      AUTO_SCREENSHOT_DELAY_MS_BY_TOOL["find"]
+    );
+    // omitted action defaults to tap → full settle; and no args at all
+    expect(getAutoScreenshotDelayMs("find", {})).toBe(AUTO_SCREENSHOT_DELAY_MS_BY_TOOL["find"]);
+    expect(getAutoScreenshotDelayMs("find")).toBe(AUTO_SCREENSHOT_DELAY_MS_BY_TOOL["find"]);
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -195,6 +221,11 @@ describe("shouldAutoScreenshot — unified surface", () => {
     for (const t of [
       "gesture-tap",
       "gesture-swipe",
+      "gesture-scroll",
+      "gesture-drag",
+      "gesture-custom",
+      "gesture-pinch",
+      "gesture-rotate",
       "button",
       "keyboard",
       "rotate",
@@ -202,6 +233,9 @@ describe("shouldAutoScreenshot — unified surface", () => {
       "restart-app",
       "open-url",
       "describe",
+      // `find`'s default action is a tap, which can trigger a transition worth
+      // capturing — so it must auto-screenshot like the other interaction tools.
+      "find",
       "run-sequence",
     ]) {
       expect(shouldAutoScreenshot(t)).toBe(true);
diff --git a/packages/skills/rules/argent.md b/packages/skills/rules/argent.md
index d4960a3d3..f2cf20db5 100644
--- a/packages/skills/rules/argent.md
+++ b/packages/skills/rules/argent.md
@@ -37,7 +37,7 @@ If argent is ABSENT, treat it as an expected state, not an error to retry. Do no
 
 <tapping_rule>
 <important>**Never** derive tap coordinates from a screenshot</important>
-Before **every** tap, you MUST call a discovery tool and extract coordinates from the result. This is not optional. Preferred tools are, in order:
+Before **every** coordinate tap, you MUST call a discovery tool and extract coordinates from the result. This is not optional. Preferred tools are, in order:
 
 - `describe` - native app-level components and safely targetable foreground apps (iOS and Android).
 - `native-describe-screen` - accessibility screen description via injected native devtools (iOS only)
@@ -45,7 +45,12 @@ Before **every** tap, you MUST call a discovery tool and extract coordinates fro
 
 `native-user-interactable-view-at-point` / `native-view-at-point` are follow-up diagnostics once you already have a candidate point (iOS only).
 
-Whenever something changed YOU MUST first call `describe`, or another appropriate discovery tool so you do not hallucinate element positions. Do not guess coordinates if you can use discovery tool. Do not tap if you have not called a discovery tool in the current step. Screenshots alone are never sufficient for coordinates.
+Choose exactly one tap path for a target:
+
+- Unknown screen/layout or ambiguous target: `describe` / `native-describe-screen` / `debugger-component-tree` -> `gesture-tap` using the returned frame or tap point.
+- Known visible target by text/label/value/role/id and no current coordinates for it: `find` can locate and act in one call.
+- Recent discovery already exposed the same target frame/tap point: do **not** call `find` for that target; use `gesture-tap`.
+- UI changed after discovery (navigation, modal, list update, keyboard, animation, reload): the old coordinates are stale. Re-discover, or use `find` if the next target is known by text/label/id.
 
 If a **tap fails twice** at the same coordinates, **stop retrying**. Re-run the discovery tool.
 
@@ -73,7 +78,7 @@ Decision order:
 - All simulator/emulator interactions go through argent MCP tools — never use `xcrun simctl`,
   raw `curl` to simulator ports, or the simulator-server binary directly.
 - Before calling any gesture tool for the first time, use ToolSearch to load its schema.
-- Interaction tools (`gesture-tap`, `gesture-swipe`, `gesture-pinch`, `gesture-rotate`, `gesture-custom`, `launch-app`, etc.) return a screenshot automatically.
+- Interaction tools (`find`, `gesture-tap`, `gesture-swipe`, `gesture-pinch`, `gesture-rotate`, `gesture-custom`, `launch-app`, etc.) return a screenshot automatically.
   Call `screenshot` separately only for a baseline before any action or after a delay.
 - Always open apps with `launch-app` or `open-url` — never tap home screen icons.
 - Always use `run-sequence` when performing multiple sequential device actions where you don't need to observe the screen between steps. More in `argent-device-interact` skill.
diff --git a/packages/skills/skills/argent-create-flow/SKILL.md b/packages/skills/skills/argent-create-flow/SKILL.md
index 40dc8aa46..b630a71e7 100644
--- a/packages/skills/skills/argent-create-flow/SKILL.md
+++ b/packages/skills/skills/argent-create-flow/SKILL.md
@@ -12,7 +12,7 @@ A flow is a recorded sequence of MCP tool calls saved to a `.yaml` file in the `
 | Tool                     | Purpose                                                                    |
 | ------------------------ | -------------------------------------------------------------------------- |
 | `flow-start-recording`   | Start recording — takes a name and executionPrerequisite, creates the file |
-| `flow-add-step`          | Execute a tool call live and record it if it succeeds                      |
+| `flow-add-step`          | Execute a tool call live and record it when the call succeeds              |
 | `flow-add-echo`          | Add a label/comment that prints during replay                              |
 | `flow-finish-recording`  | Stop recording and get a summary                                           |
 | `flow-read-prerequisite` | Read a flow's execution prerequisite without running it                    |
diff --git a/packages/skills/skills/argent-device-interact/SKILL.md b/packages/skills/skills/argent-device-interact/SKILL.md
index 1f73007c9..c741d6a2b 100644
--- a/packages/skills/skills/argent-device-interact/SKILL.md
+++ b/packages/skills/skills/argent-device-interact/SKILL.md
@@ -32,7 +32,7 @@ Use `list-devices` to get a target id. Results are tagged with `platform` (`ios`
 3. **Use `gesture-swipe` for lists/scrolling**, not `gesture-custom`, unless you need non-linear movement. On Chromium use `gesture-scroll` instead — `gesture-swipe` is touch-only. Consider whether you need multiple swipes, if yes - use `run-sequence`.
 4. **Tap a text field before typing**, then use `keyboard` to enter text.
 5. **Coordinates are normalized** — always 0.0–1.0, not pixels.
-6. **For app navigation, prefer `describe` first.** It works on any screen without app restart. Do not navigate from screenshots on regular in-app screens unless `describe` failed to expose a reliable target. Use `native-describe-screen` only when you need app-scoped UIKit properties.
+6. **For app navigation, choose one tap path.** Unknown screen/layout: `describe` -> `gesture-tap` using the returned frame. Known visible target by text/label/id and no current coordinates: use `find` directly. Do not call `find` immediately after `describe` for the same target.
 
 ## 3. Opening Apps
 
@@ -56,34 +56,42 @@ Common schemes: `messages://`, `settings://`, `maps://?q=<query>`, `tel://<numbe
 
 ## 4. Choosing the Right Tool
 
-| Action            | Tool               | Notes                                                            |
-| ----------------- | ------------------ | ---------------------------------------------------------------- |
-| Multiple actions  | `run-sequence`     | Batch steps in one call (no intermediate screenshots)            |
-| Open an app       | `launch-app`       | **Always — never tap home-screen icons**                         |
-| Restart an app    | `restart-app`      | Terminate and relaunch by bundle ID                              |
-| Open URL/scheme   | `open-url`         | Web pages, deep links, URL schemes                               |
-| Single tap        | `gesture-tap`      | Buttons, links, checkboxes                                       |
-| Scroll/swipe      | `gesture-swipe`    | Straight-line scroll or swipe                                    |
-| Scroll (Chromium) | `gesture-scroll`   | Wheel-based; deltas are window fractions, positive deltaY = down |
-| Drag (Chromium)   | `gesture-drag`     | Sliders, drag-and-drop, text selection                           |
-| Long press        | `gesture-custom`   | Context menus, drag start                                        |
-| Drag & drop       | `gesture-custom`   | Complex drag interactions                                        |
-| Pinch/zoom        | `gesture-pinch`    | Two-finger pinch with auto-interpolation                         |
-| Rotation          | `gesture-rotate`   | Two-finger rotation with auto-interpolation                      |
-| Custom gesture    | `gesture-custom`   | Arbitrary touch sequences, optional interpolation                |
-| Hardware key      | `button`           | Home, back, power, volume, appSwitch, actionButton               |
-| Type text         | `keyboard`         | iOS+Android. Supports Enter, Escape, arrows                      |
-| Rotate device     | `rotate`           | Orientation changes                                              |
-| Wait for UI       | `await-ui-element` | Block until an element is visible/hidden/exists/contains text    |
+| Action            | Tool               | Notes                                                                                                                   |
+| ----------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| Explore screen    | `describe`         | Go-to for unknown screens, full layout context, coordinates, and disambiguation before `gesture-tap`                    |
+| Locate + act      | `find`             | Use when the target is already known by text/label/value/role/id and you do not already have current coordinates for it |
+| Multiple actions  | `run-sequence`     | Batch steps in one call (no intermediate screenshots)                                                                   |
+| Open an app       | `launch-app`       | **Always — never tap home-screen icons**                                                                                |
+| Restart an app    | `restart-app`      | Terminate and relaunch by bundle ID                                                                                     |
+| Open URL/scheme   | `open-url`         | Web pages, deep links, URL schemes                                                                                      |
+| Single tap        | `gesture-tap`      | Buttons, links, checkboxes                                                                                              |
+| Scroll/swipe      | `gesture-swipe`    | Straight-line scroll or swipe                                                                                           |
+| Scroll (Chromium) | `gesture-scroll`   | Wheel-based; deltas are window fractions, positive deltaY = down                                                        |
+| Drag (Chromium)   | `gesture-drag`     | Sliders, drag-and-drop, text selection                                                                                  |
+| Long press        | `gesture-custom`   | Context menus, drag start                                                                                               |
+| Drag & drop       | `gesture-custom`   | Complex drag interactions                                                                                               |
+| Pinch/zoom        | `gesture-pinch`    | Two-finger pinch with auto-interpolation                                                                                |
+| Rotation          | `gesture-rotate`   | Two-finger rotation with auto-interpolation                                                                             |
+| Custom gesture    | `gesture-custom`   | Arbitrary touch sequences, optional interpolation                                                                       |
+| Hardware key      | `button`           | Home, back, power, volume, appSwitch, actionButton                                                                      |
+| Type text         | `keyboard`         | iOS+Android. Supports Enter, Escape, arrows                                                                             |
+| Rotate device     | `rotate`           | Orientation changes                                                                                                     |
+| Wait for UI       | `await-ui-element` | Block until an element is visible/hidden/exists/contains text                                                           |
 
 ## 5. Finding Tap Targets
 
-IMPORTANT. When moved to a different screen after an action or do not know the coordinates of component, **always** perform proper discovery first.
+IMPORTANT. When moved to a different screen after an action or you do not know the coordinates of a component, **always** perform proper discovery first. Pick one discovery/action path:
+
+- **Unknown target or layout**: start with `describe` / `debugger-component-tree`; if it returns a frame/tap point for the intended target, follow with `gesture-tap`.
+- **Known visible target, no current coordinates**: use `find` directly. Do not call `describe` first just to preflight the same target.
+- **Current coordinates already known**: use `gesture-tap`. Do not re-locate the same target with `find`.
+- **`find` failed or reported multiple plausible matches**: narrow `query` / `by` / `index`, or use `describe` / `debugger-component-tree` once to inspect the screen. After that inspection, act with either `gesture-tap` on the returned coordinates or a narrowed `find`, not both for the same target.
 
 | App type                          | Discovery tool            | What it returns                                                                                                                                                                                                                                     |
 | --------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Target app discovery              | `describe`                | Accessibility element tree for the current device screen (iOS AX-service, Android uiautomator, or Chromium DOM walker) with normalized frame coordinates. Works on any app, system dialogs, and Home screen — no app restart or `bundleId` required |
 | React Native                      | `debugger-component-tree` | React component tree with names, text, testID, and (tap: x,y)                                                                                                                                                                                       |
+| Known-target shortcut             | `find`                    | Matches the current accessibility/DOM tree by text/label/value/role/id and can tap/type/fill/read in one call. Use only when the target is already known and you do not already have a current frame/tap point for it                               |
 | App-scoped native                 | `native-describe-screen`  | Low-level app-scoped accessibility elements with normalized and raw coordinates; requires `bundleId`                                                                                                                                                |
 | Permission / system modal overlay | `describe`                | `describe` detects system dialogs automatically and returns dialog buttons with tap coordinates. Fall back to `screenshot` only if `describe` does not expose the controls                                                                          |
 | Final visual fallback             | `screenshot`              | Use only when discovery tools cannot inspect the current UI reliably. Do not derive routine in-app navigation targets from screenshots                                                                                                              |
@@ -179,6 +187,24 @@ Special keys: `enter`, `escape`, `backspace`, `tab`, `space`, `arrow-up`, `arrow
 
 Values: `Portrait`, `LandscapeLeft`, `LandscapeRight`, `PortraitUpsideDown`
 
+### find — Locate an element and optionally act on it
+
+`find` is a locate-and-act shortcut for a known target when you do not already have current coordinates: it matches the same accessibility/DOM tree as `describe`, picks the element, and performs an action. Use it for a specific visible target named by the user or known from the current screen context. Do **not** call `find` immediately after `describe` for the same target if `describe` returned a reliable frame/tap point; use `gesture-tap` instead. If you need to discover what is on screen, use `describe` / `debugger-component-tree` first. (iOS / Android / Chromium; not Vega.) On a **TV target** (Apple TV / Android TV) `find` is **read-only** — the acting actions (`tap`/`focus`/`type`/`fill`) are rejected because a D-pad UI ignores coordinate taps; use the locate/read actions to find elements and `tv-remote` (+ `keyboard`) to act.
+
+```json
+{ "udid": "<UDID>", "query": "Sign In", "by": "text", "action": "tap" }
+```
+
+- `query`: case-insensitive substring matched against the attribute named by `by`.
+- `by`: `any` (label/value/id — default), `text` (label or value), `label`, `value`, `role`, or `id`.
+- `action`: `tap` (default, centre), `focus`, `type` (focus + type `text`), `fill` (focus + clear + type `text`), `exists` (single presence check, no wait), `wait` (block until visible, `timeoutMs` default 5000ms), `get-text`, `get-attrs`.
+- `text`: the string to enter, required for `type` / `fill`.
+- `index`: when several match, which one to act on. For read (`get-text`/`get-attrs`) and `wait` it is `0 = topmost in reading order`; for a **tapping** action (`tap`/`focus`/`type`/`fill`) an enclosing container is ranked _after_ the smaller matches it wraps, so `0` is the innermost/most-specific match (this is what makes `find` pick a child input over the card that folds its text on Android). `exists` is a pure presence check and **ignores `index`** (it reports whether _any_ element matches, and its `match` is always the topmost visible one). `matchCount` counts the matches `index` can address — **visible** matches for the acting actions and `wait`, **all** matches for `get-text`/`get-attrs`/`exists` — so if it is `> 1`, narrow `query` or set `index`.
+- By default a **single snapshot** is taken (no wait). Set `timeoutMs` to poll until the element appears before acting (turns `find … tap` into wait-then-tap).
+- Returns `{ found, matchCount, match?, actionResult?, elapsed, note? }`. `found: false` carries a `note` explaining why (no match / not visible / index out of range / degraded read). It does **not** throw, so still confirm `found` before assuming the action ran. For `exists`, a `presenceUnknown: true` flag means the screen couldn't be read reliably — no tree at all (fetch error/hang), or an empty tree the adapter flagged as degraded (iOS AX down, app mid-restart, tvOS focus tree) — so `found: false` is "couldn't tell", not "confirmed absent".
+
+Use `describe` instead when you need the whole screen, need coordinates for a manual gesture, or are disambiguating a crowded layout.
+
 ### await-ui-element — Block until a UI element reaches a state
 
 Instead of polling `screenshot`/`describe` in a loop, use `await-ui-element` to block server-side until an element reaches an expected state (or `timeoutMs`, default 5000ms, elapses). It polls the same accessibility/DOM tree as `describe`. (For a plain pause, use your own harness sleep — this tool deliberately has no bare-timer mode.)
diff --git a/packages/skills/skills/argent-react-native-app-workflow/SKILL.md b/packages/skills/skills/argent-react-native-app-workflow/SKILL.md
index eba0c7975..f6b119382 100644
--- a/packages/skills/skills/argent-react-native-app-workflow/SKILL.md
+++ b/packages/skills/skills/argent-react-native-app-workflow/SKILL.md
@@ -157,14 +157,14 @@ For full simulator setup workflow, refer to the `argent-ios-simulator-setup` ski
 
 ### 4.1 Where to Look
 
-| Problem type                      | Tool / Where to look                                                                                                                                                                                                                                              |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **JavaScript errors / logs**      | Use `debugger-log-registry` to get a summary and log file path, then `Grep`/`Read` to search.                                                                                                                                                                     |
-| **React component hierarchy**     | Use `debugger-component-tree` tool for a text tree, or `debugger-inspect-element` at specific logical pixel coordinates (not normalized 0-1).                                                                                                                     |
-| **Visual state of the app**       | Use `screenshot` tool to capture the current screen, but prefer `describe` or `debugger-component-tree` for actual navigation and target discovery. If a permission prompt or system-owned modal overlay is not exposed reliably, then fall back to `screenshot`. |
-| **Evaluate JS in the app**        | Use `debugger-evaluate` tool to run JavaScript in the app's runtime.                                                                                                                                                                                              |
-| **Native crashes / native stack** | `npx react-native log-ios` or iOS Simulator: Debug → Open System Log.                                                                                                                                                                                             |
-| **Build/runtime config**          | `metro.config.js`, `babel.config.js`, `package.json` scripts, `ios/Podfile`.                                                                                                                                                                                      |
+| Problem type                      | Tool / Where to look                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **JavaScript errors / logs**      | Use `debugger-log-registry` to get a summary and log file path, then `Grep`/`Read` to search.                                                                                                                                                                                                                                                                                                                                                                      |
+| **React component hierarchy**     | Use `debugger-component-tree` tool for a text tree, or `debugger-inspect-element` at specific logical pixel coordinates (not normalized 0-1).                                                                                                                                                                                                                                                                                                                      |
+| **Visual state of the app**       | Use `screenshot` tool to capture the current screen. For interaction, use `describe` / `debugger-component-tree` when you need to learn the screen, coordinates, or disambiguation, then use `gesture-tap` on returned coordinates. Use `find` directly only for a named/id-known visible control whose current coordinates you do not already have. If a permission prompt or system-owned modal overlay is not exposed reliably, then fall back to `screenshot`. |
+| **Evaluate JS in the app**        | Use `debugger-evaluate` tool to run JavaScript in the app's runtime.                                                                                                                                                                                                                                                                                                                                                                                               |
+| **Native crashes / native stack** | `npx react-native log-ios` or iOS Simulator: Debug → Open System Log.                                                                                                                                                                                                                                                                                                                                                                                              |
+| **Build/runtime config**          | `metro.config.js`, `babel.config.js`, `package.json` scripts, `ios/Podfile`.                                                                                                                                                                                                                                                                                                                                                                                       |
 
 For comprehensive Metro debugging workflows (component inspection, console logs, JS evaluation), refer to the `argent-metro-debugger` skill.
 
@@ -209,27 +209,28 @@ If the user's intent is ambiguous (run existing tests, write new tests, or find
 
 ## Quick Reference: Tools & Commands
 
-| Goal                         | Tool / Command                                                                                                                           |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| Check port 8081              | `lsof -i :8081`                                                                                                                          |
-| Kill Metro                   | `stop-metro` tool                                                                                                                        |
-| Start Metro                  | `npx react-native start`                                                                                                                 |
-| Start Metro (reset cache)    | `npx react-native start --reset-cache`                                                                                                   |
-| Run iOS app                  | `npx react-native run-ios`                                                                                                               |
-| Run Android app              | `npx react-native run-android`                                                                                                           |
-| List devices                 | `list-devices` tool (iOS + Android)                                                                                                      |
-| Boot a device                | `boot-device` tool (pass `udid` for iOS or `avdName` for Android)                                                                        |
-| Take screenshot              | `screenshot` tool                                                                                                                        |
-| Compare visible UI changes   | `screenshot-diff` tool; follow the `argent-screenshot-diff` skill for baseline/current capture choices                                   |
-| Describe screen (a11y tree)  | `describe` tool for normal app screens and in-app modals; use `screenshot` only when permission/system overlays are not exposed reliably |
-| Read JS console logs         | `debugger-log-registry` tool                                                                                                             |
-| Reload JS bundle             | `debugger-reload-metro` tool                                                                                                             |
-| Check Metro status           | `debugger-status` tool                                                                                                                   |
-| Inspect React component tree | `debugger-component-tree` tool                                                                                                           |
-| Run JS in app                | `debugger-evaluate` tool                                                                                                                 |
-| iOS native logs              | `npx react-native log-ios`                                                                                                               |
-| Android native logs          | `npx react-native log-android` or `adb -s <serial> logcat`                                                                               |
-| Clean + reinstall (nuclear)  | See §3.1 step 3                                                                                                                          |
+| Goal                         | Tool / Command                                                                                                                                 |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Check port 8081              | `lsof -i :8081`                                                                                                                                |
+| Kill Metro                   | `stop-metro` tool                                                                                                                              |
+| Start Metro                  | `npx react-native start`                                                                                                                       |
+| Start Metro (reset cache)    | `npx react-native start --reset-cache`                                                                                                         |
+| Run iOS app                  | `npx react-native run-ios`                                                                                                                     |
+| Run Android app              | `npx react-native run-android`                                                                                                                 |
+| List devices                 | `list-devices` tool (iOS + Android)                                                                                                            |
+| Boot a device                | `boot-device` tool (pass `udid` for iOS or `avdName` for Android)                                                                              |
+| Take screenshot              | `screenshot` tool                                                                                                                              |
+| Compare visible UI changes   | `screenshot-diff` tool; follow the `argent-screenshot-diff` skill for baseline/current capture choices                                         |
+| Locate and act on a target   | `find` tool for specific visible controls when current coordinates are not already known; confirm `found: true` before assuming the action ran |
+| Describe screen (a11y tree)  | `describe` tool for normal app screens and in-app modals; use `screenshot` only when permission/system overlays are not exposed reliably       |
+| Read JS console logs         | `debugger-log-registry` tool                                                                                                                   |
+| Reload JS bundle             | `debugger-reload-metro` tool                                                                                                                   |
+| Check Metro status           | `debugger-status` tool                                                                                                                         |
+| Inspect React component tree | `debugger-component-tree` tool                                                                                                                 |
+| Run JS in app                | `debugger-evaluate` tool                                                                                                                       |
+| iOS native logs              | `npx react-native log-ios`                                                                                                                     |
+| Android native logs          | `npx react-native log-android` or `adb -s <serial> logcat`                                                                                     |
+| Clean + reinstall (nuclear)  | See §3.1 step 3                                                                                                                                |
 
 ---
 
diff --git a/packages/skills/skills/argent-react-native-profiler/SKILL.md b/packages/skills/skills/argent-react-native-profiler/SKILL.md
index 9076beb19..82a8a37a5 100644
--- a/packages/skills/skills/argent-react-native-profiler/SKILL.md
+++ b/packages/skills/skills/argent-react-native-profiler/SKILL.md
@@ -88,7 +88,7 @@ Mind the react-native and ios-native profiler selection mentioned above when sta
 
 #### Annotate every interaction
 
-After each `gesture-tap` or `gesture-swipe` call, record an annotation using the returned `timestampMs`. Compute `offsetMs = timestampMs - startedAtEpochMs`. Do this for _every_ interaction — including back-navigation swipes, not just the primary action. Pass all collected annotations to `react-profiler-analyze` in Step 3.
+After each `gesture-tap`, `gesture-swipe`, or `find` call that performs `action: "tap"` / `action: "focus"`, record an annotation using the returned `timestampMs` (`find` exposes it as `actionResult.timestampMs` for `tap` / `focus`). Compute `offsetMs = timestampMs - startedAtEpochMs`. Do this for _every_ interaction — including back-navigation swipes, not just the primary action. Pass all collected annotations to `react-profiler-analyze` in Step 3. If text entry timing matters, use `find` `action: "focus"` or `gesture-tap` to capture the focus timestamp, then call `keyboard`; `find` `type` / `fill` actions do not expose a timestamp.
 
 ### Step 2: Stop and collect
 
@@ -99,7 +99,7 @@ If `fiber_renders_captured: 0`, warn the user — React commit data may be missi
 
 Call `react-profiler-analyze` with `port`, `device_id`, `project_root`, `platform`, and `rn_version`. The report includes metadata such as `reactCompilerEnabled`, `strictModeEnabled`, and `buildMode` — check these in the returned markdown report.
 
-If you performed interactions using `gesture-tap`/`gesture-swipe`, pass `annotations` to mark when each action occurred. Each annotation's `offsetMs` must be computed as `tapTimestampMs - startedAtEpochMs`, where `tapTimestampMs` is the `timestampMs` returned by the gesture-tap/gesture-swipe tool and `startedAtEpochMs` was returned by `react-profiler-start`. Do **not** use `Date.now()` for this calculation — only server-side timestamps from the tool return values.
+If you performed interactions using `gesture-tap`, `gesture-swipe`, or `find` tap/focus actions, pass `annotations` to mark when each action occurred. Each annotation's `offsetMs` must be computed as `interactionTimestampMs - startedAtEpochMs`, where `interactionTimestampMs` is the server-side `timestampMs` returned by the interaction tool (`actionResult.timestampMs` for `find`) and `startedAtEpochMs` was returned by `react-profiler-start`. Do **not** use `Date.now()` for this calculation.
 
 If dual profiling, also call `native-profiler-analyze`, then **you must** call `profiler-combined-report` for the cross-correlated view — do not skip this step when both profilers ran; the combined report surfaces correlations that individual reports miss.
 
diff --git a/packages/skills/skills/argent-screenshot-diff/SKILL.md b/packages/skills/skills/argent-screenshot-diff/SKILL.md
index dbe0dde39..d59ea9dbe 100644
--- a/packages/skills/skills/argent-screenshot-diff/SKILL.md
+++ b/packages/skills/skills/argent-screenshot-diff/SKILL.md
@@ -7,7 +7,7 @@ description: Compare saved or live app screenshots with the argent screenshot-di
 
 Use `screenshot-diff` as supporting visual evidence for UI QA and visual regression checks. It highlights pixel-visible change or stability; it does not replace visual inspection, accessibility/component-tree state, frame/attribute checks, logs, network evidence, or app behavior.
 
-Do not use screenshot diffing for tap-coordinate discovery. Use `describe`, `debugger-component-tree`, or `native-describe-screen` to find targets first.
+Do not use screenshot diffing for tap-coordinate discovery. Use `describe`, `debugger-component-tree`, or `native-describe-screen` when you need coordinates or full-screen context, then tap returned coordinates with `gesture-tap`. Use `find` directly only for named locate-and-act targets whose current coordinates you do not already have.
 
 ## 2. When To Use
 
diff --git a/packages/skills/skills/argent-test-ui-flow/SKILL.md b/packages/skills/skills/argent-test-ui-flow/SKILL.md
index 0c72b0db2..ff756a90d 100644
--- a/packages/skills/skills/argent-test-ui-flow/SKILL.md
+++ b/packages/skills/skills/argent-test-ui-flow/SKILL.md
@@ -5,7 +5,7 @@ description: Autonomously test an app UI (iOS or Android) by running interact-sc
 
 ## Platform-agnostic
 
-The interaction tool names are identical on iOS and Android — `gesture-tap`, `gesture-swipe`, `describe`, `screenshot`, `launch-app`, etc. — and the tool-server auto-dispatches based on the `udid` you pass (UUID-shape → iOS, adb serial → Android).
+The interaction tool names are identical on iOS and Android — `find`, `gesture-tap`, `gesture-swipe`, `describe`, `screenshot`, `launch-app`, etc. — and the tool-server auto-dispatches based on the `udid` you pass (UUID-shape → iOS, adb serial → Android).
 
 **Before testing, resolve which device to test on.** Call `list-devices` and follow `<device_selection_rule>`: prefer a running device on any platform;
 
@@ -23,13 +23,13 @@ All interactions go through argent MCP tools. Ensure the simulator/emulator is r
 For implementation tasks that modify visible UI, this workflow can also serve as a visual acceptance path.
 
 1. **Baseline screenshot**: Call `screenshot` to see the current UI state. For visual regression comparison or UI change verification, capture the baseline at `scale: 1.0` with `includeImageInContext: false` and keep the returned `path` before editing whenever feasible.
-2. **Find target**: Before tapping, use a discovery tool to get element coordinates:
+2. **Choose one target path**: If you need to learn what is on screen, start with a discovery tool and then use `gesture-tap` on the returned coordinates. Use `find` only for a specific visible control whose text, label, value, role, or id is already known and whose current coordinates you do not already have; confirm `found: true` before assuming the action ran.
    - **React Native apps**: use `debugger-component-tree` — it returns component names with (tap: x,y) coordinates. This is the preferred tool for RN apps on either platform. To use it, resolve the `argent-react-native-app-workflow` skill for setup; on Android you must also run `adb -s <serial> reverse tcp:8081 tcp:8081` so Metro is reachable from the device.
    - **Standard app screens and in-app modals**: use `describe`. On iOS this returns the AX tree (falls back to native-devtools when AX is empty); on Android it returns the uiautomator tree in the same DescribeNode shape.
    - **Permission prompts / system modal overlays**: try `describe` first. Fall back to `screenshot` only if the overlay is not exposed reliably.
    - **Fallback**: use `screenshot` to estimate where the desired component is, then verify immediately after the action.
-3. **Interact**: Perform the action (`gesture-tap`, `gesture-swipe`, `keyboard`, `button`, ...) — you receive a screenshot automatically.
-4. **Verify**: Check the returned screenshot for expected results. If it shows a loading/transitional state, prefer blocking until it settles with `await-ui-element` (expected element `visible`, or a spinner `hidden`) over a guessed delay — but only with a selector you can trust (`text`/`identifier`/`role`) that the screen is known to have or that you saw in a prior `describe`; a guessed one just times out. Otherwise use a short fixed wait. Pick evidence by what's being asserted:
+3. **Interact**: Perform the action (`find`, `gesture-tap`, `gesture-swipe`, `keyboard`, `button`, ...) — you receive a screenshot automatically. If `describe` / `debugger-component-tree` already gave you a tap coordinate for the target, use `gesture-tap` rather than a second `find`.
+4. **Verify**: Check the returned screenshot for expected results. If it shows a loading/transitional state, prefer blocking until it settles with `await-ui-element` (expected element `visible`, or a spinner `hidden`) over a guessed delay — but only with a selector you can trust (`text`/`identifier`/`role`) that the screen is known to have, that came from the `find` target, or that you saw in a prior `describe`; a guessed one just times out. Otherwise use a short fixed wait. Pick evidence by what's being asserted:
    - **Visual** (layout, spacing, color, typography, image/icon rendering, clipping, overflow, text rendering): prefer `screenshot-diff` against the baseline captured in step 1 — it surfaces pixel-visible changes the auto-screenshot might miss. Fall back to visual inspection of the auto-screenshot only when a stable baseline isn't available.
    - **Structural** (navigation state, element existence, accessibility labels/values, selection, hierarchy, route): verify with `describe`, `debugger-component-tree`, or `native-describe-screen`.
    - **Runtime / log / network** (console errors, API calls, persistence, timing): verify with `view-network-logs`, `debugger-log-registry`, `debugger-evaluate`, or targeted tests.
@@ -44,7 +44,7 @@ Goal: Test [feature name]
 
 Steps:
 1. Classify expected result: visual / structural / runtime-log-network / mixed → choose evidence
-2. [Navigate / tap / type to reach stable comparable starting point] → verify auto-screenshot
+2. [Navigate / tap / type; use `describe` -> `gesture-tap` for unknown screens, or `find` directly only for known named/id targets without current coordinates] → verify auto-screenshot and any `found` result
 3. screenshot { scale: 1.0, includeImageInContext: false } → save baseline path when visual or mixed evidence needs diffing
 4. [Perform the action to test] → verify auto-screenshot
 5. Use screenshot-diff when requested or when comparable images add useful visual evidence
@@ -57,12 +57,10 @@ Steps:
 
 ```
 1. screenshot → see login screen
-2. gesture-tap { x: 0.5, y: 0.4 }  → tap email field
-3. keyboard { text: "user@example.com" }
-4. gesture-tap { x: 0.5, y: 0.55 } → tap password field
-5. keyboard { text: "password123" }
-6. gesture-tap { x: 0.5, y: 0.7 }  → tap Login button
-7. screenshot → verify home screen appeared
+2. find { query: "Email", by: "text", action: "fill", text: "user@example.com" } → confirm found
+3. find { query: "Password", by: "text", action: "fill", text: "password123" } → confirm found
+4. find { query: "Login", by: "text", action: "tap" } → confirm found
+5. screenshot / describe → verify home screen appeared
 ```
 
 ### Scroll and navigation
@@ -70,7 +68,7 @@ Steps:
 ```
 1. screenshot → see list at top
 2. gesture-swipe { fromY: 0.7, toY: 0.3 } → scroll down
-3. gesture-tap item at visible position → verify auto-screenshot
+3. If the item label is known: find { query: "<visible item label>", by: "text", action: "tap" } → confirm found. If not, describe → choose coordinates → gesture-tap.
 4. screenshot → verify detail view opened
 5. button { button: "back" }
 6. screenshot → verify returned to list
@@ -82,11 +80,10 @@ Steps:
 1. Classify expected result as visual or mixed.
 2. Navigate to the stable starting state.
 3. screenshot { scale: 1.0, includeImageInContext: false } → save baseline path.
-4. describe / debugger-component-tree → find the control and use its returned tap coordinates.
-5. gesture-tap → perform the visual behavior under test.
-6. screenshot-diff { baselinePath, captureCurrent: true, udid, outputDir } → inspect visible change or stability.
-7. describe / debugger-component-tree → verify selected state, label, route, or attributes if relevant.
-8. Report combined verdict from expected behavior, visual inspection, diff summary, and structural evidence.
+4. Use exactly one action path: `find` when the label/id is already known and current coordinates are not; otherwise `describe` / `debugger-component-tree` followed by `gesture-tap`.
+5. screenshot-diff { baselinePath, captureCurrent: true, udid, outputDir } → inspect visible change or stability.
+6. describe / debugger-component-tree → verify selected state, label, route, or attributes if relevant.
+7. Report combined verdict from expected behavior, visual inspection, diff summary, and structural evidence.
 ```
 
 ### Wait for a loading spinner
@@ -103,7 +100,8 @@ Steps:
 ## 4. Recovery Pattern
 
 - If a screen is mid-transition or loading: block until it settles with `await-ui-element` (wait for the target element to be `visible`, or the spinner/placeholder to be `hidden`) instead of a blind fixed delay, then re-check. Fall back to a fixed wait + `screenshot` only when no element reliably marks the transition.
-- If tap misses target: re-run discovery tool (`describe` / `debugger-component-tree`), retry once with new coordinates.
+- If `find` returns `found: false`, `presenceUnknown: true`, or an ambiguous `matchCount`: narrow the query, set `by`/`index`, or switch to `describe` / `debugger-component-tree` for one full-screen disambiguation pass. After that pass, use returned coordinates with `gesture-tap` when available; use a narrowed `find` only if the inspection did not produce a reliable target coordinate.
+- If coordinate tap misses target: re-run discovery tool (`describe` / `debugger-component-tree`), retry once with new coordinates.
 - If a permission dialog or modal is visible: re-run `describe` first. Stay in screenshot-driven navigation only when the overlay is not exposed reliably, then switch back to `describe` / `debugger-component-tree` as soon as it is dismissed.
 - If tap fails twice at same coordinates: stop, re-discover, report if element not found.
 - If a **saved flow** fails during `flow-execute` replay (as opposed to live test steps above): follow `argent-create-flow` skill §10 for structured diagnosis and correction.
diff --git a/packages/tool-server/src/tools/await-ui-element/index.ts b/packages/tool-server/src/tools/await-ui-element/index.ts
index d5c33182d..2e86140bd 100644
--- a/packages/tool-server/src/tools/await-ui-element/index.ts
+++ b/packages/tool-server/src/tools/await-ui-element/index.ts
@@ -1,22 +1,28 @@
 import { z } from "zod";
 import type {
-  DeviceInfo,
   Registry,
   ServiceRef,
   ToolCapability,
   ToolContext,
   ToolDefinition,
 } from "@argent/registry";
-import { chromiumCdpRef, type ChromiumCdpApi } from "../../blueprints/chromium-cdp";
+import { chromiumCdpRef } from "../../blueprints/chromium-cdp";
 import { resolveDevice } from "../../utils/device-info";
 import { isTvOsSimulator } from "../../utils/ios-devices";
 import { assertSupported } from "../../utils/capability";
 import { ensureDeps } from "../../utils/check-deps";
-import { sleepOrAbort } from "../../utils/timing";
+import { sleepOrAbort, settleWithin } from "../../utils/timing";
 import type { DescribeNode, DescribeTreeData } from "../describe/contract";
-import { describeIos, iosRequires } from "../describe/platforms/ios";
-import { describeAndroid, androidRequires } from "../describe/platforms/android";
-import { describeChromium } from "../describe/platforms/chromium";
+import {
+  includesCI,
+  isVisible,
+  nodeText,
+  firstInReadingOrder,
+  walkMatches,
+} from "../describe/match";
+import { fetchDescribeTree, appendDescribeDiagnostics } from "../describe/fetch-tree";
+import { iosRequires } from "../describe/platforms/ios";
+import { androidRequires } from "../describe/platforms/android";
 
 // Tool id. Exported so run-sequence can both allow this tool and recognise its
 // result shape (it returns { success: false } instead of throwing on an unmet
@@ -138,14 +144,11 @@ const capability: ToolCapability = {
 };
 
 // ── Tree matching ────────────────────────────────────────────────────────
-
-function nodeText(node: DescribeNode): string {
-  return [node.label, node.value].filter(Boolean).join(" ");
-}
-
-function includesCI(haystack: string | undefined, needle: string): boolean {
-  return Boolean(haystack) && haystack!.toLowerCase().includes(needle.toLowerCase());
-}
+//
+// The pure tree primitives (`includesCI`, `nodeText`, `isVisible`,
+// `firstInReadingOrder`, the root-excluding `walkMatches`) live in
+// `../describe/match` so `find` reuses the same hardened root-exclusion and
+// reading-order rules. Only the selector-shaped predicate stays local.
 
 function matchNode(node: DescribeNode, selector: Selector): boolean {
   if (selector.text !== undefined) {
@@ -162,68 +165,12 @@ function matchNode(node: DescribeNode, selector: Selector): boolean {
   return true;
 }
 
-function collectMatches(node: DescribeNode, selector: Selector, acc: DescribeNode[]): void {
-  if (matchNode(node, selector)) acc.push(node);
-  for (const child of node.children) collectMatches(child, selector, acc);
-}
-
-// Every node matching the selector in the subtree, EXCLUDING `root` itself.
-//
-// `root` is the top-level container describe puts at the head of the tree. On
-// iOS / Android it's a synthetic full-screen node (iOS `AXGroup`, Android
-// `hierarchy`/`Screen`; frame `0,0,1,1`); on Chromium it's the REAL `<html>`
-// element (`describeChromium` walks `document.documentElement`), framed from
-// `getBoundingClientRect` rather than a synthetic `0,0,1,1`. Whatever its frame,
-// `describe` renders this node only as a non-selectable `ROOT` header line, never
-// as a matchable element, and its frame always passes `isVisible`. Matching it
-// would let a role selector that is a substring of the root role (e.g.
-// `role:"AXGroup"`, also iOS's default role for untyped elements) satisfy
-// `visible`/`exists` on any screen — including an empty AX tree — and make
-// `hidden` impossible. So we skip it, walking `root.children` only — the one rule
-// we share with format-tree. (Chromium side effect: the `<html>` element's own
-// id / aria-label / author role sit on this excluded root, so a selector
-// targeting those attributes matches nothing there.)
-//
-// Past that root exclusion we do NOT mirror describe's rendered body: describe
-// drops structural / unlabeled nodes through a content-and-role filter before
-// printing, but `findAll` tests every remaining node. So a role- or
-// identifier-only selector can match a container (e.g. an unlabeled `AXGroup`)
-// that never appears in describe's output — keep that in mind when a
-// `visible`/`exists` selector is broad. A substring selector can also match
-// several real nodes, so conditions are evaluated across the whole set (see
-// evaluateMatches). Exported for unit tests.
+// Every node matching the selector in the subtree, EXCLUDING the synthetic root
+// (see `walkMatches`). A substring selector can match several real nodes, so
+// conditions are evaluated across the whole set (see evaluateMatches). Exported
+// for unit tests.
 export function findAll(root: DescribeNode, selector: Selector): DescribeNode[] {
-  const acc: DescribeNode[] = [];
-  for (const child of root.children) collectMatches(child, selector, acc);
-  return acc;
-}
-
-// describe prunes off-screen / zero-size nodes on Chromium and the compressed
-// Android dump, and iOS AX only returns on-screen leaves — so a non-zero frame
-// area is a cheap, reliable proxy for "visible".
-function isVisible(node: DescribeNode): boolean {
-  return node.frame.width > 0 && node.frame.height > 0;
-}
-
-// The describe tool renders iOS leaves sorted into reading order (top-to-bottom,
-// then left-to-right) via format-tree's renderFlat, so the element the agent
-// "sees first" is the one with the smallest (y, then x). The `text` verdict and
-// the timeout note key off a single element, so pick that same one — otherwise
-// they'd refer to whichever node DFS happened to reach first, which on iOS can
-// differ from what the agent read at the top of describe. Returns undefined for
-// an empty set.
-function firstInReadingOrder(matches: DescribeNode[]): DescribeNode | undefined {
-  let best: DescribeNode | undefined;
-  for (const n of matches) {
-    if (
-      best === undefined ||
-      n.frame.y < best.frame.y ||
-      (n.frame.y === best.frame.y && n.frame.x < best.frame.x)
-    ) {
-      best = n;
-    }
-  }
-  return best;
+  return walkMatches(root, (n) => matchNode(n, selector));
 }
 
 // Evaluate the condition over ALL elements matching the selector, not just the
@@ -269,21 +216,6 @@ function isBlindRead(data: DescribeTreeData, everMatched: boolean): boolean {
   return Boolean(data.hint || data.should_restart || everMatched);
 }
 
-// Fold an unreliable-read hint / restart prompt onto a timeout note so the agent
-// learns the real cause (degraded AX, native injection pending) rather than a
-// bare "no element matched".
-function appendDiagnostics(base: string, lastData: DescribeTreeData | null): string {
-  if (!lastData) return base;
-  const extras: string[] = [];
-  if (lastData.should_restart) {
-    extras.push(
-      "the foreground app may need a restart for native inspection — call restart-app and retry"
-    );
-  }
-  if (lastData.hint) extras.push(lastData.hint);
-  return extras.length === 0 ? base : `${base} (${extras.join("; ")})`;
-}
-
 function timeoutNote(
   params: Params,
   lastTree: DescribeNode | null,
@@ -315,47 +247,7 @@ function timeoutNote(
     default:
       base = "no element matched the selector before timeout";
   }
-  return appendDiagnostics(base, lastData);
-}
-
-// ── Per-fetch deadline / abort ─────────────────────────────────────────────
-
-type Settled<T> =
-  | { type: "value"; value: T }
-  | { type: "error"; error: string }
-  | { type: "timeout" }
-  | { type: "aborted" };
-
-// Race a tree fetch against the remaining wait budget and the abort signal. The
-// underlying describe fetch isn't cancellable (no AbortSignal reaches adb /
-// AXRuntime), so a slow or hung fetch — e.g. the Android `uiautomator dump`
-// fallback, which allows up to 20s — would otherwise blow past `timeoutMs` and
-// ignore an abort that arrives mid-fetch. We can't kill the orphaned fetch, but
-// we stop waiting on it; its eventual settle is consumed here (handlers attached
-// up front) so it can't surface as an unhandled rejection.
-function settleWithin<T>(p: Promise<T>, ms: number, signal?: AbortSignal): Promise<Settled<T>> {
-  return new Promise((resolve) => {
-    let done = false;
-    const teardown: Array<() => void> = [];
-    const finish = (r: Settled<T>) => {
-      if (done) return;
-      done = true;
-      for (const fn of teardown) fn();
-      resolve(r);
-    };
-    // Attach the settle handlers up front so a late settle from an abandoned
-    // fetch is always consumed (no unhandled rejection) even after we've moved on.
-    p.then(
-      (value) => finish({ type: "value", value }),
-      (err) => finish({ type: "error", error: err instanceof Error ? err.message : String(err) })
-    );
-    if (signal?.aborted) return finish({ type: "aborted" });
-    const onAbort = () => finish({ type: "aborted" });
-    signal?.addEventListener("abort", onAbort, { once: true });
-    teardown.push(() => signal?.removeEventListener("abort", onAbort));
-    const timer = setTimeout(() => finish({ type: "timeout" }), Math.max(0, ms));
-    teardown.push(() => clearTimeout(timer));
-  });
+  return appendDescribeDiagnostics(base, lastData);
 }
 
 // ── Tool ─────────────────────────────────────────────────────────────────
@@ -365,21 +257,6 @@ function settleWithin<T>(p: Promise<T>, ms: number, signal?: AbortSignal): Promi
 // rather than through the tool's own services() declaration. Only the Chromium
 // CDP session flows in as a normal service.
 export function createAwaitUiElementTool(registry: Registry): ToolDefinition<Params, WaitResult> {
-  async function fetchTree(
-    device: DeviceInfo,
-    params: Params,
-    services: Record<string, unknown>,
-    isTvOs: boolean
-  ): Promise<DescribeTreeData> {
-    if (device.platform === "ios") {
-      return describeIos(registry, device, { bundleId: params.bundleId }, { isTvOs });
-    }
-    if (device.platform === "android") {
-      return describeAndroid(registry, device.id);
-    }
-    return describeChromium(services.chromium as ChromiumCdpApi);
-  }
-
   return {
     id: AWAIT_UI_ELEMENT_TOOL_ID,
     description: `Block until a UI element reaches an expected state or a timeout elapses, so you don't have to poll screenshot/describe yourself.
@@ -455,7 +332,9 @@ or before tapping an element that appears asynchronously.`,
         // promptly instead of after the fetch resolves.
         const remaining = Math.max(0, deadline - Date.now());
         const settled = await settleWithin(
-          fetchTree(device, params, services, isTvOs),
+          // Pass the pre-resolved tvOS verdict so a poll loop doesn't re-shell
+          // `xcrun` each iteration (isTvOs is resolved once above the loop).
+          fetchDescribeTree(registry, device, params, services, { isTvOs }),
           remaining,
           signal
         );
diff --git a/packages/tool-server/src/tools/describe/fetch-tree.ts b/packages/tool-server/src/tools/describe/fetch-tree.ts
new file mode 100644
index 000000000..5d02b7d65
--- /dev/null
+++ b/packages/tool-server/src/tools/describe/fetch-tree.ts
@@ -0,0 +1,47 @@
+import type { DeviceInfo, Registry } from "@argent/registry";
+import type { ChromiumCdpApi } from "../../blueprints/chromium-cdp";
+import type { DescribeTreeData } from "./contract";
+import { describeIos } from "./platforms/ios";
+import { describeAndroid } from "./platforms/android";
+import { describeChromium } from "./platforms/chromium";
+
+// Shared describe-tree fetch used by the tools that poll the accessibility / DOM
+// tree (`await-ui-element`, `find`). iOS / Android resolve their AX /
+// android-devtools services through the `registry` (not the calling tool's
+// services() declaration); Chromium's CDP session flows in as a normal service.
+// Kept in one place so both pollers fetch identically and stay in sync.
+//
+// `options.isTvOs` lets a polling caller pre-resolve the tvOS verdict once and
+// pass it in, so the hot path doesn't re-shell `xcrun` on every poll iteration;
+// omitted, `describeIos` probes it itself (fine for a single-shot fetch).
+export async function fetchDescribeTree(
+  registry: Registry,
+  device: DeviceInfo,
+  params: { bundleId?: string },
+  services: Record<string, unknown>,
+  options: { isTvOs?: boolean } = {}
+): Promise<DescribeTreeData> {
+  if (device.platform === "ios") {
+    return describeIos(registry, device, { bundleId: params.bundleId }, { isTvOs: options.isTvOs });
+  }
+  if (device.platform === "android") {
+    return describeAndroid(registry, device.id);
+  }
+  return describeChromium(services.chromium as ChromiumCdpApi);
+}
+
+// Fold an unreliable-read hint / restart prompt onto a not-found / timeout note
+// so the agent learns the real cause (degraded AX, native injection pending)
+// rather than a bare "no element matched". iOS `describeIos` attaches these to an
+// empty tree instead of throwing; Android / Chromium never set them.
+export function appendDescribeDiagnostics(base: string, data: DescribeTreeData | null): string {
+  if (!data) return base;
+  const extras: string[] = [];
+  if (data.should_restart) {
+    extras.push(
+      "the foreground app may need a restart for native inspection — call restart-app and retry"
+    );
+  }
+  if (data.hint) extras.push(data.hint);
+  return extras.length === 0 ? base : `${base} (${extras.join("; ")})`;
+}
diff --git a/packages/tool-server/src/tools/describe/match.ts b/packages/tool-server/src/tools/describe/match.ts
new file mode 100644
index 000000000..28d37e09a
--- /dev/null
+++ b/packages/tool-server/src/tools/describe/match.ts
@@ -0,0 +1,90 @@
+import type { DescribeNode } from "./contract";
+
+// Pure tree-matching primitives shared by the tools that locate a node in the
+// `describe` accessibility / DOM tree (`await-ui-element`, `find`). Kept free of
+// any selector / locator shape so each consumer can supply its own predicate
+// while reusing the one hardened copy of the root-exclusion walk, the
+// reading-order comparator, and the visibility proxy.
+
+// Case-insensitive substring test. Undefined haystack never matches.
+export function includesCI(haystack: string | undefined, needle: string): boolean {
+  return Boolean(haystack) && haystack!.toLowerCase().includes(needle.toLowerCase());
+}
+
+// The element's visible text — label and value joined. Used for `text`-style
+// assertions and diagnostics.
+export function nodeText(node: DescribeNode): string {
+  return [node.label, node.value].filter(Boolean).join(" ");
+}
+
+// describe prunes off-screen / zero-size nodes on Chromium and the compressed
+// Android dump, and iOS AX only returns on-screen leaves — so a non-zero frame
+// area is a cheap, reliable proxy for "visible".
+export function isVisible(node: DescribeNode): boolean {
+  return node.frame.width > 0 && node.frame.height > 0;
+}
+
+function collect(
+  node: DescribeNode,
+  predicate: (n: DescribeNode) => boolean,
+  acc: DescribeNode[]
+): void {
+  if (predicate(node)) acc.push(node);
+  for (const child of node.children) collect(child, predicate, acc);
+}
+
+// Every node satisfying `predicate` in the subtree, EXCLUDING `root` itself.
+//
+// `root` is the top-level container describe puts at the head of the tree. On
+// iOS / Android it's a synthetic full-screen node (iOS `AXGroup`, Android
+// `hierarchy`/`Screen`; frame `0,0,1,1`); on Chromium it's the REAL `<html>`
+// element (`describeChromium` walks `document.documentElement`), framed from
+// `getBoundingClientRect` rather than a synthetic `0,0,1,1`. Whatever its frame,
+// `describe` renders this node only as a non-selectable `ROOT` header line, never
+// as a matchable element, and its frame always passes `isVisible`. Matching it
+// would let a role predicate that is a substring of the root role (e.g.
+// `AXGroup`, also iOS's default role for untyped elements) satisfy
+// `visible`/`exists` on any screen — including an empty AX tree — and make
+// `hidden` impossible. So we skip it, walking `root.children` only — the one rule
+// we share with format-tree. (Chromium side effect: the `<html>` element's own
+// id / aria-label / author role sit on this excluded root, so a predicate
+// targeting those attributes matches nothing there.)
+//
+// Past that root exclusion we do NOT mirror describe's rendered body: describe
+// drops structural / unlabeled nodes through a content-and-role filter before
+// printing, but `walkMatches` tests every remaining node. So a role- or
+// identifier-only predicate can match a container (e.g. an unlabeled `AXGroup`)
+// that never appears in describe's output — keep that in mind when a predicate is
+// broad.
+export function walkMatches(
+  root: DescribeNode,
+  predicate: (n: DescribeNode) => boolean
+): DescribeNode[] {
+  const acc: DescribeNode[] = [];
+  for (const child of root.children) collect(child, predicate, acc);
+  return acc;
+}
+
+// Reading order: top-to-bottom, then left-to-right — the order describe's
+// `renderFlat` sorts iOS leaves into, so "first" here is the element the agent
+// "saw first" at the top of describe's output. Returns a NEW array.
+export function sortReadingOrder(matches: DescribeNode[]): DescribeNode[] {
+  return matches.slice().sort((a, b) => a.frame.y - b.frame.y || a.frame.x - b.frame.x);
+}
+
+// The single topmost-then-leftmost match (smallest y, then x). Returns undefined
+// for an empty set. Equivalent to `sortReadingOrder(matches)[0]` but without the
+// allocation.
+export function firstInReadingOrder(matches: DescribeNode[]): DescribeNode | undefined {
+  let best: DescribeNode | undefined;
+  for (const n of matches) {
+    if (
+      best === undefined ||
+      n.frame.y < best.frame.y ||
+      (n.frame.y === best.frame.y && n.frame.x < best.frame.x)
+    ) {
+      best = n;
+    }
+  }
+  return best;
+}
diff --git a/packages/tool-server/src/tools/find/index.ts b/packages/tool-server/src/tools/find/index.ts
new file mode 100644
index 000000000..bd7df570b
--- /dev/null
+++ b/packages/tool-server/src/tools/find/index.ts
@@ -0,0 +1,867 @@
+import { z } from "zod";
+import type {
+  Platform,
+  Registry,
+  ServiceRef,
+  ToolCapability,
+  ToolContext,
+  ToolDefinition,
+} from "@argent/registry";
+import { chromiumCdpRef } from "../../blueprints/chromium-cdp";
+import { resolveDevice } from "../../utils/device-info";
+import { isTvOsSimulator } from "../../utils/ios-devices";
+import { getAndroidRuntimeKind } from "../../utils/adb";
+import { assertSupported } from "../../utils/capability";
+import { ensureDeps } from "../../utils/check-deps";
+import { sleepOrAbort, settleWithin } from "../../utils/timing";
+import { invokeSubTool } from "../../utils/sub-invoke";
+import type { DescribeFrame, DescribeNode, DescribeTreeData } from "../describe/contract";
+import { getDescribeTapPoint } from "../describe/contract";
+import {
+  includesCI,
+  isVisible,
+  nodeText,
+  firstInReadingOrder,
+  sortReadingOrder,
+  walkMatches,
+} from "../describe/match";
+import { fetchDescribeTree, appendDescribeDiagnostics } from "../describe/fetch-tree";
+import { iosRequires } from "../describe/platforms/ios";
+import { androidRequires } from "../describe/platforms/android";
+
+export const FIND_TOOL_ID = "find";
+
+// `wait` blocks for the element to appear; the other actions are single-shot
+// unless the caller opts into polling with `timeoutMs`.
+const DEFAULT_WAIT_TIMEOUT_MS = 5000;
+const DEFAULT_POLL_INTERVAL_MS = 400;
+// Per-fetch budget for a single-shot (non-polling) action. The describe fetch
+// isn't cancellable, so this just caps a genuinely hung read (the Android
+// `uiautomator dump` can take ~20s) while still letting an abort be observed.
+const SINGLE_SHOT_FETCH_BUDGET_MS = 30_000;
+// Upper bound on the backspaces `fill` issues to clear a field, so a wrong /
+// masked value length can't spray unbounded deletes into surrounding content.
+const MAX_CLEAR_CHARS = 64;
+// A couple of extra backspaces beyond the known text length absorbs IME / caret
+// slop; over-deleting an already-empty field is a no-op, so we bias up.
+const CLEAR_BUFFER = 2;
+
+// After the focusing tap, wait before the first keystroke so the field is
+// actually focused. Android must also raise the soft keyboard, so tapping and
+// typing immediately drops the first key ("bluesky" → "luesky"); iOS focuses
+// quickly (small insurance) and Chromium focus over CDP is synchronous.
+function focusSettleMs(platform: Platform): number {
+  if (platform === "android") return 450;
+  if (platform === "ios") return 150;
+  return 0;
+}
+
+// Which attribute(s) the query is matched against. `any` (the default) spans the
+// content attributes — label, value, identifier — but NOT role: role strings
+// (`AXButton`, `button`, `TextView`) are generic, so folding them into `any`
+// would make a content query like "image" match every icon. Match role with an
+// explicit `by:"role"`.
+const LOCATOR_ATTRS = ["any", "text", "label", "value", "role", "id"] as const;
+type LocatorAttr = (typeof LOCATOR_ATTRS)[number];
+
+const ACTIONS = [
+  "tap",
+  "focus",
+  "fill",
+  "type",
+  "exists",
+  "wait",
+  "get-text",
+  "get-attrs",
+] as const;
+type FindAction = (typeof ACTIONS)[number];
+
+// Actions that touch the device (a tap, or a tap + typing). All require a visible
+// match (a zero-area frame has no usable tap point). Read-only actions (`exists`,
+// `get-text`, `get-attrs`, `wait`) do not tap.
+const TAPPING_ACTIONS = new Set<FindAction>(["tap", "focus", "fill", "type"]);
+
+// The concrete attribute a node matched on — surfaced so the agent (and tests)
+// can see why a node was chosen, which is otherwise opaque for `any` / `text`.
+type MatchedField = "label" | "value" | "role" | "id";
+
+const zodSchema = z
+  .object({
+    udid: z
+      .string()
+      .min(1)
+      .describe("Target device id from `list-devices` (iOS UDID, Android serial, or Chromium id)."),
+    query: z
+      .string()
+      .min(1)
+      .describe(
+        'Value to match against the located attribute (case-insensitive substring), e.g. "Sign In".'
+      ),
+    by: z
+      .enum(LOCATOR_ATTRS)
+      .default("any")
+      .describe(
+        "Which attribute to match: any (label/value/id — the default), text (label or value), " +
+          "label, value, role, id."
+      ),
+    action: z
+      .enum(ACTIONS)
+      .default("tap")
+      .describe(
+        "tap (default): tap the match's centre. focus: tap to give it keyboard focus. " +
+          "type: focus then type `text`. fill: focus, clear, then type `text`. " +
+          "exists: report whether it is present (single check). wait: block until it is visible. " +
+          "get-text: return its label+value. get-attrs: return its full attributes."
+      ),
+    text: z
+      .string()
+      .optional()
+      .describe("Text to enter into the field. Required for action `type` or `fill`."),
+    index: z
+      .number()
+      .int()
+      .min(0)
+      .default(0)
+      .describe(
+        "When several elements match, which one to act on (default 0). Ordering is action-dependent: " +
+          "a read-only action (exists/get-text/get-attrs/wait) uses plain reading order, so 0 is the " +
+          "topmost; a tapping action (tap/focus/type/fill) ranks an enclosing container after the " +
+          "smaller matches it wraps, so 0 is the innermost match. `matchCount` reports how many matched."
+      ),
+    timeoutMs: z
+      .number()
+      .int()
+      .positive()
+      .max(120_000)
+      .optional()
+      .describe(
+        `For action \`wait\`, how long to block (default ${DEFAULT_WAIT_TIMEOUT_MS}ms). For any other ` +
+          "action, set this to poll until the element appears before acting; omitted means a single check."
+      ),
+    pollIntervalMs: z
+      .number()
+      .int()
+      .min(50)
+      .max(5000)
+      .optional()
+      .describe(
+        `How often to re-check the tree while waiting (default ${DEFAULT_POLL_INTERVAL_MS}ms).`
+      ),
+    bundleId: z
+      .string()
+      .optional()
+      .describe(
+        "Optional iOS app bundle id passed to the describe fallback (see `describe`). Ignored on Android / Chromium."
+      ),
+  })
+  .refine((p) => (p.action !== "fill" && p.action !== "type" ? true : Boolean(p.text)), {
+    message: "action `type`/`fill` requires `text`",
+    path: ["text"],
+  });
+
+type Params = z.infer<typeof zodSchema>;
+
+interface FindMatchInfo {
+  role: string;
+  label?: string;
+  value?: string;
+  identifier?: string;
+  frame: DescribeFrame;
+  tapPoint: { x: number; y: number };
+  visible: boolean;
+  matchedField: MatchedField;
+  // Only the truthy interactivity flags are included, so the payload stays small.
+  flags?: Record<string, boolean>;
+}
+
+type FindActionResult =
+  | { kind: "tap"; tapped: boolean; timestampMs: number }
+  | { kind: "focus"; focused: boolean; timestampMs: number }
+  | { kind: "type"; typed: string; keys: number }
+  // `backspacesSent` is the number of backspaces issued to clear the field, NOT a
+  // count of characters proven deleted — the tree doesn't report the caret
+  // position, so we can't know how many actually landed on the value vs slop
+  // past its end. Named honestly so a caller never reads it as "chars removed".
+  | { kind: "fill"; typed: string; keys: number; backspacesSent: number }
+  | { kind: "get-text"; text: string };
+
+interface FindResult {
+  found: boolean;
+  action: FindAction;
+  by: LocatorAttr;
+  query: string;
+  // How many actionable matches the locator found: visible matches for tapping
+  // actions / `wait`, all matches for the read-only checks. Same space as
+  // `index`, so the agent can tell when a query is ambiguous and narrow it.
+  matchCount: number;
+  elapsed: number;
+  // Present whenever an element was located. For `get-attrs` this IS the answer.
+  match?: FindMatchInfo;
+  // Present for actions that do something beyond locating (tap/focus/type/fill/get-text).
+  actionResult?: FindActionResult;
+  // `exists` only: set when the tree could not be read at all (a fetch error /
+  // hang with no usable snapshot), so `found: false` means "couldn't tell", not
+  // "confirmed absent". Lets a caller distinguish an unreadable screen from a
+  // genuine miss instead of trusting a blind negative.
+  presenceUnknown?: boolean;
+  note?: string;
+}
+
+// A tvOS simulator shape-classifies as `apple`, and an Android TV emulator as
+// `android`, so both pass this gate — but `find` is READ-ONLY on a TV target:
+// the acting actions (tap/focus/type/fill) are rejected at runtime (see the TV
+// guard in `execute`) because a D-pad-driven TV ignores coordinate taps and its
+// keyboard rejects the named `backspace` key `fill` needs. Locate / exists /
+// wait / get-text / get-attrs still work; use `tv-remote` (+ `keyboard`) to act.
+const capability: ToolCapability = {
+  apple: { simulator: true, device: true },
+  android: { emulator: true, device: true, unknown: true },
+  chromium: { app: true },
+};
+
+// ── Locator matching ───────────────────────────────────────────────────────
+
+// The attribute (if any) `node` matches `query` on, given the locator `by`.
+// Returns the first satisfying field in a stable priority (label, value, id) so
+// `any` / `text` report a deterministic `matchedField`.
+export function locatorField(
+  node: DescribeNode,
+  by: LocatorAttr,
+  query: string
+): MatchedField | null {
+  const label = includesCI(node.label, query);
+  const value = includesCI(node.value, query);
+  const id = includesCI(node.identifier, query);
+  const role = includesCI(node.role, query);
+  switch (by) {
+    case "label":
+      return label ? "label" : null;
+    case "value":
+      return value ? "value" : null;
+    case "role":
+      return role ? "role" : null;
+    case "id":
+      return id ? "id" : null;
+    case "text":
+      return label ? "label" : value ? "value" : null;
+    case "any":
+      return label ? "label" : value ? "value" : id ? "id" : null;
+  }
+}
+
+// All nodes matching the locator, root excluded (see `walkMatches`). Exported
+// for unit tests.
+export function findMatches(tree: DescribeNode, by: LocatorAttr, query: string): DescribeNode[] {
+  return walkMatches(tree, (n) => locatorField(n, by, query) !== null);
+}
+
+// True when `a`'s frame spatially encloses `b`'s and is strictly larger — i.e.
+// `b` nests inside `a`. A small epsilon absorbs rounding in the normalized
+// coordinates so a child flush against its parent's edge still counts.
+function frameEncloses(a: DescribeFrame, b: DescribeFrame): boolean {
+  const EPS = 1e-6;
+  const encloses =
+    a.x <= b.x + EPS &&
+    a.y <= b.y + EPS &&
+    a.x + a.width + EPS >= b.x + b.width &&
+    a.y + a.height + EPS >= b.y + b.height;
+  return encloses && a.width * a.height > b.width * b.height + EPS;
+}
+
+// Order the actionable pool for the chosen action, so `index` addresses the most
+// useful match first. Read-only actions keep plain reading order (top-to-bottom,
+// then left-to-right — what the agent "saw first"). For a TAPPING action we also
+// demote any match whose frame encloses another match: an enclosing container is
+// almost always an aggregating parent (e.g. an Android View that folds a child
+// input's text into its own content-desc), and tapping its centre hits the
+// container — or a sibling control inside it — not the specific element. Pushing
+// containers after the smaller matches they wrap makes the default `index:0` land
+// on the inner, more specific target; `matchCount` and the ambiguity note still
+// surface the choice so a caller can override with `index`.
+function orderMatches(pool: DescribeNode[], action: FindAction): DescribeNode[] {
+  if (!TAPPING_ACTIONS.has(action)) return sortReadingOrder(pool);
+  const isContainer = (n: DescribeNode) =>
+    pool.some((m) => m !== n && frameEncloses(n.frame, m.frame));
+  return pool
+    .map((node, i) => ({ node, i, container: isContainer(node) }))
+    .sort(
+      (a, b) =>
+        Number(a.container) - Number(b.container) ||
+        a.node.frame.y - b.node.frame.y ||
+        a.node.frame.x - b.node.frame.x ||
+        a.i - b.i
+    )
+    .map((e) => e.node);
+}
+
+const FLAG_KEYS: ReadonlyArray<keyof DescribeNode> = [
+  "clickable",
+  "longClickable",
+  "scrollable",
+  "checkable",
+  "checked",
+  "disabled",
+  "password",
+  "focused",
+  "selected",
+];
+
+function collectFlags(node: DescribeNode): Record<string, boolean> | undefined {
+  const flags: Record<string, boolean> = {};
+  for (const key of FLAG_KEYS) {
+    if (node[key] === true) flags[key] = true;
+  }
+  return Object.keys(flags).length > 0 ? flags : undefined;
+}
+
+function toMatchInfo(node: DescribeNode, by: LocatorAttr, query: string): FindMatchInfo {
+  const info: FindMatchInfo = {
+    role: node.role,
+    frame: node.frame,
+    tapPoint: getDescribeTapPoint(node.frame),
+    visible: isVisible(node),
+    // locatorField returned non-null for every node in `findMatches`, so the
+    // fallback is unreachable; it keeps the type honest without a non-null bang.
+    matchedField: locatorField(node, by, query) ?? "label",
+  };
+  if (node.label !== undefined) info.label = node.label;
+  if (node.value !== undefined) info.value = node.value;
+  if (node.identifier !== undefined) info.identifier = node.identifier;
+  const flags = collectFlags(node);
+  if (flags) info.flags = flags;
+  return info;
+}
+
+// ── Action dispatch (delegates the device effect to the existing tools) ──────
+
+async function tapAt(
+  registry: Registry,
+  ctx: ToolContext | undefined,
+  udid: string,
+  point: { x: number; y: number }
+): Promise<{ tapped: boolean; timestampMs: number }> {
+  return invokeSubTool(registry, ctx, "gesture-tap", { udid, x: point.x, y: point.y });
+}
+
+async function typeText(
+  registry: Registry,
+  ctx: ToolContext | undefined,
+  udid: string,
+  text: string
+): Promise<{ typed: string; keys: number }> {
+  return invokeSubTool(registry, ctx, "keyboard", { udid, text });
+}
+
+// The point `fill` taps to focus a field before clearing it: the field's
+// bottom-trailing corner (95% across, 90% down) rather than its centre. The clear
+// is leftward-only backspaces, so it relies on the focusing tap parking the caret
+// at/after the END of the text — the last character, on the last line. A centre
+// tap can strand the caret mid-text in EITHER axis of a content-sized field:
+//   - horizontally, in a field whose text runs past the middle (a long single
+//     line, a web/contenteditable, a custom input) → the backspaces delete the
+//     left part and leave right-hand residue;
+//   - vertically, in a multi-line text view → the caret parks on an interior
+//     line and every line BELOW it survives (the bug the old `height/2` left
+//     open — its own comment named "a multi-line text view" as the target case).
+// Biasing to the bottom-right corner puts the caret past the last line's end so
+// the whole value clears. Kept inside the frame and clamped to the screen. (iOS
+// single-line fields re-anchor the caret to the end on focus regardless, and a
+// short field collapses this to roughly its centre, so it only changes behaviour
+// for the tall / long fields that need it.)
+function trailingEdgeTapPoint(frame: DescribeFrame): { x: number; y: number } {
+  return {
+    x: Math.min(frame.x + frame.width * 0.95, 1),
+    y: Math.min(frame.y + frame.height * 0.9, 1),
+  };
+}
+
+// Tap to focus a field, then wait `settleMs` so it is actually focused (and the
+// soft keyboard is up) before the first key. Returns false if the request was
+// aborted during the settle, so the caller can skip typing.
+async function focusAndSettle(
+  registry: Registry,
+  ctx: ToolContext | undefined,
+  udid: string,
+  point: { x: number; y: number },
+  settleMs: number
+): Promise<boolean> {
+  await tapAt(registry, ctx, udid, point);
+  return sleepOrAbort(settleMs, ctx?.signal);
+}
+
+// Length of a field's current editable text, on the platforms where the tree
+// actually exposes it. Where the live text lands depends on the adapter: iOS (and
+// an Android EditText WITH a content-desc) put the typed text in `value` while
+// `label` holds a static placeholder; an Android EditText WITHOUT a content-desc
+// has no `value` and surfaces the typed text as `label`. So `value`, WHENEVER it
+// is present, is the content — and `label` is then only a placeholder we must NOT
+// count; only when `value` is entirely absent does `label` carry the text.
+//
+// (An earlier version took `max(value,label)` to be safe, but that counts the
+// placeholder on an empty field — `value:"" , label:"Search"` → 6 phantom
+// backspaces, each a keyboard round-trip, and a >64-char placeholder even trips a
+// bogus "clear may be incomplete" warning for an already-empty field. Preferring
+// `value` when present avoids both while staying exact for the content case; a
+// tiny CLEAR_BUFFER at the call site still absorbs IME / caret slop, and
+// over-deleting past a field's end is a no-op anyway.)
+//
+// This is NOT reliable on Chromium: `describeChromium`'s accessibleName prefers a
+// static aria-label / placeholder over the live `el.value`, and a form control's
+// `value` (ownText) is always empty — so for a placeholder/aria-labelled input
+// the current content is in NEITHER attribute and its length is unknowable here.
+// The `fill` handler special-cases Chromium instead of trusting this.
+function editableTextLength(node: DescribeNode): number {
+  if (node.value !== undefined) return node.value.length;
+  return node.label?.length ?? 0;
+}
+
+// Send `count` backspaces to a focused field, stopping early on abort. The
+// keyboard tool exposes no select-all modifier, so a clear is N backspaces; the
+// trailing-edge focus tap (see `trailingEdgeTapPoint`) parks the caret at/after
+// the end of the text, so they delete leftwards through the value. Returns how
+// many backspaces were actually SENT — not a count of characters proven removed
+// (the tree never reports the caret position). Deciding `count` (and whether it
+// may fall short of the field's true length) is the caller's job, since only it
+// knows how reliably the platform reported the field's text.
+async function clearField(
+  registry: Registry,
+  ctx: ToolContext | undefined,
+  udid: string,
+  count: number
+): Promise<number> {
+  for (let i = 0; i < count; i++) {
+    if (ctx?.signal?.aborted) return i;
+    await invokeSubTool(registry, ctx, "keyboard", { udid, key: "backspace" });
+  }
+  return count;
+}
+
+// ── Tool ─────────────────────────────────────────────────────────────────
+
+// `find` is a factory (like `describe` / `await-ui-element`) because the iOS /
+// Android tree fetch resolves AX / android-devtools through the registry rather
+// than the tool's own services() declaration. Only the Chromium CDP session
+// flows in as a normal service (and backs both the tree fetch and the action).
+// The action itself is delegated to `gesture-tap` / `keyboard` via invokeSubTool,
+// which resolve their own transport — so `find` never eagerly spawns the
+// simulator-server for a read-only action.
+export function createFindTool(registry: Registry): ToolDefinition<Params, FindResult> {
+  return {
+    id: FIND_TOOL_ID,
+    description: `Locate a UI element by a locator and optionally act on it — discovery + action in one call, so you don't have to describe → read coordinates → tap.
+
+Locator: \`query\` is a case-insensitive substring matched against the attribute named by \`by\` (any = label/value/id, the default; text = label or value; or label / value / role / id).
+Actions (\`action\`, default \`tap\`): tap (centre), focus, type (focus + type \`text\`), fill (focus + clear + type \`text\`), exists (single presence check), wait (block until visible, \`timeoutMs\` default ${DEFAULT_WAIT_TIMEOUT_MS}ms), get-text, get-attrs.
+\`fill\` is DESTRUCTIVE: it clears the field with backspaces before typing, and the clear is sized from an accessibility tree that can under- or over-report the length (masked/rich-text/Chromium fields) — the result \`note\` flags when a clear may be incomplete or may have deleted adjacent content, so check it. Prefer \`fill\` only when you must replace existing text; use \`type\` to append.
+
+Returns { found, matchCount, match?, actionResult?, elapsed, note? }. When several match, the topmost in reading order is used (for a tapping action an enclosing container is ranked after the smaller matches it wraps; set \`index\` to pick another; \`matchCount\` reports how many). A single snapshot is taken by default — set \`timeoutMs\` to poll until the element appears before acting.
+On a TV target (Apple TV / Android TV) find is READ-ONLY — locate / exists / wait / get-text / get-attrs only; the acting actions can't drive a D-pad UI, so use tv-remote (+ keyboard) to act.
+Example: tap "Sign In" → { query: "Sign In", by: "text", action: "tap" }.`,
+    alwaysLoad: true,
+    longRunning: true,
+    searchHint:
+      "find locate element tap focus type fill exists wait get text attrs by label value role id selector single call",
+    zodSchema,
+    capability,
+    services: (params): Record<string, ServiceRef> => {
+      const device = resolveDevice(params.udid);
+      if (device.platform === "chromium") {
+        return { chromium: chromiumCdpRef(device) };
+      }
+      return {};
+    },
+    async execute(services, params, ctx?: ToolContext) {
+      const signal = ctx?.signal;
+      const { by, query, action, index } = params;
+
+      const device = resolveDevice(params.udid);
+      assertSupported(FIND_TOOL_ID, capability, device);
+      if (device.platform === "ios") await ensureDeps(iosRequires);
+      else if (device.platform === "android") await ensureDeps(androidRequires);
+
+      // Resolve the tvOS verdict once, before the wait clock and outside the
+      // per-fetch budget: describeIos would otherwise re-shell `xcrun` on every
+      // poll (blowing a tight timeoutMs for an uncached UDID). Mirrors
+      // await-ui-element; passed through to fetchDescribeTree below.
+      const isTvOs = device.platform === "ios" && (await isTvOsSimulator(device.id));
+
+      // A TV target is D-pad driven: coordinate taps do nothing on tvOS, and an
+      // Android TV keyboard rejects the named `backspace` key `fill` clears with
+      // (it throws mid-action, leaving the field focused/dirty). So the acting
+      // actions can't work — `find` is read-only on TV. Probe the Android form
+      // factor only for an acting action (a read-only find works on TV and
+      // shouldn't pay the adb round-trip); tvOS is already resolved above.
+      //
+      // Fail CLOSED on an indeterminate Android probe: `getAndroidRuntimeKind`
+      // returns undefined only when the serial isn't a ready `device` (offline /
+      // mid-boot) or its form factor can't be read yet — none is a target we
+      // should fire a blind coordinate tap / backspace at, and a booted mobile
+      // device reports "mobile" reliably. iOS is deliberately asymmetric:
+      // `getSimulatorRuntimeKind` (behind `isTvOs`) also returns undefined for a
+      // *physical* iPhone — a legit acting target that isn't in the simulator
+      // list — so we can't fail closed there without blocking every real device;
+      // a rare stalled-xcrun tvOS miss is accepted over that regression.
+      const androidActingKind =
+        TAPPING_ACTIONS.has(action) && device.platform === "android"
+          ? await getAndroidRuntimeKind(device.id)
+          : undefined;
+      const actingOnTv =
+        TAPPING_ACTIONS.has(action) &&
+        (isTvOs || (device.platform === "android" && androidActingKind !== "mobile"));
+
+      // Start the discovery clock after setup so its fixed cost isn't charged
+      // against timeoutMs (the deadline should bound polling, not resolution).
+      const start = Date.now();
+
+      // `wait` blocks (default budget); every other action is a single check
+      // unless the caller passes timeoutMs to opt into polling.
+      const timeoutMs =
+        action === "wait" ? (params.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS) : (params.timeoutMs ?? 0);
+      const pollIntervalMs = params.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+      const polling = timeoutMs > 0;
+      const requireVisible = action === "wait" || TAPPING_ACTIONS.has(action);
+      const deadline = start + timeoutMs;
+
+      const baseResult = (): Omit<FindResult, "found" | "matchCount"> => ({
+        action,
+        by,
+        query,
+        elapsed: Date.now() - start,
+      });
+      const cancelled = (): FindResult => ({
+        ...baseResult(),
+        found: false,
+        matchCount: 0,
+        note: "find was cancelled before the element was located",
+      });
+
+      // Reject an acting action on a TV target up front — before any device
+      // effect — so a `fill` can't focus a field and then throw on its first
+      // backspace (Android TV), and a `tap`/`type` can't silently no-op against a
+      // remote-driven screen (tvOS). Nothing is mutated; point the agent at the
+      // read-only actions and `tv-remote`.
+      if (actingOnTv) {
+        return {
+          ...baseResult(),
+          found: false,
+          matchCount: 0,
+          note:
+            `find cannot \`${action}\` on a TV target — Apple TV / Android TV are D-pad driven, so ` +
+            `coordinate taps and keyboard clears don't work (and would leave a field dirty). find is ` +
+            `read-only on TV: use exists / wait / get-text / get-attrs to locate, and drive the UI with ` +
+            `tv-remote (D-pad) plus keyboard.`,
+        };
+      }
+
+      let lastTree: DescribeNode | null = null;
+      let lastData: DescribeTreeData | null = null;
+      let fetchError: string | undefined;
+
+      // ── Discovery: one snapshot, or poll until the element appears ──────────
+      for (;;) {
+        if (signal?.aborted) return cancelled();
+
+        // Bound each fetch: in poll mode to the time left before the deadline (so
+        // a slow describe can't overshoot timeoutMs); in single-shot mode to a
+        // generous cap. Either way an abort mid-fetch is observed promptly.
+        const budget = polling ? Math.max(0, deadline - Date.now()) : SINGLE_SHOT_FETCH_BUDGET_MS;
+        const settled = await settleWithin(
+          fetchDescribeTree(registry, device, params, services, { isTvOs }),
+          budget,
+          signal
+        );
+
+        if (settled.type === "aborted") return cancelled();
+        if (settled.type === "timeout") {
+          if (lastTree === null) {
+            // `wait` blocks against a wait budget; any other polling action races
+            // a poll budget; a single-shot read has only the fetch cap. Name the
+            // one that actually applied so the note isn't misleading.
+            const budgetName = !polling
+              ? "fetch"
+              : action === "wait"
+                ? `${timeoutMs}ms wait`
+                : `${timeoutMs}ms poll`;
+            fetchError ??= `tree fetch did not complete within the ${budgetName} budget`;
+          }
+          break;
+        }
+        if (settled.type === "error") {
+          fetchError = settled.error;
+        } else {
+          lastData = settled.value;
+          lastTree = settled.value.tree;
+          fetchError = undefined;
+        }
+
+        const matches = lastTree ? findMatches(lastTree, by, query) : [];
+        const pool = requireVisible ? matches.filter(isVisible) : matches;
+        // `exists` reports presence regardless of index; the others just need the
+        // requested index to be in range (which element it maps to — reading order
+        // vs the tapping-action container demotion — is settled at resolve time,
+        // and doesn't change whether index-th exists).
+        const satisfied = action === "exists" ? matches.length > 0 : pool.length > index;
+
+        if (satisfied || Date.now() >= deadline) break;
+        // Clamp the poll sleep to the time left so a large pollIntervalMs can't
+        // overshoot the deadline before the final poll.
+        const sleepMs = Math.min(pollIntervalMs, Math.max(0, deadline - Date.now()));
+        if (!(await sleepOrAbort(sleepMs, signal))) return cancelled();
+      }
+
+      // ── Resolve the chosen match from the final snapshot ────────────────────
+      const allMatches = lastTree ? findMatches(lastTree, by, query) : [];
+      const pool = requireVisible ? allMatches.filter(isVisible) : allMatches;
+      const matchCount = pool.length;
+      const chosen = orderMatches(pool, action)[index];
+
+      if (action === "exists") {
+        const result: FindResult = { ...baseResult(), found: matchCount > 0, matchCount };
+        // Report the topmost VISIBLE match, so `exists`'s reported element is the
+        // one a subsequent tap (which acts on the topmost visible) would target —
+        // not a zero-area ghost that sorts above it with a degenerate tapPoint.
+        // Fall back to the topmost of all matches when none is visible.
+        const top =
+          firstInReadingOrder(allMatches.filter(isVisible)) ?? firstInReadingOrder(allMatches);
+        if (top) result.match = toMatchInfo(top, by, query);
+        if (matchCount === 0) {
+          // `exists` returns found:false for both "confirmed absent" and "couldn't
+          // actually see the screen". Only the latter is presence-unknown. A BLIND
+          // read is any of: no usable tree was ever read (lastTree null ⇒ a fetch
+          // error/hang), OR the adapter flagged the snapshot as untrustworthy — an
+          // empty/degraded iOS AX tree, native-injection-pending, or a tvOS focus
+          // tree the AX service can't serve all come back EMPTY plus a `hint` /
+          // `should_restart` rather than throwing. Gating only on lastTree===null
+          // (the old check) missed those: on tvOS / a device mid-restart, exists
+          // read an empty-but-flagged tree and reported a confirmed absence. Mirror
+          // await-ui-element's `isBlindRead` so a caller never treats "couldn't see
+          // the screen" as "the element is gone".
+          const blind =
+            lastTree === null || Boolean(lastData?.hint) || Boolean(lastData?.should_restart);
+          if (blind) {
+            result.presenceUnknown = true;
+            const reason =
+              lastTree === null
+                ? fetchError
+                  ? `the UI tree could not be read (${fetchError})`
+                  : "the UI tree could not be read"
+                : "the UI tree was empty or could not be read reliably";
+            result.note = appendDescribeDiagnostics(`presence unknown — ${reason}`, lastData);
+          } else {
+            result.note = appendDescribeDiagnostics(
+              `no element matched ${by}="${query}"`,
+              lastData
+            );
+          }
+        }
+        return result;
+      }
+
+      if (!chosen) {
+        // Distinguish "no element matched" from "matched but not on screen" and
+        // "matched but the requested index is out of range" so the agent can act.
+        let note: string;
+        if (fetchError && lastTree === null) {
+          // Only when NO usable tree was ever read is a fetchError the cause. A
+          // fetchError left over from a transient error poll AFTER an earlier poll
+          // read the screen (lastTree set) must not mislabel a genuine miss as a
+          // fetch failure — fall through to "no element matched". Mirrors the
+          // `exists` branch's lastTree===null guard.
+          note = `tree fetch failed: ${fetchError}`;
+        } else if (allMatches.length === 0) {
+          note = `no element matched ${by}="${query}"`;
+        } else if (requireVisible && pool.length === 0) {
+          note = `${allMatches.length} element(s) matched ${by}="${query}" but none is visible (zero-area frame), so it cannot be acted on`;
+        } else {
+          note = `index ${index} is out of range — only ${pool.length} actionable element(s) matched ${by}="${query}"`;
+        }
+        return {
+          ...baseResult(),
+          found: false,
+          matchCount,
+          note: appendDescribeDiagnostics(note, lastData),
+        };
+      }
+
+      const match = toMatchInfo(chosen, by, query);
+      const result: FindResult = { ...baseResult(), found: true, matchCount, match };
+      if (matchCount > 1) {
+        const verb = TAPPING_ACTIONS.has(action) ? "acted on" : "selected";
+        // Describe what index 0 means for THIS action. A tapping action ranks an
+        // enclosing container after the smaller matches it wraps — so 0 is the
+        // topmost match EXCEPT that a container is demoted below what it encloses.
+        // (Avoid calling 0 the "innermost match" flatly: when the matches are
+        // disjoint siblings with no nesting there is no inner/outer at all — it is
+        // just the topmost, and only nesting changes that.)
+        const zeroMeans = TAPPING_ACTIONS.has(action)
+          ? "topmost, but an enclosing container ranks after the matches it wraps"
+          : "topmost in reading order";
+        const which = index === 0 ? `index 0 (${zeroMeans})` : `index ${index} (0 = ${zeroMeans})`;
+        result.note = `${matchCount} elements matched ${by}="${query}"; ${verb} ${which}. Narrow the query or set \`index\` to target another.`;
+      }
+
+      // A cancel that lands AFTER the element was located and a device effect was
+      // already dispatched (the focus tap always fires; a `fill` may also have
+      // sent backspaces). Unlike `cancelled()`, report the element as found with
+      // an accurate account of what was mutated, so a caller doing recovery isn't
+      // told "nothing happened" when the field was in fact focused / partly cleared.
+      const cancelledMidAction = (detail: string): FindResult => ({
+        ...baseResult(),
+        found: true,
+        matchCount,
+        match,
+        note: [result.note, `find was cancelled ${detail}`].filter(Boolean).join(" "),
+      });
+
+      // ── Perform the action ─────────────────────────────────────────────────
+      switch (action) {
+        case "tap": {
+          const r = await tapAt(registry, ctx, params.udid, match.tapPoint);
+          result.actionResult = { kind: "tap", tapped: r.tapped, timestampMs: r.timestampMs };
+          break;
+        }
+        case "focus": {
+          const r = await tapAt(registry, ctx, params.udid, match.tapPoint);
+          result.actionResult = { kind: "focus", focused: r.tapped, timestampMs: r.timestampMs };
+          break;
+        }
+        case "type": {
+          const focused = await focusAndSettle(
+            registry,
+            ctx,
+            params.udid,
+            match.tapPoint,
+            focusSettleMs(device.platform)
+          );
+          if (!focused)
+            return cancelledMidAction(
+              "after focusing the element but before typing; the field is focused but no text was entered"
+            );
+          const r = await typeText(registry, ctx, params.udid, params.text!);
+          result.actionResult = { kind: "type", typed: r.typed, keys: r.keys };
+          break;
+        }
+        case "fill": {
+          // Resolve the editable REGION to clear, which is not always `chosen`.
+          // The container demotion in `orderMatches` ranks an enclosing match after
+          // the inner element for tapping actions — right for a plain tap (hit the
+          // specific control), but wrong for fill's clear when a text field is
+          // wrapped by a larger matching node: an iOS search bar exposes a narrow
+          // inner AXTextField (~5% wide) INSIDE a wide AXGroup that actually carries
+          // the value; an Android EditText can be folded into a container. The wide
+          // node spans the editable region and holds the live text, so the caret
+          // must be parked at ITS trailing edge and the clear sized to ITS length.
+          // Trusting the demoted proxy's frame instead lands the trailing-edge tap
+          // at the field's far LEFT — the backspaces then delete nothing and the
+          // new text is prepended onto the old (the reproduced "abcd" → "WxyzAbcd"
+          // bug). Pick the tightest match that still encloses `chosen`.
+          const enclosing = pool.filter(
+            (n) => n !== chosen && frameEncloses(n.frame, chosen.frame)
+          );
+          const editable = enclosing.length
+            ? enclosing.reduce((a, b) =>
+                a.frame.width * a.frame.height <= b.frame.width * b.frame.height ? a : b
+              )
+            : chosen;
+          // Focus at the editable region's trailing edge (not its centre) so the
+          // leftward backspaces below start from the end of the text — see
+          // `trailingEdgeTapPoint`. `match.tapPoint` (the located element's centre)
+          // is still what the result reports as the tap point.
+          const focused = await focusAndSettle(
+            registry,
+            ctx,
+            params.udid,
+            trailingEdgeTapPoint(editable.frame),
+            focusSettleMs(device.platform)
+          );
+          if (!focused)
+            return cancelledMidAction(
+              "after focusing the element but before clearing; the field is focused but not yet modified"
+            );
+          // Size the clear. On Chromium the DOM a11y snapshot never gives a
+          // reliable editable length: a form control's live `el.value` is masked
+          // behind a static aria-label / placeholder (and `value` is empty), while
+          // a contenteditable reports only its *direct* text nodes in `value` — an
+          // undercount that omits text nested in inline children (a <b>, a mention
+          // span). Trusting either would under-clear and leave stale text for the
+          // new value to be typed on top of, so on Chromium we always clear up to
+          // the cap and flag it. Elsewhere `editableTextLength` reads the real
+          // length off the editable region (never shorter than the live text).
+          const lengthHidden = device.platform === "chromium";
+          const knownLength = editableTextLength(editable);
+          const clearTarget = lengthHidden ? MAX_CLEAR_CHARS : knownLength;
+          const clearCount = Math.min(MAX_CLEAR_CHARS, clearTarget + CLEAR_BUFFER);
+          const backspacesSent = await clearField(registry, ctx, params.udid, clearCount);
+          // clearField stops early on abort but can't signal it; bail before
+          // typing so a cancelled fill doesn't push `text` in and report success.
+          if (signal?.aborted)
+            return cancelledMidAction(
+              `after focusing and sending ${backspacesSent} backspace(s) but before typing; the field may be partially cleared`
+            );
+          const r = await typeText(registry, ctx, params.udid, params.text!);
+          result.actionResult = { kind: "fill", typed: r.typed, keys: r.keys, backspacesSent };
+          // Surface any caveat that the fixed-count clear may have gone wrong, so
+          // neither failure mode is ever a silent success. On Chromium the clear
+          // runs to the cap (the length is unknowable — see above), which is safe
+          // in BOTH directions only for an <input>/<textarea> or a contenteditable
+          // that is the whole editable host. It is NOT safe when the matched node
+          // is an inner block of a larger contenteditable: the trailing-edge focus
+          // parks the caret at that block's end, so backspacing past its start
+          // merges/deletes the PRECEDING block. We can't detect an ancestor
+          // contenteditable from the a11y snapshot, so we flag both directions
+          // (under-clear residue AND over-delete into adjacent content) rather than
+          // warning only about leftover text.
+          const clearCaveats: string[] = [];
+          if (lengthHidden) {
+            clearCaveats.push(
+              `on Chromium the field's current text is not reliably exposed by the DOM ` +
+                `accessibility snapshot (an input's live value is masked by a placeholder / ` +
+                `aria-label, and a contenteditable reports only its direct text nodes), so the ` +
+                `clear was sized to the ${MAX_CLEAR_CHARS}-char cap: a longer field may retain ` +
+                `text, and — for an inner block of a multi-block rich-text editor — the ` +
+                `fixed-count backspaces can run past the block's start and delete into the ` +
+                `preceding block. Verify the field and the content around it before relying on it.`
+            );
+          } else if (knownLength > MAX_CLEAR_CHARS) {
+            // Cap is measured against the field's real length, not length+buffer,
+            // so a 63–64 char field (fully cleared by the 64 backspaces) doesn't
+            // draw a spurious warning.
+            clearCaveats.push(
+              `the field holds more than ${MAX_CLEAR_CHARS} characters, so the clear was capped at ` +
+                `${MAX_CLEAR_CHARS} and may be incomplete — verify the field before relying on it.`
+            );
+          }
+          // A password's real length is hidden: `value` is unset and any `label`
+          // is a redacted placeholder ("[password]"), so the clear can't be sized
+          // reliably — warn even though some backspaces were sent. NOTE this only
+          // fires where the adapter sets `password` (Android uiautomator, Chromium
+          // <input type=password>); iOS AX exposes no secure-field flag, so an iOS
+          // secure field with an empty/short AXValue can still under-clear here
+          // without this warning — a known gap the tree gives us no signal to close.
+          if (editable.password && !editable.value) {
+            clearCaveats.push(
+              "this looks like a password field with a masked value, so the field's length was unknown — " +
+                "the clear may be incomplete; verify the field is empty before relying on it."
+            );
+          }
+          if (clearCaveats.length > 0) {
+            result.note = [result.note, ...clearCaveats].filter(Boolean).join(" ");
+          }
+          break;
+        }
+        case "wait":
+          // Discovery already blocked until the element was visible; nothing more.
+          break;
+        case "get-text":
+          result.actionResult = { kind: "get-text", text: nodeText(chosen) };
+          break;
+        case "get-attrs":
+          // The answer is `result.match` (the full attributes); no separate action.
+          break;
+      }
+
+      result.elapsed = Date.now() - start;
+      return result;
+    },
+  };
+}
diff --git a/packages/tool-server/src/tools/flows/flow-add-step.ts b/packages/tool-server/src/tools/flows/flow-add-step.ts
index 85db66b0e..5f13c3301 100644
--- a/packages/tool-server/src/tools/flows/flow-add-step.ts
+++ b/packages/tool-server/src/tools/flows/flow-add-step.ts
@@ -1,10 +1,12 @@
 import { z } from "zod";
 import type { Registry, ToolDefinition } from "@argent/registry";
 import { getActiveFlow, appendStepToActiveFlow, type FlowSavedTo } from "./flow-utils";
+import { isMissedFindResult, missedFindError } from "./flow-step-results";
+import { isUnmetUiWaitResult } from "../await-ui-element";
 import { invokeSubTool } from "../../utils/sub-invoke";
 
 const zodSchema = z.object({
-  command: z.string().describe('MCP tool name (e.g. "tap", "screenshot", "launch-app")'),
+  command: z.string().describe('MCP tool name (e.g. "gesture-tap", "screenshot", "launch-app")'),
   args: z
     .string()
     .optional()
@@ -27,7 +29,7 @@ export function createFlowAddStepTool(
 > {
   return {
     id: "flow-add-step",
-    description: `Execute a tool call and record it as a step in the active flow. Use when recording a flow with flow-start-recording and you want to run and capture each action. Returns { message, toolResult, flowFile } on success. If it fails an error is returned and nothing is recorded. Error if the tool name is not found in the registry or arguments are invalid JSON.\nIf a step was recorded by mistake, edit the .yaml file directly to remove it.`,
+    description: `Execute a tool call live and record it as a step in the active flow unless the tool throws, a find step returns { found: false } (a find with action: "exists" is exempt — its found: false is a valid "not present" answer and is still recorded), or an await-ui-element step's condition is not met ({ success: false }). Use when recording a flow with flow-start-recording and you want to run and capture each action. Returns { message, toolResult, flowFile } after recording. If the tool throws, find does not locate an element, or a wait's condition is not met, an error is returned and nothing is recorded. Error if the tool name is not found in the registry or arguments are invalid JSON.`,
     zodSchema,
     services: () => ({}),
     async execute(_services, params, ctx) {
@@ -35,6 +37,22 @@ export function createFlowAddStepTool(
       const args: Record<string, unknown> = params.args ? JSON.parse(params.args) : {};
 
       const toolResult = await invokeSubTool(registry, ctx, params.command, args);
+      if (isMissedFindResult(params.command, toolResult)) {
+        throw new Error(missedFindError(toolResult));
+      }
+      // An await-ui-element whose condition never held returns { success: false }
+      // instead of throwing. Recording it would bake a step that `flow-run` halts
+      // on for every replay (it stops on `isUnmetUiWaitResult` too) — reject it at
+      // record time, symmetric with the missed-find guard above, so a recorded
+      // flow only ever contains steps that actually succeeded live.
+      if (isUnmetUiWaitResult(params.command, toolResult)) {
+        const note = (toolResult as { note?: unknown }).note;
+        throw new Error(
+          typeof note === "string" && note.length > 0
+            ? `await-ui-element condition was not met: ${note}`
+            : "await-ui-element condition was not met"
+        );
+      }
 
       const { flowFile, savedTo } = await appendStepToActiveFlow({
         kind: "tool",
diff --git a/packages/tool-server/src/tools/flows/flow-run.ts b/packages/tool-server/src/tools/flows/flow-run.ts
index ae8dd02fd..310e5d0a9 100644
--- a/packages/tool-server/src/tools/flows/flow-run.ts
+++ b/packages/tool-server/src/tools/flows/flow-run.ts
@@ -8,6 +8,7 @@ import {
   setActiveProjectRoot,
   type FlowStep,
 } from "./flow-utils";
+import { isMissedFindResult, missedFindError } from "./flow-step-results";
 import { sleepOrAbort } from "../../utils/timing";
 import { invokeSubTool } from "../../utils/sub-invoke";
 import { isUnmetUiWaitResult } from "../await-ui-element";
@@ -73,6 +74,9 @@ Use when you want to replay a recorded flow or run a scripted sequence of device
 Fails if the flow file does not exist or a step tool raises an error (execution stops at that step).
 An \`await-ui-element\` step whose condition is not met before its timeout also stops the flow there
 (its later steps were recorded assuming the condition held), so use one to gate a step on a screen transition.
+A \`find\` step that returns \`{ found: false }\` also stops the flow there, so replay never silently
+continues after a missed locate-and-act step — except a \`find\` with \`action: "exists"\`, whose
+\`found: false\` is a valid "not present" answer that lets replay continue.
 
 If the flow has an execution prerequisite and prerequisiteAcknowledged is not
 set to true, the tool returns a notice with the prerequisite instead of running.
@@ -131,6 +135,14 @@ Use flow-read-prerequisite to inspect the prerequisite beforehand.`,
             });
             break;
           }
+          if (isMissedFindResult(step.name, result)) {
+            steps.push({
+              kind: "tool",
+              tool: step.name,
+              error: missedFindError(result),
+            });
+            break;
+          }
           steps.push({
             kind: "tool",
             tool: step.name,
diff --git a/packages/tool-server/src/tools/flows/flow-start-recording.ts b/packages/tool-server/src/tools/flows/flow-start-recording.ts
index cb67acfff..e5efe0a29 100644
--- a/packages/tool-server/src/tools/flows/flow-start-recording.ts
+++ b/packages/tool-server/src/tools/flows/flow-start-recording.ts
@@ -49,8 +49,10 @@ Returns { message, flowFile, savedTo } and optionally { previousFlow } if a prio
 Fails if the .argent/flows/ directory cannot be created or the flow file cannot be written.
 
 After starting, use flow-add-step to append tool calls — each step is executed
-LIVE so you can verify it works before it gets recorded. Use flow-add-echo
-to add labels. Call flow-finish-recording when done.
+LIVE and then recorded unless the tool throws. Inspect each returned result
+before continuing; remove or replace recorded steps whose result reports a
+non-throwing failure. Use flow-add-echo to add labels. Call
+flow-finish-recording when done.
 
 If a recorded step turns out to be wrong, you can edit the .yaml file directly
 to remove or reorder steps.`,
diff --git a/packages/tool-server/src/tools/flows/flow-step-results.ts b/packages/tool-server/src/tools/flows/flow-step-results.ts
new file mode 100644
index 000000000..f27263b7b
--- /dev/null
+++ b/packages/tool-server/src/tools/flows/flow-step-results.ts
@@ -0,0 +1,24 @@
+import { FIND_TOOL_ID } from "../find";
+
+type MissedFindResult = {
+  found: false;
+  note?: unknown;
+};
+
+export function isMissedFindResult(tool: string, result: unknown): result is MissedFindResult {
+  if (tool !== FIND_TOOL_ID || typeof result !== "object" || result === null) return false;
+  const r = result as { found?: unknown; action?: unknown };
+  // `exists` reports presence as a yes/no answer: found:false is a SUCCESSFUL
+  // "not present" result, not a missed locate, so it must never stop a flow or
+  // block a step from being recorded. Every other action that returns found:false
+  // (tap/type/fill/wait/get-text/get-attrs) genuinely failed to act on/read an
+  // element, which is a real miss.
+  if (r.action === "exists") return false;
+  return r.found === false;
+}
+
+export function missedFindError(result: MissedFindResult): string {
+  return typeof result.note === "string" && result.note.length > 0
+    ? `find did not locate an element: ${result.note}`
+    : "find did not locate an element";
+}
diff --git a/packages/tool-server/src/tools/run-sequence/index.ts b/packages/tool-server/src/tools/run-sequence/index.ts
index 4502a2073..a5ffeb99b 100644
--- a/packages/tool-server/src/tools/run-sequence/index.ts
+++ b/packages/tool-server/src/tools/run-sequence/index.ts
@@ -21,6 +21,15 @@ const ALLOWED_TOOLS = new Set([
   // `keyboard` types into the focused field there.
   "tv-remote",
   AWAIT_UI_ELEMENT_TOOL_ID,
+  // `find` is deliberately NOT allowed under the current run-sequence semantics.
+  // A missed `find` returns { found: false } WITHOUT throwing — but so does an
+  // unmet await-ui-element (it returns { success: false }); the difference is not
+  // "throws vs doesn't". The reason is that run-sequence's stop-on-failure guard
+  // only recognises an unmet await-ui-element wait (`isUnmetUiWaitResult`), not a
+  // missed find (`isMissedFindResult` lives in the flow runners, not here). So a
+  // `find … tap` that located nothing would silently let the sequence continue
+  // past it. Wiring find in would mean teaching the guard below about
+  // `isMissedFindResult` too — until then, use individual `find` calls instead.
 ]);
 
 const zodSchema = z.object({
diff --git a/packages/tool-server/src/utils/setup-registry.ts b/packages/tool-server/src/utils/setup-registry.ts
index 27913be20..bb6628a27 100644
--- a/packages/tool-server/src/utils/setup-registry.ts
+++ b/packages/tool-server/src/utils/setup-registry.ts
@@ -48,6 +48,7 @@ import { networkLogsTool } from "../tools/network/network-logs";
 import { networkRequestTool } from "../tools/network/network-request";
 import { createDescribeTool } from "../tools/describe";
 import { createAwaitUiElementTool } from "../tools/await-ui-element";
+import { createFindTool } from "../tools/find";
 import { createReactProfilerStartTool } from "../tools/profiler/react/react-profiler-start";
 import { createReactProfilerStopTool } from "../tools/profiler/react/react-profiler-stop";
 import { createReactProfilerStatusTool } from "../tools/profiler/react/react-profiler-status";
@@ -138,6 +139,7 @@ export function createRegistry(): Registry {
   registry.registerTool(networkRequestTool);
   registry.registerTool(createDescribeTool(registry));
   registry.registerTool(createAwaitUiElementTool(registry));
+  registry.registerTool(createFindTool(registry));
   registry.registerTool(createReactProfilerStartTool(registry));
   registry.registerTool(createReactProfilerStopTool(registry));
   registry.registerTool(createReactProfilerStatusTool(registry));
diff --git a/packages/tool-server/src/utils/sub-invoke.ts b/packages/tool-server/src/utils/sub-invoke.ts
index 1413564d3..43830d450 100644
--- a/packages/tool-server/src/utils/sub-invoke.ts
+++ b/packages/tool-server/src/utils/sub-invoke.ts
@@ -4,11 +4,14 @@ import type { Registry, ToolContext } from "@argent/registry";
 /**
  * Dispatch a tool as a child of the current orchestrator invocation.
  *
- * run-sequence / flow-execute / flow-add-step run their steps by calling
+ * run-sequence / flow-execute / flow-add-step / find run their steps (or, for
+ * `find`, their delegated gesture-tap / keyboard effects) by calling
  * `registry.invokeTool` directly. Each such call would otherwise emit its
  * lifecycle events under a fresh, unrecorded invocation id — so the AI-client /
  * platform attribution the HTTP layer captured for the outer request never
- * reaches the nested gestures, and they're recorded as anonymous.
+ * reaches the nested gestures, and they're recorded as anonymous. (This is why a
+ * single `find … fill` emits `find` plus a child `gesture-tap` and N child
+ * `keyboard` events, all attributed to the outer request — intended.)
  *
  * When the outer request carried attribution, `ctx.recordChildInvocation` is
  * present: mint an id, register it (inheriting the outer AI client, with the
diff --git a/packages/tool-server/src/utils/timing.ts b/packages/tool-server/src/utils/timing.ts
index 41de17285..27c5e9452 100644
--- a/packages/tool-server/src/utils/timing.ts
+++ b/packages/tool-server/src/utils/timing.ts
@@ -19,3 +19,45 @@ export function sleepOrAbort(ms: number, signal?: AbortSignal): Promise<boolean>
     signal?.addEventListener("abort", onAbort, { once: true });
   });
 }
+
+export type Settled<T> =
+  | { type: "value"; value: T }
+  | { type: "error"; error: string }
+  | { type: "timeout" }
+  | { type: "aborted" };
+
+// Race a promise (typically a tree fetch) against a time budget and an abort
+// signal. The underlying describe fetch isn't cancellable (no AbortSignal reaches
+// adb / AXRuntime), so a slow or hung fetch — e.g. the Android `uiautomator dump`
+// fallback, which allows up to 20s — would otherwise blow past the caller's
+// deadline and ignore an abort that arrives mid-fetch. We can't kill the orphaned
+// fetch, but we stop waiting on it; its eventual settle is consumed here (handlers
+// attached up front) so it can't surface as an unhandled rejection.
+export function settleWithin<T>(
+  p: Promise<T>,
+  ms: number,
+  signal?: AbortSignal
+): Promise<Settled<T>> {
+  return new Promise((resolve) => {
+    let done = false;
+    const teardown: Array<() => void> = [];
+    const finish = (r: Settled<T>) => {
+      if (done) return;
+      done = true;
+      for (const fn of teardown) fn();
+      resolve(r);
+    };
+    // Attach the settle handlers up front so a late settle from an abandoned
+    // fetch is always consumed (no unhandled rejection) even after we've moved on.
+    p.then(
+      (value) => finish({ type: "value", value }),
+      (err) => finish({ type: "error", error: err instanceof Error ? err.message : String(err) })
+    );
+    if (signal?.aborted) return finish({ type: "aborted" });
+    const onAbort = () => finish({ type: "aborted" });
+    signal?.addEventListener("abort", onAbort, { once: true });
+    teardown.push(() => signal?.removeEventListener("abort", onAbort));
+    const timer = setTimeout(() => finish({ type: "timeout" }), Math.max(0, ms));
+    teardown.push(() => clearTimeout(timer));
+  });
+}
diff --git a/packages/tool-server/test/await-ui-element.test.ts b/packages/tool-server/test/await-ui-element.test.ts
index f08e1c771..a3bd1355f 100644
--- a/packages/tool-server/test/await-ui-element.test.ts
+++ b/packages/tool-server/test/await-ui-element.test.ts
@@ -1,4 +1,22 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// The describe path probes device form factor before reading the tree: iOS via
+// `isTvOsSimulator` (shells `xcrun`), and Android via `isAndroidTv` (shells `adb
+// devices`) on EVERY poll. Left real, those subprocess calls make the polling
+// tests nondeterministic — under parallel-suite load a single poll's probe can
+// outlast a tight timeoutMs, flipping a semantic note to "did not complete" (the
+// pre-existing flakiness this file's Android `hidden` tests hit). Stub both to a
+// plain (mobile) verdict so the tree fetch is deterministic and off the host's
+// devices; every fixture here is a mobile target.
+vi.mock("../src/utils/ios-devices", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../src/utils/ios-devices")>()),
+  isTvOsSimulator: vi.fn(async () => false),
+}));
+vi.mock("../src/utils/adb", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../src/utils/adb")>()),
+  isAndroidTv: vi.fn(async () => false),
+}));
+
 import type { AXServiceApi, AXDescribeResponse } from "../src/blueprints/ax-service";
 import type { AndroidDevtoolsApi } from "../src/blueprints/android-devtools";
 import type { ChromiumCdpApi } from "../src/blueprints/chromium-cdp";
diff --git a/packages/tool-server/test/chromium-describe-value-extraction.test.ts b/packages/tool-server/test/chromium-describe-value-extraction.test.ts
new file mode 100644
index 000000000..410e17421
--- /dev/null
+++ b/packages/tool-server/test/chromium-describe-value-extraction.test.ts
@@ -0,0 +1,209 @@
+import { describe, it, expect } from "vitest";
+
+import { describeChromium } from "../src/tools/describe/platforms/chromium";
+import type { ChromiumCdpApi } from "../src/blueprints/chromium-cdp";
+import type { DescribeNode } from "../src/tools/describe/contract";
+
+// find's Chromium `fill` clear rests on a load-bearing premise about the DOM
+// walker (see find/index.ts): a form control's live `el.value` is NEVER surfaced
+// — an <input> is described as label=placeholder with `value` empty — and a
+// contenteditable reports ONLY its direct text nodes (an undercount that omits
+// text nested in inline children). find.test.ts feeds a hand-built tree, so it
+// asserts the *consequences* of that premise without ever exercising the walker
+// that produces it: if describeChromium started exposing el.value, those tests
+// would stay green while find's cap logic silently broke.
+//
+// This test runs the REAL in-page script — the exact `expression` describeChromium
+// hands to Runtime.evaluate — against a minimal, faithful DOM stand-in, so the
+// premise is verified against the actual walker. No jsdom/happy-dom dependency:
+// we inject the DOM globals the script references as `new Function` params (see
+// `runPageScript`).
+
+type Attrs = Record<string, string>;
+
+class FakeEl {
+  tagName: string;
+  children: FakeEl[];
+  // ownText walks childNodes and keeps only nodeType===3 (text) nodes, so a
+  // contenteditable's direct text precedes its element children here, exactly as
+  // "Hello <b>world</b>" lays out in the real DOM.
+  childNodes: Array<FakeEl | { nodeType: number; nodeValue: string }>;
+  shadowRoot: null = null;
+  id: string;
+  href?: string;
+  value?: string;
+  placeholder?: string;
+  type?: string;
+  alt?: string;
+  title?: string;
+  scrollHeight = 0;
+  clientHeight = 0;
+  scrollWidth = 0;
+  clientWidth = 0;
+  private attrs: Attrs;
+
+  constructor(
+    opts: {
+      tag?: string;
+      attrs?: Attrs;
+      children?: FakeEl[];
+      text?: string;
+      id?: string;
+      href?: string;
+      value?: string;
+      placeholder?: string;
+      type?: string;
+      alt?: string;
+      title?: string;
+    } = {}
+  ) {
+    this.tagName = (opts.tag ?? "div").toUpperCase();
+    this.attrs = opts.attrs ?? {};
+    this.children = opts.children ?? [];
+    this.id = opts.id ?? "";
+    if (opts.href !== undefined) this.href = opts.href;
+    if (opts.value !== undefined) this.value = opts.value;
+    if (opts.placeholder !== undefined) this.placeholder = opts.placeholder;
+    if (opts.type !== undefined) this.type = opts.type;
+    if (opts.alt !== undefined) this.alt = opts.alt;
+    if (opts.title !== undefined) this.title = opts.title;
+    this.childNodes = [
+      ...(opts.text ? [{ nodeType: 3, nodeValue: opts.text }] : []),
+      ...this.children,
+    ];
+  }
+  getAttribute(name: string): string | null {
+    return name in this.attrs ? this.attrs[name]! : null;
+  }
+  hasAttribute(name: string): boolean {
+    return name in this.attrs;
+  }
+  // A non-zero rect keeps the walker's visibility check from pruning the node.
+  getBoundingClientRect() {
+    return { left: 10, top: 10, right: 110, bottom: 30, width: 100, height: 20 };
+  }
+}
+// The script branches on `instanceof HTMLInputElement` etc.; subclassing lets us
+// pass these constructors in as the corresponding globals.
+class FakeInput extends FakeEl {}
+class FakeTextArea extends FakeEl {}
+class FakeImage extends FakeEl {}
+// Minimal `Node` stand-in. This repo's DESCRIBE_DOM_SCRIPT never references `Node`
+// directly, yet the CI runner threw "Node is not defined" evaluating it — a bare
+// `new Function` resolves any stray DOM-global reference (introduced by the host's
+// transform / eval realm) against Node.js's sparse global scope. Injecting a stub
+// (carrying the standard nodeType constants, in case a reference reads them) makes
+// the eval host-independent. Passed as the `Node` param below.
+class FakeNode {
+  static readonly ELEMENT_NODE = 1;
+  static readonly TEXT_NODE = 3;
+  static readonly COMMENT_NODE = 8;
+  static readonly DOCUMENT_NODE = 9;
+  static readonly DOCUMENT_FRAGMENT_NODE = 11;
+}
+
+// Evaluate describeChromium's real page-eval `expression` against the fake DOM by
+// injecting every identifier it can reference as an explicit `new Function` param,
+// so the eval never depends on the host realm's ambient globals. `Element` and
+// `HTMLElement` map to the base fake; the form controls to their subclasses.
+function runPageScript(expression: string, win: unknown, doc: unknown): string {
+  // Evaluates our OWN constant page-script string against injected fakes — not
+  // attacker input — so the implied-eval rule doesn't apply here.
+  // eslint-disable-next-line @typescript-eslint/no-implied-eval
+  const run = new Function(
+    "window",
+    "document",
+    "Node",
+    "Element",
+    "HTMLElement",
+    "HTMLInputElement",
+    "HTMLTextAreaElement",
+    "HTMLImageElement",
+    `return (${expression});`
+  );
+  return run(win, doc, FakeNode, FakeEl, FakeEl, FakeInput, FakeTextArea, FakeImage) as string;
+}
+
+// Run describeChromium end-to-end: its Runtime.evaluate `expression` (the real
+// DESCRIBE_DOM_SCRIPT) is executed against the fake DOM via `runPageScript`.
+async function walkDom(root: FakeEl): Promise<DescribeNode> {
+  const win = {
+    innerWidth: 1024,
+    innerHeight: 768,
+    getComputedStyle: () => ({
+      visibility: "",
+      display: "block",
+      opacity: "",
+      overflowY: "visible",
+      overflowX: "visible",
+    }),
+  };
+  const doc = { documentElement: root, getElementById: () => null };
+  const api = {
+    refreshViewport: async () => ({ width: win.innerWidth, height: win.innerHeight }),
+    getViewport: () => ({ width: win.innerWidth, height: win.innerHeight }),
+    cdp: {
+      send: async (method: string, params?: { expression?: string }) => {
+        if (method !== "Runtime.evaluate" || !params?.expression) return {};
+        return { result: { value: runPageScript(params.expression, win, doc) } };
+      },
+    },
+  } as unknown as ChromiumCdpApi;
+  const { tree } = await describeChromium(api);
+  return tree;
+}
+
+function findNode(
+  node: DescribeNode,
+  pred: (n: DescribeNode) => boolean
+): DescribeNode | undefined {
+  if (pred(node)) return node;
+  for (const c of node.children ?? []) {
+    const f = findNode(c, pred);
+    if (f) return f;
+  }
+  return undefined;
+}
+
+describe("describeChromium — Chromium fill premise (value extraction)", () => {
+  it("describes a populated <input> as label=placeholder with NO value", async () => {
+    const input = new FakeInput({
+      tag: "input",
+      type: "email",
+      placeholder: "Email",
+      value: "typed@example.com", // the live value the walker must NOT surface
+    });
+    const tree = await walkDom(new FakeEl({ tag: "body", children: [input] }));
+
+    const node = findNode(tree, (n) => n.label === "Email");
+    expect(node).toBeDefined();
+    // accessibleName prefers the placeholder; ownText (childNodes text) is empty
+    // for a form control, so `value` is unset — the length is unknowable, which
+    // is exactly why find's Chromium `fill` clears to the cap.
+    expect(node!.value).toBeUndefined();
+    expect(node!.value).not.toBe("typed@example.com");
+  });
+
+  it("describes a contenteditable with ONLY its direct text nodes (inline children undercounted)", async () => {
+    // "Hello <b>world</b>" — "Hello " is a direct text node; "world" is nested in
+    // an inline <b> child and must be excluded from the parent's value.
+    const bold = new FakeEl({ tag: "b", text: "world" });
+    const ce = new FakeEl({
+      tag: "div",
+      attrs: { contenteditable: "" },
+      text: "Hello ",
+      children: [bold],
+    });
+    const tree = await walkDom(new FakeEl({ tag: "body", children: [ce] }));
+
+    // ownText collapses/trims whitespace, so "Hello " → "Hello".
+    const node = findNode(tree, (n) => n.value === "Hello");
+    expect(node).toBeDefined();
+    // The undercount find must not trust: the real content is "Hello world" but
+    // `value` reports only the 5-char direct text.
+    expect(node!.value).toBe("Hello");
+    expect(node!.value).not.toContain("world");
+    // "world" surfaces on the nested child, never merged into the parent's value.
+    expect(findNode(tree, (n) => n.value === "world")).toBeDefined();
+  });
+});
diff --git a/packages/tool-server/test/find.test.ts b/packages/tool-server/test/find.test.ts
new file mode 100644
index 000000000..09b7203aa
--- /dev/null
+++ b/packages/tool-server/test/find.test.ts
@@ -0,0 +1,1415 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// describeIos probes isTvOsSimulator, which shells `xcrun simctl list` (~100ms,
+// uncached for an unknown UDID). Stub it so these tests stay deterministic and
+// off the host's simulators — every iOS fixture here is a plain mobile device.
+vi.mock("../src/utils/ios-devices", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../src/utils/ios-devices")>()),
+  isTvOsSimulator: vi.fn(async () => false),
+}));
+
+// `find` probes getAndroidRuntimeKind for an acting action to keep itself
+// read-only on TV (and to fail closed on an indeterminate probe). Stub it to a
+// plain "mobile" verdict so the Android acting tests don't shell adb; the
+// Android-TV / indeterminate tests override it per-case.
+//
+// ALSO stub isAndroidTv: the Android *describe* path (`describeAndroid`) calls it
+// directly to attach a TV hint, and its real implementation shells `adb`. Leaving
+// it unmocked passes only where adb happens to be on PATH (a dev laptop) and
+// fails on an adb-less CI runner (the tree never parses → found:false). Mocking
+// both keeps every Android path adb-free regardless of the host.
+vi.mock("../src/utils/adb", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../src/utils/adb")>()),
+  getAndroidRuntimeKind: vi.fn(async () => "mobile"),
+  isAndroidTv: vi.fn(async () => false),
+}));
+
+import { isTvOsSimulator } from "../src/utils/ios-devices";
+import { getAndroidRuntimeKind, isAndroidTv } from "../src/utils/adb";
+import type { AXServiceApi, AXDescribeResponse } from "../src/blueprints/ax-service";
+import type { AndroidDevtoolsApi } from "../src/blueprints/android-devtools";
+import type { ChromiumCdpApi } from "../src/blueprints/chromium-cdp";
+import { createFindTool, findMatches, locatorField } from "../src/tools/find";
+import type { DescribeNode } from "../src/tools/describe/contract";
+import { __primeDepCacheForTests, __resetDepCacheForTests } from "../src/utils/check-deps";
+
+const IOS_UDID = "AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA";
+const ANDROID_SERIAL = "emulator-5554";
+const CHROMIUM_ID = "chromium-cdp-9222";
+
+// ── Mocks (mirror await-ui-element.test.ts, plus an invokeTool spy) ───────────
+
+function makeSequencedAXService(
+  responses: AXDescribeResponse[],
+  opts: { degraded?: boolean } = {}
+): { api: AXServiceApi; calls: () => number } {
+  let i = 0;
+  const api: AXServiceApi = {
+    degraded: opts.degraded ?? false,
+    describe: async () => responses[Math.min(i++, responses.length - 1)]!,
+    alertCheck: async () => false,
+    ping: async () => true,
+  };
+  return { api, calls: () => i };
+}
+
+function axResponse(elements: AXDescribeResponse["elements"]): AXDescribeResponse {
+  return { alertVisible: false, screenFrame: { width: 440, height: 956 }, elements };
+}
+
+type SubInvocation = { toolId: string; args: Record<string, unknown> };
+
+// Registry mock that serves the iOS AX / Android devtools services AND records
+// the gesture-tap / keyboard sub-tool invocations `find` dispatches, returning
+// canned results for each.
+function makeMockRegistry(opts: { ax?: AXServiceApi; android?: AndroidDevtoolsApi } = {}) {
+  const invocations: SubInvocation[] = [];
+  const registry = {
+    resolveService: vi.fn(async (urn: string) => {
+      if (urn.startsWith("AXService:")) {
+        if (!opts.ax) throw new Error("no AX service configured");
+        return opts.ax;
+      }
+      if (urn.startsWith("AndroidDevtools:")) {
+        if (!opts.android) throw new Error("no Android devtools configured");
+        return opts.android;
+      }
+      throw new Error(`unexpected service: ${urn}`);
+    }),
+    invokeTool: vi.fn(async (toolId: string, args: Record<string, unknown>) => {
+      invocations.push({ toolId, args });
+      if (toolId === "gesture-tap") return { tapped: true, timestampMs: 1234 };
+      if (toolId === "keyboard") {
+        if (typeof args.key === "string") return { typed: args.key, keys: 1 };
+        const text = typeof args.text === "string" ? args.text : "";
+        return { typed: text, keys: text.length };
+      }
+      return {};
+    }),
+  } as any;
+  return { registry, invocations };
+}
+
+function makeChromiumApi(treeJson: unknown): ChromiumCdpApi {
+  return {
+    refreshViewport: async () => ({ width: 1024, height: 768 }),
+    getViewport: () => ({ width: 1024, height: 768 }),
+    cdp: {
+      send: async (method: string) => {
+        if (method === "Runtime.evaluate") {
+          return { result: { value: JSON.stringify({ tree: treeJson, truncated: false }) } };
+        }
+        return {};
+      },
+    },
+  } as unknown as ChromiumCdpApi;
+}
+
+// A Chromium api whose evaluate always throws — the fetch-failure case.
+function makeFailingChromiumApi(): ChromiumCdpApi {
+  return {
+    refreshViewport: async () => ({ width: 1024, height: 768 }),
+    getViewport: () => ({ width: 1024, height: 768 }),
+    cdp: {
+      send: async () => {
+        throw new Error("renderer detached");
+      },
+    },
+  } as unknown as ChromiumCdpApi;
+}
+
+const FRAME = { x: 0.1, y: 0.4, width: 0.8, height: 0.05 };
+const CENTER = { x: FRAME.x + FRAME.width / 2, y: FRAME.y + FRAME.height / 2 };
+// `fill` focuses at the field's bottom-trailing corner (95% across, 90% down),
+// not its centre, so the clear's leftward backspaces start from the end of the
+// text on the last line (handles multi-line fields, not just long single lines).
+const TRAILING = { x: FRAME.x + FRAME.width * 0.95, y: FRAME.y + FRAME.height * 0.9 };
+
+// ── Pure locator matching (hand-built trees, no platform adapter) ────────────
+
+describe("find — locator matching", () => {
+  const node = (over: Partial<DescribeNode>): DescribeNode => ({
+    role: "AXStaticText",
+    frame: FRAME,
+    children: [],
+    ...over,
+  });
+  const tree = (children: DescribeNode[]): DescribeNode => ({
+    role: "AXGroup",
+    frame: { x: 0, y: 0, width: 1, height: 1 },
+    children,
+  });
+
+  it("matches by label / value / role / id independently", () => {
+    const n = node({
+      label: "Sign In",
+      value: "v-text",
+      identifier: "login-btn",
+      role: "AXButton",
+    });
+    expect(locatorField(n, "label", "sign")).toBe("label");
+    expect(locatorField(n, "value", "v-text")).toBe("value");
+    expect(locatorField(n, "role", "button")).toBe("role");
+    expect(locatorField(n, "id", "login")).toBe("id");
+    // label-only locator must NOT match on the value/role/id
+    expect(locatorField(n, "label", "login-btn")).toBeNull();
+    expect(locatorField(n, "value", "Sign In")).toBeNull();
+  });
+
+  it("is case-insensitive substring", () => {
+    expect(locatorField(node({ label: "Continue" }), "label", "TINU")).toBe("label");
+  });
+
+  it("`text` matches label OR value, preferring label", () => {
+    expect(locatorField(node({ label: "Status", value: "Done" }), "text", "done")).toBe("value");
+    expect(locatorField(node({ label: "Done", value: "x" }), "text", "done")).toBe("label");
+  });
+
+  it("`any` spans label/value/id but NOT role", () => {
+    expect(locatorField(node({ identifier: "submit" }), "any", "submit")).toBe("id");
+    expect(locatorField(node({ value: "hello" }), "any", "hello")).toBe("value");
+    // role is deliberately excluded from `any`
+    expect(locatorField(node({ role: "AXButton" }), "any", "button")).toBeNull();
+    expect(locatorField(node({ role: "AXButton" }), "role", "button")).toBe("role");
+  });
+
+  it("findMatches collects every match but never the synthetic root", () => {
+    const t = tree([node({ role: "AXGroup", label: "inner" }), node({ label: "leaf" })]);
+    expect(findMatches(t, "role", "AXGroup")).toHaveLength(1); // only the inner AXGroup child
+    expect(findMatches(t, "any", "nomatch")).toHaveLength(0);
+  });
+});
+
+// ── Tool execution ───────────────────────────────────────────────────────────
+
+describe("find tool", () => {
+  beforeEach(() => {
+    __resetDepCacheForTests();
+    __primeDepCacheForTests(["xcrun", "adb"]);
+    // Reset call history AND implementation so a per-test TV override can't leak
+    // into a later test — mockClear alone keeps the sticky implementation, which
+    // would let a `mockResolvedValue("tv")` bleed into a following acting test.
+    vi.mocked(isTvOsSimulator).mockReset();
+    vi.mocked(isTvOsSimulator).mockResolvedValue(false);
+    vi.mocked(getAndroidRuntimeKind).mockReset();
+    vi.mocked(getAndroidRuntimeKind).mockResolvedValue("mobile");
+    // isAndroidTv is used by the describe-android hint path (not find's guard);
+    // keep it false so the Android tree fetch never shells adb on any host.
+    vi.mocked(isAndroidTv).mockReset();
+    vi.mocked(isAndroidTv).mockResolvedValue(false);
+  });
+
+  const iosTool = (ax: AXServiceApi) => {
+    const { registry, invocations } = makeMockRegistry({ ax });
+    return { tool: createFindTool(registry), invocations, registry };
+  };
+  const keyboardCalls = (inv: SubInvocation[]) => inv.filter((i) => i.toolId === "keyboard");
+  const backspaces = (inv: SubInvocation[]) => inv.filter((i) => i.args.key === "backspace");
+
+  it("exposes the find id", () => {
+    expect(createFindTool(makeMockRegistry().registry).id).toBe("find");
+  });
+
+  // ── tap ──
+  it("taps the matched element's centre via gesture-tap", async () => {
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "Sign In", frame: FRAME, traits: ["button"] }]),
+    ]);
+    const { tool, invocations } = iosTool(api);
+
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Sign In", by: "text", action: "tap", index: 0 }
+    );
+
+    expect(result.found).toBe(true);
+    expect(result.actionResult).toMatchObject({ kind: "tap", tapped: true });
+    const tap = invocations.find((i) => i.toolId === "gesture-tap")!;
+    expect(tap.args).toMatchObject({ udid: IOS_UDID, x: CENTER.x, y: CENTER.y });
+  });
+
+  it("defaults action to tap and by to any", async () => {
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "Hello World", frame: FRAME, traits: [] }]),
+    ]);
+    const { tool, invocations } = iosTool(api);
+    const params = tool.zodSchema!.parse({ udid: IOS_UDID, query: "hello" });
+    const result = await tool.execute({}, params as never);
+    expect(result.action).toBe("tap");
+    expect(result.by).toBe("any");
+    expect(invocations.some((i) => i.toolId === "gesture-tap")).toBe(true);
+  });
+
+  // ── focus ──
+  it("`focus` taps the match centre and reports kind:focus", async () => {
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "Email", frame: FRAME, traits: ["textfield"] }]),
+    ]);
+    const { tool, invocations } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Email", by: "label", action: "focus", index: 0 }
+    );
+    expect(result.found).toBe(true);
+    expect(result.actionResult).toMatchObject({ kind: "focus", focused: true });
+    const tap = invocations.find((i) => i.toolId === "gesture-tap")!;
+    expect(tap.args).toMatchObject({ x: CENTER.x, y: CENTER.y });
+    expect(keyboardCalls(invocations)).toHaveLength(0);
+  });
+
+  // ── index / ambiguity ──
+  it("acts on the index-th match in reading order, reports matchCount and an ambiguity note", async () => {
+    const top = { label: "Item", frame: { x: 0.1, y: 0.2, width: 0.5, height: 0.05 }, traits: [] };
+    const bottom = {
+      label: "Item",
+      frame: { x: 0.1, y: 0.8, width: 0.5, height: 0.05 },
+      traits: [],
+    };
+    const { api } = makeSequencedAXService([axResponse([bottom, top])]);
+    const { tool, invocations } = iosTool(api);
+
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Item", by: "label", action: "tap", index: 1 }
+    );
+
+    expect(result.matchCount).toBe(2);
+    expect(result.found).toBe(true);
+    expect(result.note).toMatch(/2 elements matched.*acted on index 1/i);
+    const tap = invocations.find((i) => i.toolId === "gesture-tap")!;
+    expect(tap.args.y).toBeCloseTo(0.8 + 0.05 / 2); // index 1 = the lower one
+  });
+
+  it("read-only multi-match note says `selected`, not `acted on`", async () => {
+    const a = { label: "Row", frame: { x: 0.1, y: 0.2, width: 0.5, height: 0.05 }, traits: [] };
+    const b = { label: "Row", frame: { x: 0.1, y: 0.5, width: 0.5, height: 0.05 }, traits: [] };
+    const { api } = makeSequencedAXService([axResponse([a, b])]);
+    const { tool } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Row", by: "label", action: "get-text", index: 0 }
+    );
+    expect(result.note).toMatch(/selected index 0/i);
+    expect(result.note).not.toMatch(/acted on/i);
+  });
+
+  it("returns found:false with an out-of-range note when index exceeds matches", async () => {
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "Only", frame: FRAME, traits: [] }]),
+    ]);
+    const { tool, invocations } = iosTool(api);
+
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Only", by: "label", action: "tap", index: 3 }
+    );
+
+    expect(result.found).toBe(false);
+    expect(result.note).toMatch(/out of range/i);
+    expect(invocations.some((i) => i.toolId === "gesture-tap")).toBe(false);
+  });
+
+  // ── zero-area / not actionable (Chromium mock returns the tree verbatim) ──
+  it("does not tap a match with a zero-area frame", async () => {
+    const tree = {
+      role: "html",
+      frame: { x: 0, y: 0, width: 1, height: 1 },
+      children: [
+        {
+          role: "button",
+          label: "Ghost",
+          frame: { x: 0.1, y: 0.4, width: 0, height: 0 },
+          children: [],
+        },
+      ],
+    };
+    const { registry, invocations } = makeMockRegistry({});
+    const tool = createFindTool(registry);
+
+    const result = await tool.execute(
+      { chromium: makeChromiumApi(tree) },
+      { udid: CHROMIUM_ID, query: "Ghost", by: "label", action: "tap", index: 0 }
+    );
+
+    expect(result.found).toBe(false);
+    expect(result.matchCount).toBe(0); // no actionable (visible) matches
+    expect(result.note).toMatch(/none is visible|zero-area/i);
+    expect(invocations.some((i) => i.toolId === "gesture-tap")).toBe(false);
+  });
+
+  // ── exists (single-shot) ──
+  it("`exists` reports presence in a single check (no polling)", async () => {
+    const { api, calls } = makeSequencedAXService([
+      axResponse([{ label: "Present", frame: FRAME, traits: [] }]),
+    ]);
+    const { tool } = iosTool(api);
+    const found = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Present", by: "label", action: "exists", index: 0 }
+    );
+    expect(found.found).toBe(true);
+    expect(found.actionResult).toBeUndefined();
+    expect(found.match?.label).toBe("Present");
+    expect(calls()).toBe(1);
+  });
+
+  it("`exists` is true even for a zero-area (not-visible) match", async () => {
+    const tree = {
+      role: "html",
+      frame: { x: 0, y: 0, width: 1, height: 1 },
+      children: [
+        {
+          role: "div",
+          label: "Hidden",
+          frame: { x: 0.1, y: 0.4, width: 0, height: 0 },
+          children: [],
+        },
+      ],
+    };
+    const { registry } = makeMockRegistry({});
+    const tool = createFindTool(registry);
+    const result = await tool.execute(
+      { chromium: makeChromiumApi(tree) },
+      { udid: CHROMIUM_ID, query: "Hidden", by: "label", action: "exists", index: 0 }
+    );
+    expect(result.found).toBe(true);
+  });
+
+  it("`exists` reports the topmost VISIBLE match, not a zero-area ghost that sorts above it", async () => {
+    // Two matches: a zero-area ghost at y=0.1 (sorts first in reading order) and a
+    // real visible one lower at y=0.5. exists must report the VISIBLE match — the
+    // element a subsequent tap would hit — not the ghost with its degenerate
+    // tapPoint. (Every other exists test has ≤1 match, so the .filter(isVisible)
+    // that picks the visible one was never exercised — T1.)
+    const tree = {
+      role: "html",
+      frame: { x: 0, y: 0, width: 1, height: 1 },
+      children: [
+        {
+          role: "button",
+          label: "Submit",
+          frame: { x: 0.1, y: 0.1, width: 0, height: 0 }, // zero-area ghost, sorts first
+          children: [],
+        },
+        {
+          role: "button",
+          label: "Submit",
+          frame: { x: 0.1, y: 0.5, width: 0.6, height: 0.05 }, // the real, visible one
+          children: [],
+        },
+      ],
+    };
+    const { registry } = makeMockRegistry({});
+    const tool = createFindTool(registry);
+    const result = await tool.execute(
+      { chromium: makeChromiumApi(tree) },
+      { udid: CHROMIUM_ID, query: "Submit", by: "label", action: "exists", index: 0 }
+    );
+    expect(result.found).toBe(true);
+    expect(result.matchCount).toBe(2); // both counted for a read-only presence check
+    // Reported match is the visible one (y≈0.5), NOT the zero-area ghost (y≈0.1).
+    expect(result.match!.frame.y).toBeCloseTo(0.5, 2);
+    expect(result.match!.visible).toBe(true);
+  });
+
+  it("`exists` returns found:false for a missing element", async () => {
+    const { api } = makeSequencedAXService([axResponse([])]);
+    const { tool } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Nope", by: "label", action: "exists", index: 0 }
+    );
+    expect(result.found).toBe(false);
+    expect(result.matchCount).toBe(0);
+  });
+
+  // ── wait (polls) ──
+  it("`wait` polls until the element becomes visible", async () => {
+    const { api, calls } = makeSequencedAXService([
+      axResponse([]),
+      axResponse([{ label: "Loaded", frame: FRAME, traits: [] }]),
+    ]);
+    const { tool } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      {
+        udid: IOS_UDID,
+        query: "Loaded",
+        by: "label",
+        action: "wait",
+        index: 0,
+        timeoutMs: 2000,
+        pollIntervalMs: 10,
+      }
+    );
+    expect(result.found).toBe(true);
+    expect(result.actionResult).toBeUndefined();
+    expect(calls()).toBeGreaterThan(1);
+  });
+
+  it("`wait` times out with a note when the element never appears", async () => {
+    const { api } = makeSequencedAXService([axResponse([])]);
+    const { tool } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      {
+        udid: IOS_UDID,
+        query: "Never",
+        by: "label",
+        action: "wait",
+        index: 0,
+        timeoutMs: 30,
+        pollIntervalMs: 10,
+      }
+    );
+    expect(result.found).toBe(false);
+    expect(result.note).toMatch(/no element matched/i);
+    expect(result.elapsed).toBeGreaterThanOrEqual(30);
+  });
+
+  it("polls before acting when timeoutMs is set on a tap", async () => {
+    const { api, calls } = makeSequencedAXService([
+      axResponse([]),
+      axResponse([{ label: "Appears", frame: FRAME, traits: ["button"] }]),
+    ]);
+    const { tool, invocations } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      {
+        udid: IOS_UDID,
+        query: "Appears",
+        by: "label",
+        action: "tap",
+        index: 0,
+        timeoutMs: 2000,
+        pollIntervalMs: 10,
+      }
+    );
+    expect(result.found).toBe(true);
+    expect(calls()).toBeGreaterThan(1);
+    expect(invocations.some((i) => i.toolId === "gesture-tap")).toBe(true);
+  });
+
+  // ── type ──
+  it("`type` focuses (centre) then types the text", async () => {
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "Email", frame: FRAME, traits: ["textfield"] }]),
+    ]);
+    const { tool, invocations } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Email", by: "label", action: "type", text: "hi", index: 0 }
+    );
+    expect(result.found).toBe(true);
+    expect(result.actionResult).toMatchObject({ kind: "type", typed: "hi" });
+    expect(invocations.map((i) => i.toolId)).toEqual(["gesture-tap", "keyboard"]);
+    // focus tap is the centre, NOT a trailing-edge bias
+    expect(invocations[0]!.args).toMatchObject({ x: CENTER.x, y: CENTER.y });
+    expect(backspaces(invocations)).toHaveLength(0);
+  });
+
+  // ── fill ──
+  it("`fill` focuses at the trailing edge, clears the field's text length + buffer, then types", async () => {
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "Field", value: "abcd", frame: FRAME, traits: ["textfield"] }]),
+    ]);
+    const { tool, invocations } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Field", by: "label", action: "fill", text: "new", index: 0 }
+    );
+    expect(result.found).toBe(true);
+    // clear length = the live text length (value "abcd"=4) + CLEAR_BUFFER 2. The
+    // static placeholder label "Field" is NOT counted now that `value` is present.
+    expect(backspaces(invocations)).toHaveLength(4 + 2);
+    expect(result.actionResult).toMatchObject({ kind: "fill", typed: "new", backspacesSent: 6 });
+    expect(invocations[0]!.toolId).toBe("gesture-tap");
+    // focus is biased to the bottom-trailing corner so the caret starts at the
+    // end, NOT the centre where a mid-text caret could strand right-hand residue.
+    expect(invocations[0]!.args).toMatchObject({ x: TRAILING.x, y: TRAILING.y });
+    expect(invocations[0]!.args.x as number).toBeGreaterThan(CENTER.x);
+    expect(invocations[0]!.args.y as number).toBeGreaterThan(CENTER.y);
+    expect(invocations.at(-1)).toMatchObject({ toolId: "keyboard", args: { text: "new" } });
+  });
+
+  it("`fill` clears text carried in `label` when `value` is unset (Android bare EditText)", async () => {
+    // An Android EditText WITHOUT a content-desc surfaces its typed text as
+    // `label` with `value` unset. Sizing the clear from `value` alone would send
+    // only CLEAR_BUFFER backspaces and type the new text on top of the leftover
+    // (filling "old@example.com" with "new@x.io" → "old@example.cnew@x.io").
+    // max(value,label) sizes it from `label` here — reliable on Android.
+    const xml =
+      `<?xml version="1.0" encoding="UTF-8"?>` +
+      `<hierarchy rotation="0">` +
+      `<node class="android.widget.FrameLayout" bounds="[0,0][1080,2400]">` +
+      `<node text="old@example.com" class="android.widget.EditText" clickable="true" focusable="true" bounds="[50,300][1030,400]" />` +
+      `</node>` +
+      `</hierarchy>`;
+    const android: AndroidDevtoolsApi = {
+      getHierarchy: async () => ({ xml }),
+      getScreenSize: async () => ({ width: 1080, height: 2400, rotation: 0 }),
+    } as unknown as AndroidDevtoolsApi;
+    const { registry, invocations } = makeMockRegistry({ android });
+    const tool = createFindTool(registry);
+    const result = await tool.execute(
+      {},
+      {
+        udid: ANDROID_SERIAL,
+        query: "old@example.com",
+        by: "label",
+        action: "fill",
+        text: "new@x.io",
+        index: 0,
+      }
+    );
+    expect(result.found).toBe(true);
+    expect(result.match).toMatchObject({ matchedField: "label", label: "old@example.com" });
+    // 15 (label length) + CLEAR_BUFFER 2 — NOT the 2 the value-only path would send
+    expect(backspaces(invocations)).toHaveLength(15 + 2);
+    expect((result.actionResult as { backspacesSent: number }).backspacesSent).toBe(17);
+    expect(result.note ?? "").not.toMatch(/capped/i);
+    expect(invocations.at(-1)).toMatchObject({ toolId: "keyboard", args: { text: "new@x.io" } });
+  });
+
+  it("`fill` on Chromium clears to the cap and warns — the live text isn't in the a11y snapshot", async () => {
+    // describeChromium.accessibleName prefers a static aria-label / placeholder
+    // over el.value, and value (ownText) is always empty for a form control, so a
+    // populated <input placeholder="Email"> is described as label="Email",
+    // value=unset — the live content length is unknowable. Sizing from `label`
+    // (5) would leave a longer value behind silently; instead we clear up to the
+    // cap and flag it.
+    const tree = {
+      role: "textbox",
+      frame: { x: 0, y: 0, width: 1, height: 1 },
+      children: [
+        {
+          role: "textbox",
+          label: "Email", // a placeholder, NOT the live value
+          frame: { x: 0.1, y: 0.4, width: 0.8, height: 0.05 },
+          children: [],
+        },
+      ],
+    };
+    const { registry, invocations } = makeMockRegistry({});
+    const tool = createFindTool(registry);
+    const result = await tool.execute(
+      { chromium: makeChromiumApi(tree) },
+      { udid: CHROMIUM_ID, query: "Email", by: "label", action: "fill", text: "new@x.io", index: 0 }
+    );
+    expect(result.found).toBe(true);
+    // full MAX_CLEAR_CHARS clear, not the 7 that label="Email" (5)+buffer implies
+    expect(backspaces(invocations)).toHaveLength(64);
+    expect((result.actionResult as { backspacesSent: number }).backspacesSent).toBe(64);
+    expect(result.note).toMatch(/chromium/i);
+    expect(result.note).toMatch(/verify/i);
+    expect(result.note ?? "").not.toMatch(/capped/i); // it's the unknown-length caveat, not the cap
+    expect(invocations.at(-1)).toMatchObject({ toolId: "keyboard", args: { text: "new@x.io" } });
+  });
+
+  it("`fill` on a Chromium contenteditable clears to the cap despite a non-empty (undercounted) value", async () => {
+    // A contenteditable is described with `value` = its DIRECT text nodes only —
+    // text nested in inline children (a <b>, a mention span) is excluded, so a
+    // populated field reports a non-empty but UNDERCOUNTED value. Sizing the
+    // clear from that undercount would delete only the leading chars and leave
+    // the rest for the new text to be typed on top of. On Chromium the length is
+    // never trusted: clear to the cap and warn regardless of a non-empty value.
+    const tree = {
+      role: "textbox",
+      frame: { x: 0, y: 0, width: 1, height: 1 },
+      children: [
+        {
+          role: "textbox",
+          value: "abc", // direct text only; real content ("abc<b>…</b>") is far longer
+          frame: { x: 0.1, y: 0.4, width: 0.8, height: 0.05 },
+          children: [],
+        },
+      ],
+    };
+    const { registry, invocations } = makeMockRegistry({});
+    const tool = createFindTool(registry);
+    const result = await tool.execute(
+      { chromium: makeChromiumApi(tree) },
+      { udid: CHROMIUM_ID, query: "abc", by: "value", action: "fill", text: "ZZZ", index: 0 }
+    );
+    expect(result.found).toBe(true);
+    // NOT the 3+buffer the undercounted value="abc" would imply — full cap clear.
+    expect(backspaces(invocations)).toHaveLength(64);
+    expect((result.actionResult as { backspacesSent: number }).backspacesSent).toBe(64);
+    expect(result.note).toMatch(/chromium/i);
+    expect(result.note).toMatch(/verify/i);
+    // The caveat warns about BOTH directions, not just leftover text: a fixed-count
+    // clear on an inner block of a multi-block editor can backspace past the block's
+    // start and delete into the PRECEDING block. Guards commit b473a39c's direction.
+    expect(result.note).toMatch(/preceding block/i);
+    expect(invocations.at(-1)).toMatchObject({ toolId: "keyboard", args: { text: "ZZZ" } });
+  });
+
+  it("`fill` sizes from the field text, and only warns `capped` past MAX_CLEAR_CHARS chars", async () => {
+    const fillIos = async (value: string) => {
+      const svc = makeSequencedAXService([
+        axResponse([{ label: "F", value, frame: FRAME, traits: ["textfield"] }]),
+      ]);
+      const t = iosTool(svc.api);
+      const r = await t.tool.execute(
+        {},
+        { udid: IOS_UDID, query: "F", by: "label", action: "fill", text: "x", index: 0 }
+      );
+      return { backspaces: backspaces(t.invocations).length, note: r.note ?? "", result: r };
+    };
+
+    // short field → value.length + CLEAR_BUFFER, no cap warning
+    const short = await fillIos("abcd");
+    expect(short.backspaces).toBe(4 + 2);
+    expect(short.note).not.toMatch(/capped/i);
+
+    // exactly MAX_CLEAR_CHARS chars → the 64 backspaces fully clear it, so NO
+    // spurious cap warning (the off-by-CLEAR_BUFFER boundary).
+    const exact = await fillIos("a".repeat(64));
+    expect(exact.backspaces).toBe(64);
+    expect(exact.note).not.toMatch(/capped/i);
+
+    // longer than the cap → genuinely may be incomplete → warn.
+    const over = await fillIos("a".repeat(65));
+    expect(over.backspaces).toBe(64);
+    expect(over.note).toMatch(/capped/i);
+  });
+
+  it("`fill` warns on a masked password field with an unknown length", async () => {
+    const tree = {
+      role: "html",
+      frame: { x: 0, y: 0, width: 1, height: 1 },
+      children: [
+        {
+          role: "textbox",
+          label: "Password",
+          value: "",
+          password: true,
+          frame: { x: 0.1, y: 0.4, width: 0.8, height: 0.05 },
+          children: [],
+        },
+      ],
+    };
+    const { registry } = makeMockRegistry({});
+    const tool = createFindTool(registry);
+    const result = await tool.execute(
+      { chromium: makeChromiumApi(tree) },
+      { udid: CHROMIUM_ID, query: "Password", by: "label", action: "fill", text: "pw", index: 0 }
+    );
+    expect(result.match?.flags?.password).toBe(true);
+    expect(result.note).toMatch(/password/i);
+  });
+
+  it("`fill` clears the enclosing editable region, not the demoted inner proxy (H1)", async () => {
+    // The iOS search-bar shape that reproduced the "abcd" → "WxyzAbcd" bug: a wide
+    // AXGroup that actually carries the value ("abcd") wraps a narrow inner
+    // AXTextField proxy (no value). Both match "Search". For a tapping action the
+    // container is demoted, so index 0 = the narrow proxy. fill must still focus +
+    // size the clear against the WIDE region: trusting the proxy's frame parks the
+    // caret at the field's far left (backspaces delete nothing, new text prepends).
+    const group = {
+      label: "Search",
+      value: "abcd",
+      frame: { x: 0.1, y: 0.4, width: 0.761, height: 0.05 },
+      traits: [],
+    };
+    const proxy = {
+      label: "Search",
+      frame: { x: 0.11, y: 0.41, width: 0.051, height: 0.03 },
+      traits: ["searchField"],
+    };
+    const { api } = makeSequencedAXService([axResponse([group, proxy])]);
+    const { tool, invocations } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Search", by: "label", action: "fill", text: "wxyz", index: 0 }
+    );
+    expect(result.found).toBe(true);
+    expect(result.matchCount).toBe(2);
+    // index 0 is the demoted-past inner proxy (narrow frame ≈ 0.051 wide).
+    expect(result.match!.frame.width).toBeCloseTo(0.051, 3);
+    // …but the focus tap lands on the WIDE region's trailing edge (x ≈ 0.82), well
+    // to the right of the proxy's own trailing edge (≈ 0.16) — this is the fix.
+    const focusTap = invocations.find((i) => i.toolId === "gesture-tap")!;
+    expect(focusTap.args.x as number).toBeCloseTo(0.1 + 0.761 * 0.95, 2);
+    expect(focusTap.args.x as number).toBeGreaterThan(0.5);
+    // The clear is sized from the WIDE region's value ("abcd"=4) + CLEAR_BUFFER,
+    // NOT the proxy's placeholder label ("Search"=6 → the old 8-backspace path).
+    expect(backspaces(invocations)).toHaveLength(4 + 2);
+    expect(invocations.at(-1)).toMatchObject({ toolId: "keyboard", args: { text: "wxyz" } });
+  });
+
+  it("`fill` on an empty field backspaces only the buffer, not the placeholder label (L3)", async () => {
+    // An empty iOS field exposes value="" with the placeholder in `label`
+    // ("Search"). Sizing from the label would send 6+buffer phantom backspaces
+    // (each a keyboard round-trip); preferring the present `value` sizes it to the
+    // real (zero) length, so only the CLEAR_BUFFER backspaces are sent.
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "Search", value: "", frame: FRAME, traits: ["searchField"] }]),
+    ]);
+    const { tool, invocations } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Search", by: "label", action: "fill", text: "hi", index: 0 }
+    );
+    expect(result.found).toBe(true);
+    // 0 (empty value) + CLEAR_BUFFER 2 — NOT 6 (label) + 2 the placeholder implies.
+    expect(backspaces(invocations)).toHaveLength(2);
+    expect(result.note ?? "").not.toMatch(/capped|incomplete/i);
+    expect(invocations.at(-1)).toMatchObject({ toolId: "keyboard", args: { text: "hi" } });
+  });
+
+  // ── get-text / get-attrs ──
+  it("`get-text` returns label + value, no device action", async () => {
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "Title", value: "Subtitle", frame: FRAME, traits: [] }]),
+    ]);
+    const { tool, invocations } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Title", by: "label", action: "get-text", index: 0 }
+    );
+    expect(result.actionResult).toMatchObject({ kind: "get-text", text: "Title Subtitle" });
+    expect(invocations).toHaveLength(0);
+  });
+
+  it("`get-text` joins only the present fields (label only → no trailing space)", async () => {
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "JustLabel", frame: FRAME, traits: [] }]),
+    ]);
+    const { tool } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "JustLabel", by: "label", action: "get-text", index: 0 }
+    );
+    expect((result.actionResult as { text: string }).text).toBe("JustLabel");
+  });
+
+  it("`get-attrs` returns the attributes in `match` (role, frame, tapPoint, matchedField), no actionResult", async () => {
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "Card", frame: FRAME, traits: ["button"] }]),
+    ]);
+    const { tool, invocations } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Card", by: "any", action: "get-attrs", index: 0 }
+    );
+    expect(result.actionResult).toBeUndefined();
+    expect(result.match).toMatchObject({
+      role: "AXButton",
+      label: "Card",
+      matchedField: "label",
+      tapPoint: { x: CENTER.x, y: CENTER.y },
+    });
+    expect(invocations).toHaveLength(0);
+  });
+
+  // ── diagnostics / errors ──
+  it("surfaces the degraded-AX restart hint on a not-found note", async () => {
+    const { api } = makeSequencedAXService([axResponse([])], { degraded: true });
+    const { tool } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Anything", by: "label", action: "tap", index: 0 }
+    );
+    expect(result.found).toBe(false);
+    expect(result.note).toMatch(/boot-device|restart/i);
+  });
+
+  it("surfaces the degraded-AX hint on an `exists` not-found note too", async () => {
+    const { api } = makeSequencedAXService([axResponse([])], { degraded: true });
+    const { tool } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Anything", by: "label", action: "exists", index: 0 }
+    );
+    expect(result.found).toBe(false);
+    expect(result.note).toMatch(/boot-device|restart/i);
+    // A degraded AX tree is untrustworthy, so an empty one is a BLIND read, not a
+    // confirmed absence — exists flags presenceUnknown (M1).
+    expect(result.presenceUnknown).toBe(true);
+  });
+
+  it("`exists` reports presenceUnknown (not a confirmed absence) when the tree is unreadable", async () => {
+    // An unreadable screen (Chromium renderer detached, never a usable tree) must
+    // not read as "confirmed absent": exists surfaces presenceUnknown so a caller
+    // can tell "couldn't check" from "checked and it's gone".
+    const { registry } = makeMockRegistry({});
+    const tool = createFindTool(registry);
+    const result = await tool.execute(
+      { chromium: makeFailingChromiumApi() },
+      { udid: CHROMIUM_ID, query: "Continue", by: "text", action: "exists", index: 0 }
+    );
+    expect(result.found).toBe(false);
+    expect(result.presenceUnknown).toBe(true);
+    expect(result.note).toMatch(/presence unknown|could not be read/i);
+    expect(result.note).toMatch(/renderer detached/);
+  });
+
+  it("`exists` does NOT set presenceUnknown for a genuine absence (tree read, no match)", async () => {
+    const { api } = makeSequencedAXService([axResponse([])]);
+    const { tool } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Nope", by: "label", action: "exists", index: 0 }
+    );
+    expect(result.found).toBe(false);
+    expect(result.presenceUnknown).toBeUndefined();
+    expect(result.note).toMatch(/no element matched/i);
+  });
+
+  // ── cancellation ──
+  it("aborts promptly when the signal fires mid-wait", async () => {
+    const { api } = makeSequencedAXService([axResponse([])]);
+    const { tool } = iosTool(api);
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 20);
+    const result = await tool.execute(
+      {},
+      {
+        udid: IOS_UDID,
+        query: "Nope",
+        by: "label",
+        action: "wait",
+        index: 0,
+        timeoutMs: 5000,
+        pollIntervalMs: 10,
+      },
+      { signal: controller.signal } as never
+    );
+    expect(result.found).toBe(false);
+    expect(result.note).toMatch(/cancel/i);
+    expect(result.elapsed).toBeLessThan(2000);
+  });
+
+  it("aborts a `fill` during the focus settle, before any keystroke", async () => {
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "Field", value: "abc", frame: FRAME, traits: ["textfield"] }]),
+    ]);
+    const { tool, invocations } = iosTool(api);
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 20); // fires during the ~150ms iOS settle
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Field", by: "label", action: "fill", text: "new", index: 0 },
+      { signal: controller.signal } as never
+    );
+    // The element WAS located and the focus tap fired, so a mid-action cancel is
+    // reported as found:true with an accurate note (not "nothing happened").
+    expect(result.found).toBe(true);
+    expect(result.match).toBeDefined();
+    expect(result.note).toMatch(/cancel/i);
+    expect(result.note).toMatch(/not yet modified/i);
+    // the focus tap may have fired, but no keystrokes (clear/type) ran
+    expect(keyboardCalls(invocations)).toHaveLength(0);
+  });
+
+  it("aborts a `fill` when the signal fires mid-clear, before typing the text", async () => {
+    // Abort after the first backspace (during the clear loop, past the focus
+    // settle): find must bail before pushing `text` in and must not report success.
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "Field", value: "abcdef", frame: FRAME, traits: ["textfield"] }]),
+    ]);
+    const controller = new AbortController();
+    const invocations: SubInvocation[] = [];
+    const registry = {
+      resolveService: async (urn: string) => {
+        if (urn.startsWith("AXService:")) return api;
+        throw new Error(`unexpected service: ${urn}`);
+      },
+      invokeTool: async (toolId: string, args: Record<string, unknown>) => {
+        invocations.push({ toolId, args });
+        if (toolId === "gesture-tap") return { tapped: true, timestampMs: 1 };
+        if (toolId === "keyboard" && args.key === "backspace") {
+          controller.abort(); // abort as soon as the clear loop sends a key
+          return { typed: "backspace", keys: 1 };
+        }
+        if (toolId === "keyboard") {
+          const text = typeof args.text === "string" ? args.text : "";
+          return { typed: text, keys: text.length };
+        }
+        return {};
+      },
+    } as any;
+    const tool = createFindTool(registry);
+
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Field", by: "label", action: "fill", text: "new", index: 0 },
+      { signal: controller.signal } as never
+    );
+
+    // The element was located and the field was partially cleared before the
+    // cancel, so the result reports found:true and says the field may be
+    // partially cleared — not "cancelled before the element was located".
+    expect(result.found).toBe(true);
+    expect(result.match).toBeDefined();
+    expect(result.note).toMatch(/cancel/i);
+    expect(result.note).toMatch(/partially cleared/i);
+    // the text was never typed (no keyboard call carrying `text`)
+    expect(
+      invocations.some((i) => i.toolId === "keyboard" && typeof i.args.text === "string")
+    ).toBe(false);
+  });
+
+  // ── Android branch ──
+  it("drives the Android devtools path and taps a node", async () => {
+    const xml =
+      `<?xml version="1.0" encoding="UTF-8"?>` +
+      `<hierarchy rotation="0">` +
+      `<node class="android.widget.FrameLayout" bounds="[0,0][1080,2400]">` +
+      `<node text="Sign in" resource-id="com.demo:id/signin" class="android.widget.Button" clickable="true" bounds="[100,200][980,320]" />` +
+      `</node>` +
+      `</hierarchy>`;
+    const android: AndroidDevtoolsApi = {
+      getHierarchy: async () => ({ xml }),
+      getScreenSize: async () => ({ width: 1080, height: 2400, rotation: 0 }),
+    } as unknown as AndroidDevtoolsApi;
+    const { registry, invocations } = makeMockRegistry({ android });
+    const tool = createFindTool(registry);
+    const result = await tool.execute(
+      {},
+      { udid: ANDROID_SERIAL, query: "Sign in", by: "text", action: "tap", index: 0 }
+    );
+    expect(result.found).toBe(true);
+    expect(invocations.some((i) => i.toolId === "gesture-tap")).toBe(true);
+  });
+
+  // ── Chromium branch ──
+  it("matches a DOM node and dispatches the tap on Chromium", async () => {
+    const tree = {
+      role: "html",
+      frame: { x: 0, y: 0, width: 1, height: 1 },
+      children: [
+        {
+          role: "button",
+          label: "Continue",
+          clickable: true,
+          frame: { x: 0.4, y: 0.8, width: 0.2, height: 0.05 },
+          children: [],
+        },
+      ],
+    };
+    const { registry, invocations } = makeMockRegistry({});
+    const tool = createFindTool(registry);
+    const result = await tool.execute(
+      { chromium: makeChromiumApi(tree) },
+      { udid: CHROMIUM_ID, query: "Continue", by: "text", action: "tap", index: 0 }
+    );
+    expect(result.found).toBe(true);
+    const tap = invocations.find((i) => i.toolId === "gesture-tap")!;
+    expect(tap.args.udid).toBe(CHROMIUM_ID);
+    expect(tap.args.x as number).toBeCloseTo(0.5);
+    expect(tap.args.y as number).toBeCloseTo(0.825);
+  });
+
+  // ── M1: container-vs-child on a tapping action ──
+  it("taps the inner input, not the enclosing container that folds its text (Android)", async () => {
+    // A clickable card with no own label borrows its descendants' text into its
+    // content-desc ("Server / localhost"), so both the card AND the EditText match
+    // "localhost". The card sorts first in reading order (smaller y) and encloses
+    // the input — a plain reading-order pick would tap the card's centre (the M1
+    // bug). For a tapping action `find` demotes the enclosing container, so the
+    // default index 0 lands on the inner input.
+    const xml =
+      `<?xml version="1.0" encoding="UTF-8"?>` +
+      `<hierarchy rotation="0">` +
+      `<node class="android.widget.FrameLayout" bounds="[0,0][1080,2400]">` +
+      `<node class="android.widget.LinearLayout" clickable="true" bounds="[40,600][1040,900]">` +
+      `<node text="Server" class="android.widget.TextView" bounds="[60,620][400,680]" />` +
+      `<node text="localhost" class="android.widget.EditText" clickable="true" focusable="true" bounds="[60,760][1000,860]" />` +
+      `</node>` +
+      `</node>` +
+      `</hierarchy>`;
+    const android: AndroidDevtoolsApi = {
+      getHierarchy: async () => ({ xml }),
+      getScreenSize: async () => ({ width: 1080, height: 2400, rotation: 0 }),
+    } as unknown as AndroidDevtoolsApi;
+    const { registry, invocations } = makeMockRegistry({ android });
+    const tool = createFindTool(registry);
+    const result = await tool.execute(
+      {},
+      { udid: ANDROID_SERIAL, query: "localhost", by: "any", action: "tap", index: 0 }
+    );
+    expect(result.found).toBe(true);
+    expect(result.matchCount).toBe(2); // both the card and the input match
+    // Chosen = the inner input (narrower frame), NOT the enclosing card.
+    expect(result.match!.frame.width).toBeCloseTo(940 / 1080, 2);
+    const tap = invocations.find((i) => i.toolId === "gesture-tap")!;
+    // input centre y ≈ 0.3375, NOT the card centre y ≈ 0.3125
+    expect(tap.args.y as number).toBeCloseTo(0.3375, 2);
+    expect(tap.args.y as number).not.toBeCloseTo(0.3125, 2);
+    // The ambiguity note explains a tapping action demotes the enclosing
+    // container below the matches it wraps (so index 0 is the inner input).
+    expect(result.note).toMatch(/enclosing container ranks after/i);
+  });
+
+  it("keeps plain reading order for a read-only action (no container demotion)", async () => {
+    // get-text is read-only: the enclosing container is NOT demoted, so index 0 is
+    // the topmost-in-reading-order match (the card), proving demotion is scoped to
+    // tapping actions.
+    const xml =
+      `<?xml version="1.0" encoding="UTF-8"?>` +
+      `<hierarchy rotation="0">` +
+      `<node class="android.widget.FrameLayout" bounds="[0,0][1080,2400]">` +
+      `<node class="android.widget.LinearLayout" clickable="true" bounds="[40,600][1040,900]">` +
+      `<node text="localhost" class="android.widget.EditText" clickable="true" focusable="true" bounds="[60,760][1000,860]" />` +
+      `</node>` +
+      `</node>` +
+      `</hierarchy>`;
+    const android: AndroidDevtoolsApi = {
+      getHierarchy: async () => ({ xml }),
+      getScreenSize: async () => ({ width: 1080, height: 2400, rotation: 0 }),
+    } as unknown as AndroidDevtoolsApi;
+    const { registry } = makeMockRegistry({ android });
+    const tool = createFindTool(registry);
+    const result = await tool.execute(
+      {},
+      { udid: ANDROID_SERIAL, query: "localhost", by: "any", action: "get-text", index: 0 }
+    );
+    expect(result.matchCount).toBe(2);
+    // Card is topmost (y ≈ 0.25) → index 0 is the card (wider frame), not the input.
+    expect(result.match!.frame.width).toBeCloseTo(1000 / 1080, 2);
+    expect(result.note).toMatch(/topmost in reading order/i);
+  });
+
+  // ── M2: find is read-only on a TV target ──
+  it("rejects an acting action on a tvOS target without mutating anything", async () => {
+    vi.mocked(isTvOsSimulator).mockResolvedValueOnce(true);
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "Field", value: "abc", frame: FRAME, traits: ["textfield"] }]),
+    ]);
+    const { tool, invocations } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Field", by: "label", action: "fill", text: "new", index: 0 }
+    );
+    expect(result.found).toBe(false);
+    expect(result.matchCount).toBe(0);
+    expect(result.note).toMatch(/read-only on TV|tv-remote/i);
+    // Nothing was tapped or typed — the field is never focused or backspaced.
+    expect(invocations).toHaveLength(0);
+    expect(isTvOsSimulator).toHaveBeenCalledTimes(1);
+  });
+
+  it("allows a read-only action on a tvOS target (not rejected; returns a valid absent answer)", async () => {
+    // Symmetric with the Android-TV read-only test below: a read-only find never
+    // drives the D-pad, so it is NOT rejected on tvOS — only the acting actions
+    // are (the acting gate is `TAPPING_ACTIONS.has(action) && isTvOs`). The tvOS
+    // verdict is resolved UNCONDITIONALLY (find/index.ts:469), so this guards the
+    // read-only branch that the acting-reject test can't.
+    //
+    // Unlike Android TV (uiautomator serves a real tree), tvOS find goes through
+    // describeIos, whose iOS accessibility service does NOT serve the tvOS focus
+    // tree — it short-circuits to an EMPTY tree plus a TVOS_HINT pointing at
+    // `describe` + `tv-remote`. So a read-only find on tvOS resolves to a valid
+    // "not present" answer (found:false), never found:true. What matters here is
+    // that it is a normal read result carrying that hint — NOT the acting-on-TV
+    // rejection, and NOT a blind-read presenceUnknown (the empty tree WAS read).
+    vi.mocked(isTvOsSimulator).mockResolvedValueOnce(true);
+    // The AX response is irrelevant — describeIos short-circuits tvOS before the
+    // ax-service is even resolved — but iosTool needs some api.
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "Now Playing", frame: FRAME, traits: [] }]),
+    ]);
+    const { tool, invocations } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Now Playing", by: "text", action: "exists", index: 0 }
+    );
+    // A valid read result, not an acting-on-TV rejection: exists ran the tvOS
+    // describe path. The tree came back EMPTY but flagged (TVOS_HINT) — the AX
+    // service can't serve the tvOS focus tree — so this is a BLIND read, not a
+    // confirmed absence: exists must surface presenceUnknown so a caller doesn't
+    // read "couldn't see the screen" as "the element is gone" (M1).
+    expect(result.found).toBe(false);
+    expect(result.matchCount).toBe(0);
+    expect(result.presenceUnknown).toBe(true);
+    // Crucially: NOT rejected as an unsupported acting-on-TV action.
+    expect(result.note ?? "").not.toMatch(/read-only on TV|cannot `?exists`? on a TV/i);
+    // The note carries the tvOS hint, proving the tvOS describe path ran and the
+    // verdict was threaded through (rather than the normal AX path or a rejection).
+    expect(result.note).toMatch(/Apple TV|tvOS|tv-remote/i);
+    expect(invocations).toHaveLength(0); // no device effect for a read
+    expect(isTvOsSimulator).toHaveBeenCalledTimes(1); // the tvOS verdict was resolved
+  });
+
+  it("rejects an acting action on an Android TV target without mutating anything", async () => {
+    vi.mocked(getAndroidRuntimeKind).mockResolvedValueOnce("tv");
+    const { registry, invocations } = makeMockRegistry({});
+    const tool = createFindTool(registry);
+    const result = await tool.execute(
+      {},
+      { udid: ANDROID_SERIAL, query: "Sign in", by: "text", action: "tap", index: 0 }
+    );
+    expect(result.found).toBe(false);
+    expect(result.note).toMatch(/TV/);
+    expect(result.note).toMatch(/tv-remote/i);
+    expect(invocations).toHaveLength(0);
+    expect(getAndroidRuntimeKind).toHaveBeenCalledTimes(1);
+  });
+
+  it("fails closed: rejects an acting action when the Android form factor can't be determined", async () => {
+    // Mid-boot / offline: getAndroidRuntimeKind returns undefined. We can't prove
+    // the target is a mobile device, so an acting find must NOT fire a blind
+    // coordinate tap (which would no-op on a TV and be reported as tapped:true) —
+    // it fails closed exactly like a confirmed TV target (L2).
+    vi.mocked(getAndroidRuntimeKind).mockResolvedValueOnce(undefined);
+    const { registry, invocations } = makeMockRegistry({});
+    const tool = createFindTool(registry);
+    const result = await tool.execute(
+      {},
+      { udid: ANDROID_SERIAL, query: "Sign in", by: "text", action: "tap", index: 0 }
+    );
+    expect(result.found).toBe(false);
+    expect(result.matchCount).toBe(0);
+    expect(result.note).toMatch(/tv-remote/i);
+    expect(invocations).toHaveLength(0); // nothing tapped
+    expect(getAndroidRuntimeKind).toHaveBeenCalledTimes(1);
+  });
+
+  it("allows a read-only action on an Android TV target (find is read-only, not blocked, on TV)", async () => {
+    // A read-only find never touches the D-pad, so it is NOT rejected on TV — only
+    // the acting actions are. get-text works on a TV target as on a phone. Even if
+    // the form-factor probe WOULD say "tv", a read-only find never calls it (the
+    // acting-guard short-circuits on the action), so no adb round-trip is paid.
+    vi.mocked(getAndroidRuntimeKind).mockResolvedValueOnce("tv");
+    const xml =
+      `<?xml version="1.0" encoding="UTF-8"?>` +
+      `<hierarchy rotation="0">` +
+      `<node class="android.widget.FrameLayout" bounds="[0,0][1080,2400]">` +
+      `<node text="Now Playing" class="android.widget.TextView" bounds="[60,300][900,380]" />` +
+      `</node>` +
+      `</hierarchy>`;
+    const android: AndroidDevtoolsApi = {
+      getHierarchy: async () => ({ xml }),
+      getScreenSize: async () => ({ width: 1080, height: 2400, rotation: 0 }),
+    } as unknown as AndroidDevtoolsApi;
+    const { registry, invocations } = makeMockRegistry({ android });
+    const tool = createFindTool(registry);
+    const result = await tool.execute(
+      {},
+      { udid: ANDROID_SERIAL, query: "Now Playing", by: "text", action: "get-text", index: 0 }
+    );
+    expect(result.found).toBe(true);
+    expect(result.actionResult).toMatchObject({ kind: "get-text", text: "Now Playing" });
+    // A read-only action is never rejected as an unsupported TV action.
+    expect(result.note ?? "").not.toMatch(/read-only on TV|cannot .*get-text/i);
+    expect(invocations).toHaveLength(0); // no device effect for a read
+    // Read-only never probes the form factor, so the "tv" override was never read.
+    expect(getAndroidRuntimeKind).not.toHaveBeenCalled();
+    // No manual restore needed: beforeEach resets the mock implementation (T4).
+  });
+
+  // ── T3: the tvOS verdict is resolved ONCE, before the poll clock ──
+  it("resolves the tvOS verdict once across a polling wait, not per fetch", async () => {
+    const { api, calls } = makeSequencedAXService([
+      axResponse([]),
+      axResponse([{ label: "Loaded", frame: FRAME, traits: [] }]),
+    ]);
+    const { tool } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      {
+        udid: IOS_UDID,
+        query: "Loaded",
+        by: "label",
+        action: "wait",
+        index: 0,
+        timeoutMs: 2000,
+        pollIntervalMs: 10,
+      }
+    );
+    expect(result.found).toBe(true);
+    expect(calls()).toBeGreaterThan(1); // several fetches …
+    expect(isTvOsSimulator).toHaveBeenCalledTimes(1); // … but one tvOS probe
+  });
+
+  // ── T1: discovery-loop non-happy paths (slow / hung / aborted fetch) ──
+  const hangingAX = (): AXServiceApi => ({
+    degraded: false,
+    describe: () => new Promise<never>(() => {}), // never resolves
+    alertCheck: async () => false,
+    ping: async () => true,
+  });
+
+  it("bounds a single hung fetch to the wait budget instead of blocking forever", async () => {
+    const { tool } = iosTool(hangingAX());
+    const startedAt = Date.now();
+    const result = await tool.execute(
+      {},
+      {
+        udid: IOS_UDID,
+        query: "Nope",
+        by: "label",
+        action: "wait",
+        index: 0,
+        timeoutMs: 80,
+        pollIntervalMs: 10,
+      }
+    );
+    expect(result.found).toBe(false);
+    expect(Date.now() - startedAt).toBeLessThan(1000);
+    expect(result.note).toMatch(/did not complete within/i);
+  });
+
+  it("a final fetch straddling the deadline still yields the tree-based note, not a fetch failure", async () => {
+    // First poll returns a usable (empty) tree; later polls hang. The loop must
+    // give up at the deadline and, because it already read the screen, report the
+    // normal "no element matched" — NOT "did not complete" (reserved for never
+    // having read the screen at all).
+    let i = 0;
+    const api: AXServiceApi = {
+      degraded: false,
+      describe: () => (i++ === 0 ? Promise.resolve(axResponse([])) : new Promise<never>(() => {})),
+      alertCheck: async () => false,
+      ping: async () => true,
+    };
+    const { tool } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      {
+        udid: IOS_UDID,
+        query: "Nope",
+        by: "label",
+        action: "wait",
+        index: 0,
+        timeoutMs: 120,
+        pollIntervalMs: 30,
+      }
+    );
+    expect(result.found).toBe(false);
+    expect(result.note).toMatch(/no element matched/i);
+    expect(result.note ?? "").not.toMatch(/did not complete/i);
+  });
+
+  it("aborts promptly while a fetch is in flight (settleWithin's aborted branch)", async () => {
+    // The fetch never resolves, so the abort is observed by settleWithin mid-fetch
+    // — not by sleepOrAbort between polls (the existing abort test covers that).
+    const { tool } = iosTool(hangingAX());
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 30);
+    const result = await tool.execute(
+      {},
+      {
+        udid: IOS_UDID,
+        query: "Nope",
+        by: "label",
+        action: "wait",
+        index: 0,
+        timeoutMs: 5000,
+        pollIntervalMs: 10,
+      },
+      { signal: controller.signal } as never
+    );
+    expect(result.found).toBe(false);
+    expect(result.note).toMatch(/cancel/i);
+    expect(result.elapsed).toBeLessThan(2000);
+  });
+
+  // ── T2: the poll-sleep is clamped to the deadline ──
+  it("clamps the poll sleep to the deadline so a large pollIntervalMs can't overshoot timeoutMs", async () => {
+    // Element never appears; pollIntervalMs (1000) dwarfs timeoutMs (100). Without
+    // the clamp the first sleep would run the full 1000ms past the single second
+    // poll. With the clamp, elapsed lands just past the 100ms deadline.
+    const { api } = makeSequencedAXService([axResponse([])]);
+    const { tool } = iosTool(api);
+    const result = await tool.execute(
+      {},
+      {
+        udid: IOS_UDID,
+        query: "Never",
+        by: "label",
+        action: "wait",
+        index: 0,
+        timeoutMs: 100,
+        pollIntervalMs: 1000,
+      }
+    );
+    expect(result.found).toBe(false);
+    expect(result.elapsed).toBeGreaterThanOrEqual(100);
+    expect(result.elapsed).toBeLessThan(600);
+  });
+
+  // ── T4: `type` bails on a mid-settle abort before entering text ──
+  it("aborts a `type` during the focus settle, before any keystroke", async () => {
+    const { api } = makeSequencedAXService([
+      axResponse([{ label: "Email", frame: FRAME, traits: ["textfield"] }]),
+    ]);
+    const { tool, invocations } = iosTool(api);
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 20); // fires during the ~150ms iOS settle
+    const result = await tool.execute(
+      {},
+      { udid: IOS_UDID, query: "Email", by: "label", action: "type", text: "hi", index: 0 },
+      { signal: controller.signal } as never
+    );
+    // Located and focus-tapped, then cancelled before typing: found:true with an
+    // accurate note, and crucially NO text entered.
+    expect(result.found).toBe(true);
+    expect(result.match).toBeDefined();
+    expect(result.note).toMatch(/cancel/i);
+    expect(result.note).toMatch(/no text was entered/i);
+    expect(keyboardCalls(invocations)).toHaveLength(0);
+  });
+
+  // ── T5: matchCount counts all matches for reads, visible-only for taps ──
+  it("counts zero-area matches for read-only actions but not for tapping ones", async () => {
+    const mixedTree = {
+      role: "html",
+      frame: { x: 0, y: 0, width: 1, height: 1 },
+      children: [
+        {
+          role: "div",
+          label: "Row",
+          frame: { x: 0.1, y: 0.2, width: 0.5, height: 0.05 },
+          children: [],
+        },
+        { role: "div", label: "Row", frame: { x: 0.1, y: 0.4, width: 0, height: 0 }, children: [] },
+      ],
+    };
+    const read = createFindTool(makeMockRegistry({}).registry);
+    const readResult = await read.execute(
+      { chromium: makeChromiumApi(mixedTree) },
+      { udid: CHROMIUM_ID, query: "Row", by: "label", action: "get-text", index: 0 }
+    );
+    // get-text pool = ALL matches (the zero-area one included) → 2
+    expect(readResult.matchCount).toBe(2);
+    expect((readResult.actionResult as { text: string }).text).toBe("Row");
+
+    const tapTool = createFindTool(makeMockRegistry({}).registry);
+    const tapResult = await tapTool.execute(
+      { chromium: makeChromiumApi(mixedTree) },
+      { udid: CHROMIUM_ID, query: "Row", by: "label", action: "tap", index: 0 }
+    );
+    // tap pool = VISIBLE matches only → 1 (the zero-area one is excluded)
+    expect(tapResult.matchCount).toBe(1);
+  });
+
+  // ── Schema ──
+  describe("schema validation", () => {
+    const schema = createFindTool(makeMockRegistry().registry).zodSchema!;
+
+    it("requires udid and query", () => {
+      expect(schema.safeParse({ query: "x" }).success).toBe(false);
+      expect(schema.safeParse({ udid: IOS_UDID }).success).toBe(false);
+    });
+
+    it("rejects fill/type without text", () => {
+      expect(schema.safeParse({ udid: IOS_UDID, query: "x", action: "fill" }).success).toBe(false);
+      expect(schema.safeParse({ udid: IOS_UDID, query: "x", action: "type" }).success).toBe(false);
+    });
+
+    it("accepts fill/type with text and applies defaults", () => {
+      const parsed = schema.parse({ udid: IOS_UDID, query: "x", action: "fill", text: "y" });
+      expect(parsed.by).toBe("any");
+      expect(parsed.index).toBe(0);
+    });
+
+    it("rejects an unknown action / by", () => {
+      expect(schema.safeParse({ udid: IOS_UDID, query: "x", action: "swipe" }).success).toBe(false);
+      expect(schema.safeParse({ udid: IOS_UDID, query: "x", by: "placeholder" }).success).toBe(
+        false
+      );
+    });
+  });
+});
diff --git a/packages/tool-server/test/flows/flow-tools.test.ts b/packages/tool-server/test/flows/flow-tools.test.ts
index 18822fdb6..137abc6a9 100644
--- a/packages/tool-server/test/flows/flow-tools.test.ts
+++ b/packages/tool-server/test/flows/flow-tools.test.ts
@@ -292,6 +292,133 @@ describe("flow-add-step", () => {
     expect(flow.steps).toEqual([]);
   });
 
+  it("does not record when find returns found:false", async () => {
+    const registry = createMockRegistry({
+      find: { result: { found: false, note: 'no element matched text="Login"' } },
+    });
+    const tool = createFlowAddStepTool(registry);
+
+    await flowStartRecordingTool.execute(
+      {},
+      { name: "find-miss-recording", project_root: tmpDir, executionPrerequisite: PREREQ }
+    );
+
+    await expect(
+      tool.execute({}, { command: "find", args: '{"query":"Login","by":"text","action":"tap"}' })
+    ).rejects.toThrow(/find did not locate an element.*Login/i);
+
+    const content = await readFlowFile("find-miss-recording");
+    const flow = parseFlow(content);
+    expect(flow.steps).toEqual([]);
+  });
+
+  it("does not record when an await-ui-element step's condition is not met (L6)", async () => {
+    // An unmet await-ui-element returns { success: false } instead of throwing.
+    // Recording it would bake a step that flow-run halts on for EVERY replay
+    // (flow-run stops on isUnmetUiWaitResult), so flow-add-step must reject it at
+    // record time — symmetric with the missed-find guard above.
+    const registry = createMockRegistry({
+      "await-ui-element": {
+        result: { success: false, elapsed: 5000, note: "no element matched the selector" },
+      },
+    });
+    const tool = createFlowAddStepTool(registry);
+
+    await flowStartRecordingTool.execute(
+      {},
+      { name: "wait-miss-recording", project_root: tmpDir, executionPrerequisite: PREREQ }
+    );
+
+    await expect(
+      tool.execute(
+        {},
+        {
+          command: "await-ui-element",
+          args: '{"condition":"visible","selector":{"text":"Continue"}}',
+        }
+      )
+    ).rejects.toThrow(/await-ui-element condition was not met.*selector/i);
+
+    const content = await readFlowFile("wait-miss-recording");
+    const flow = parseFlow(content);
+    expect(flow.steps).toEqual([]);
+  });
+
+  it("records a met await-ui-element step (success:true is a normal recordable step)", async () => {
+    const registry = createMockRegistry({
+      "await-ui-element": { result: { success: true, elapsed: 120 } },
+    });
+    const tool = createFlowAddStepTool(registry);
+
+    await flowStartRecordingTool.execute(
+      {},
+      { name: "wait-hit-recording", project_root: tmpDir, executionPrerequisite: PREREQ }
+    );
+
+    const result = await tool.execute(
+      {},
+      {
+        command: "await-ui-element",
+        args: '{"condition":"visible","selector":{"text":"Continue"}}',
+      }
+    );
+    expect(result.toolResult).toMatchObject({ success: true });
+    const flow = parseFlow(result.flowFile);
+    expect(flow.steps).toHaveLength(1);
+    expect(flow.steps[0]).toMatchObject({ kind: "tool", name: "await-ui-element" });
+  });
+
+  it("records find steps when the element is found", async () => {
+    const registry = createMockRegistry({
+      find: { result: { found: true, matchCount: 1 } },
+    });
+    const tool = createFlowAddStepTool(registry);
+
+    await flowStartRecordingTool.execute(
+      {},
+      { name: "find-hit-recording", project_root: tmpDir, executionPrerequisite: PREREQ }
+    );
+
+    const result = await tool.execute(
+      {},
+      { command: "find", args: '{"query":"Login","by":"text","action":"tap"}' }
+    );
+
+    expect(result.toolResult).toEqual({ found: true, matchCount: 1 });
+    const flow = parseFlow(result.flowFile);
+    expect(flow.steps).toEqual([
+      {
+        kind: "tool",
+        name: "find",
+        args: { query: "Login", by: "text", action: "tap" },
+      },
+    ]);
+  });
+
+  it("records an `exists` find that returns found:false (a valid absent answer, not a miss)", async () => {
+    const registry = createMockRegistry({
+      find: { result: { found: false, action: "exists", matchCount: 0 } },
+    });
+    const tool = createFlowAddStepTool(registry);
+
+    await flowStartRecordingTool.execute(
+      {},
+      { name: "exists-false-recording", project_root: tmpDir, executionPrerequisite: PREREQ }
+    );
+
+    // Must NOT throw: for `exists`, found:false is the successful "not present"
+    // result, so the step is recorded rather than aborting the recording.
+    const result = await tool.execute(
+      {},
+      { command: "find", args: '{"query":"Spinner","by":"text","action":"exists"}' }
+    );
+    expect(result.toolResult).toMatchObject({ found: false, action: "exists" });
+    const flow = parseFlow(result.flowFile);
+    expect(flow.steps).toEqual([
+      { kind: "tool", name: "find", args: { query: "Spinner", by: "text", action: "exists" } },
+    ]);
+  });
+
   it("handles omitted args", async () => {
     const registry = createMockRegistry({
       screenshot: { result: { url: "http://..." } },
@@ -581,6 +708,75 @@ describe("flow-execute", () => {
     });
   });
 
+  it("stops when a recorded find step returns found:false", async () => {
+    const registry = createMockRegistry({
+      find: { result: { found: false, note: 'no element matched text="Continue"' } },
+      tap: { result: { tapped: true } },
+    });
+    const runFlow = createRunFlowTool(registry);
+
+    const dir = path.join(tmpDir, ".argent", "flows");
+    await fs.mkdir(dir, { recursive: true });
+    const content = serializeFlow({
+      executionPrerequisite: "",
+      steps: [
+        { kind: "tool", name: "find", args: { query: "Continue", by: "text", action: "tap" } },
+        { kind: "tool", name: "tap", args: { x: 0.5 } },
+      ],
+    });
+    await fs.writeFile(path.join(dir, "find-miss-replay.yaml"), content);
+
+    const result = await runFlow.execute({}, { name: "find-miss-replay", project_root: tmpDir });
+    assertFlowRunResult(result);
+
+    expect(registry.invokeTool).toHaveBeenCalledTimes(1);
+    expect(result.steps).toHaveLength(1);
+    expect(result.steps[0]).toMatchObject({
+      kind: "tool",
+      tool: "find",
+      error: expect.stringMatching(/find did not locate an element.*Continue/i),
+    });
+  });
+
+  it("does NOT stop the flow when a recorded `exists` find returns found:false (a valid absent answer)", async () => {
+    // Mirror of the record-side test ("records an `exists` find that returns
+    // found:false"): on replay, `exists` reporting found:false is a successful
+    // "not present" answer, not a missed locate — isMissedFindResult exempts it,
+    // so the step is recorded normally and the flow continues to the next step.
+    // Guards against a regression that drops the `r.action === "exists"` check in
+    // flow-step-results.ts, which would abort replay of every recorded exists step.
+    const registry = createMockRegistry({
+      find: { result: { found: false, action: "exists", matchCount: 0 } },
+      tap: { result: { tapped: true } },
+    });
+    const runFlow = createRunFlowTool(registry);
+
+    const dir = path.join(tmpDir, ".argent", "flows");
+    await fs.mkdir(dir, { recursive: true });
+    const content = serializeFlow({
+      executionPrerequisite: "",
+      steps: [
+        { kind: "tool", name: "find", args: { query: "Spinner", by: "text", action: "exists" } },
+        { kind: "tool", name: "tap", args: { x: 0.5 } },
+      ],
+    });
+    await fs.writeFile(path.join(dir, "exists-false-replay.yaml"), content);
+
+    const result = await runFlow.execute({}, { name: "exists-false-replay", project_root: tmpDir });
+    assertFlowRunResult(result);
+
+    // Both steps run: the exists step is NOT an error, and the following tap fires.
+    expect(registry.invokeTool).toHaveBeenCalledTimes(2);
+    expect(result.steps).toHaveLength(2);
+    expect(result.steps[0]).toMatchObject({
+      kind: "tool",
+      tool: "find",
+      result: { found: false, action: "exists" },
+    });
+    expect(result.steps[0]).not.toHaveProperty("error");
+    expect(result.steps[1]).toMatchObject({ kind: "tool", tool: "tap", result: { tapped: true } });
+  });
+
   it("throws when flow file does not exist", async () => {
     const registry = createMockRegistry({});
     const runFlow = createRunFlowTool(registry);
diff --git a/packages/tool-server/test/run-sequence.test.ts b/packages/tool-server/test/run-sequence.test.ts
index 1635f7512..cfb36fced 100644
--- a/packages/tool-server/test/run-sequence.test.ts
+++ b/packages/tool-server/test/run-sequence.test.ts
@@ -81,6 +81,34 @@ describe("run-sequence", () => {
     expect(failed && "error" in failed && failed.error).toMatch(/not allowed/);
   });
 
+  it("does NOT allow `find` — a missed find would silently continue the sequence (T3)", async () => {
+    // `find` is deliberately excluded from run-sequence: a missed `find … tap`
+    // returns { found: false } WITHOUT throwing, and run-sequence's stop guard only
+    // recognises an unmet await-ui-element (isUnmetUiWaitResult), not a missed find
+    // (isMissedFindResult lives in the flow runners). Wiring find in without teaching
+    // the guard would let the sequence run the NEXT step blind against a screen where
+    // the find failed. This locks the exclusion so adding find to ALLOWED_TOOLS
+    // without the guard can't slip through green.
+    const { registry, calls } = makeMockRegistry();
+    const tool = createRunSequenceTool(registry);
+    const result = await tool.execute!(
+      {},
+      {
+        udid: IOS,
+        steps: [
+          { tool: "find", args: { query: "Sign In", action: "tap" } },
+          { tool: "gesture-tap", args: { x: 0.5, y: 0.5 } },
+        ],
+      }
+    );
+    // The find step is rejected as not-allowed and halts before the tap runs.
+    expect(result.completed).toBe(0);
+    expect(calls.map((c) => c.tool)).toEqual([]); // find was never invoked
+    const failed = result.steps[0];
+    expect(failed && "error" in failed && failed.error).toMatch(/not allowed/);
+    expect(failed && "error" in failed && failed.error).toMatch(/find/);
+  });
+
   it("declares no eager service so a tvOS udid never spawns simulator-server", () => {
     const { registry } = makeMockRegistry();
     const tool = createRunSequenceTool(registry);