@unotest/mobile 0.1.1 → 0.8.0

package/dist/mcp/server.js

@@ -17,7 +17,7 @@ __export(pg_client_exports, {
 async function create(databaseUrl) {
   const pgMod = await import("pg").catch(() => {
     throw new Error(
-      `'pg' driver requested by DATABASE_URL but the 'pg' package is not installed. Run: pnpm add -D pg @types/pg`
+      `'pg' driver requested by DATABASE_URL but the 'pg' package is not installed. Install it (npm i -D pg @types/pg, or your package manager's equivalent).`
     );
   });
   const PoolCtor = pgMod.default?.Pool ?? pgMod.Pool;
@@ -66,7 +66,7 @@ function isWriteSql(sql) {
 async function create2(databaseUrl) {
   const mod = await import("mysql2/promise").catch(() => {
     throw new Error(
-      `'mysql' driver requested by DATABASE_URL but the 'mysql2' package is not installed. Run: pnpm add -D mysql2`
+      `'mysql' driver requested by DATABASE_URL but the 'mysql2' package is not installed. Install it (npm i -D mysql2, or your package manager's equivalent).`
     );
   });
   const pool = mod.createPool(databaseUrl);
@@ -116,7 +116,7 @@ function parseSqlitePath(databaseUrl) {
 async function create3(databaseUrl) {
   const mod = await import("better-sqlite3").catch(() => {
     throw new Error(
-      `'sqlite' driver requested by DATABASE_URL but the 'better-sqlite3' package is not installed. Run: pnpm add -D better-sqlite3 @types/better-sqlite3`
+      `'sqlite' driver requested by DATABASE_URL but the 'better-sqlite3' package is not installed. Install it (npm i -D better-sqlite3 @types/better-sqlite3, or your package manager's equivalent).`
     );
   });
   const Database = mod.default ?? mod;
@@ -174,33 +174,65 @@ function ensureLoaded() {
 }
 __name(ensureLoaded, "ensureLoaded");
 var EnvSchema = z.object({
-  APP_BUNDLE_ID: z.string().min(1),
-  APP_URL_SCHEME: z.string().min(1),
-  INVITE_DEEPLINK_PREFIX: z.string().min(1),
-  API_BASE_URL: z.string().url(),
+  // APP_BUNDLE_ID — required at appLaunch / install time. We let the schema
+  // accept it as optional so commands that don't touch the app (`doctor`,
+  // `lint`) work without it. Use-site (WdaDriver) validates and errors with
+  // a clear message if missing.
+  APP_BUNDLE_ID: z.string().min(1).optional(),
+  // APP_URL_SCHEME — only consumed by the (currently unimplemented) Expo
+  // dev-client recovery flow. Optional; reserved for future use.
+  APP_URL_SCHEME: z.string().min(1).optional(),
+  // APP_PERMISSIONS — comma-separated `simctl privacy` services that
+  // `install --clean` (CLI + MCP) auto-grants before launch. Populated
+  // by `install --update-env` from detected NS*UsageDescription keys in
+  // the .app's Info.plist (P4 / S4). Optional — apps that don't request
+  // privacy services leave this unset.
+  // Example: APP_PERMISSIONS=location,motion
+  APP_PERMISSIONS: z.string().optional(),
+  // API_BASE_URL — only required if scenarios call `apiCall(...)`. Lazy:
+  // the ApiClient is constructed at first use, not at startup.
+  API_BASE_URL: z.string().url().optional(),
   // PROJECT_ROOT — optional default cwd for the `shell(...)` DSL primitive.
   // When unset, shell commands run from process.cwd(). Set to the absolute
   // path of the project-under-test when its CLI must be invoked from a
-  // specific directory (e.g. monorepo root for `pnpm --filter ...`).
+  // specific directory (e.g. monorepo root).
   PROJECT_ROOT: z.string().optional(),
-  // DATABASE_URL — connection string for native pg/mysql/sqlite client
-  // (Stage 0 plugin DbClient). Format examples:
+  // DATABASE_URL — only required if scenarios call `dbQuery(...)` /
+  // `dbExec(...)`. Lazy: the DbClient is constructed at first use, not at
+  // startup. Format examples:
   //   postgresql://user:pass@host:5432/dbname
   //   mysql://user:pass@host:3306/dbname
   //   sqlite:./e2e.db
   //   sqlite::memory:
-  DATABASE_URL: z.string().min(1),
-  SIM_A_NAME: z.string().min(1),
-  SIM_B_NAME: z.string().min(1),
+  DATABASE_URL: z.string().min(1).optional(),
+  // SIM_A_NAME / SIM_B_NAME — schema-optional so non-UI commands work
+  // without them. Pool-aware validation in loadEnv() below requires the
+  // names for slots actually present in SIM_POOL.
+  SIM_A_NAME: z.string().min(1).optional(),
+  SIM_B_NAME: z.string().min(1).optional(),
   SIM_POOL: z.string().default("A,B"),
-  METRO_URL: z.string().url(),
+  // METRO_URL — only consumed by the (currently unimplemented) Expo
+  // dev-client recovery flow. Optional; reserved for future use.
+  METRO_URL: z.string().url().optional(),
   // Expo dev-client builds show a "Development Servers" launcher after a clean
-  // launch (clearState wipes the remembered Metro URL). When true, the driver
-  // auto-opens `exp+<APP_URL_SCHEME>://expo-development-client/?url=<METRO_URL>`
-  // after `app_launch clean: true` to bypass the launcher.
+  // launch. When true, the driver auto-opens
+  // `exp+<APP_URL_SCHEME>://expo-development-client/?url=<METRO_URL>` after
+  // `app_launch clean: true` to bypass the launcher. (Flow not yet wired.)
   EXPO_DEV_CLIENT: z.string().optional().transform((v) => v === "true" || v === "1"),
-  SESSION_LOG_PATH: z.string().default("sessions/current.jsonl"),
-  ARTIFACTS_DIR: z.string().default("artifacts"),
+  SESSION_LOG_PATH: z.string().default("unotest/sessions/current.jsonl"),
+  // Explicit kill-switch for session recording. When "1"/"true", or when
+  // SESSION_LOG_PATH is empty, buildApp wires a NoopSessionRecorder. Used
+  // by evals harness and any consumer that wants the MCP server to make
+  // no on-disk session log.
+  SESSION_LOG_DISABLE: z.string().optional().transform((v) => v === "1" || v === "true"),
+  // When true, recorder writes the FULL tool result alongside the
+  // truncated preview. Off by default — snapshots can be megabytes.
+  SESSION_LOG_FULL: z.string().optional().transform((v) => v === "1" || v === "true"),
+  ARTIFACTS_DIR: z.string().default("unotest/artifacts"),
+  // Where ExplorationService persists per-session JSONL recording logs.
+  // Default: <ARTIFACTS_DIR>/explorations. Folded into the gitignored
+  // `unotest/artifacts/` tree by the init template.
+  EXPLORATIONS_DIR: z.string().optional(),
   // WDA per-slot port mapping (D-13 parallel multi-device). Stored as a
   // comma-separated `slot=port` list, e.g. "A=8100,B=8101". Each slot present
   // in SIM_POOL needs a port.
@@ -231,7 +263,7 @@ ${issues}`
     const value = process.env[key];
     if (!value) {
       throw new Error(
-        `SIM_POOL lists slot "${slot}" but ${key} is not set in unotest/.env`
+        `SIM_POOL lists slot "${slot}" but ${key} is not set in unotest/.env. Either add ${key}=<simulator-name> or shrink SIM_POOL to omit slot "${slot}".`
       );
     }
     simBySlot[slot] = value;
@@ -262,7 +294,8 @@ ${issues}`
     wdaPortBySlot,
     defaultActionWaitMs: raw.WDA_DEFAULT_ACTION_WAIT_MS,
     defaultWaitForTimeoutMs: raw.WDA_DEFAULT_WAITFOR_TIMEOUT_MS,
-    pausedRuntimeTtlMs: raw.PAUSED_RUNTIME_TTL_MS
+    pausedRuntimeTtlMs: raw.PAUSED_RUNTIME_TTL_MS,
+    explorationsDir: raw.EXPLORATIONS_DIR ?? `${raw.ARTIFACTS_DIR}/explorations`
   };
   return cached;
 }
@@ -401,27 +434,84 @@ async function listSimulators() {
   return out;
 }
 __name(listSimulators, "listSimulators");
-async function resolveSimByName(name) {
+function friendlyRuntime(runtime) {
+  const m = runtime.match(/SimRuntime\.([A-Za-z]+)-(\d+)-(\d+)$/);
+  if (!m) return runtime;
+  return `${m[1]} ${m[2]}.${m[3]}`;
+}
+__name(friendlyRuntime, "friendlyRuntime");
+async function resolveSimByName(spec) {
+  const { name, runtimeHint } = parseSimSpec(spec);
   const all = await listSimulators();
-  const matches = all.filter((s) => s.name === name);
+  let matches = all.filter((s) => s.name === name);
+  if (runtimeHint) {
+    matches = matches.filter((s) => friendlyRuntime(s.runtime).toLowerCase().includes(runtimeHint.toLowerCase()));
+  }
   if (matches.length === 0) {
-    const available = all.map((s) => s.name).join(", ") || "(none)";
-    throw new Error(`Sim "${name}" not found. Available: ${available}`);
+    const available = all.map((s) => `${s.name} @ ${friendlyRuntime(s.runtime)}`).join(", ") || "(none)";
+    throw new Error(
+      `Sim "${spec}" not found. Available: ${available}. If you have multiple sims with the same name, disambiguate via "<name> @ <runtime>" (e.g. "iPhone 16 @ iOS 17.5").`
+    );
   }
   const booted = matches.find((s) => s.state === "Booted");
   return booted ?? matches[0];
 }
 __name(resolveSimByName, "resolveSimByName");
+function parseSimSpec(spec) {
+  const idx = spec.lastIndexOf("@");
+  if (idx === -1) return { name: spec.trim() };
+  return {
+    name: spec.slice(0, idx).trim(),
+    runtimeHint: spec.slice(idx + 1).trim()
+  };
+}
+__name(parseSimSpec, "parseSimSpec");
 async function bootSim(udid) {
   try {
     await exec2("xcrun", ["simctl", "boot", udid]);
+    if (process.env.SIMCTL_HEADLESS !== "1") await openSimulatorApp();
+    return;
   } catch (e) {
     const msg = e.stderr ?? String(e);
-    if (msg.includes("Booted") || msg.includes("current state: Booted")) return;
-    throw e;
+    if (msg.includes("Booted") || msg.includes("current state: Booted")) {
+      if (process.env.SIMCTL_HEADLESS !== "1") await openSimulatorApp();
+      return;
+    }
+    const state = await currentSimState(udid).catch(() => null);
+    if (state === "Booted") {
+      if (process.env.SIMCTL_HEADLESS !== "1") await openSimulatorApp();
+      return;
+    }
+    if (state && state !== "Shutdown") {
+      throw new Error(
+        `simctl boot ${udid} failed and sim is in transitional state "${state}". Wait a few seconds and retry, or force-shutdown: \`xcrun simctl shutdown ${udid}\`.
+Original error: ${msg.trim().split("\n").slice(0, 4).join(" | ")}`
+      );
+    }
+    throw new Error(
+      `simctl boot ${udid} failed. Sim is "${state ?? "unknown"}".
+Common fixes:
+  \u2022 Open Simulator.app, pick this device manually, ensure it boots.
+  \u2022 Erase: \`xcrun simctl erase ${udid}\` (wipes content & settings).
+  \u2022 Restart CoreSimulator: \`sudo killall -9 com.apple.CoreSimulator.CoreSimulatorService\`.
+Original error: ${msg.trim().split("\n").slice(0, 4).join(" | ")}`
+    );
   }
 }
 __name(bootSim, "bootSim");
+async function currentSimState(udid) {
+  const sims = await listSimulators();
+  const sim = sims.find((s) => s.udid === udid);
+  return sim ? sim.state : null;
+}
+__name(currentSimState, "currentSimState");
+async function openSimulatorApp() {
+  try {
+    await exec2("open", ["-a", "Simulator"]);
+  } catch {
+  }
+}
+__name(openSimulatorApp, "openSimulatorApp");
 async function shutdownSim(udid) {
   try {
     await exec2("xcrun", ["simctl", "shutdown", udid]);
@@ -449,9 +539,37 @@ async function terminateApp(udid, bundleId) {
 }
 __name(terminateApp, "terminateApp");
 async function launchApp(udid, bundleId, args = []) {
-  await exec2("xcrun", ["simctl", "launch", udid, bundleId, ...args]);
+  const { stdout } = await exec2("xcrun", ["simctl", "launch", udid, bundleId, ...args]);
+  const m = stdout.match(/:\s*(\d+)/);
+  const pid = m ? Number.parseInt(m[1], 10) : 0;
+  return { pid };
 }
 __name(launchApp, "launchApp");
+async function isPidAlive(pid) {
+  if (pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+__name(isPidAlive, "isPidAlive");
+async function assertLaunchedAndStable(udid, bundleId, pid, options = {}) {
+  const settleMs = options.settleMs ?? 1500;
+  await new Promise((r) => setTimeout(r, settleMs));
+  const alive = await isPidAlive(pid);
+  if (alive) return;
+  const procName = bundleId.split(".").pop() ?? bundleId;
+  throw new Error(
+    `App "${bundleId}" started (PID ${pid}) but exited within ${settleMs}ms \u2014 looks like a crash on launch.
+See the crash reason:
+  xcrun simctl spawn ${udid} log show --predicate 'process == "${procName}" OR senderImagePath CONTAINS "${bundleId}"' --last 30s --info
+Or open Console.app, filter by your app name.
+Common causes: missing native module (rebuild after changing native deps), JS bundle baked against wrong workspace/env, signing issues.`
+  );
+}
+__name(assertLaunchedAndStable, "assertLaunchedAndStable");
 async function uninstallApp(udid, bundleId) {
   try {
     await exec2("xcrun", ["simctl", "uninstall", udid, bundleId]);
@@ -463,6 +581,63 @@ async function installApp(udid, appPath) {
   await exec2("xcrun", ["simctl", "install", udid, appPath]);
 }
 __name(installApp, "installApp");
+async function isAppInstalled(udid, bundleId) {
+  try {
+    await exec2("xcrun", ["simctl", "get_app_container", udid, bundleId]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+__name(isAppInstalled, "isAppInstalled");
+async function eraseSim(udid) {
+  await exec2("xcrun", ["simctl", "erase", udid]);
+}
+__name(eraseSim, "eraseSim");
+async function keychainResetSim(udid) {
+  await exec2("xcrun", ["simctl", "keychain", udid, "reset"]);
+}
+__name(keychainResetSim, "keychainResetSim");
+async function privacyGrantSim(udid, service, bundleId) {
+  await exec2("xcrun", ["simctl", "privacy", udid, "grant", service, bundleId]);
+}
+__name(privacyGrantSim, "privacyGrantSim");
+async function pinEnglishKeyboardSim(udid) {
+  await exec2("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "-g",
+    "AppleKeyboards",
+    "-array",
+    "en_US@hw=US;sw=QWERTY"
+  ]);
+  await exec2("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "-g",
+    "AppleLanguages",
+    "-array",
+    "en"
+  ]);
+  await exec2("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "-g",
+    "AppleLocale",
+    "-string",
+    "en_US"
+  ]);
+}
+__name(pinEnglishKeyboardSim, "pinEnglishKeyboardSim");
 
 // src/driver/simctl/adapter.ts
 var SimctlAdapter = class {
@@ -487,6 +662,9 @@ var SimctlAdapter = class {
   async launch(udid, bundleId, args) {
     return launchApp(udid, bundleId, args);
   }
+  async assertLaunchedAndStable(udid, bundleId, pid, settleMs) {
+    return assertLaunchedAndStable(udid, bundleId, pid, settleMs !== void 0 ? { settleMs } : {});
+  }
   async terminate(udid, bundleId) {
     return terminateApp(udid, bundleId);
   }
@@ -496,12 +674,51 @@ var SimctlAdapter = class {
   async screenshot(udid) {
     return screenshotPng(udid);
   }
+  async isInstalled(udid, bundleId) {
+    return isAppInstalled(udid, bundleId);
+  }
+  async erase(udid) {
+    return eraseSim(udid);
+  }
+  /** B5 — wipes simulator keychain so auth tokens don't survive `clean`
+   *  launches. Used by `installApp({clean})` and `WdaDriver.appLaunch({clean})`. */
+  async keychainReset(udid) {
+    return keychainResetSim(udid);
+  }
+  /** S4 — pre-grant an iOS privacy service to a bundle so the app skips
+   *  the SpringBoard permission dialog on first launch. */
+  async privacyGrant(udid, service, bundleId) {
+    return privacyGrantSim(udid, service, bundleId);
+  }
+  /** S8 — pin the sim's keyboard to en_US@QWERTY so WDA's typeText
+   *  doesn't drop Latin chars when the sim was last on a Cyrillic layout. */
+  async pinEnglishKeyboard(udid) {
+    return pinEnglishKeyboardSim(udid);
+  }
+  async openSimulatorApp() {
+    return openSimulatorApp();
+  }
 };
 
-// src/driver/wda/session.ts
-import { setTimeout as delay } from "timers/promises";
-
 // src/driver/wda/http-client.ts
+var NoAlertPresentError = class extends Error {
+  static {
+    __name(this, "NoAlertPresentError");
+  }
+  constructor(message) {
+    super(message);
+    this.name = "NoAlertPresentError";
+  }
+};
+var WdaSessionGoneError = class extends Error {
+  static {
+    __name(this, "WdaSessionGoneError");
+  }
+  constructor(message) {
+    super(message);
+    this.name = "WdaSessionGoneError";
+  }
+};
 var WdaHttpClient = class {
   static {
     __name(this, "WdaHttpClient");
@@ -578,6 +795,39 @@ var WdaHttpClient = class {
   async openUrl(sessionId, url) {
     await this.post(`/session/${encodeURIComponent(sessionId)}/url`, { url });
   }
+  // ---- Alerts (native SpringBoard) ---------------------------------------
+  //
+  // These hit WDA's /alert/* endpoints which talk to the *system* alert
+  // hierarchy (SpringBoard process), NOT the app's a11y tree. Use for
+  // UIAlertController-backed dialogs: permission prompts, ATT, Sign Out
+  // confirms, iOS update banners. App-level Modals belong to regular tap.
+  //
+  // `name` in WdaAcceptAlertRequest taps a specific button by label.
+  // Omitted = WDA's position-based fallback, which is kind-dependent (see
+  // FBAlert.m): UIAlertController accept = LAST button, dismiss = FIRST;
+  // action sheet is reversed. Pass `name` whenever the alert isn't a plain
+  // 1-button modal — it's the only label-stable path.
+  async acceptAlert(sessionId, req = {}) {
+    await mapNoAlert(
+      this.post(
+        `/session/${encodeURIComponent(sessionId)}/alert/accept`,
+        req.name ? { name: req.name } : {}
+      )
+    );
+  }
+  async dismissAlert(sessionId) {
+    await mapNoAlert(this.post(`/session/${encodeURIComponent(sessionId)}/alert/dismiss`, {}));
+  }
+  async alertText(sessionId) {
+    return mapNoAlert(
+      this.get(`/session/${encodeURIComponent(sessionId)}/alert/text`)
+    );
+  }
+  async alertButtons(sessionId) {
+    return mapNoAlert(
+      this.get(`/session/${encodeURIComponent(sessionId)}/alert/buttons`)
+    );
+  }
   // ---- internals ---------------------------------------------------------
   async get(path) {
     return this.request("GET", path);
@@ -597,12 +847,32 @@ var WdaHttpClient = class {
     const resp = await this.fetchFn(`${this.baseUrl}${path}`, init);
     if (!resp.ok) {
       const text = await resp.text().catch(() => "<no body>");
-      throw new Error(`WDA ${method} ${path} failed: HTTP ${resp.status} \u2014 ${text.slice(0, 500)}`);
+      const snippet = text.slice(0, 500);
+      if (resp.status === 404 && /no such session|could not find session|invalid session id/i.test(snippet)) {
+        throw new WdaSessionGoneError(
+          `WDA ${method} ${path} reports session is gone: ${snippet}`
+        );
+      }
+      throw new Error(`WDA ${method} ${path} failed: HTTP ${resp.status} \u2014 ${snippet}`);
     }
     if (resp.status === 204) return void 0;
     return await resp.json();
   }
 };
+async function mapNoAlert(p) {
+  try {
+    return await p;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/HTTP 404/.test(msg) && /alert/i.test(msg)) {
+      throw new NoAlertPresentError(
+        `No active iOS alert on this device. WDA: ${msg.slice(msg.indexOf("HTTP"))}`
+      );
+    }
+    throw err;
+  }
+}
+__name(mapNoAlert, "mapNoAlert");
 function extractElementId(h) {
   const id = h["element-6066-11e4-a52e-4f735466cecf"] ?? h.ELEMENT;
   if (!id) {
@@ -612,6 +882,9 @@ function extractElementId(h) {
 }
 __name(extractElementId, "extractElementId");
 
+// src/driver/wda/session.ts
+import { setTimeout as delay } from "timers/promises";
+
 // src/driver/wda/probe.ts
 async function tryProbeWda(port, timeoutMs, fetchFn = (input, init) => fetch(input, init)) {
   const ctrl = new AbortController();
@@ -687,13 +960,13 @@ var WdaRunner = class {
   async stop() {
     if (!this.child) return;
     const child = this.child;
-    return new Promise((resolve4) => {
-      child.once("exit", () => resolve4());
+    return new Promise((resolve6) => {
+      child.once("exit", () => resolve6());
       try {
         child.kill("SIGTERM");
       } catch (e) {
         this.logger.warn(`WdaRunner.stop: kill SIGTERM failed: ${e.message}`);
-        resolve4();
+        resolve6();
       }
       setTimeout(() => {
         if (this.child) {
@@ -750,6 +1023,7 @@ var WdaSession = class {
       });
       this.sessionId = created.sessionId ?? created.value.sessionId;
       this.deps.logger.debug(`wda session started: ${this.deps.slot} (${this.sessionId})`);
+      await this.warmupTree();
     } catch (e) {
       if (this.runnerHandle) {
         try {
@@ -784,6 +1058,45 @@ var WdaSession = class {
       }
     }
   }
+  /**
+   * Warm up the accessibility tree after a fresh session by polling
+   * `/source` until two consecutive readings agree on node count. iOS
+   * XCTest's a11y discovery is asynchronous: the first `/source` after
+   * createSession can return a partial tree (often only the application
+   * root) for ~150-300ms while attributes are still being populated. A
+   * caller's first `a11yTree()` would then see that partial state and
+   * the agent acts on a half-built screen. Caps at 4 attempts so a
+   * truly animating screen (rare at start time) doesn't hang the boot.
+   */
+  async warmupTree() {
+    if (this.deps.skipWarmup) return;
+    const delayMs = this.deps.warmupDelayMs ?? 150;
+    let prevCount = -1;
+    for (let i = 0; i < 4; i++) {
+      let count = 0;
+      try {
+        const resp = await this.client.source(this.sessionId);
+        count = countWdaSource(resp.value);
+      } catch (e) {
+        this.deps.logger.warn(
+          `WdaSession[${this.deps.slot}] warmup /source attempt ${i + 1} failed: ${e.message}`
+        );
+      }
+      if (i > 0 && count > 0 && count === prevCount) {
+        this.deps.logger.debug(
+          `WdaSession[${this.deps.slot}] warmup settled at attempt ${i + 1} (${count} nodes)`
+        );
+        return;
+      }
+      prevCount = count;
+      if (i < 3 && delayMs > 0) {
+        await new Promise((r) => setTimeout(r, delayMs));
+      }
+    }
+    this.deps.logger.warn(
+      `WdaSession[${this.deps.slot}] warmup did not settle in 4 attempts \u2014 proceeding with possibly-partial tree`
+    );
+  }
   async waitUntilReady(timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     let lastErr;
@@ -801,6 +1114,13 @@ var WdaSession = class {
     );
   }
 };
+function countWdaSource(n) {
+  if (!n || typeof n !== "object") return 0;
+  let total = 1;
+  for (const c of n.children ?? []) total += countWdaSource(c);
+  return total;
+}
+__name(countWdaSource, "countWdaSource");
 async function defaultStartWdaRunner(handle, port, binaryProvider, simctl, logger) {
   const probe = await tryProbeWda(port, 1500);
   if (probe?.ready) {
@@ -835,7 +1155,7 @@ function mapNode(raw) {
   if (name) out.testId = name;
   if (text) out.text = text;
   if (labelOut) out.label = labelOut;
-  if (raw.type) out.role = raw.type;
+  if (raw.type) out.role = shortRole(raw.type);
   const bounds = parseRect(raw.rect);
   if (bounds) out.bounds = bounds;
   const enabled = parseBool(raw.isEnabled);
@@ -845,6 +1165,11 @@ function mapNode(raw) {
   return out;
 }
 __name(mapNode, "mapNode");
+function shortRole(t) {
+  if (!t) return void 0;
+  return t.replace(/^XCUIElementType/, "").toLowerCase();
+}
+__name(shortRole, "shortRole");
 function nonEmpty(s) {
   if (s == null) return void 0;
   const trimmed = s.trim();
@@ -917,10 +1242,24 @@ var WdaDriver = class _WdaDriver {
   async appLaunch(slot, opts) {
     const h = await this.boot(slot);
     const bundleId = opts.bundleId ?? this.deps.appBundleId;
+    if (!bundleId) {
+      throw new Error(
+        `appLaunch needs a bundle id \u2014 set APP_BUNDLE_ID in unotest/.env or pass it explicitly.`
+      );
+    }
+    const installed = await this.simctl.isInstalled(h.udid, bundleId);
+    if (!installed) {
+      throw new Error(
+        `App "${bundleId}" is not installed on ${h.name} (slot ${slot}).
+Install it first: \`npx unotest-mobile install <path-to-.app>\` (or set APP_PATH in unotest/.env and run \`unotest-mobile install\`).`
+      );
+    }
     if (opts.clean) {
       await this.simctl.terminate(h.udid, bundleId);
+      await this.simctl.keychainReset(h.udid);
     }
-    await this.simctl.launch(h.udid, bundleId);
+    const { pid } = await this.simctl.launch(h.udid, bundleId);
+    await this.simctl.assertLaunchedAndStable(h.udid, bundleId, pid);
   }
   async openDeeplink(slot, url) {
     const h = await this.boot(slot);
@@ -928,53 +1267,59 @@ var WdaDriver = class _WdaDriver {
   }
   // ---- UiDriver ----------------------------------------------------------
   async tap(slot, selector) {
-    const session = await this.getSession(slot);
-    const bounds = await this.resolveBounds(slot, selector);
-    const { cx, cy } = center(bounds);
-    await session.client.tap(session.getSessionId(), { x: cx, y: cy });
+    await this.withFreshSession(slot, async (session) => {
+      const bounds = await this.resolveBounds(slot, selector);
+      const { cx, cy } = center(bounds);
+      await session.client.tap(session.getSessionId(), { x: cx, y: cy });
+    });
   }
   async type(slot, selector, text) {
-    const session = await this.getSession(slot);
-    const elementId = await this.resolveElementId(slot, selector);
-    await session.client.setElementValue(session.getSessionId(), elementId, {
-      value: Array.from(text)
+    await this.withFreshSession(slot, async (session) => {
+      const elementId = await this.resolveElementId(slot, selector);
+      await session.client.setElementValue(session.getSessionId(), elementId, {
+        value: Array.from(text)
+      });
     });
   }
   async swipe(slot, direction, from) {
-    const session = await this.getSession(slot);
-    const size = await session.client.windowSize(session.getSessionId());
-    const w = size.value.width;
-    const h = size.value.height;
-    let fromX, fromY;
-    if (from) {
-      const b = await this.resolveBounds(slot, from);
-      const c = center(b);
-      fromX = c.cx;
-      fromY = c.cy;
-    } else {
-      fromX = w / 2;
-      fromY = h / 2;
-    }
-    const dist2 = Math.min(w, h) * 0.4;
-    const toX = direction === "left" ? fromX - dist2 : direction === "right" ? fromX + dist2 : fromX;
-    const toY = direction === "up" ? fromY - dist2 : direction === "down" ? fromY + dist2 : fromY;
-    await session.client.drag(session.getSessionId(), { fromX, fromY, toX, toY, duration: 0.3 });
+    await this.withFreshSession(slot, async (session) => {
+      const size = await session.client.windowSize(session.getSessionId());
+      const w = size.value.width;
+      const h = size.value.height;
+      let fromX, fromY;
+      if (from) {
+        const b = await this.resolveBounds(slot, from);
+        const c = center(b);
+        fromX = c.cx;
+        fromY = c.cy;
+      } else {
+        fromX = w / 2;
+        fromY = h / 2;
+      }
+      const dist2 = Math.min(w, h) * 0.4;
+      const toX = direction === "left" ? fromX - dist2 : direction === "right" ? fromX + dist2 : fromX;
+      const toY = direction === "up" ? fromY - dist2 : direction === "down" ? fromY + dist2 : fromY;
+      await session.client.drag(session.getSessionId(), { fromX, fromY, toX, toY, duration: 0.3 });
+    });
   }
   async pressKey(slot, key) {
     const session = await this.getSession(slot);
-    if (key === "home") {
-      await session.client.pressKey(session.getSessionId(), "home");
-      return;
-    }
-    if (key === "enter") {
-      await session.client.typeText(session.getSessionId(), { value: ["\n"] });
-      return;
-    }
-    if (key === "escape") {
-      await session.client.typeText(session.getSessionId(), { value: ["\x1B"] });
-      return;
+    if (key !== "home" && key !== "enter" && key !== "escape") {
+      throw new Error(
+        "pressKey('back') is not supported on iOS - use swipe-back or app-specific control"
+      );
     }
-    throw new Error(`pressKey('back') is not supported on iOS \u2014 use swipe-back or app-specific control`);
+    await this.withFreshSession(slot, async (session2) => {
+      if (key === "home") {
+        await session2.client.pressKey(session2.getSessionId(), "home");
+        return;
+      }
+      if (key === "enter") {
+        await session2.client.typeText(session2.getSessionId(), { value: ["\n"] });
+        return;
+      }
+      await session2.client.typeText(session2.getSessionId(), { value: [""] });
+    });
   }
   async waitFor(slot, selector, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 1e4;
@@ -990,13 +1335,64 @@ var WdaDriver = class _WdaDriver {
   }
   // ---- InspectionDriver --------------------------------------------------
   async screenshot(slot) {
-    const session = await this.getSession(slot);
-    return session.client.screenshot(session.getSessionId());
+    return this.withFreshSession(
+      slot,
+      (session) => session.client.screenshot(session.getSessionId())
+    );
   }
   async a11yTree(slot, _opts = {}) {
-    const session = await this.getSession(slot);
-    const resp = await session.client.source(session.getSessionId());
-    return parseWdaSource(resp.value);
+    return this.withFreshSession(slot, async (session) => {
+      const resp = await session.client.source(session.getSessionId());
+      return parseWdaSource(resp.value);
+    });
+  }
+  async windowSize(slot) {
+    return this.withFreshSession(slot, async (session) => {
+      const size = await session.client.windowSize(session.getSessionId());
+      return { width: size.value.width, height: size.value.height };
+    });
+  }
+  // ---- AlertController ---------------------------------------------------
+  //
+  // Native UIAlertController dialogs live in SpringBoard, outside the app's
+  // a11y tree. Resolver-driven `tap()` cannot reach them: even when a
+  // selector "matches" by ordinal, the actions API targets app-process
+  // coordinates and the SpringBoard alert stays put. WDA's /alert/*
+  // endpoints know to talk to the active system alert.
+  async acceptAlert(slot, button) {
+    await this.withFreshSession(slot, async (session) => {
+      await session.client.acceptAlert(
+        session.getSessionId(),
+        button !== void 0 ? { name: button } : {}
+      );
+    });
+  }
+  async dismissAlert(slot) {
+    await this.withFreshSession(
+      slot,
+      (session) => session.client.dismissAlert(session.getSessionId())
+    );
+  }
+  async readAlert(slot) {
+    return this.withFreshSession(slot, async (session) => {
+      const resp = await session.client.alertText(session.getSessionId());
+      return { text: resp.value };
+    });
+  }
+  // `null` on no-alert keeps the A11yTreeTool probe branch-free; the
+  // outline pipeline only renders the `alert:` section when readAlert
+  // succeeded first, so a second NoAlertPresentError here would be a
+  // SpringBoard race anyway — quieter to drop than throw.
+  async readAlertButtons(slot) {
+    return this.withFreshSession(slot, async (session) => {
+      try {
+        const resp = await session.client.alertButtons(session.getSessionId());
+        return resp.value;
+      } catch (e) {
+        if (e instanceof NoAlertPresentError) return null;
+        throw e;
+      }
+    });
   }
   // ---- ContextController stub (D-9) --------------------------------------
   async listContexts(_slot) {
@@ -1011,6 +1407,42 @@ var WdaDriver = class _WdaDriver {
     return _WdaDriver.NATIVE_CONTEXT;
   }
   // ---- internals ---------------------------------------------------------
+  /**
+   * B6 — run `fn` against the cached session for `slot`. If WDA reports
+   * the session is gone (sim erase / app crash / runner killed) we
+   * silently drop the dead session, create a fresh one, and retry the
+   * call ONCE. Persistent failures bubble up to the caller as usual.
+   *
+   * Why ONCE: a single retry covers the "stale handle in cache" case
+   * (the common one — `--erase` between an MCP eval setup and the first
+   * tool call, runner restart, etc). If a second attempt also dies, the
+   * underlying WDA is genuinely broken and a retry loop would just
+   * waste 10+ seconds per call before the harness times out.
+   *
+   * Pre-existing `getSession` flow stays unchanged for ad-hoc internal
+   * calls (resolveBounds / resolveElementId) — those use the cached
+   * session directly and ride the retry of their outer caller.
+   */
+  async withFreshSession(slot, fn) {
+    const session = await this.getSession(slot);
+    try {
+      return await fn(session);
+    } catch (e) {
+      const isSessionGone = e instanceof WdaSessionGoneError || e instanceof Error && e.name === "WdaSessionGoneError";
+      if (!isSessionGone) throw e;
+      const msg = e instanceof Error ? e.message : String(e);
+      this.deps.logger.child(`wda:${slot}`).warn(
+        `WDA session ${session.getSessionId()} is gone (${msg.slice(0, 200)}); dropping cached session and retrying once.`
+      );
+      try {
+        await session.stop();
+      } catch {
+      }
+      this.sessions.delete(slot);
+      const fresh = await this.getSession(slot);
+      return fn(fresh);
+    }
+  }
   async getSession(slot) {
     const existing = this.sessions.get(slot);
     if (existing) return existing;
@@ -1021,6 +1453,23 @@ var WdaDriver = class _WdaDriver {
         `No WDA port configured for slot "${slot}". Set EnvConfig.wdaPortBySlot or add WDA_PORT_${slot} to .env.`
       );
     }
+    if (!this.deps.sessionFactory && !this.deps.appBundleId) {
+      throw new Error(
+        `WDA session needs APP_BUNDLE_ID \u2014 set it in unotest/.env. WebDriverAgent attaches to a specific app via the bundle id.`
+      );
+    }
+    if (!this.deps.sessionFactory && this.deps.appBundleId) {
+      const installed = await this.simctl.isInstalled(handle.udid, this.deps.appBundleId);
+      if (!installed) {
+        throw new Error(
+          `App "${this.deps.appBundleId}" is not installed on ${handle.name} (slot ${slot}).
+Install it first:
+  npx unotest-mobile install <path-to-.app>           # if you have the .app
+  npx unotest-mobile install                          # if APP_PATH is set in unotest/.env
+In an MCP session, call the \`app_install\` tool \u2014 it will read APP_PATH or ask you for the path.`
+        );
+      }
+    }
     const session = this.deps.sessionFactory ? this.deps.sessionFactory(slot, handle, port) : new WdaSession({
       slot,
       handle,
@@ -1490,59 +1939,74 @@ function dist(a, b) {
 __name(dist, "dist");
 
 // src/inspection/tree-inspector.ts
-var INTERACTIVE_ROLE_HINTS = [
+var INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
   "button",
   "textfield",
-  "securefield",
-  "secureinput",
-  "input",
-  "link",
+  "securetextfield",
   "switch",
+  "checkbox",
+  "link",
   "slider",
   "picker",
-  "checkbox",
   "tab",
   "menuitem"
-];
+]);
 function isInteractiveRole(role) {
-  if (!role) return false;
-  const r = role.toLowerCase();
-  return INTERACTIVE_ROLE_HINTS.some((hint) => r.includes(hint));
+  return role !== void 0 && INTERACTIVE_ROLES.has(role);
 }
 __name(isInteractiveRole, "isInteractiveRole");
 function isNoise(n) {
   return !n.testId && !n.text && !n.label && !isInteractiveRole(n.role);
 }
 __name(isNoise, "isNoise");
-function stripAttrs(n, children) {
-  const out = { children };
+function dedupeFields(n) {
+  const out = { children: n.children };
+  if (n.role) out.role = n.role;
   if (n.testId) out.testId = n.testId;
   if (n.text) out.text = n.text;
   if (n.label) out.label = n.label;
-  if (isInteractiveRole(n.role)) out.role = n.role;
-  return out;
-}
-__name(stripAttrs, "stripAttrs");
-function compactSubtree(n) {
-  let totalSeen = 1;
-  const newChildren = [];
-  for (const c of n.children) {
-    const r = compactSubtree(c);
-    totalSeen += r.totalSeen;
-    newChildren.push(...r.kept);
+  if (n.clipped) out.clipped = n.clipped;
+  if (out.text && out.label && out.text === out.label) {
+    delete out.label;
   }
-  if (isNoise(n)) {
-    return { totalSeen, kept: newChildren };
+  const interactive = isInteractiveRole(out.role);
+  if (out.testId && !interactive && (out.testId === out.text || out.testId === out.label)) {
+    delete out.testId;
   }
-  return { totalSeen, kept: [stripAttrs(n, newChildren)] };
+  return out;
 }
-__name(compactSubtree, "compactSubtree");
-function countNodes(n) {
-  let total = 1;
-  for (const c of n.children) total += countNodes(c);
-  return total;
+__name(dedupeFields, "dedupeFields");
+function classify(bounds, viewport) {
+  if (!bounds) return "on-screen";
+  const { x, y, width, height } = bounds;
+  const yMax = y + height;
+  const xMax = x + width;
+  if (yMax <= 0) return "top";
+  if (y >= viewport.height) return "bottom";
+  if (xMax <= 0) return "left";
+  if (x >= viewport.width) return "right";
+  if (y < 0) return "clipped:top";
+  if (yMax > viewport.height) return "clipped:bottom";
+  if (x < 0) return "clipped:left";
+  if (xMax > viewport.width) return "clipped:right";
+  return "on-screen";
 }
-__name(countNodes, "countNodes");
+__name(classify, "classify");
+function clippedSide(c) {
+  switch (c) {
+    case "clipped:top":
+      return "top";
+    case "clipped:bottom":
+      return "bottom";
+    case "clipped:left":
+      return "left";
+    case "clipped:right":
+      return "right";
+    default:
+      return void 0;
+  }
+}
+__name(clippedSide, "clippedSide");
 function collectTestIds(n, counts) {
   if (n.testId) counts.set(n.testId, (counts.get(n.testId) ?? 0) + 1);
   for (const c of n.children) collectTestIds(c, counts);
@@ -1557,45 +2021,102 @@ function applyIndex(n, counts, running) {
   for (const c of n.children) applyIndex(c, counts, running);
 }
 __name(applyIndex, "applyIndex");
-function indexDuplicates(tree) {
+function indexOnScreenDuplicates(nodes) {
   const counts = /* @__PURE__ */ new Map();
-  collectTestIds(tree, counts);
-  applyIndex(tree, counts, /* @__PURE__ */ new Map());
-  return tree;
+  for (const n of nodes) collectTestIds(n, counts);
+  const running = /* @__PURE__ */ new Map();
+  for (const n of nodes) applyIndex(n, counts, running);
+}
+__name(indexOnScreenDuplicates, "indexOnScreenDuplicates");
+function countSemanticNodes(nodes) {
+  let total = 0;
+  for (const n of nodes) {
+    total += 1;
+    total += countSemanticNodes(n.children);
+  }
+  return total;
+}
+__name(countSemanticNodes, "countSemanticNodes");
+function countOffScreen(off) {
+  return off.top.length + off.bottom.length + off.left.length + off.right.length;
+}
+__name(countOffScreen, "countOffScreen");
+function buildSemanticTree(raw, viewport) {
+  const onScreenRoots = [];
+  const offScreen = { top: [], bottom: [], left: [], right: [] };
+  let totalSeen = 0;
+  function makeKept(n, clipped) {
+    const base = { children: [] };
+    if (n.role) base.role = n.role;
+    if (n.testId) base.testId = n.testId;
+    if (n.text) base.text = n.text;
+    if (n.label) base.label = n.label;
+    if (clipped) base.clipped = clipped;
+    return dedupeFields(base);
+  }
+  __name(makeKept, "makeKept");
+  function makeOffScreen(n) {
+    const out = {};
+    if (n.role) out.role = n.role;
+    if (n.testId) out.testId = n.testId;
+    if (n.text) out.text = n.text;
+    if (n.label) out.label = n.label;
+    const deduped = dedupeFields({ ...out, children: [] });
+    const flat = {};
+    if (deduped.role) flat.role = deduped.role;
+    if (deduped.testId) flat.testId = deduped.testId;
+    if (deduped.text) flat.text = deduped.text;
+    if (deduped.label) flat.label = deduped.label;
+    return flat;
+  }
+  __name(makeOffScreen, "makeOffScreen");
+  function walk2(node, onScreenParent) {
+    totalSeen += 1;
+    const c = classify(node.bounds, viewport);
+    const onSide = c === "on-screen" || c.startsWith("clipped:");
+    if (onSide) {
+      if (isNoise(node)) {
+        for (const child of node.children) walk2(child, onScreenParent);
+        return;
+      }
+      const kept = makeKept(node, clippedSide(c));
+      if (onScreenParent) onScreenParent.children.push(kept);
+      else onScreenRoots.push(kept);
+      for (const child of node.children) walk2(child, kept);
+      return;
+    }
+    const side = c;
+    if (!isNoise(node)) {
+      offScreen[side].push(makeOffScreen(node));
+    }
+    for (const child of node.children) walk2(child, null);
+  }
+  __name(walk2, "walk");
+  walk2(raw, null);
+  indexOnScreenDuplicates(onScreenRoots);
+  return {
+    on_screen: onScreenRoots,
+    off_screen: offScreen,
+    _meta: {
+      totalNodes: totalSeen,
+      onScreen: countSemanticNodes(onScreenRoots),
+      offScreen: countOffScreen(offScreen),
+      viewport: { width: viewport.width, height: viewport.height }
+    }
+  };
 }
-__name(indexDuplicates, "indexDuplicates");
+__name(buildSemanticTree, "buildSemanticTree");
 var TreeInspector = class {
   static {
     __name(this, "TreeInspector");
   }
   /**
-   * D-16-aware compaction:
-   *   - drop wrappers with no identifying signal,
-   *   - strip layout-only attributes (bounds, enabled, focused, non-interactive role),
-   *   - keep text-only and label-only leaves,
-   *   - report `_meta` at the root.
-   */
-  compactTree(root) {
-    const result = compactSubtree(root);
-    const out = result.kept.length === 1 ? result.kept[0] : { children: result.kept };
-    const shown = countNodes(out);
-    out._meta = { totalNodes: result.totalSeen, shown, mode: "compact" };
-    return out;
-  }
-  /**
-   * Convenience: compact + index duplicates. The shape most MCP-tools want.
-   */
-  compactWithIds(root) {
-    return indexDuplicates(this.compactTree(root));
-  }
-  /**
-   * Annotate the raw tree as `full` (carries _meta for symmetry, no shape
-   * changes). Useful for MCP tools whose only choice is compact vs full.
+   * Partition a raw a11y tree against a viewport. The P1 entry — outline
+   * renderer (in `outline-renderer.ts`) consumes the returned
+   * `SemanticTree` directly.
    */
-  withMode(root, mode) {
-    if (mode === "compact") return this.compactWithIds(root);
-    const total = countNodes(root);
-    return { ...root, _meta: { totalNodes: total, shown: total, mode: "full" } };
+  semanticTree(raw, viewport) {
+    return buildSemanticTree(raw, viewport);
   }
   /**
    * DFS path from root to `target`, encoded as "child-index/child-index/...".
@@ -2867,6 +3388,10 @@ var AstExecutor = class {
       }
       return;
     }
+    if (stmt instanceof MetaBlockStatement) {
+      yield* this.execStatement(stmt.body, runtime, opts, getSteps, setSteps, runStartMs, userFns, callStack);
+      return;
+    }
     if (stmt instanceof ReturnStatement) {
       const expr = stmt.expression;
       const value = yield* this.evalExpression(expr, runtime, opts, getSteps, setSteps, runStartMs, userFns, callStack);
@@ -3278,6 +3803,11 @@ var DslLinter = class {
     if (!this.deps.registry.has(name) && !userFns.has(name)) {
       diags.push(diag("error", "E1", `Unknown DSL function "${name}"`, call));
     }
+    const fn = this.deps.registry.get(name);
+    if (fn) {
+      this.checkArity(call, fn, diags);
+      this.checkArgTypes(call, fn, diags);
+    }
     if (name === "setDevice" && call.arguments.length > 0) {
       const arg0 = call.arguments[0];
       if (arg0 instanceof ValueExpression) {
@@ -3313,6 +3843,77 @@ var DslLinter = class {
       this.checkExpression(arg, diags, recordCall, isFirstUiSeen, userFns, allowReturn);
     }
   }
+  checkArity(call, fn, diags) {
+    const max = fn.argTypes.length;
+    const min = fn.minArgs ?? max;
+    const got = call.arguments.length;
+    if (got < min) {
+      diags.push(
+        diag(
+          "error",
+          "E5",
+          `${fn.name}(): expected ${min === max ? `${min}` : `at least ${min}`} arg${min === 1 ? "" : "s"}, got ${got}`,
+          call
+        )
+      );
+      return;
+    }
+    if (!fn.variadic && got > max) {
+      diags.push(
+        diag(
+          "error",
+          "E5",
+          `${fn.name}(): expected at most ${max} arg${max === 1 ? "" : "s"}, got ${got}`,
+          call
+        )
+      );
+    }
+  }
+  /**
+   * For each provided arg up to argTypes.length, infer its static type and
+   * compare to the declared signature. Only emits E6 when the inferred type
+   * is UNAMBIGUOUS — we never flag "any" sources (variables, helper-call
+   * results, BinaryExpression, ArrayExpression).
+   */
+  checkArgTypes(call, fn, diags) {
+    const limit = Math.min(call.arguments.length, fn.argTypes.length);
+    for (let i = 0; i < limit; i++) {
+      const expected = fn.argTypes[i];
+      if (expected === "any") continue;
+      const inferred = this.inferExprType(call.arguments[i]);
+      if (inferred === "any") continue;
+      if (inferred === expected) continue;
+      if (expected === "boolean" && inferred === "number" || expected === "number" && inferred === "boolean") {
+        continue;
+      }
+      diags.push(
+        diag(
+          "error",
+          "E6",
+          `${fn.name}(): arg ${i} expected ${expected}, got ${describeInferred(call.arguments[i], inferred)}`,
+          call
+        )
+      );
+    }
+  }
+  /** Best-effort static type for an expression node. "any" = unknown. */
+  inferExprType(expr) {
+    if (expr instanceof ValueExpression) {
+      const v = expr.value;
+      if (v instanceof StringValue) return "string";
+      if (v instanceof NumberValue) return "number";
+      return "any";
+    }
+    if (expr instanceof VariableExpression) {
+      if (expr.name === "true" || expr.name === "false") return "boolean";
+      return "any";
+    }
+    if (expr instanceof FunctionalExpression) {
+      const callee = this.deps.registry.get(expr.name);
+      return callee ? callee.returnType : "any";
+    }
+    return "any";
+  }
   isForbiddenStatement(stmt) {
     return stmt instanceof ForStatement || stmt instanceof WhileStatement || stmt instanceof DoWhileStatement || stmt instanceof VarStatement || stmt instanceof PrintStatement || stmt instanceof BreakStatement || stmt instanceof ContinueStatement || stmt instanceof IncrementStatement || stmt instanceof ArrayAssignmentStatement;
   }
@@ -3324,6 +3925,19 @@ function isBlockMappable2(name) {
   return name.startsWith("test_") || name.startsWith("flow_");
 }
 __name(isBlockMappable2, "isBlockMappable");
+function describeInferred(expr, inferred) {
+  if (expr instanceof FunctionalExpression) {
+    return `${inferred} (${expr.name}() returns ${inferred})`;
+  }
+  if (expr instanceof ValueExpression) {
+    return `${inferred} literal`;
+  }
+  if (expr instanceof VariableExpression && (expr.name === "true" || expr.name === "false")) {
+    return `boolean literal \`${expr.name}\``;
+  }
+  return inferred;
+}
+__name(describeInferred, "describeInferred");
 function diag(severity, code, message, node) {
   const tok = node.token;
   return {
@@ -3359,6 +3973,41 @@ var FunctionRegistry = class {
   }
 };
 
+// src/dsl/functions/alerts.ts
+function asString(x, fn, idx) {
+  if (typeof x !== "string") throw new Error(`${fn}(): arg ${idx} must be a string. Got ${typeof x}.`);
+  return x;
+}
+__name(asString, "asString");
+var acceptAlert = {
+  name: "acceptAlert",
+  argTypes: ["string"],
+  returnType: "void",
+  minArgs: 0,
+  invoke: /* @__PURE__ */ __name(async (runtime, buttonArg) => {
+    const button = buttonArg !== void 0 ? asString(buttonArg, "acceptAlert", 0) : void 0;
+    await runtime.driver.acceptAlert(runtime.currentDeviceSlot, button);
+  }, "invoke")
+};
+var dismissAlert = {
+  name: "dismissAlert",
+  argTypes: [],
+  returnType: "void",
+  invoke: /* @__PURE__ */ __name(async (runtime) => {
+    await runtime.driver.dismissAlert(runtime.currentDeviceSlot);
+  }, "invoke")
+};
+var readAlert = {
+  name: "readAlert",
+  argTypes: [],
+  returnType: "string",
+  invoke: /* @__PURE__ */ __name(async (runtime) => {
+    const { text } = await runtime.driver.readAlert(runtime.currentDeviceSlot);
+    return text;
+  }, "invoke")
+};
+var ALERT_FUNCTIONS = [acceptAlert, dismissAlert, readAlert];
+
 // src/dsl/functions/asserts.ts
 function asSelector(x, fn, idx) {
   if (typeof x !== "object" || x === null) {
@@ -3474,11 +4123,11 @@ var ASSERT_FUNCTIONS = [
 ];
 
 // src/dsl/functions/data.ts
-function asString(x, fn, idx) {
+function asString2(x, fn, idx) {
   if (typeof x !== "string") throw new Error(`${fn}(): arg ${idx} must be a string. Got ${typeof x}.`);
   return x;
 }
-__name(asString, "asString");
+__name(asString2, "asString");
 function toSqlParam(v) {
   if (v === null || v === void 0) return null;
   if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
@@ -3489,8 +4138,9 @@ var dbQuery = {
   name: "dbQuery",
   argTypes: ["string"],
   returnType: "string",
+  variadic: true,
   invoke: /* @__PURE__ */ __name(async (runtime, sqlArg, ...rest) => {
-    const sql = asString(sqlArg, "dbQuery", 0);
+    const sql = asString2(sqlArg, "dbQuery", 0);
     const params = rest.map((a, i) => {
       try {
         return toSqlParam(a);
@@ -3511,8 +4161,9 @@ var dbExec = {
   name: "dbExec",
   argTypes: ["string"],
   returnType: "string",
+  variadic: true,
   invoke: /* @__PURE__ */ __name(async (runtime, sqlArg, ...rest) => {
-    const sql = asString(sqlArg, "dbExec", 0);
+    const sql = asString2(sqlArg, "dbExec", 0);
     const params = rest.map((a, i) => {
       try {
         return toSqlParam(a);
@@ -3534,8 +4185,9 @@ var shell = {
   name: "shell",
   argTypes: ["string"],
   returnType: "string",
+  variadic: true,
   invoke: /* @__PURE__ */ __name(async (runtime, cmdArg, ...rest) => {
-    const cmd = asString(cmdArg, "shell", 0);
+    const cmd = asString2(cmdArg, "shell", 0);
     const args = rest.map((a, i) => {
       if (a === null || a === void 0) return "";
       if (typeof a === "string") return a;
@@ -3553,14 +4205,14 @@ var apiCall = {
   returnType: "string",
   minArgs: 2,
   invoke: /* @__PURE__ */ __name(async (runtime, methodArg, pathArg, bodyArg) => {
-    const method = asString(methodArg, "apiCall", 0).toUpperCase();
-    const path = asString(pathArg, "apiCall", 1);
+    const method = asString2(methodArg, "apiCall", 0).toUpperCase();
+    const path = asString2(pathArg, "apiCall", 1);
     if (method !== "GET" && method !== "POST" && method !== "PUT" && method !== "PATCH" && method !== "DELETE") {
       throw new Error(`apiCall(): unsupported method "${method}"`);
     }
     let body;
     if (bodyArg !== void 0) {
-      const bodyJson = asString(bodyArg, "apiCall", 2);
+      const bodyJson = asString2(bodyArg, "apiCall", 2);
       try {
         body = JSON.parse(bodyJson);
       } catch (e) {
@@ -3580,11 +4232,11 @@ var apiCall = {
 var DATA_FUNCTIONS = [dbQuery, dbExec, apiCall, shell];
 
 // src/dsl/functions/device.ts
-function asString2(x, fn, idx) {
+function asString3(x, fn, idx) {
   if (typeof x !== "string") throw new Error(`${fn}(): arg ${idx} must be a string. Got ${typeof x}.`);
   return x;
 }
-__name(asString2, "asString");
+__name(asString3, "asString");
 function asBoolean(x, fn, idx) {
   if (typeof x !== "boolean") throw new Error(`${fn}(): arg ${idx} must be a boolean. Got ${typeof x}.`);
   return x;
@@ -3595,7 +4247,7 @@ var setDevice = {
   argTypes: ["string"],
   returnType: "void",
   invoke: /* @__PURE__ */ __name((runtime, slotArg) => {
-    const slot = asString2(slotArg, "setDevice", 0);
+    const slot = asString3(slotArg, "setDevice", 0);
     runtime.setCurrentDeviceSlot(slot);
   }, "invoke")
 };
@@ -3614,7 +4266,7 @@ var openDeeplink = {
   argTypes: ["string"],
   returnType: "void",
   invoke: /* @__PURE__ */ __name(async (runtime, urlArg) => {
-    const url = asString2(urlArg, "openDeeplink", 0);
+    const url = asString3(urlArg, "openDeeplink", 0);
     await runtime.driver.openDeeplink(runtime.currentDeviceSlot, url);
   }, "invoke")
 };
@@ -3736,11 +4388,11 @@ function asSelector2(x, fn, idx) {
   return x;
 }
 __name(asSelector2, "asSelector");
-function asString3(x, fn, idx) {
+function asString4(x, fn, idx) {
   if (typeof x !== "string") throw new Error(`${fn}(): arg ${idx} must be a string. Got ${typeof x}.`);
   return x;
 }
-__name(asString3, "asString");
+__name(asString4, "asString");
 function asNumber2(x, fn, idx) {
   if (typeof x !== "number") throw new Error(`${fn}(): arg ${idx} must be a number. Got ${typeof x}.`);
   return x;
@@ -3779,7 +4431,7 @@ var type_ = {
   returnType: "void",
   invoke: /* @__PURE__ */ __name(async (runtime, selectorArg, textArg) => {
     const selector = asSelector2(selectorArg, "type", 0);
-    const text = asString3(textArg, "type", 1);
+    const text = asString4(textArg, "type", 1);
     await pollUntilFound(runtime, selector, runtime.envConfig.defaultActionWaitMs);
     await runtime.driver.type(runtime.currentDeviceSlot, selector, text);
   }, "invoke")
@@ -3790,7 +4442,7 @@ var swipe = {
   returnType: "void",
   minArgs: 1,
   invoke: /* @__PURE__ */ __name(async (runtime, directionArg, fromArg) => {
-    const direction = asString3(directionArg, "swipe", 0);
+    const direction = asString4(directionArg, "swipe", 0);
     if (direction !== "up" && direction !== "down" && direction !== "left" && direction !== "right") {
       throw new Error(`swipe(): direction must be 'up'|'down'|'left'|'right'. Got "${direction}".`);
     }
@@ -3807,7 +4459,7 @@ var pressKey = {
   argTypes: ["string"],
   returnType: "void",
   invoke: /* @__PURE__ */ __name(async (runtime, keyArg) => {
-    const key = asString3(keyArg, "pressKey", 0);
+    const key = asString4(keyArg, "pressKey", 0);
     if (key !== "back" && key !== "home" && key !== "enter" && key !== "escape") {
       throw new Error(`pressKey(): key must be 'back'|'home'|'enter'|'escape'. Got "${key}".`);
     }
@@ -3841,6 +4493,7 @@ var ALL_DSL_FUNCTIONS = [
   ...DEVICE_FUNCTIONS,
   ...UI_FUNCTIONS,
   ...SELECTOR_FUNCTIONS,
+  ...ALERT_FUNCTIONS,
   ...DATA_FUNCTIONS,
   ...ASSERT_FUNCTIONS,
   ...TIME_FUNCTIONS
@@ -4021,9 +4674,9 @@ var TestRuntimeManager = class {
 };
 
 // src/runner/fs-scenario-repository.ts
-import { readFileSync as readFileSync2 } from "fs";
+import { readFileSync as readFileSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, writeFileSync } from "fs";
 import { readdir } from "fs/promises";
-import { resolve, join as join2, sep } from "path";
+import { dirname as dirname2, resolve, join as join2, sep } from "path";
 var FileSystemScenarioRepository = class {
   static {
     __name(this, "FileSystemScenarioRepository");
@@ -4051,14 +4704,29 @@ var FileSystemScenarioRepository = class {
     }
   }
   async load(name) {
-    if (name.includes("..") || name.startsWith("/") || name.includes("\\")) {
-      throw new Error(`Invalid scenario name "${name}"`);
-    }
-    const relPath = name.split("/").join(sep) + ".js";
-    const path = join2(this.scenariosDir, relPath);
+    const path = this.pathFor(name);
     const source = readFileSync2(path, "utf8");
     return { name, source };
   }
+  async has(name) {
+    return existsSync2(this.pathFor(name));
+  }
+  async save(name, source, opts) {
+    const path = this.pathFor(name);
+    if (existsSync2(path) && !opts?.overwrite) {
+      throw new Error(`scenario "${name}" already exists at ${path}`);
+    }
+    mkdirSync2(dirname2(path), { recursive: true });
+    writeFileSync(path, source);
+    return path;
+  }
+  pathFor(name) {
+    if (name.includes("..") || name.startsWith("/") || name.includes("\\")) {
+      throw new Error(`Invalid scenario name "${name}"`);
+    }
+    const relPath = name.split("/").join(sep) + ".js";
+    return join2(this.scenariosDir, relPath);
+  }
 };
 
 // vendor/dsl/parser/token.ts
@@ -4886,7 +5554,7 @@ __name(collectOrigins, "collectOrigins");
 
 // src/runner/helper-repository.ts
 import { readdir as readdir2, readFile } from "fs/promises";
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { join as join3, relative } from "path";
 var FileSystemHelperRepository = class {
   static {
@@ -4899,7 +5567,7 @@ var FileSystemHelperRepository = class {
     this.helpersDir = join3(deps.scenariosDir, "_helpers");
   }
   async loadAll() {
-    if (!existsSync2(this.helpersDir)) return [];
+    if (!existsSync3(this.helpersDir)) return [];
     const files = await collectJsFiles(this.helpersDir);
     const out = [];
     for (const absolutePath of files) {
@@ -4932,28 +5600,373 @@ async function collectJsFiles(dir) {
 __name(collectJsFiles, "collectJsFiles");
 
 // src/mcp/session-recorder.ts
-import { appendFileSync, mkdirSync as mkdirSync2, writeFileSync } from "fs";
-import { dirname as dirname2, resolve as resolve2 } from "path";
+import { appendFileSync, mkdirSync as mkdirSync3, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname3, resolve as resolve2 } from "path";
 var SessionRecorder = class {
   static {
     __name(this, "SessionRecorder");
   }
   path;
-  constructor(path) {
+  full;
+  constructor(path, opts = {}) {
     this.path = resolve2(process.cwd(), path);
-    mkdirSync2(dirname2(this.path), { recursive: true });
+    this.full = opts.full ?? false;
+    mkdirSync3(dirname3(this.path), { recursive: true });
   }
   record(action) {
-    const entry = { ts: (/* @__PURE__ */ new Date()).toISOString(), ...action };
+    const { full_result, ...rest } = action;
+    const entry = { ts: (/* @__PURE__ */ new Date()).toISOString(), ...rest };
+    if (this.full && full_result !== void 0) entry.full_result = full_result;
     appendFileSync(this.path, JSON.stringify(entry) + "\n");
   }
   reset() {
-    writeFileSync(this.path, "");
+    writeFileSync2(this.path, "");
   }
   getPath() {
     return this.path;
   }
 };
+var NoopSessionRecorder = class {
+  static {
+    __name(this, "NoopSessionRecorder");
+  }
+  record(_action) {
+  }
+  reset() {
+  }
+  getPath() {
+    return "(disabled)";
+  }
+};
+
+// src/mcp/exploration/exploration.service.ts
+import { mkdirSync as mkdirSync4, readdirSync as readdirSync2, readFileSync as readFileSync3, appendFileSync as appendFileSync2, statSync } from "fs";
+import { join as join4 } from "path";
+import { randomUUID } from "crypto";
+
+// src/mcp/exploration/stability.ts
+function classifyStability(selector) {
+  if (!selector) return "stable";
+  if (selector.testId) return "stable";
+  if (selector.label && selector.ordinal === void 0) return "stable";
+  if (selector.text && selector.ordinal === void 0) return "stable";
+  return "fragile";
+}
+__name(classifyStability, "classifyStability");
+
+// src/mcp/exploration/exploration.service.ts
+var ExplorationService = class {
+  static {
+    __name(this, "ExplorationService");
+  }
+  sessions = /* @__PURE__ */ new Map();
+  logs = /* @__PURE__ */ new Map();
+  dir;
+  clock;
+  generateId;
+  constructor(deps) {
+    this.dir = deps.explorationsDir;
+    this.clock = deps.clock ?? (() => /* @__PURE__ */ new Date());
+    this.generateId = deps.generateId ?? (() => randomUUID());
+    mkdirSync4(this.dir, { recursive: true });
+    this.restore();
+  }
+  startSession(params) {
+    const explorationId = `exp-${this.generateId()}`;
+    const actionLogId = `log-${this.generateId()}`;
+    const startedAt = this.clock().toISOString();
+    const session = {
+      explorationId,
+      scenarioName: params.scenarioName,
+      device: params.device,
+      status: "active",
+      startedAt,
+      actionLogId,
+      ...params.title !== void 0 ? { title: params.title } : {},
+      ...params.description !== void 0 ? { description: params.description } : {}
+    };
+    this.sessions.set(explorationId, session);
+    this.logs.set(actionLogId, { logId: actionLogId, createdAt: startedAt, entries: [] });
+    this.append(explorationId, { kind: "session_started", session });
+    return session;
+  }
+  getSession(explorationId) {
+    return this.sessions.get(explorationId);
+  }
+  getLog(explorationId) {
+    const s = this.sessions.get(explorationId);
+    return s ? this.logs.get(s.actionLogId) : void 0;
+  }
+  addEntry(explorationId, params) {
+    const session = this.requireActive(explorationId);
+    const log = this.logs.get(session.actionLogId);
+    const entry = {
+      entryId: `e-${this.generateId()}`,
+      performedAt: this.clock().toISOString(),
+      action: params.action,
+      device: params.device,
+      description: params.description,
+      section: params.section,
+      stability: classifyStability(params.selector),
+      ...params.selector !== void 0 ? { selector: params.selector } : {},
+      ...params.value !== void 0 ? { value: params.value } : {},
+      ...params.key !== void 0 ? { key: params.key } : {},
+      ...params.direction !== void 0 ? { direction: params.direction } : {},
+      ...params.from !== void 0 ? { from: params.from } : {},
+      ...params.url !== void 0 ? { url: params.url } : {},
+      ...params.bundleId !== void 0 ? { bundleId: params.bundleId } : {},
+      ...params.clean !== void 0 ? { clean: params.clean } : {},
+      ...params.timeoutMs !== void 0 ? { timeoutMs: params.timeoutMs } : {},
+      ...params.optional !== void 0 ? { optional: params.optional } : {},
+      ...params.button !== void 0 ? { button: params.button } : {}
+    };
+    log.entries.push(entry);
+    this.append(explorationId, { kind: "entry_added", entry });
+    return entry;
+  }
+  removeEntry(explorationId, entryId) {
+    const session = this.requireKnown(explorationId);
+    const log = this.logs.get(session.actionLogId);
+    const idx = log.entries.findIndex((e) => e.entryId === entryId);
+    if (idx < 0) return false;
+    log.entries.splice(idx, 1);
+    this.append(explorationId, { kind: "entry_removed", entryId });
+    return true;
+  }
+  stopSession(explorationId) {
+    const session = this.requireKnown(explorationId);
+    if (session.status === "stopped") return session;
+    session.status = "stopped";
+    this.append(explorationId, { kind: "session_stopped", stoppedAt: this.clock().toISOString() });
+    return session;
+  }
+  listSessions() {
+    return [...this.sessions.values()];
+  }
+  // ──────────────────────────────────────────────────────────────────────
+  requireKnown(explorationId) {
+    const s = this.sessions.get(explorationId);
+    if (!s) throw new ExplorationNotFoundError(explorationId);
+    return s;
+  }
+  requireActive(explorationId) {
+    const s = this.requireKnown(explorationId);
+    if (s.status !== "active") {
+      throw new ExplorationStoppedError(explorationId);
+    }
+    return s;
+  }
+  append(explorationId, record) {
+    appendFileSync2(join4(this.dir, `${explorationId}.jsonl`), JSON.stringify(record) + "\n");
+  }
+  restore() {
+    let files;
+    try {
+      files = readdirSync2(this.dir).filter((f) => f.endsWith(".jsonl"));
+    } catch {
+      return;
+    }
+    for (const file of files) {
+      const full = join4(this.dir, file);
+      try {
+        if (!statSync(full).isFile()) continue;
+        const text = readFileSync3(full, "utf8");
+        this.replayFile(text);
+      } catch {
+      }
+    }
+  }
+  replayFile(jsonl) {
+    const lines = jsonl.split("\n").filter((l) => l.length > 0);
+    let session = null;
+    let log = null;
+    for (const line of lines) {
+      let rec;
+      try {
+        rec = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      switch (rec.kind) {
+        case "session_started": {
+          session = { ...rec.session };
+          log = { logId: session.actionLogId, createdAt: session.startedAt, entries: [] };
+          this.sessions.set(session.explorationId, session);
+          this.logs.set(session.actionLogId, log);
+          break;
+        }
+        case "entry_added": {
+          if (log) log.entries.push(rec.entry);
+          break;
+        }
+        case "entry_removed": {
+          if (log) {
+            const idx = log.entries.findIndex((e) => e.entryId === rec.entryId);
+            if (idx >= 0) log.entries.splice(idx, 1);
+          }
+          break;
+        }
+        case "session_stopped": {
+          if (session) session.status = "stopped";
+          break;
+        }
+      }
+    }
+  }
+};
+var ExplorationNotFoundError = class extends Error {
+  static {
+    __name(this, "ExplorationNotFoundError");
+  }
+  code = "EXPLORATION_NOT_FOUND";
+  constructor(explorationId) {
+    super(`exploration session not found: ${explorationId}`);
+    this.name = "ExplorationNotFoundError";
+  }
+};
+var ExplorationStoppedError = class extends Error {
+  static {
+    __name(this, "ExplorationStoppedError");
+  }
+  code = "EXPLORATION_STOPPED";
+  constructor(explorationId) {
+    super(`exploration session already stopped: ${explorationId}`);
+    this.name = "ExplorationStoppedError";
+  }
+};
+
+// src/mcp/exploration/format-selector.ts
+function formatSelector(selector) {
+  if (selector.ordinal !== void 0) {
+    const { ordinal: ordinal2, ...rest } = selector;
+    const inner = formatSelector(rest);
+    return inner === null ? null : `ordinal(${inner}, ${ordinal2})`;
+  }
+  if (selector.testId !== void 0) return `getByTestId(${JSON.stringify(selector.testId)})`;
+  if (selector.text !== void 0) return `getByText(${JSON.stringify(selector.text)})`;
+  if (selector.label !== void 0) return `getByLabel(${JSON.stringify(selector.label)})`;
+  return null;
+}
+__name(formatSelector, "formatSelector");
+function describeShape(selector) {
+  const keys = Object.keys(selector).filter((k) => selector[k] !== void 0);
+  return keys.length === 0 ? "<empty>" : keys.sort().join("+");
+}
+__name(describeShape, "describeShape");
+
+// src/mcp/exploration/dsl-view.service.ts
+var DslViewService = class {
+  static {
+    __name(this, "DslViewService");
+  }
+  generate(session, log) {
+    const warnings = [];
+    const lines = [];
+    lines.push(renderHeader(session));
+    lines.push(`function test_${session.scenarioName.replace(/[^a-zA-Z0-9_]/g, "_")}() {`);
+    lines.push(`  setDevice(${JSON.stringify(session.device)});`);
+    let openSection = null;
+    for (const entry of log.entries) {
+      if (entry.section !== openSection) {
+        if (openSection !== null) lines.push("  //@endcollapse");
+        lines.push(`  //@collapse(${JSON.stringify(entry.section)})`);
+        openSection = entry.section;
+      }
+      const result = renderEntry(entry);
+      if (result.kind === "skip") {
+        warnings.push({
+          entryId: entry.entryId,
+          type: "NO_DSL_PRIMITIVE",
+          message: result.reason
+        });
+        lines.push(`  // SKIPPED (${result.reason}) \u2014 replace with getByTestId/getByText/getByLabel`);
+        continue;
+      }
+      if (entry.stability === "fragile") {
+        warnings.push({
+          entryId: entry.entryId,
+          type: "FRAGILE_LOCATOR",
+          message: `${entry.action} selector lacks a stable identifier \u2014 add a testId in the app`
+        });
+      }
+      for (const w of result.warnings ?? []) {
+        warnings.push({ ...w, entryId: entry.entryId });
+      }
+      lines.push("  " + result.stmt);
+    }
+    if (openSection !== null) lines.push("  //@endcollapse");
+    lines.push("}");
+    return { draftDsl: lines.join("\n") + "\n", warnings };
+  }
+};
+function renderHeader(session) {
+  const title = session.title ?? session.scenarioName;
+  return [
+    `// id-${session.scenarioName}`,
+    `// ${title}`,
+    `// #4287f5`
+  ].join("\n");
+}
+__name(renderHeader, "renderHeader");
+function renderEntry(entry) {
+  const sel = /* @__PURE__ */ __name((s) => {
+    const out = formatSelector(s);
+    if (out === null) {
+      return { kind: "skip", reason: `selector shape ${describeShape(s)} has no DSL primitive` };
+    }
+    return out;
+  }, "sel");
+  switch (entry.action) {
+    case "tap": {
+      if (!entry.selector) return { kind: "skip", reason: "tap missing selector" };
+      const s = sel(entry.selector);
+      if (typeof s !== "string") return s;
+      return { kind: "stmt", stmt: `tap(${s});` };
+    }
+    case "type": {
+      if (!entry.selector) return { kind: "skip", reason: "type missing selector" };
+      const s = sel(entry.selector);
+      if (typeof s !== "string") return s;
+      return { kind: "stmt", stmt: `type(${s}, ${JSON.stringify(entry.value ?? "")});` };
+    }
+    case "swipe": {
+      const dir = JSON.stringify(entry.direction ?? "up");
+      if (entry.from) {
+        const s = sel(entry.from);
+        if (typeof s !== "string") return s;
+        return { kind: "stmt", stmt: `swipe(${dir}, ${s});` };
+      }
+      return { kind: "stmt", stmt: `swipe(${dir});` };
+    }
+    case "wait_for": {
+      if (!entry.selector) return { kind: "skip", reason: "wait_for missing selector" };
+      const s = sel(entry.selector);
+      if (typeof s !== "string") return s;
+      return { kind: "stmt", stmt: `waitFor(${s}, ${entry.timeoutMs ?? 5e3});` };
+    }
+    case "press_key":
+      return { kind: "stmt", stmt: `pressKey(${JSON.stringify(entry.key ?? "enter")});` };
+    case "app_launch": {
+      const warnings = entry.bundleId ? [
+        {
+          type: "BUNDLE_ID_IGNORED",
+          message: `app_launch recorded with bundleId="${entry.bundleId}" \u2014 DSL appLaunch() reads bundle from APP_BUNDLE_ID env; override at runtime if needed.`
+        }
+      ] : [];
+      return { kind: "stmt", stmt: `appLaunch(${entry.clean ? "true" : "false"});`, warnings };
+    }
+    case "open_deeplink":
+      return { kind: "stmt", stmt: `openDeeplink(${JSON.stringify(entry.url ?? "")});` };
+    case "accept_alert":
+      return {
+        kind: "stmt",
+        stmt: entry.button ? `acceptAlert(${JSON.stringify(entry.button)});` : `acceptAlert();`
+      };
+    case "dismiss_alert":
+      return { kind: "stmt", stmt: `dismissAlert();` };
+  }
+}
+__name(renderEntry, "renderEntry");
 
 // src/fixtures/db.ts
 async function createDbClient(databaseUrl) {
@@ -5159,9 +6172,13 @@ async function buildApp(opts = {}) {
   const scenarioRepository = opts.scenarioRepository ?? new FileSystemScenarioRepository({ scenariosDir: scenariosDirAbs });
   const helperRepository = opts.helperRepository ?? new FileSystemHelperRepository({ scenariosDir: scenariosDirAbs });
   const scenarioLoader = new ScenarioLoader(scenarioRepository, helperRepository);
-  const sessionRecorder = new SessionRecorder(envConfig.SESSION_LOG_PATH);
-  const db = opts.db ?? await createDbClient(envConfig.DATABASE_URL);
-  const api = createApiClient(envConfig.API_BASE_URL, logger.child("api"));
+  const sessionRecorder = envConfig.SESSION_LOG_DISABLE || envConfig.SESSION_LOG_PATH === "" ? new NoopSessionRecorder() : new SessionRecorder(envConfig.SESSION_LOG_PATH, { full: envConfig.SESSION_LOG_FULL });
+  const exploration = new ExplorationService({
+    explorationsDir: resolve3(envConfig.explorationsDir)
+  });
+  const dslView = new DslViewService();
+  const db = opts.db ?? (envConfig.DATABASE_URL ? await createDbClient(envConfig.DATABASE_URL) : missingEnvDbClient());
+  const api = envConfig.API_BASE_URL ? createApiClient(envConfig.API_BASE_URL, logger.child("api")) : missingEnvApiClient();
   const shell2 = opts.shell ?? new NodeShellExecutor({
     logger: logger.child("shell"),
     defaultCwd: envConfig.PROJECT_ROOT ?? process.cwd()
@@ -5185,6 +6202,8 @@ async function buildApp(opts = {}) {
     helperRepository,
     scenarioLoader,
     sessionRecorder,
+    exploration,
+    dslView,
     db,
     api,
     shell: shell2,
@@ -5200,9 +6219,53 @@ async function buildApp(opts = {}) {
   };
 }
 __name(buildApp, "buildApp");
+function missingEnvDbClient() {
+  const fail = /* @__PURE__ */ __name(() => {
+    throw new Error(
+      `DATABASE_URL is not set in unotest/.env \u2014 required for dbQuery / dbExec. Set it (postgresql://, mysql://, or sqlite:) or remove the dbQuery / dbExec call from the scenario.`
+    );
+  }, "fail");
+  return {
+    query: /* @__PURE__ */ __name(() => fail(), "query"),
+    exec: /* @__PURE__ */ __name(() => fail(), "exec"),
+    close: /* @__PURE__ */ __name(async () => {
+    }, "close")
+  };
+}
+__name(missingEnvDbClient, "missingEnvDbClient");
+function missingEnvApiClient() {
+  const fail = /* @__PURE__ */ __name(() => {
+    throw new Error(
+      `API_BASE_URL is not set in unotest/.env \u2014 required for apiCall. Set it or remove the apiCall call from the scenario.`
+    );
+  }, "fail");
+  return {
+    call: /* @__PURE__ */ __name(() => fail(), "call"),
+    login: /* @__PURE__ */ __name(() => fail(), "login")
+  };
+}
+__name(missingEnvApiClient, "missingEnvApiClient");
 
-// src/mcp/tools/legacy.tool.ts
-import { z as z3 } from "zod";
+// src/util/cli-entry.ts
+function runMain(main, errorExitCode) {
+  main().then(
+    (code) => process.exit(code),
+    (e) => {
+      const msg = e instanceof Error ? e.message : String(e);
+      process.stderr.write(`\u2717 ${msg}
+`);
+      if (process.env.UNOTEST_DEBUG === "1" && e instanceof Error && e.stack) {
+        process.stderr.write(`${e.stack}
+`);
+      }
+      process.exit(errorExitCode);
+    }
+  );
+}
+__name(runMain, "runMain");
+
+// src/mcp/tools/device.tool.ts
+import { z as z2 } from "zod";
 
 // src/mcp/tools/base.tool.ts
 var BaseTool = class {
@@ -5237,58 +6300,180 @@ var BaseTool = class {
     }
   }
   /**
-   * Wrap `fn` with session-log recording AND error→fail conversion. The
-   * recorder lives on AppServices (Phase 8 addition); slices that include it
-   * get tracking for free, slices that don't simply skip recording.
+   * Wrap `fn` with session-log recording AND error→fail conversion.
+   *
+   * Three outcomes are classified:
+   *  - thrown exception → result: "error", error_class = exception class name
+   *  - returned `{isError: true}` (e.g. via `this.fail(...)`) → result: "error",
+   *    error_class = "ReturnedError"
+   *  - any other return → result: "ok"
    *
-   * Use this from concrete tool `register` callbacks — the convention saves
-   * 4-5 lines of boilerplate per tool.
+   * Duration is measured in both branches. A short result_preview (truncated
+   * concatenation of text content) is always recorded; the full result is
+   * passed to the recorder, which writes it only when SESSION_LOG_FULL=1.
    */
   async tracked(toolName, args, fn) {
     const recorder = this.services.sessionRecorder;
+    const t0 = Date.now();
     try {
       const out = await fn();
-      if (recorder) recorder.record({ tool: toolName, args, result: "ok" });
+      const duration_ms = Date.now() - t0;
+      if (recorder) {
+        if (isReturnedError(out)) {
+          const errText = extractText(out);
+          recorder.record({
+            tool: toolName,
+            args,
+            result: "error",
+            error: errText,
+            error_class: "ReturnedError",
+            duration_ms,
+            result_preview: truncate2(errText),
+            full_result: out
+          });
+        } else {
+          const preview = truncate2(extractText(out));
+          recorder.record({
+            tool: toolName,
+            args,
+            result: "ok",
+            duration_ms,
+            result_preview: preview,
+            full_result: out
+          });
+        }
+      }
       return out;
     } catch (e) {
+      const duration_ms = Date.now() - t0;
       const msg = e instanceof Error ? e.message : String(e);
-      if (recorder) recorder.record({ tool: toolName, args, result: "error", error: msg });
+      const error_class = e instanceof Error ? e.constructor.name : "UnknownError";
+      if (recorder) {
+        recorder.record({
+          tool: toolName,
+          args,
+          result: "error",
+          error: msg,
+          error_class,
+          duration_ms,
+          result_preview: truncate2(msg)
+        });
+      }
       return this.fail(msg);
     }
   }
 };
+var PREVIEW_MAX_BYTES = 4096;
+function truncate2(s) {
+  if (s.length <= PREVIEW_MAX_BYTES) return s;
+  return s.slice(0, PREVIEW_MAX_BYTES) + `\u2026[truncated ${s.length - PREVIEW_MAX_BYTES} chars]`;
+}
+__name(truncate2, "truncate");
+function isReturnedError(out) {
+  return typeof out === "object" && out !== null && out.isError === true;
+}
+__name(isReturnedError, "isReturnedError");
+function extractText(out) {
+  if (typeof out !== "object" || out === null) return String(out);
+  const content = out.content;
+  if (!Array.isArray(content)) return "";
+  const parts = [];
+  for (const item of content) {
+    if (item && typeof item === "object" && item.type === "text") {
+      const text = item.text;
+      if (typeof text === "string") parts.push(text);
+    }
+  }
+  return parts.join("\n");
+}
+__name(extractText, "extractText");
 
-// src/mcp/tools/selector-param.ts
-import { z as z2 } from "zod";
-var SelectorShape = {
-  testId: z2.string().optional(),
-  text: z2.string().optional(),
-  label: z2.string().optional(),
-  ordinal: z2.number().int().nonnegative().optional(),
-  pointPercent: z2.object({
-    x: z2.number().min(0).max(1),
-    y: z2.number().min(0).max(1)
-  }).optional()
-};
-function coerceJsonObject(v) {
-  if (typeof v !== "string") return v;
-  try {
-    return JSON.parse(v);
-  } catch {
-    return v;
+// src/inspection/outline-types.ts
+var OUTLINE_TESTID_RE = /^[^\s"{}\x00-\x1F\x7F]+$/;
+
+// src/inspection/outline-renderer.ts
+var SIDES = ["top", "bottom", "left", "right"];
+function renderOutline(tree) {
+  const lines = [];
+  if (tree.alert) {
+    renderAlertSection(tree.alert, lines);
+  }
+  lines.push("on_screen:");
+  if (tree.on_screen.length === 0) {
+    lines.push("  (empty)");
+  } else {
+    for (const root of tree.on_screen) renderNode(root, 1, lines);
+  }
+  lines.push("off_screen:");
+  for (const side of SIDES) {
+    const list = tree.off_screen[side];
+    if (list.length === 0) {
+      lines.push(`  ${side}: (empty)`);
+    } else {
+      lines.push(`  ${side}:`);
+      for (const node of list) {
+        lines.push(`    ${renderLine(
+          node,
+          /*isOffScreen*/
+          true
+        )}`);
+      }
+    }
   }
+  const m = tree._meta;
+  lines.push("_meta:");
+  lines.push(
+    `  totalNodes: ${m.totalNodes}  onScreen: ${m.onScreen}  offScreen: ${m.offScreen}`
+  );
+  lines.push(`  viewport: ${m.viewport.width}x${m.viewport.height}`);
+  lines.push(`  mode: outline`);
+  if (tree.alert) lines.push(`  alert_active: true`);
+  return lines.join("\n");
 }
-__name(coerceJsonObject, "coerceJsonObject");
-var SelectorParam = z2.preprocess(
-  coerceJsonObject,
-  z2.object(SelectorShape).refine(
-    (s) => Boolean(s.testId || s.text || s.label || s.pointPercent),
-    { message: "selector requires one of testId/text/label/pointPercent" }
-  )
-);
-var SelectorParamOptional = z2.preprocess(coerceJsonObject, z2.object(SelectorShape).optional());
+__name(renderOutline, "renderOutline");
+function renderAlertSection(alert, out) {
+  out.push("alert:");
+  out.push(`  text: "${escapeName(alert.text)}"`);
+  if (alert.buttons !== null) {
+    out.push(`  buttons: [${alert.buttons.join(", ")}]`);
+  }
+  out.push(`  hint: use acceptAlert("<label>") or dismissAlert \u2014 direct tap won't reach SpringBoard`);
+}
+__name(renderAlertSection, "renderAlertSection");
+function renderNode(n, depth, out) {
+  out.push("  ".repeat(depth) + renderLine(
+    n,
+    /*isOffScreen*/
+    false
+  ));
+  for (const c of n.children) renderNode(c, depth + 1, out);
+}
+__name(renderNode, "renderNode");
+function renderLine(n, isOffScreen) {
+  const parts = ["-"];
+  const interactive = isInteractiveRole(n.role);
+  const name = interactive && n.text !== void 0 && n.text === n.testId && n.label && n.label !== n.testId ? n.label : n.text ?? n.label;
+  const isRedundantRole = n.role === "statictext" || n.role === "other";
+  const showRole = !!n.role && !(name !== void 0 && isRedundantRole);
+  if (showRole) parts.push(n.role);
+  if (name !== void 0) parts.push(`"${escapeName(name)}"`);
+  const testIdShouldShow = n.testId !== void 0 && OUTLINE_TESTID_RE.test(n.testId) && (interactive || n.testId !== name);
+  if (testIdShouldShow) parts.push(`#${n.testId}`);
+  const flags = [];
+  if (!isOffScreen) {
+    const clipped = n.clipped;
+    if (clipped) flags.push(`clipped: ${clipped}`);
+  }
+  if (flags.length > 0) parts.push(`{${flags.join(", ")}}`);
+  return parts.join(" ");
+}
+__name(renderLine, "renderLine");
+function escapeName(s) {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+}
+__name(escapeName, "escapeName");
 
-// src/mcp/tools/legacy.tool.ts
+// src/mcp/tools/device.tool.ts
 var DevicesListTool = class extends BaseTool {
   static {
     __name(this, "DevicesListTool");
@@ -5332,7 +6517,7 @@ var ScreenshotTool = class extends BaseTool {
       {
         title: "Screenshot",
         description: "Returns a PNG screenshot of the device as MCP image content (inline base64). Does not write to disk.",
-        inputSchema: { device: z3.string().describe("device slot, e.g. 'A'") }
+        inputSchema: { device: z2.string().describe("device slot, e.g. 'A'") }
       },
       async ({ device }) => this.tracked("screenshot", { device }, async () => {
         const buf = await this.services.driver.screenshot(device);
@@ -5354,178 +6539,46 @@ var A11yTreeTool = class extends BaseTool {
       "a11y_tree",
       {
         title: "Accessibility tree",
-        description: "Returns the accessibility hierarchy. mode='compact' (default) drops layout-only nodes (no testId/text/label and no interactive role), strips bounds/enabled/focused/non-interactive role, indexes duplicate testIds with @N suffix, and includes _meta at the root. mode='full' returns the raw tree.",
+        description: (
+          // P1: default mode is `outline` — compact custom-grammar text
+          // (line-per-node, indent-based hierarchy, on_screen/off_screen
+          // partition). 60-75% token reduction vs the older compact JSON.
+          // `full` returns raw JSON tree with bounds + normalized short
+          // roles (button, textfield, …) — escape hatch for debugging.
+          // NB: descriptions stay self-contained — this MCP is consumed
+          // from arbitrary user projects where our repo docs don't exist.
+          `Returns the accessibility hierarchy. mode='outline' (default) \u2014 line-per-node text format, indent = hierarchy, sections 'on_screen:' / 'off_screen: { top|bottom|left|right }' / '_meta:', node syntax '- role "name" #testId {flags}', lowercase short roles (button, textfield, \u2026), 60-75% token saving vs JSON. mode='full' \u2014 raw JSON tree with bounds and normalized lowercase roles for debugging.`
+        ),
         inputSchema: {
-          device: z3.string(),
-          mode: z3.enum(["compact", "full"]).optional()
+          device: z2.string(),
+          mode: z2.enum(["outline", "full"]).optional()
         }
       },
       async ({ device, mode }) => {
-        const m = mode ?? "compact";
+        const m = mode ?? "outline";
         return this.tracked("a11y_tree", { device, mode: m }, async () => {
           const raw = await this.services.driver.a11yTree(device);
-          const out = this.services.treeInspector.withMode(raw, m);
-          return this.okJson(out);
+          if (m === "full") {
+            return this.okJson({ ...raw, _meta: { mode: "full" } });
+          }
+          const vp = await this.services.driver.windowSize(device);
+          let alert;
+          try {
+            const text = await this.services.driver.readAlert(device);
+            if (text && text.text !== "") {
+              const buttons = await this.services.driver.readAlertButtons(device).catch(() => null);
+              alert = { text: text.text, buttons };
+            }
+          } catch {
+          }
+          const semantic = this.services.treeInspector.semanticTree(raw, vp);
+          if (alert) semantic.alert = alert;
+          return this.ok(renderOutline(semantic));
         });
       }
     );
   }
 };
-var TapTool = class extends BaseTool {
-  static {
-    __name(this, "TapTool");
-  }
-  register(server) {
-    server.registerTool(
-      "tap",
-      {
-        title: "Tap",
-        description: "Tap on a selector (testId | text | label | ordinal | pointPercent).",
-        inputSchema: { device: z3.string(), selector: SelectorParam }
-      },
-      async ({ device, selector }) => this.tracked("tap", { device, selector }, async () => {
-        await this.services.driver.tap(device, selector);
-        return this.ok(`tap ok on ${device}`);
-      })
-    );
-  }
-};
-var TypeTool = class extends BaseTool {
-  static {
-    __name(this, "TypeTool");
-  }
-  register(server) {
-    server.registerTool(
-      "type",
-      {
-        title: "Type text",
-        description: "Tap the input by selector and type text.",
-        inputSchema: { device: z3.string(), selector: SelectorParam, text: z3.string() }
-      },
-      async ({ device, selector, text }) => this.tracked("type", { device, selector, text }, async () => {
-        await this.services.driver.type(device, selector, text);
-        return this.ok(`type ok on ${device}`);
-      })
-    );
-  }
-};
-var PressKeyTool = class extends BaseTool {
-  static {
-    __name(this, "PressKeyTool");
-  }
-  register(server) {
-    server.registerTool(
-      "press_key",
-      {
-        title: "Press key",
-        description: "Press a system key: back | home | enter | escape. (iOS has no native back; the tool will surface a clear error.)",
-        inputSchema: {
-          device: z3.string(),
-          key: z3.enum(["back", "home", "enter", "escape"])
-        }
-      },
-      async ({ device, key }) => this.tracked("press_key", { device, key }, async () => {
-        await this.services.driver.pressKey(device, key);
-        return this.ok(`pressKey ${key} on ${device}`);
-      })
-    );
-  }
-};
-var SwipeTool = class extends BaseTool {
-  static {
-    __name(this, "SwipeTool");
-  }
-  register(server) {
-    server.registerTool(
-      "swipe",
-      {
-        title: "Swipe",
-        description: "Swipe in a direction, optionally anchored at a selector.",
-        inputSchema: {
-          device: z3.string(),
-          direction: z3.enum(["up", "down", "left", "right"]),
-          from: SelectorParamOptional
-        }
-      },
-      async ({ device, direction, from }) => this.tracked("swipe", { device, direction, from }, async () => {
-        await this.services.driver.swipe(device, direction, from);
-        return this.ok(`swipe ${direction} on ${device}`);
-      })
-    );
-  }
-};
-var OpenDeeplinkTool = class extends BaseTool {
-  static {
-    __name(this, "OpenDeeplinkTool");
-  }
-  register(server) {
-    server.registerTool(
-      "open_deeplink",
-      {
-        title: "Open deep link",
-        description: "Open a URL on the device (custom URL scheme / universal link).",
-        inputSchema: { device: z3.string(), url: z3.string() }
-      },
-      async ({ device, url }) => this.tracked("open_deeplink", { device, url }, async () => {
-        await this.services.driver.openDeeplink(device, url);
-        return this.ok(`open_deeplink on ${device}: ${url}`);
-      })
-    );
-  }
-};
-var AppLaunchTool = class extends BaseTool {
-  static {
-    __name(this, "AppLaunchTool");
-  }
-  register(server) {
-    server.registerTool(
-      "app_launch",
-      {
-        title: "Launch app",
-        description: "Launch the app under test; clean=true terminates the running process and starts cold (D-3 fix: no uninstall \u2014 preserves the dev-client).",
-        inputSchema: {
-          device: z3.string(),
-          bundleId: z3.string().optional(),
-          clean: z3.boolean().optional()
-        }
-      },
-      async ({ device, bundleId, clean }) => this.tracked("app_launch", { device, bundleId, clean }, async () => {
-        const opts = {};
-        if (bundleId !== void 0) opts.bundleId = bundleId;
-        if (clean !== void 0) opts.clean = clean;
-        await this.services.driver.appLaunch(device, opts);
-        return this.ok(`app_launch on ${device}${clean ? " (clean)" : ""}`);
-      })
-    );
-  }
-};
-var WaitForTool = class extends BaseTool {
-  static {
-    __name(this, "WaitForTool");
-  }
-  register(server) {
-    server.registerTool(
-      "wait_for",
-      {
-        title: "Wait for selector",
-        description: "Poll the a11y tree until a selector becomes visible.",
-        inputSchema: {
-          device: z3.string(),
-          selector: SelectorParam,
-          timeoutMs: z3.number().int().positive().optional(),
-          optional: z3.boolean().optional()
-        }
-      },
-      async ({ device, selector, timeoutMs, optional }) => this.tracked("wait_for", { device, selector, timeoutMs, optional }, async () => {
-        const opts = {};
-        if (timeoutMs !== void 0) opts.timeoutMs = timeoutMs;
-        if (optional !== void 0) opts.optional = optional;
-        const visible = await this.services.driver.waitFor(device, selector, opts);
-        return this.ok(`wait_for ${visible ? "visible" : "absent"} on ${device}`);
-      })
-    );
-  }
-};
 var SessionResetTool = class extends BaseTool {
   static {
     __name(this, "SessionResetTool");
@@ -5547,14 +6600,14 @@ var SessionResetTool = class extends BaseTool {
 };
 
 // src/mcp/tools/resolve-selector.tool.ts
-import { z as z4 } from "zod";
-var SelectorInput = z4.preprocess(
+import { z as z3 } from "zod";
+var SelectorInput = z3.preprocess(
   (v) => typeof v === "string" ? safeJsonParse(v) : v,
-  z4.object({
-    testId: z4.string().optional(),
-    text: z4.string().optional(),
-    label: z4.string().optional(),
-    ordinal: z4.number().int().nonnegative().optional()
+  z3.object({
+    testId: z3.string().optional(),
+    text: z3.string().optional(),
+    label: z3.string().optional(),
+    ordinal: z3.number().int().nonnegative().optional()
   })
 );
 function safeJsonParse(s) {
@@ -5576,11 +6629,11 @@ var ResolveSelectorTool = class extends BaseTool {
         title: "Resolve selector against current screen",
         description: "Returns either the matched A11yNode or up to 3 near-misses (with score + reason). Use this when a tap/type fails to understand which element is actually on screen. Selector shape: {testId?, text?, label?, ordinal?}.",
         inputSchema: {
-          device: z4.string(),
+          device: z3.string(),
           selector: SelectorInput
         }
       },
-      async ({ device, selector }) => this.safe(async () => {
+      async ({ device, selector }) => this.tracked("resolve_selector", { device, selector }, async () => {
         const tree = await this.services.driver.a11yTree(device);
         const r = this.services.selectorResolver.resolve(tree, selector);
         if (r.ok) {
@@ -5603,6 +6656,345 @@ var ResolveSelectorTool = class extends BaseTool {
   }
 };
 
+// src/mcp/tools/app-install.tool.ts
+import { resolve as resolve5 } from "path";
+import { z as z4 } from "zod";
+
+// src/runner/install/install-app.ts
+import { execFile as execFile5 } from "child_process";
+import { existsSync as existsSync4, statSync as statSync2 } from "fs";
+import { resolve as resolve4 } from "path";
+import { promisify as promisify5 } from "util";
+
+// src/runner/install/info-plist.ts
+import { execFile as execFile4 } from "child_process";
+import { join as join5 } from "path";
+import { promisify as promisify4 } from "util";
+var exec4 = promisify4(execFile4);
+async function readInfoPlist(appPath) {
+  const plistPath = join5(appPath, "Info.plist");
+  const { stdout } = await exec4("plutil", ["-convert", "json", "-o", "-", plistPath]);
+  const raw = JSON.parse(stdout);
+  const bundleId = typeof raw.CFBundleIdentifier === "string" ? raw.CFBundleIdentifier : void 0;
+  const urlSchemes = [];
+  if (Array.isArray(raw.CFBundleURLTypes)) {
+    for (const type of raw.CFBundleURLTypes) {
+      if (type && typeof type === "object" && Array.isArray(type.CFBundleURLSchemes)) {
+        for (const scheme of type.CFBundleURLSchemes) {
+          if (typeof scheme === "string") urlSchemes.push(scheme);
+        }
+      }
+    }
+  }
+  const usageDescriptions = [];
+  for (const [key, value] of Object.entries(raw)) {
+    if (key.startsWith("NS") && key.endsWith("UsageDescription") && typeof value === "string") {
+      usageDescriptions.push({ key, description: value });
+    }
+  }
+  return { ...bundleId ? { bundleId } : {}, urlSchemes, usageDescriptions };
+}
+__name(readInfoPlist, "readInfoPlist");
+
+// src/runner/install/permission-mapper.ts
+var NS_TO_SIMCTL_SERVICE = Object.freeze({
+  // Location
+  NSLocationWhenInUseUsageDescription: "location",
+  NSLocationAlwaysAndWhenInUseUsageDescription: "location-always",
+  NSLocationAlwaysUsageDescription: "location-always",
+  // Media
+  NSPhotoLibraryUsageDescription: "photos",
+  NSPhotoLibraryAddUsageDescription: "photos-add",
+  NSMicrophoneUsageDescription: "microphone",
+  NSMediaLibraryUsageDescription: "media-library",
+  // Personal data
+  NSContactsUsageDescription: "contacts",
+  NSCalendarsUsageDescription: "calendar",
+  // legacy (pre-iOS 17)
+  NSCalendarsFullAccessUsageDescription: "calendar",
+  // iOS 17+ preferred
+  NSCalendarsWriteOnlyAccessUsageDescription: "calendar",
+  // iOS 17+ write-only
+  NSRemindersUsageDescription: "reminders",
+  // Sensors / device
+  NSMotionUsageDescription: "motion",
+  // Siri
+  NSSiriUsageDescription: "siri",
+  // Camera + push notifications are not exposed via `simctl privacy` —
+  // camera needs the alert-dismiss path (B1), push needs UNUserNotificationCenter.
+  NSCameraUsageDescription: null
+});
+var KNOWN_SIMCTL_SERVICES = new Set(
+  Object.values(NS_TO_SIMCTL_SERVICE).filter((v) => v !== null)
+);
+function inferSimctlServices(usageDescriptions) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const u of usageDescriptions) {
+    const svc = NS_TO_SIMCTL_SERVICE[u.key];
+    if (svc !== void 0 && svc !== null && !seen.has(svc)) {
+      seen.add(svc);
+      out.push(svc);
+    }
+  }
+  return out;
+}
+__name(inferSimctlServices, "inferSimctlServices");
+
+// src/runner/install/install-app.ts
+var exec5 = promisify5(execFile5);
+async function installApp2(opts, deps) {
+  const appPathAbsolute = resolve4(opts.appPath);
+  if (!existsSync4(appPathAbsolute)) {
+    throw new Error(`App path does not exist: ${appPathAbsolute}`);
+  }
+  if (!appPathAbsolute.endsWith(".app")) {
+    throw new Error(
+      `App path must point to a .app bundle (directory ending in .app), got: ${appPathAbsolute}. If you have an .ipa or .zip \u2014 extract it first.`
+    );
+  }
+  if (!statSync2(appPathAbsolute).isDirectory()) {
+    throw new Error(`App path must be a directory (.app bundle), got file: ${appPathAbsolute}`);
+  }
+  const infoPlist = `${appPathAbsolute}/Info.plist`;
+  if (!existsSync4(infoPlist)) {
+    throw new Error(`Info.plist not found inside .app: ${infoPlist}`);
+  }
+  const readBundleId = deps.readBundleId ?? readBundleIdViaPlistBuddy;
+  const appBundleId = (await readBundleId(appPathAbsolute)).trim();
+  if (!appBundleId) {
+    throw new Error(`Could not read CFBundleIdentifier from ${infoPlist}`);
+  }
+  const readUrlScheme = deps.readUrlScheme ?? readUrlSchemeViaPlistBuddy;
+  const appUrlScheme = await readUrlScheme(appPathAbsolute);
+  const readUsageDescriptions = deps.readUsageDescriptions ?? (async (p) => (await readInfoPlist(p)).usageDescriptions);
+  const usageDescriptions = await readUsageDescriptions(appPathAbsolute);
+  const detectedPermissions = inferSimctlServices(usageDescriptions);
+  if (opts.slots.length === 0) {
+    throw new Error(`No slots to install on. Pass --slot or check SIM_POOL in unotest/.env.`);
+  }
+  for (const slot of opts.slots) {
+    if (!opts.simBySlot[slot]) {
+      throw new Error(
+        `Slot "${slot}" requested but no SIM_${slot}_NAME in unotest/.env (or not in SIM_POOL).`
+      );
+    }
+  }
+  const slotResults = [];
+  for (const slot of opts.slots) {
+    const simName = opts.simBySlot[slot];
+    const sim = await deps.simctl.resolveByName(simName);
+    let erased = false;
+    if (opts.erase) {
+      deps.logger.info(`[${slot}] erasing ${simName} (${sim.udid})`);
+      try {
+        await deps.simctl.shutdown(sim.udid);
+      } catch {
+      }
+      await deps.simctl.erase(sim.udid);
+      erased = true;
+    }
+    deps.logger.info(`[${slot}] booting ${simName} (${sim.udid})`);
+    await deps.simctl.boot(sim.udid);
+    if (process.env.SIMCTL_HEADLESS !== "1") {
+      await deps.simctl.openSimulatorApp();
+    }
+    let uninstalled = false;
+    if (opts.clean) {
+      deps.logger.info(`[${slot}] uninstalling existing ${appBundleId}`);
+      try {
+        await deps.simctl.uninstall(sim.udid, appBundleId);
+        uninstalled = true;
+      } catch {
+      }
+      deps.logger.info(`[${slot}] resetting keychain on ${sim.udid}`);
+      await deps.simctl.keychainReset(sim.udid);
+    }
+    deps.logger.info(`[${slot}] installing ${appPathAbsolute}`);
+    await deps.simctl.install(sim.udid, appPathAbsolute);
+    if (opts.permissions && opts.permissions.length > 0) {
+      for (const service of opts.permissions) {
+        deps.logger.info(`[${slot}] granting ${service} to ${appBundleId}`);
+        await deps.simctl.privacyGrant(sim.udid, service, appBundleId);
+      }
+    }
+    if (opts.pinKeyboard !== false) {
+      deps.logger.info(`[${slot}] pinning keyboard to en_US@QWERTY`);
+      await deps.simctl.pinEnglishKeyboard(sim.udid);
+    }
+    let launched = false;
+    if (opts.launch) {
+      deps.logger.info(`[${slot}] launching ${appBundleId}`);
+      const { pid } = await deps.simctl.launch(sim.udid, appBundleId);
+      await deps.simctl.assertLaunchedAndStable(sim.udid, appBundleId, pid);
+      launched = true;
+    }
+    slotResults.push({ slot, simName, udid: sim.udid, erased, uninstalled, launched });
+  }
+  return {
+    appBundleId,
+    appUrlScheme,
+    appPathAbsolute,
+    bundleIdMismatch: opts.envBundleId !== void 0 && opts.envBundleId !== appBundleId,
+    detectedPermissions,
+    slots: slotResults
+  };
+}
+__name(installApp2, "installApp");
+async function readBundleIdViaPlistBuddy(appPath) {
+  const { stdout } = await exec5("/usr/libexec/PlistBuddy", [
+    "-c",
+    "Print :CFBundleIdentifier",
+    `${appPath}/Info.plist`
+  ]);
+  return stdout;
+}
+__name(readBundleIdViaPlistBuddy, "readBundleIdViaPlistBuddy");
+async function readUrlSchemeViaPlistBuddy(appPath) {
+  try {
+    const { stdout } = await exec5("/usr/libexec/PlistBuddy", [
+      "-c",
+      "Print :CFBundleURLTypes:0:CFBundleURLSchemes:0",
+      `${appPath}/Info.plist`
+    ]);
+    const scheme = stdout.trim();
+    return scheme.length > 0 ? scheme : void 0;
+  } catch {
+    return void 0;
+  }
+}
+__name(readUrlSchemeViaPlistBuddy, "readUrlSchemeViaPlistBuddy");
+
+// src/runner/install/update-env-file.ts
+import { existsSync as existsSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+function updateEnvFile(path, updates) {
+  const original = existsSync5(path) ? readFileSync4(path, "utf8") : "";
+  const lines = original.split(/\r?\n/);
+  const added = [];
+  const changed = [];
+  const unchanged = [];
+  for (const { key, value } of updates) {
+    const newLine = `${key}=${value}`;
+    const re = new RegExp(`^\\s*${escapeRegex(key)}\\s*=`);
+    let foundAt = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (re.test(lines[i] ?? "")) {
+        foundAt = i;
+        break;
+      }
+    }
+    if (foundAt === -1) {
+      if (lines.length > 0 && lines[lines.length - 1] !== "") lines.push("");
+      lines.push(newLine);
+      added.push(key);
+    } else if (lines[foundAt] === newLine) {
+      unchanged.push(key);
+    } else {
+      lines[foundAt] = newLine;
+      changed.push(key);
+    }
+  }
+  if (added.length > 0 || changed.length > 0) {
+    writeFileSync3(path, lines.join("\n"));
+  }
+  return { added, changed, unchanged };
+}
+__name(updateEnvFile, "updateEnvFile");
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+__name(escapeRegex, "escapeRegex");
+
+// src/mcp/tools/app-install.tool.ts
+var AppInstallTool = class extends BaseTool {
+  static {
+    __name(this, "AppInstallTool");
+  }
+  register(server) {
+    server.registerTool(
+      "app_install",
+      {
+        title: "Install iOS app on simulator",
+        description: "Installs a .app bundle on the configured simulator slot(s). If `path` is omitted, falls back to APP_PATH in unotest/.env. If neither is set, returns an error instructing you to ask the user for the .app path, then call again with `path` + `updateEnv: true`. Use this tool when a scenario fails with `App ... is not installed on ...`.",
+        inputSchema: {
+          path: z4.string().optional().describe("Absolute or relative path to a .app bundle. Falls back to APP_PATH env."),
+          slot: z4.enum(["A", "B", "all"]).optional().describe("Slot to install on. Default: 'A'."),
+          clean: z4.boolean().optional().describe(
+            "Uninstall existing app AND wipe the simulator keychain before reinstall. Use this when scenarios need a fresh signed-out state \u2014 `simctl uninstall` alone leaves auth tokens behind, so without keychain reset the next launch may still land on a logged-in screen."
+          ),
+          erase: z4.boolean().optional().describe("Erase simulator content & settings before install (destructive)."),
+          launch: z4.boolean().optional().describe("Launch the app after install for a quick sanity check."),
+          updateEnv: z4.boolean().optional().describe(
+            "Persist `path` as APP_PATH in unotest/.env. Also syncs APP_BUNDLE_ID if mismatched."
+          )
+        }
+      },
+      async ({ path, slot, clean, erase, launch, updateEnv }) => this.tracked("app_install", { path, slot, clean, erase, launch, updateEnv }, async () => {
+        const env = this.services.envConfig;
+        const appPath = path ?? process.env.APP_PATH;
+        if (!appPath) {
+          return this.failJson({
+            error: "missing-app-path",
+            message: "No path provided and APP_PATH is not set in unotest/.env. Ask the user for the path to the .app bundle, then call this tool again with `path: '<path>'` and `updateEnv: true` to persist it."
+          });
+        }
+        const slotChoice = slot ?? "A";
+        const slots = slotChoice === "all" ? env.simPool : env.simPool.includes(slotChoice) ? [slotChoice] : null;
+        if (slots === null) {
+          return this.failJson({
+            error: "slot-not-in-pool",
+            message: `Slot "${slotChoice}" is not in SIM_POOL (${env.simPool.join(",")}). Adjust SIM_POOL or pick a slot in the pool.`
+          });
+        }
+        let permissions = env.APP_PERMISSIONS && env.APP_PERMISSIONS.trim().length > 0 ? env.APP_PERMISSIONS.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+        if (permissions === void 0 && updateEnv) {
+          try {
+            const plist = await readInfoPlist(resolve5(appPath));
+            const detected = inferSimctlServices(plist.usageDescriptions);
+            if (detected.length > 0) permissions = detected;
+          } catch {
+          }
+        }
+        const result = await installApp2(
+          {
+            appPath,
+            slots,
+            simBySlot: env.simBySlot,
+            envBundleId: env.APP_BUNDLE_ID,
+            clean,
+            erase,
+            launch,
+            ...permissions !== void 0 ? { permissions } : {}
+          },
+          { simctl: new SimctlAdapter(), logger: this.services.logger.child("install") }
+        );
+        let envWrite;
+        if (updateEnv) {
+          const updates = [{ key: "APP_PATH", value: result.appPathAbsolute }];
+          if (result.bundleIdMismatch) {
+            updates.push({ key: "APP_BUNDLE_ID", value: result.appBundleId });
+          }
+          if (permissions !== void 0 && permissions.length > 0 && permissions.join(",") !== (env.APP_PERMISSIONS ?? "")) {
+            updates.push({ key: "APP_PERMISSIONS", value: permissions.join(",") });
+          }
+          envWrite = updateEnvFile(resolve5("unotest/.env"), updates);
+        }
+        return this.okJson({
+          appBundleId: result.appBundleId,
+          appPathAbsolute: result.appPathAbsolute,
+          bundleIdMismatch: result.bundleIdMismatch,
+          envBundleId: env.APP_BUNDLE_ID ?? null,
+          detectedPermissions: result.detectedPermissions,
+          grantedPermissions: permissions ?? null,
+          slots: result.slots,
+          envWrite: envWrite ?? null,
+          hint: result.bundleIdMismatch && !updateEnv ? "App bundle id differs from APP_BUNDLE_ID in .env \u2014 call again with updateEnv:true to sync, or update .env manually." : void 0
+        });
+      })
+    );
+  }
+};
+
 // src/mcp/tools/debugger.tool.ts
 import { z as z5 } from "zod";
 
@@ -5747,7 +7139,7 @@ var TestRuntime = class {
 };
 
 // src/mcp/tools/debugger.tool.ts
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 var RunTestTool = class extends BaseTool {
   static {
     __name(this, "RunTestTool");
@@ -5766,7 +7158,7 @@ var RunTestTool = class extends BaseTool {
           maxDurationMs: z5.number().int().positive().optional()
         }
       },
-      async ({ name, mode, pauseOnFailure, maxSteps, maxDurationMs }) => this.safe(async () => {
+      async ({ name, mode, pauseOnFailure, maxSteps, maxDurationMs }) => this.tracked("run_test", { name, mode, pauseOnFailure, maxSteps, maxDurationMs }, async () => {
         const { scenarioLoader, dslLinter, astExecutor, testRuntimeManager, envConfig, logger, driver, selectorResolver, treeInspector, failureExplainer, screenshotAnnotator, actionDiffer, db, api, shell: shell2 } = this.services;
         const loaded2 = await scenarioLoader.load(name);
         const entryDiags = dslLinter.lint(loaded2.ast, loaded2.source.source, {
@@ -5788,7 +7180,7 @@ var RunTestTool = class extends BaseTool {
             message: `Entry function "${testFn}" not found in ${name}.js. Convention: unotest/e2e/${name}.js \u2192 function ${testFn}().`
           });
         }
-        const runId = `e2e-${randomUUID().slice(0, 8)}`;
+        const runId = `e2e-${randomUUID2().slice(0, 8)}`;
         const runtime = new TestRuntime({
           runId,
           envConfig,
@@ -5842,7 +7234,7 @@ var StepTool = class extends BaseTool {
         description: "After paused-step or paused-failure, advances the executor by one statement. On failure-retry: re-runs the failed statement.",
         inputSchema: { runtimeId: z5.string() }
       },
-      async ({ runtimeId }) => this.safe(async () => {
+      async ({ runtimeId }) => this.tracked("step", { runtimeId }, async () => {
         const next = await this.services.testRuntimeManager.step(runtimeId);
         return this.okJson({ next });
       })
@@ -5861,7 +7253,7 @@ var ResumeTool = class extends BaseTool {
         description: "After paused-failure: re-executes the failed statement (D-17 Resume semantics) and continues until completion or next failure. After paused-step: advances and continues.",
         inputSchema: { runtimeId: z5.string() }
       },
-      async ({ runtimeId }) => this.safe(async () => {
+      async ({ runtimeId }) => this.tracked("resume", { runtimeId }, async () => {
         const next = await this.services.testRuntimeManager.resume(runtimeId);
         return this.okJson({ next });
       })
@@ -5880,7 +7272,7 @@ var InspectRuntimeTool = class extends BaseTool {
         description: "Returns vars, current device, last event, last result for the given runtimeId. Resets the TTL timer.",
         inputSchema: { runtimeId: z5.string() }
       },
-      async ({ runtimeId }) => this.safe(async () => {
+      async ({ runtimeId }) => this.tracked("inspect_runtime", { runtimeId }, async () => {
         return this.okJson(this.services.testRuntimeManager.inspect(runtimeId));
       })
     );
@@ -5898,7 +7290,7 @@ var AbortRuntimeTool = class extends BaseTool {
         description: "Cleanly stops the generator and runs onAbort cleanup. After this call the runtime is forgotten.",
         inputSchema: { runtimeId: z5.string() }
       },
-      async ({ runtimeId }) => this.safe(async () => {
+      async ({ runtimeId }) => this.tracked("abort_runtime", { runtimeId }, async () => {
         await this.services.testRuntimeManager.abort(runtimeId);
         return this.okJson({ status: "aborted", runtimeId });
       })
@@ -5917,33 +7309,488 @@ var ListRuntimesTool = class extends BaseTool {
         description: "Useful when several tests have been kicked off \u2014 find the one that failed and is awaiting inspection.",
         inputSchema: {}
       },
-      async () => this.safe(async () => {
+      async () => this.tracked("list_runtimes", {}, async () => {
         return this.okJson({ runtimes: this.services.testRuntimeManager.list() });
       })
     );
   }
 };
 
+// src/mcp/tools/explore.tool.ts
+import { z as z7 } from "zod";
+
+// src/mcp/tools/selector-param.ts
+import { z as z6 } from "zod";
+var SelectorShape = {
+  testId: z6.string().optional(),
+  text: z6.string().optional(),
+  label: z6.string().optional(),
+  ordinal: z6.number().int().nonnegative().optional(),
+  pointPercent: z6.object({
+    x: z6.number().min(0).max(1),
+    y: z6.number().min(0).max(1)
+  }).optional()
+};
+function coerceJsonObject(v) {
+  if (typeof v !== "string") return v;
+  try {
+    return JSON.parse(v);
+  } catch {
+    return v;
+  }
+}
+__name(coerceJsonObject, "coerceJsonObject");
+var SelectorParam = z6.preprocess(
+  coerceJsonObject,
+  z6.object(SelectorShape).refine(
+    (s) => Boolean(s.testId || s.text || s.label || s.pointPercent),
+    { message: "selector requires one of testId/text/label/pointPercent" }
+  )
+);
+var SelectorParamOptional = z6.preprocess(coerceJsonObject, z6.object(SelectorShape).optional());
+
+// src/mcp/tools/explore.tool.ts
+var ACTION_ENUM = [
+  "tap",
+  "type",
+  "press_key",
+  "swipe",
+  "wait_for",
+  "app_launch",
+  "open_deeplink",
+  "accept_alert",
+  "dismiss_alert"
+];
+var KEY_ENUM = ["back", "home", "enter", "escape"];
+var DIRECTION_ENUM = ["up", "down", "left", "right"];
+var stepShape = {
+  explorationId: z7.string().optional(),
+  action: z7.enum(ACTION_ENUM),
+  device: z7.string().optional(),
+  selector: SelectorParamOptional,
+  value: z7.string().optional(),
+  key: z7.enum(KEY_ENUM).optional(),
+  direction: z7.enum(DIRECTION_ENUM).optional(),
+  from: SelectorParamOptional,
+  url: z7.string().optional(),
+  bundleId: z7.string().optional(),
+  clean: z7.boolean().optional(),
+  timeoutMs: z7.number().int().positive().optional(),
+  optional: z7.boolean().optional(),
+  button: z7.string().optional(),
+  description: z7.string().optional(),
+  section: z7.string().optional()
+};
+function validateRecordingArgs(args) {
+  if (!args.section) return "section required when recording";
+  if (!args.description) return "description required when recording";
+  const missing = missingRequiredFields(args);
+  if (missing) return missing;
+  if (args.action === "wait_for" && args.optional === true) {
+    return "wait_for { optional: true } cannot be recorded: DSL waitFor doesn't support optional semantics, so the generated test would diverge from the recorded behavior. Use ad-hoc (omit explorationId) or fold the optional case into a different action.";
+  }
+  return null;
+}
+__name(validateRecordingArgs, "validateRecordingArgs");
+function missingRequiredFields(a) {
+  switch (a.action) {
+    case "tap":
+      return a.selector ? null : "tap requires selector";
+    case "type":
+      if (!a.selector) return "type requires selector";
+      if (a.value === void 0) return "type requires value";
+      return null;
+    case "press_key":
+      return a.key ? null : "press_key requires key";
+    case "swipe":
+      return a.direction ? null : "swipe requires direction";
+    case "wait_for":
+      return a.selector ? null : "wait_for requires selector";
+    case "open_deeplink":
+      return a.url ? null : "open_deeplink requires url";
+    case "app_launch":
+    case "accept_alert":
+    case "dismiss_alert":
+      return null;
+  }
+}
+__name(missingRequiredFields, "missingRequiredFields");
+async function runDriverAction(driver, device, a) {
+  switch (a.action) {
+    case "tap":
+      await driver.tap(device, a.selector);
+      return {};
+    case "type":
+      await driver.type(device, a.selector, a.value);
+      return {};
+    case "press_key":
+      await driver.pressKey(device, a.key);
+      return {};
+    case "swipe":
+      await driver.swipe(device, a.direction, a.from);
+      return {};
+    case "wait_for": {
+      const opts = {};
+      if (a.timeoutMs !== void 0) opts.timeoutMs = a.timeoutMs;
+      if (a.optional !== void 0) opts.optional = a.optional;
+      const visible = await driver.waitFor(device, a.selector, opts);
+      return { visible };
+    }
+    case "app_launch": {
+      const opts = {};
+      if (a.bundleId !== void 0) opts.bundleId = a.bundleId;
+      if (a.clean !== void 0) opts.clean = a.clean;
+      await driver.appLaunch(device, opts);
+      return {};
+    }
+    case "open_deeplink":
+      await driver.openDeeplink(device, a.url);
+      return {};
+    case "accept_alert":
+      await driver.acceptAlert(device, a.button);
+      return {};
+    case "dismiss_alert":
+      await driver.dismissAlert(device);
+      return {};
+  }
+}
+__name(runDriverAction, "runDriverAction");
+var ExploreStartTool = class extends BaseTool {
+  static {
+    __name(this, "ExploreStartTool");
+  }
+  register(server) {
+    server.registerTool(
+      "explore_start",
+      {
+        title: "Start a recording session",
+        description: "Begins an ExplorationSession. Returns { explorationId }. Subsequent explore_step calls that include this id will be recorded into an ActionLog; calls without it are ad-hoc. Device slot ('A' or 'B') is fixed for the session. No auto-launch: the first explore_step must do the app_launch / open_deeplink so it appears in the generated test.",
+        inputSchema: {
+          scenario_name: z7.string().min(1).describe("Logical name; later used by save_exploration_as_test as the test file name."),
+          device: z7.string().min(1).describe("Slot from SIM_POOL, e.g. 'A'."),
+          title: z7.string().optional(),
+          description: z7.string().optional()
+        }
+      },
+      async ({ scenario_name, device, title, description }) => this.tracked(
+        "explore_start",
+        { scenario_name, device, title, description },
+        async () => {
+          const session = this.services.exploration.startSession({
+            scenarioName: scenario_name,
+            device,
+            ...title !== void 0 ? { title } : {},
+            ...description !== void 0 ? { description } : {}
+          });
+          return this.okJson({
+            explorationId: session.explorationId,
+            scenarioName: session.scenarioName,
+            device: session.device,
+            status: session.status,
+            startedAt: session.startedAt
+          });
+        }
+      )
+    );
+  }
+};
+var ExploreStopTool = class extends BaseTool {
+  static {
+    __name(this, "ExploreStopTool");
+  }
+  register(server) {
+    server.registerTool(
+      "explore_stop",
+      {
+        title: "Stop a recording session",
+        description: "Marks the session as stopped. The device stays running (no teardown). After stop, generate_dsl_from_exploration / save_exploration_as_test remain callable; further explore_step calls with this id will fail.",
+        inputSchema: {
+          explorationId: z7.string().min(1)
+        }
+      },
+      async ({ explorationId }) => this.tracked("explore_stop", { explorationId }, async () => {
+        const session = this.services.exploration.getSession(explorationId);
+        if (!session) return this.fail(`exploration session not found: ${explorationId}`);
+        const log = this.services.exploration.getLog(explorationId);
+        this.services.exploration.stopSession(explorationId);
+        return this.okJson({
+          stepCount: log.entries.length,
+          readyForConversion: true
+        });
+      })
+    );
+  }
+};
+var ExploreStateTool = class extends BaseTool {
+  static {
+    __name(this, "ExploreStateTool");
+  }
+  register(server) {
+    server.registerTool(
+      "explore_state",
+      {
+        title: "Inspect the recording session log",
+        description: "Returns the session status and all recorded ActionEntries. Each entry carries its per-entry `stability` annotation (stable | fragile). The full warnings list (FRAGILE_LOCATOR / NO_DSL_PRIMITIVE / BUNDLE_ID_IGNORED) is NOT returned here \u2014 it is derived on demand by generate_dsl_from_exploration.",
+        inputSchema: {
+          explorationId: z7.string().min(1)
+        }
+      },
+      async ({ explorationId }) => this.tracked("explore_state", { explorationId }, async () => {
+        const session = this.services.exploration.getSession(explorationId);
+        if (!session) return this.fail(`exploration session not found: ${explorationId}`);
+        const log = this.services.exploration.getLog(explorationId);
+        return this.okJson({
+          session: {
+            explorationId: session.explorationId,
+            scenarioName: session.scenarioName,
+            device: session.device,
+            status: session.status,
+            startedAt: session.startedAt,
+            ...session.title !== void 0 ? { title: session.title } : {}
+          },
+          entries: log.entries
+        });
+      })
+    );
+  }
+};
+var ExploreStepTool = class extends BaseTool {
+  static {
+    __name(this, "ExploreStepTool");
+  }
+  register(server) {
+    server.registerTool(
+      "explore_step",
+      {
+        title: "Execute (and optionally record) a UI action",
+        description: "Universal action runner. With explorationId \u2192 executes AND records the action into the session log (section + description required). Without explorationId \u2192 ad-hoc execution, nothing recorded. Failed actions are never recorded. action: tap | type | press_key | swipe | wait_for | app_launch | open_deeplink | accept_alert | dismiss_alert. Required per action: tap/type/wait_for \u2192 selector; type \u2192 +value; press_key \u2192 key; swipe \u2192 direction (from optional anchor); open_deeplink \u2192 url. app_launch and *_alert have no required fields. app_launch { clean: true } terminates the running app, wipes the simulator keychain (B5 \u2014 auth tokens otherwise survive a clean launch), then starts cold. Recording-time reject: wait_for { optional: true } \u2014 DSL waitFor has no optional semantics; use it ad-hoc instead.",
+        inputSchema: stepShape
+      },
+      async (rawArgs) => this.tracked("explore_step", rawArgs, async () => {
+        const args = rawArgs;
+        const session = args.explorationId ? this.services.exploration.getSession(args.explorationId) : null;
+        if (args.explorationId && !session) {
+          return this.fail(`exploration session not found: ${args.explorationId}`);
+        }
+        const willRecord = session?.status === "active";
+        if (args.explorationId && session && !willRecord) {
+          return this.fail(
+            `exploration session ${args.explorationId} is stopped \u2014 cannot record. Omit explorationId for ad-hoc execution, or start a new session.`
+          );
+        }
+        const device = args.device ?? session?.device;
+        if (!device) {
+          return this.fail("device required (or pass an active explorationId)");
+        }
+        if (willRecord) {
+          const err = validateRecordingArgs(args);
+          if (err) return this.fail(err);
+        } else {
+          const missing = missingRequiredFields(args);
+          if (missing) return this.fail(missing);
+        }
+        const result = await runDriverAction(this.services.driver, device, args);
+        if (willRecord) {
+          const entry = this.services.exploration.addEntry(args.explorationId, {
+            action: args.action,
+            device,
+            description: args.description,
+            section: args.section,
+            ...args.selector !== void 0 ? { selector: args.selector } : {},
+            ...args.value !== void 0 ? { value: args.value } : {},
+            ...args.key !== void 0 ? { key: args.key } : {},
+            ...args.direction !== void 0 ? { direction: args.direction } : {},
+            ...args.from !== void 0 ? { from: args.from } : {},
+            ...args.url !== void 0 ? { url: args.url } : {},
+            ...args.bundleId !== void 0 ? { bundleId: args.bundleId } : {},
+            ...args.clean !== void 0 ? { clean: args.clean } : {},
+            ...args.timeoutMs !== void 0 ? { timeoutMs: args.timeoutMs } : {},
+            ...args.optional !== void 0 ? { optional: args.optional } : {},
+            ...args.button !== void 0 ? { button: args.button } : {}
+          });
+          return this.okJson({
+            entryId: entry.entryId,
+            recorded: true,
+            success: true,
+            ...result
+          });
+        }
+        return this.okJson({ recorded: false, success: true, ...result });
+      })
+    );
+  }
+};
+var ExploreRecordTool = class extends BaseTool {
+  static {
+    __name(this, "ExploreRecordTool");
+  }
+  register(server) {
+    server.registerTool(
+      "explore_record",
+      {
+        title: "Record an action without executing it",
+        description: "Appends an ActionEntry to the session log without invoking the driver. Use to manually add a step (assert, after-the-fact action). Required: explorationId, action, section, description, plus per-action fields (same as explore_step). Same recording-time rejects apply (e.g. wait_for { optional: true }).",
+        inputSchema: stepShape
+      },
+      async (rawArgs) => this.tracked("explore_record", rawArgs, async () => {
+        const args = rawArgs;
+        if (!args.explorationId) return this.fail("explorationId required");
+        const session = this.services.exploration.getSession(args.explorationId);
+        if (!session) return this.fail(`exploration session not found: ${args.explorationId}`);
+        if (session.status !== "active") {
+          return this.fail(`exploration session ${args.explorationId} is stopped`);
+        }
+        const device = args.device ?? session.device;
+        const err = validateRecordingArgs({ ...args, device });
+        if (err) return this.fail(err);
+        const entry = this.services.exploration.addEntry(args.explorationId, {
+          action: args.action,
+          device,
+          description: args.description,
+          section: args.section,
+          ...args.selector !== void 0 ? { selector: args.selector } : {},
+          ...args.value !== void 0 ? { value: args.value } : {},
+          ...args.key !== void 0 ? { key: args.key } : {},
+          ...args.direction !== void 0 ? { direction: args.direction } : {},
+          ...args.from !== void 0 ? { from: args.from } : {},
+          ...args.url !== void 0 ? { url: args.url } : {},
+          ...args.bundleId !== void 0 ? { bundleId: args.bundleId } : {},
+          ...args.clean !== void 0 ? { clean: args.clean } : {},
+          ...args.timeoutMs !== void 0 ? { timeoutMs: args.timeoutMs } : {},
+          ...args.optional !== void 0 ? { optional: args.optional } : {},
+          ...args.button !== void 0 ? { button: args.button } : {}
+        });
+        return this.okJson({ entryId: entry.entryId, recorded: true });
+      })
+    );
+  }
+};
+var ExploreRemoveStepTool = class extends BaseTool {
+  static {
+    __name(this, "ExploreRemoveStepTool");
+  }
+  register(server) {
+    server.registerTool(
+      "explore_remove_step",
+      {
+        title: "Remove an entry from the recording session log",
+        description: "Deletes the entry by entryId. Returns { removed: true } or { removed: false } if not found.",
+        inputSchema: {
+          explorationId: z7.string().min(1),
+          entryId: z7.string().min(1)
+        }
+      },
+      async ({ explorationId, entryId }) => this.tracked("explore_remove_step", { explorationId, entryId }, async () => {
+        const session = this.services.exploration.getSession(explorationId);
+        if (!session) return this.fail(`exploration session not found: ${explorationId}`);
+        const removed = this.services.exploration.removeEntry(explorationId, entryId);
+        return this.okJson({ removed });
+      })
+    );
+  }
+};
+var GenerateDslFromExplorationTool = class extends BaseTool {
+  static {
+    __name(this, "GenerateDslFromExplorationTool");
+  }
+  register(server) {
+    server.registerTool(
+      "generate_dsl_from_exploration",
+      {
+        title: "Render the session log as a DSL test",
+        description: "Returns { draftDsl, warnings } from the current ActionLog. Pure function \u2014 does not mutate the log. Warnings: FRAGILE_LOCATOR (selector lacks stable identifier), NO_DSL_PRIMITIVE (entry skipped \u2014 selector shape has no DSL function), BUNDLE_ID_IGNORED (app_launch with explicit bundleId \u2014 DSL appLaunch reads it from APP_BUNDLE_ID env). Adjacent same-section entries collapse into one //@collapse \u2026 //@endcollapse block.",
+        inputSchema: {
+          explorationId: z7.string().min(1)
+        }
+      },
+      async ({ explorationId }) => this.tracked("generate_dsl_from_exploration", { explorationId }, async () => {
+        const session = this.services.exploration.getSession(explorationId);
+        if (!session) return this.fail(`exploration session not found: ${explorationId}`);
+        const log = this.services.exploration.getLog(explorationId);
+        const result = this.services.dslView.generate(session, log);
+        return this.okJson(result);
+      })
+    );
+  }
+};
+var SaveExplorationAsTestTool = class extends BaseTool {
+  static {
+    __name(this, "SaveExplorationAsTestTool");
+  }
+  register(server) {
+    server.registerTool(
+      "save_exploration_as_test",
+      {
+        title: "Persist the generated DSL as a runnable scenario",
+        description: "Renders the ActionLog as DSL and writes it to unotest/e2e/<scenarioName>.js. Returns { path, actionCount, warnings }. Policy: by default, NO_DSL_PRIMITIVE warnings block the save \u2014 pass force: true to write anyway with `// SKIPPED \u2026` comments inline. If the file already exists, pass overwrite: true to replace it.",
+        inputSchema: {
+          explorationId: z7.string().min(1),
+          scenarioName: z7.string().min(1),
+          overwrite: z7.boolean().optional(),
+          force: z7.boolean().optional()
+        }
+      },
+      async ({ explorationId, scenarioName, overwrite, force }) => this.tracked(
+        "save_exploration_as_test",
+        { explorationId, scenarioName, overwrite, force },
+        async () => {
+          const session = this.services.exploration.getSession(explorationId);
+          if (!session) return this.fail(`exploration session not found: ${explorationId}`);
+          const log = this.services.exploration.getLog(explorationId);
+          const { draftDsl, warnings } = this.services.dslView.generate(session, log);
+          const blockers = warnings.filter((w) => w.type === "NO_DSL_PRIMITIVE");
+          if (blockers.length > 0 && !force) {
+            return this.failJson({
+              error: "no_dsl_primitive",
+              message: `${blockers.length} entry/entries have selector shapes with no DSL primitive. Pass force: true to write with '// SKIPPED' comments, or edit those entries first via explore_remove_step + explore_record.`,
+              blockers,
+              warnings
+            });
+          }
+          try {
+            const path = await this.services.scenarioRepository.save(scenarioName, draftDsl, {
+              ...overwrite !== void 0 ? { overwrite } : {}
+            });
+            return this.okJson({ path, actionCount: log.entries.length, warnings });
+          } catch (e) {
+            return this.fail(e.message);
+          }
+        }
+      )
+    );
+  }
+};
+
 // src/mcp/tools/index.ts
 function registerAllTools(server, services) {
   new DevicesListTool({ envConfig: services.envConfig, sessionRecorder: services.sessionRecorder }).register(server);
   new ScreenshotTool({ driver: services.driver, envConfig: services.envConfig, sessionRecorder: services.sessionRecorder }).register(server);
   new A11yTreeTool({ driver: services.driver, treeInspector: services.treeInspector, sessionRecorder: services.sessionRecorder }).register(server);
-  new TapTool({ driver: services.driver, envConfig: services.envConfig, sessionRecorder: services.sessionRecorder }).register(server);
-  new TypeTool({ driver: services.driver, envConfig: services.envConfig, sessionRecorder: services.sessionRecorder }).register(server);
-  new PressKeyTool({ driver: services.driver, envConfig: services.envConfig, sessionRecorder: services.sessionRecorder }).register(server);
-  new SwipeTool({ driver: services.driver, envConfig: services.envConfig, sessionRecorder: services.sessionRecorder }).register(server);
-  new OpenDeeplinkTool({ driver: services.driver, envConfig: services.envConfig, sessionRecorder: services.sessionRecorder }).register(server);
-  new AppLaunchTool({ driver: services.driver, envConfig: services.envConfig, sessionRecorder: services.sessionRecorder }).register(server);
-  new WaitForTool({ driver: services.driver, envConfig: services.envConfig, sessionRecorder: services.sessionRecorder }).register(server);
   new SessionResetTool({ sessionRecorder: services.sessionRecorder }).register(server);
+  const exploreServices = {
+    driver: services.driver,
+    envConfig: services.envConfig,
+    exploration: services.exploration,
+    dslView: services.dslView,
+    scenarioRepository: services.scenarioRepository,
+    sessionRecorder: services.sessionRecorder
+  };
+  new ExploreStartTool(exploreServices).register(server);
+  new ExploreStopTool(exploreServices).register(server);
+  new ExploreStateTool(exploreServices).register(server);
+  new ExploreStepTool(exploreServices).register(server);
+  new ExploreRecordTool(exploreServices).register(server);
+  new ExploreRemoveStepTool(exploreServices).register(server);
+  new GenerateDslFromExplorationTool(exploreServices).register(server);
+  new SaveExplorationAsTestTool(exploreServices).register(server);
   new ResolveSelectorTool({
     driver: services.driver,
     selectorResolver: services.selectorResolver,
     treeInspector: services.treeInspector,
     screenshotAnnotator: services.screenshotAnnotator,
     failureExplainer: services.failureExplainer,
-    logger: services.logger
+    logger: services.logger,
+    sessionRecorder: services.sessionRecorder
   }).register(server);
   const dbgServices = {
     testRuntimeManager: services.testRuntimeManager,
@@ -5960,7 +7807,8 @@ function registerAllTools(server, services) {
     failureExplainer: services.failureExplainer,
     db: services.db,
     api: services.api,
-    shell: services.shell
+    shell: services.shell,
+    sessionRecorder: services.sessionRecorder
   };
   new RunTestTool(dbgServices).register(server);
   new StepTool(dbgServices).register(server);
@@ -5968,6 +7816,11 @@ function registerAllTools(server, services) {
   new InspectRuntimeTool(dbgServices).register(server);
   new AbortRuntimeTool(dbgServices).register(server);
   new ListRuntimesTool(dbgServices).register(server);
+  new AppInstallTool({
+    envConfig: services.envConfig,
+    logger: services.logger,
+    sessionRecorder: services.sessionRecorder
+  }).register(server);
 }
 __name(registerAllTools, "registerAllTools");
 
@@ -6012,15 +7865,16 @@ async function startMcpServer() {
   services.logger.info(
     `unotest-mobile MCP server up on stdio (session log: ${services.sessionRecorder.getPath()})`
   );
+  await new Promise(() => {
+  });
 }
 __name(startMcpServer, "startMcpServer");
 if (import.meta.url === `file://${process.argv[1]}`) {
-  startMcpServer().catch((e) => {
-    console.error("[mcp] fatal:", e);
-    process.exit(1);
-  });
+  runMain(async () => {
+    await startMcpServer();
+    return 0;
+  }, 1);
 }
 export {
   startMcpServer
 };
-//# sourceMappingURL=server.js.map