@syrin/iris 0.4.0 → 0.5.0

package/dist/cli.js

@@ -48,6 +48,7 @@ var CRAWL_DEFAULTS = {
   /** HTTP status at/above which a response counts as a failed request. */
   FAILED_STATUS: 400
 };
+var UpdateCheckIntervalMs = 24 * 60 * 60 * 1e3;
 var CONTRACT_FILE_VERSION = 1;
 var FROM_DISK_ARG = "fromDisk";
 var ContractReadError = {
@@ -651,10 +652,97 @@ var AnnotationSchema = z2.discriminatedUnion("kind", [
 ]);
 
 // ../server/dist/index.js
-import { join as join2 } from "path";
+import { join as join5 } from "path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
+// ../server/dist/http-server.js
+import * as http from "http";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+
+// ../server/dist/log.js
+function log(event, fields = {}) {
+  const line = JSON.stringify({ event, ...fields });
+  process.stderr.write(`${line}
+`);
+}
+
+// ../server/dist/http-server.js
+var MCP_SSE_PATH = "/mcp/sse";
+var MCP_MESSAGE_PATH = "/mcp/message";
+function createSharedServer() {
+  let mcpFactory;
+  const transports = /* @__PURE__ */ new Map();
+  const httpServer = http.createServer((req, res) => {
+    const url = req.url ?? "/";
+    if (req.method === "GET" && url === MCP_SSE_PATH) {
+      if (mcpFactory === void 0) {
+        res.writeHead(503, { "Content-Type": "text/plain" });
+        res.end("MCP server not ready");
+        return;
+      }
+      const mcpServer = mcpFactory();
+      const transport = new SSEServerTransport(MCP_MESSAGE_PATH, res);
+      const sid = transport.sessionId;
+      transports.set(sid, transport);
+      res.on("close", () => {
+        transports.delete(sid);
+        transport.close().catch(() => void 0);
+        mcpServer.close().catch(() => void 0);
+        log("mcp_client_disconnected", { sessionId: sid });
+      });
+      mcpServer.connect(transport).then(() => {
+        log("mcp_client_connected", { sessionId: sid });
+      }).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        log("mcp_connect_error", { error: message });
+      });
+      return;
+    }
+    if (req.method === "POST" && url.startsWith(MCP_MESSAGE_PATH)) {
+      const parsed = new URL(url, "http://localhost");
+      const sessionId = parsed.searchParams.get("sessionId");
+      if (sessionId === null) {
+        res.writeHead(400, { "Content-Type": "text/plain" });
+        res.end("missing sessionId");
+        return;
+      }
+      const transport = transports.get(sessionId);
+      if (transport === void 0) {
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("session not found");
+        return;
+      }
+      transport.handlePostMessage(req, res).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        log("mcp_message_error", { error: message });
+      });
+      return;
+    }
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("not found");
+  });
+  function attachMcp(factory) {
+    mcpFactory = factory;
+  }
+  async function close() {
+    for (const transport of transports.values()) {
+      await transport.close();
+    }
+    transports.clear();
+    await new Promise((resolve, reject) => {
+      httpServer.close((err) => {
+        if (err !== void 0 && err !== null)
+          reject(err);
+        else
+          resolve();
+      });
+    });
+  }
+  return { httpServer, attachMcp, close };
+}
+
 // ../server/dist/bridge.js
+import * as http2 from "http";
 import { WebSocketServer } from "ws";
 
 // ../server/dist/events/ring-buffer.js
@@ -1076,7 +1164,16 @@ var SessionManager = class {
   }
   /**
    * Resolve the target session. With an explicit id, returns it. With none and exactly
-   * one connected, returns that. Otherwise throws a clear, agent-readable error.
+   * one connected, returns that.
+   *
+   * With none and multiple connected, applies smart auto-selection:
+   *   1. Prefer non-throttled sessions (not hidden + recently heard from).
+   *   2. Within each tier, prefer lowest lastSeenMs (most recently active SDK heartbeat).
+   *   3. If two or more non-throttled sessions are within 1 s of each other, throw —
+   *      genuinely ambiguous, agent must specify sessionId.
+   *   4. If ALL sessions are throttled (e.g. user is working in their editor on another
+   *      desktop), skip the gap check and pick the freshest heartbeat. This lets the agent
+   *      keep working in the background without requiring sessionId every time.
    */
   resolve(sessionId) {
     if (sessionId !== void 0) {
@@ -1090,25 +1187,33 @@ var SessionManager = class {
     if (this.#sessions.size === 0) {
       throw new Error("no browser session connected \u2014 is your app running with @syrin/iris-browser enabled?");
     }
-    if (this.#sessions.size > 1) {
-      const ids = [...this.#sessions.keys()].join(", ");
-      throw new Error(`multiple sessions connected (${ids}); pass sessionId to target one`);
+    const all = [...this.#sessions.values()];
+    if (all.length === 1) {
+      const [only] = all;
+      if (only === void 0)
+        throw new Error("session lookup failed");
+      only.markAgentActivity();
+      return only;
     }
-    const [only] = this.#sessions.values();
-    if (only === void 0)
+    const scored = all.map((s) => ({ s, score: s.throttled() ? 1 : 0, ms: s.lastSeenMs() }));
+    const bestScore = Math.min(...scored.map((x) => x.score));
+    const candidates = scored.filter((x) => x.score === bestScore);
+    candidates.sort((a, b) => a.ms - b.ms);
+    const [best, runnerUp] = candidates;
+    if (best === void 0)
       throw new Error("session lookup failed");
-    only.markAgentActivity();
-    return only;
+    const allThrottled = bestScore === 1;
+    const RECENCY_GAP_MS = allThrottled ? 0 : 1e3;
+    const clearWinner = runnerUp === void 0 || best.ms + RECENCY_GAP_MS < runnerUp.ms;
+    if (!clearWinner) {
+      const detail = all.map((s) => `${s.id} (${s.throttled() ? "throttled" : "active"}, lastSeenMs=${s.lastSeenMs()})`).join(", ");
+      throw new Error(`multiple sessions connected \u2014 pass sessionId to target one: ${detail}`);
+    }
+    best.s.markAgentActivity();
+    return best.s;
   }
 };
 
-// ../server/dist/log.js
-function log(event, fields = {}) {
-  const line = JSON.stringify({ event, ...fields });
-  process.stderr.write(`${line}
-`);
-}
-
 // ../server/dist/bridge.js
 function rawToString(raw) {
   if (typeof raw === "string")
@@ -1127,16 +1232,30 @@ var Bridge = class {
   #clock;
   constructor(options) {
     this.#clock = options.clock ?? (() => Date.now());
-    this.#wss = new WebSocketServer({
-      port: options.port,
-      host: options.host ?? "127.0.0.1",
-      path: IRIS_WS_PATH
-    });
-    this.ready = new Promise((resolve) => {
-      this.#wss.on("listening", () => {
-        resolve(this.#wss.address().port);
+    if (options.server !== void 0) {
+      const srv = options.server;
+      this.#wss = new WebSocketServer({ server: srv, path: IRIS_WS_PATH });
+      this.ready = new Promise((resolve) => {
+        if (srv.listening) {
+          resolve(srv.address().port);
+        } else {
+          srv.once("listening", () => {
+            resolve(srv.address().port);
+          });
+        }
       });
-    });
+    } else {
+      this.#wss = new WebSocketServer({
+        port: options.port,
+        host: options.host ?? "127.0.0.1",
+        path: IRIS_WS_PATH
+      });
+      this.ready = new Promise((resolve) => {
+        this.#wss.on("listening", () => {
+          resolve(this.#wss.address().port);
+        });
+      });
+    }
     this.#wss.on("connection", (socket) => {
       this.#onConnection(socket);
     });
@@ -1335,7 +1454,13 @@ var IrisTool = {
   /** Navigate the connected browser tab to a URL. */
   NAVIGATE: "iris_navigate",
   /** Reload the connected browser tab (soft or hard). */
-  REFRESH: "iris_refresh"
+  REFRESH: "iris_refresh",
+  /** Report running version, latest available, changelog, and breaking changes. */
+  VERSION_INFO: "iris_version_info",
+  /** Install the latest server version and restart (Claude Code reconnects automatically). */
+  APPLY_UPDATE: "iris_apply_update",
+  /** Restore the previous server version and restart. */
+  ROLLBACK: "iris_rollback"
 };
 
 // ../server/dist/project/iris-dir.js
@@ -1362,11 +1487,11 @@ function flowPath(root, name) {
 function isValidFlowName(name) {
   return FLOW_NAME_PATTERN.test(name) && !name.includes("..");
 }
-async function ensureIrisDir(fs, root) {
+async function ensureIrisDir(fs2, root) {
   const p = irisDirPaths(root);
-  await fs.mkdir(p.root);
-  await fs.mkdir(p.flows);
-  await fs.mkdir(p.baselines);
+  await fs2.mkdir(p.root);
+  await fs2.mkdir(p.flows);
+  await fs2.mkdir(p.baselines);
 }
 var JSON_INDENT = 2;
 function stableSerialize(capabilities, generatedAt) {
@@ -1383,21 +1508,21 @@ function stableSerialize(capabilities, generatedAt) {
   return `${JSON.stringify(envelope, null, JSON_INDENT)}
 `;
 }
-async function writeContract(fs, root, capabilities, now) {
-  await ensureIrisDir(fs, root);
-  await fs.writeFile(irisDirPaths(root).contract, stableSerialize(capabilities, now()));
+async function writeContract(fs2, root, capabilities, now) {
+  await ensureIrisDir(fs2, root);
+  await fs2.writeFile(irisDirPaths(root).contract, stableSerialize(capabilities, now()));
 }
-async function readContract(fs, root) {
+async function readContract(fs2, root) {
   const path = irisDirPaths(root).contract;
-  if (!await fs.exists(path))
+  if (!await fs2.exists(path))
     return { ok: false, reason: ContractReadError.MISSING };
   let text;
   try {
-    text = await fs.readFile(path);
+    text = await fs2.readFile(path);
   } catch (error) {
     return {
       ok: false,
-      reason: fs.isNotFound(error) ? ContractReadError.MISSING : ContractReadError.MALFORMED
+      reason: fs2.isNotFound(error) ? ContractReadError.MISSING : ContractReadError.MALFORMED
     };
   }
   let parsed;
@@ -1484,8 +1609,8 @@ var FlowStore = class {
   #fs;
   #root;
   #clock;
-  constructor(fs, root, clock) {
-    this.#fs = fs;
+  constructor(fs2, root, clock) {
+    this.#fs = fs2;
     this.#root = root;
     this.#clock = clock;
   }
@@ -1631,8 +1756,8 @@ var ProjectStore = class {
   #fs;
   #root;
   #clock;
-  constructor(fs, root, clock) {
-    this.#fs = fs;
+  constructor(fs2, root, clock) {
+    this.#fs = fs2;
     this.#root = root;
     this.#clock = clock;
   }
@@ -1811,10 +1936,10 @@ function createNodeFileSystem() {
 
 // ../server/dist/mcp.js
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 
 // ../server/dist/tools/tools.js
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 
 // ../server/dist/input/real-input.js
 var DriveError = class extends Error {
@@ -3423,8 +3548,8 @@ async function diffPng(baselineBytes, currentBytes, opts = {}) {
 var VisualStore = class {
   #fs;
   #root;
-  constructor(fs, root) {
-    this.#fs = fs;
+  constructor(fs2, root) {
+    this.#fs = fs2;
     this.#root = root;
   }
   /** The absolute baseline path for `name` (for echoing back to the agent). */
@@ -4050,6 +4175,266 @@ function withControl(session, result) {
   return control === void 0 ? result : { ...result, control };
 }
 
+// ../server/dist/update/update-tools.js
+import { z as z14 } from "zod";
+
+// ../server/dist/update/update-checker.js
+import * as fs from "fs";
+import * as https from "https";
+import { join as join2 } from "path";
+import { homedir } from "os";
+var IRIS_HOME = join2(homedir(), ".iris");
+var MANIFEST_PATH = join2(IRIS_HOME, "update-manifest.json");
+var NPM_REGISTRY = "https://registry.npmjs.org/@syrin/iris/latest";
+function loadManifest() {
+  if (!fs.existsSync(MANIFEST_PATH))
+    return null;
+  try {
+    const raw = fs.readFileSync(MANIFEST_PATH, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function saveManifest(manifest) {
+  fs.mkdirSync(IRIS_HOME, { recursive: true });
+  fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2), "utf8");
+}
+function isCacheFresh(manifest) {
+  const checked = new Date(manifest.lastChecked).getTime();
+  return Date.now() - checked < UpdateCheckIntervalMs;
+}
+function fetchNpmInfo() {
+  return new Promise((resolve, reject) => {
+    const req = https.get(NPM_REGISTRY, (res) => {
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => {
+        body += chunk;
+      });
+      res.on("end", () => {
+        try {
+          resolve(JSON.parse(body));
+        } catch (err) {
+          reject(err instanceof Error ? err : new Error(String(err)));
+        }
+      });
+      res.on("error", reject);
+    });
+    req.setTimeout(5e3, () => {
+      req.destroy();
+      reject(new Error("npm registry request timed out"));
+    });
+    req.on("error", reject);
+  });
+}
+async function checkForUpdate(currentVersion) {
+  const cached = loadManifest();
+  if (cached !== null && cached.currentVersion === currentVersion && isCacheFresh(cached)) {
+    return cached;
+  }
+  try {
+    const info = await fetchNpmInfo();
+    const updateAvailable = info.version !== currentVersion;
+    const manifest = {
+      currentVersion,
+      latestVersion: info.version,
+      updateAvailable,
+      lastChecked: (/* @__PURE__ */ new Date()).toISOString(),
+      ...info.iris?.changelog !== void 0 ? { changelog: info.iris.changelog } : {},
+      ...info.iris?.breakingChanges !== void 0 ? { breakingChanges: info.iris.breakingChanges } : {},
+      ...cached?.previousVersion !== void 0 ? { previousVersion: cached.previousVersion } : {}
+    };
+    saveManifest(manifest);
+    return manifest;
+  } catch (err) {
+    log("iris_update_check_failed", {
+      error: err instanceof Error ? err.message : String(err)
+    });
+    if (cached !== null)
+      return { ...cached, currentVersion };
+    return {
+      currentVersion,
+      updateAvailable: false,
+      lastChecked: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+}
+
+// ../server/dist/update/updater.js
+import { execFile } from "child_process";
+import { existsSync as existsSync2 } from "fs";
+import { platform } from "os";
+import { dirname, join as join3 } from "path";
+var NPM_BIN = platform() === "win32" ? "npm.cmd" : "npm";
+var NPM_TIMEOUT_MS = 12e4;
+var ExecutionKind = {
+  /** Launched via `npx @syrin/iris` — npm re-resolves the package on restart. */
+  NPX: "npx",
+  /** Installed globally via `npm install -g`. */
+  GLOBAL: "global",
+  /** Installed as a local project dependency. */
+  LOCAL: "local"
+};
+function detectExecutionKind() {
+  const script = process.argv[1] ?? "";
+  if (script.includes("/_npx/") || script.includes("\\_npx\\"))
+    return ExecutionKind.NPX;
+  if (script.includes("/node_modules/") || script.includes("\\node_modules\\")) {
+    return ExecutionKind.LOCAL;
+  }
+  return ExecutionKind.GLOBAL;
+}
+function findLocalProjectRoot() {
+  let dir = process.cwd();
+  for (; ; ) {
+    if (existsSync2(join3(dir, "package.json")))
+      return dir;
+    const parent = dirname(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+function runNpm(args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(NPM_BIN, args, { timeout: NPM_TIMEOUT_MS, ...opts.cwd !== void 0 ? { cwd: opts.cwd } : {} }, (err, _stdout, stderr) => {
+      if (err !== null) {
+        reject(new Error(`npm ${args.join(" ")} failed: ${stderr !== "" ? stderr : err.message}`));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+async function installVersion(version, kind) {
+  const pkg = `@syrin/iris@${version}`;
+  if (kind === ExecutionKind.NPX) {
+    log("iris_update_npx_strategy", {
+      note: "Running via npx \u2014 exiting so Claude Code restarts and npx fetches the new version"
+    });
+    return;
+  }
+  if (kind === ExecutionKind.LOCAL) {
+    const root = findLocalProjectRoot();
+    if (root !== null) {
+      await runNpm(["install", pkg], { cwd: root });
+      return;
+    }
+    log("iris_update_local_no_root", { fallback: "global" });
+  }
+  await runNpm(["install", "-g", pkg]);
+}
+async function installVersionRollback(version, kind) {
+  if (kind === ExecutionKind.NPX) {
+    log("iris_rollback_npx_strategy", {
+      note: "Running via npx \u2014 update your .mcp.json args to pin the version you want to restore"
+    });
+    return;
+  }
+  await installVersion(version, kind);
+}
+async function applyUpdate(targetVersion) {
+  const manifest = loadManifest();
+  if (manifest !== null) {
+    saveManifest({ ...manifest, previousVersion: manifest.currentVersion });
+  }
+  const kind = detectExecutionKind();
+  log("iris_update_applying", { version: targetVersion, executionKind: kind });
+  await installVersion(targetVersion, kind);
+  log("iris_update_applied", { version: targetVersion, executionKind: kind });
+  process.exit(0);
+}
+async function rollback() {
+  const manifest = loadManifest();
+  if (manifest === null || manifest.previousVersion === void 0) {
+    throw new Error("No previous version available for rollback");
+  }
+  const prev = manifest.previousVersion;
+  const kind = detectExecutionKind();
+  log("iris_rollback_applying", { version: prev, executionKind: kind });
+  await installVersionRollback(prev, kind);
+  log("iris_rollback_applied", { version: prev, executionKind: kind });
+  process.exit(0);
+}
+
+// ../server/dist/server-version.js
+import { createRequire } from "module";
+var _pkg = createRequire(import.meta.url)("../package.json");
+var SERVER_VERSION = _pkg.version;
+
+// ../server/dist/update/update-tools.js
+var UPDATE_TOOLS = [
+  {
+    name: IrisTool.VERSION_INFO,
+    description: "Returns the running Iris version, latest available version, release changelog, and any breaking changes. Call this at the start of a session or when unexpected tool behavior suggests a version mismatch.",
+    inputSchema: {},
+    outputSchema: {
+      currentVersion: z14.string().describe("The Iris server version currently running."),
+      latestVersion: z14.string().optional().describe("Latest published version on npm."),
+      updateAvailable: z14.boolean().describe("True when a newer version is available to install."),
+      executionKind: z14.string().describe('How iris was launched: "npx" (no install needed \u2014 restart applies update), "global" (npm install -g), or "local" (project node_modules).'),
+      changelog: z14.string().optional().describe("Release notes for the latest version."),
+      breakingChanges: z14.array(z14.string()).optional().describe("Breaking changes in the latest version that may affect your scripts."),
+      rollbackAvailable: z14.boolean().describe("True when a previous version is stored and can be restored."),
+      previousVersion: z14.string().optional().describe("The version that would be restored on rollback.")
+    },
+    handler: async (_deps) => {
+      const manifest = await checkForUpdate(SERVER_VERSION);
+      return {
+        currentVersion: manifest.currentVersion,
+        ...manifest.latestVersion !== void 0 ? { latestVersion: manifest.latestVersion } : {},
+        updateAvailable: manifest.updateAvailable,
+        executionKind: detectExecutionKind(),
+        ...manifest.changelog !== void 0 ? { changelog: manifest.changelog } : {},
+        ...manifest.breakingChanges !== void 0 ? { breakingChanges: manifest.breakingChanges } : {},
+        rollbackAvailable: manifest.previousVersion !== void 0,
+        ...manifest.previousVersion !== void 0 ? { previousVersion: manifest.previousVersion } : {}
+      };
+    }
+  },
+  {
+    name: IrisTool.APPLY_UPDATE,
+    description: 'Install the latest Iris server version and restart. Strategy depends on how iris was launched (check executionKind from iris_version_info): "global" and "local" installs run npm install then exit; "npx" just exits \u2014 Claude Code restarts and npx re-resolves the latest version from npm automatically. The MCP connection briefly drops during restart.',
+    inputSchema: {
+      confirm: z14.boolean().describe("Set to true to confirm the update should be applied. Required to prevent accidental upgrades.")
+    },
+    outputSchema: {
+      ok: z14.boolean(),
+      message: z14.string().optional()
+    },
+    handler: async (_deps, args) => {
+      if (args["confirm"] !== true) {
+        return { ok: false, message: "Set confirm:true to apply the update" };
+      }
+      const manifest = await checkForUpdate(SERVER_VERSION);
+      if (!manifest.updateAvailable || manifest.latestVersion === void 0) {
+        return { ok: false, message: "No update available \u2014 already on the latest version" };
+      }
+      await applyUpdate(manifest.latestVersion);
+      return { ok: true };
+    }
+  },
+  {
+    name: IrisTool.ROLLBACK,
+    description: "Restore the previous Iris server version and restart. Use when an update introduced a regression. The MCP connection will briefly drop \u2014 Claude Code restarts the process automatically with the restored binary.",
+    inputSchema: {
+      confirm: z14.boolean().describe("Set to true to confirm the rollback. Required to prevent accidental downgrades.")
+    },
+    outputSchema: {
+      ok: z14.boolean(),
+      message: z14.string().optional()
+    },
+    handler: async (_deps, args) => {
+      if (args["confirm"] !== true) {
+        return { ok: false, message: "Set confirm:true to apply the rollback" };
+      }
+      await rollback();
+      return { ok: true };
+    }
+  }
+];
+
 // ../server/dist/tools/tools.js
 async function snapshotTree(deps, sessionId) {
   const session = deps.sessions.resolve(sessionId);
@@ -4060,7 +4445,7 @@ async function snapshotTree(deps, sessionId) {
   return { lines: normalizeLines(snap.tree ?? ""), route: snap.status?.route ?? "" };
 }
 var sessionIdShape6 = {
-  sessionId: z14.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open \u2014 Iris resolves it automatically.")
+  sessionId: z15.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open \u2014 Iris resolves it automatically.")
 };
 async function commandOrThrow3(deps, sessionId, name, args) {
   const session = deps.sessions.resolve(sessionId);
@@ -4137,17 +4522,17 @@ var TOOLS = [
     description: "List connected browser sessions (tab url/title, sessionId, last-seen, health: hidden/focused/throttled, and `realInputAvailable` \u2014 true when native CDP/launched real input is driving this tab), plus a `recommendation` pointing to `iris drive` when a tab is hidden/throttled and may be un-scriptable from here.",
     inputSchema: {},
     outputSchema: {
-      sessions: z14.array(z14.object({
-        sessionId: z14.string(),
-        url: z14.string(),
-        title: z14.string().optional(),
-        lastSeenMs: z14.number(),
-        throttled: z14.boolean(),
-        focused: z14.boolean(),
-        hidden: z14.boolean(),
-        realInputAvailable: z14.boolean().optional(),
-        stale: z14.boolean().optional(),
-        recommendation: z14.string().optional()
+      sessions: z15.array(z15.object({
+        sessionId: z15.string(),
+        url: z15.string(),
+        title: z15.string().optional(),
+        lastSeenMs: z15.number(),
+        throttled: z15.boolean(),
+        focused: z15.boolean(),
+        hidden: z15.boolean(),
+        realInputAvailable: z15.boolean().optional(),
+        stale: z15.boolean().optional(),
+        recommendation: z15.string().optional()
       })).describe("Connected browser sessions with health state.")
     },
     handler: async (deps) => {
@@ -4163,13 +4548,13 @@ var TOOLS = [
     name: IrisTool.SNAPSHOT,
     description: "Semantic accessibility snapshot of the page or a subtree. mode: full|interactive|status. Use to see what is on screen right now.",
     inputSchema: {
-      scope: z14.string().optional().describe("CSS selector or element ref to restrict the snapshot to a subtree. Omit to snapshot the whole page."),
-      mode: z14.nativeEnum(SnapshotMode).optional().describe("full = all elements; interactive = only clickable/focusable elements; status = only route + title. Default: full."),
+      scope: z15.string().optional().describe("CSS selector or element ref to restrict the snapshot to a subtree. Omit to snapshot the whole page."),
+      mode: z15.nativeEnum(SnapshotMode).optional().describe("full = all elements; interactive = only clickable/focusable elements; status = only route + title. Default: full."),
       ...sessionIdShape6
     },
     outputSchema: {
-      tree: z14.string().optional().describe("Indented ARIA tree of every element on the page (or the scoped subtree)."),
-      status: z14.object({ route: z14.string(), title: z14.string().optional() }).optional()
+      tree: z15.string().optional().describe("Indented ARIA tree of every element on the page (or the scoped subtree)."),
+      status: z15.object({ route: z15.string(), title: z15.string().optional() }).optional()
     },
     handler: (deps, args) => commandOrThrow3(deps, asString4(args["sessionId"]), IrisCommand.SNAPSHOT, {
       scope: args["scope"],
@@ -4180,25 +4565,25 @@ var TOOLS = [
     name: IrisTool.QUERY,
     description: "Find elements by Testing-Library semantics. Pass `by` (role|text|label|placeholder|testid|alt) and `value` (the query string). Returns matching refs + descriptors + visibility. On zero matches, also returns hint:{ route, presentTestids[], knownEmptyState } so you can distinguish an empty state from a missing element WITHOUT taking a snapshot.",
     inputSchema: {
-      by: z14.string().describe("Query strategy: role | text | label | placeholder | testid | alt"),
-      value: z14.string().describe("Query value for the selected strategy (e.g. by=role value=button, or by=testid value=submit-btn)."),
-      name: z14.string().optional().describe("Accessible name filter \u2014 narrows results when `by` is role and the page has many elements of that role."),
-      scope: z14.string().optional().describe("CSS selector or element ref to restrict the search to a subtree."),
+      by: z15.string().describe("Query strategy: role | text | label | placeholder | testid | alt"),
+      value: z15.string().describe("Query value for the selected strategy (e.g. by=role value=button, or by=testid value=submit-btn)."),
+      name: z15.string().optional().describe("Accessible name filter \u2014 narrows results when `by` is role and the page has many elements of that role."),
+      scope: z15.string().optional().describe("CSS selector or element ref to restrict the search to a subtree."),
       ...sessionIdShape6
     },
     outputSchema: {
-      elements: z14.array(z14.object({
-        ref: z14.string(),
-        role: z14.string(),
-        name: z14.string(),
-        value: z14.string().optional(),
-        states: z14.array(z14.string()),
-        visible: z14.boolean()
+      elements: z15.array(z15.object({
+        ref: z15.string(),
+        role: z15.string(),
+        name: z15.string(),
+        value: z15.string().optional(),
+        states: z15.array(z15.string()),
+        visible: z15.boolean()
       })),
-      hint: z14.object({
-        route: z14.string(),
-        presentTestids: z14.array(z14.string()),
-        knownEmptyState: z14.boolean()
+      hint: z15.object({
+        route: z15.string(),
+        presentTestids: z15.array(z15.string()),
+        knownEmptyState: z15.boolean()
       }).optional().describe("Present only on zero matches \u2014 tells you what IS on the page so you can diagnose the miss.")
     },
     handler: (deps, args) => commandOrThrow3(deps, asString4(args["sessionId"]), IrisCommand.QUERY, {
@@ -4212,18 +4597,18 @@ var TOOLS = [
     name: IrisTool.INSPECT,
     description: "Deep info on one element by ref: full a11y props, visibility, box, and (with @syrin/iris-react) component stack + source file.",
     inputSchema: {
-      ref: z14.string().describe("Element ref from iris_snapshot or iris_query (e.g. 'e42')."),
+      ref: z15.string().describe("Element ref from iris_snapshot or iris_query (e.g. 'e42')."),
       ...sessionIdShape6
     },
     outputSchema: {
-      ref: z14.string(),
-      role: z14.string(),
-      name: z14.string(),
-      value: z14.string().optional(),
-      states: z14.array(z14.string()),
-      visible: z14.boolean(),
-      box: z14.object({ x: z14.number(), y: z14.number(), width: z14.number(), height: z14.number() }).optional(),
-      component: z14.object({ name: z14.string(), sourceFile: z14.string().optional() }).optional()
+      ref: z15.string(),
+      role: z15.string(),
+      name: z15.string(),
+      value: z15.string().optional(),
+      states: z15.array(z15.string()),
+      visible: z15.boolean(),
+      box: z15.object({ x: z15.number(), y: z15.number(), width: z15.number(), height: z15.number() }).optional(),
+      component: z15.object({ name: z15.string().optional(), sourceFile: z15.string().optional() }).optional()
     },
     handler: (deps, args) => commandOrThrow3(deps, asString4(args["sessionId"]), IrisCommand.INSPECT, {
       ref: args["ref"]
@@ -4233,19 +4618,19 @@ var TOOLS = [
     name: IrisTool.ACT,
     description: 'Execute one action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. Returns immediately with a `since` cursor \u2014 observe the reaction with iris_observe. Carries effect:{dispatched,targetMatched,visible,enabled,focusMoved,valueChanged,domMutatedWithin,occluded,occludedBy,scrolledIntoView} to tell "action missed" from "app didn\'t react"; dispatched=landed, settled=a real frame flushed, and a settle timeout never fails the tool. occluded=true means the click point is covered by another element (a real user could not click it) \u2014 synthetic dispatch still delivered the event; scrolledIntoView=true means an off-viewport target was scrolled in first. inputMode is "real" (native CDP, no synthetic effect block) or "synthetic"; clicks default to the occlusion-honest synthetic path even when CDP is configured \u2014 pass args.native:true to force a trusted native click (file pickers, clipboard). inputModeReason explains any real\u2192synthetic choice so it is never silent. Full model (real-input, throttled tabs, `iris drive`): docs/usage.md \xA718.',
     inputSchema: {
-      ref: z14.string().describe("Element ref from iris_snapshot or iris_query (e.g. 'e42')."),
-      action: z14.string().describe("Action to perform: click | dblclick | hover | focus | fill | type | clear | select | check | uncheck | submit | press | scrollIntoView"),
-      args: z14.record(z14.unknown()).optional().describe("Action-specific arguments: { value } for fill/select, { text } for type/press, { native: true } to force a trusted native click."),
-      refuseWhenThrottled: z14.boolean().optional().describe("Throw instead of silently sending synthetic events when the tab is throttled/backgrounded. Default: false (synthetic events are still sent)."),
+      ref: z15.string().describe("Element ref from iris_snapshot or iris_query (e.g. 'e42')."),
+      action: z15.string().describe("Action to perform: click | dblclick | hover | focus | fill | type | clear | select | check | uncheck | submit | press | scrollIntoView"),
+      args: z15.record(z15.unknown()).optional().describe("Action-specific arguments: { value } for fill/select, { text } for type/press, { native: true } to force a trusted native click."),
+      refuseWhenThrottled: z15.boolean().optional().describe("Throw instead of silently sending synthetic events when the tab is throttled/backgrounded. Default: false (synthetic events are still sent)."),
       ...sessionIdShape6
     },
     outputSchema: {
-      since: z14.number().describe("Cursor \u2014 pass to iris_observe/iris_wait_for/iris_assert to scope reaction queries to this act."),
-      dispatched: z14.boolean(),
-      settled: z14.boolean().nullable(),
-      inputMode: z14.string(),
-      result: z14.unknown().optional(),
-      session: z14.object({ lastSeenMs: z14.number(), throttled: z14.boolean(), focused: z14.boolean() }).optional()
+      since: z15.number().describe("Cursor \u2014 pass to iris_observe/iris_wait_for/iris_assert to scope reaction queries to this act."),
+      dispatched: z15.boolean(),
+      settled: z15.boolean().nullable(),
+      inputMode: z15.string(),
+      result: z15.unknown().optional(),
+      session: z15.object({ lastSeenMs: z15.number(), throttled: z15.boolean(), focused: z15.boolean() }).optional()
     },
     handler: async (deps, args) => {
       const session = deps.sessions.resolve(asString4(args["sessionId"]));
@@ -4301,14 +4686,14 @@ var TOOLS = [
     name: IrisTool.ACT_SEQUENCE,
     description: "Run multiple actions in order (fill -> fill -> submit) in one round-trip. Returns per-step effects[] (see iris_act).",
     inputSchema: {
-      steps: z14.array(z14.record(z14.unknown())).describe("Ordered list of { ref, action, args? } objects. Each step is equivalent to one iris_act call."),
+      steps: z15.array(z15.record(z15.unknown())).describe("Ordered list of { ref, action, args? } objects. Each step is equivalent to one iris_act call."),
       ...sessionIdShape6
     },
     outputSchema: {
-      since: z14.number(),
-      dispatched: z14.boolean(),
-      result: z14.unknown().optional(),
-      session: z14.object({ lastSeenMs: z14.number(), throttled: z14.boolean(), focused: z14.boolean() }).optional()
+      since: z15.number(),
+      dispatched: z15.boolean(),
+      result: z15.unknown().optional(),
+      session: z15.object({ lastSeenMs: z15.number(), throttled: z15.boolean(), focused: z15.boolean() }).optional()
     },
     handler: async (deps, args) => {
       const session = deps.sessions.resolve(asString4(args["sessionId"]));
@@ -4336,23 +4721,23 @@ var TOOLS = [
     name: IrisTool.ACT_AND_WAIT,
     description: "Act on a ref, then wait for a predicate to hold \u2014 one hop for the act->observe->assert loop. Returns { effect } (the action result), { verdict } (predicate pass/evidence/near-miss), and { trace } (the reaction report of everything the app did after the action). timeout_ms 0 evaluates the predicate once without waiting.",
     inputSchema: {
-      ref: z14.string().describe("Element ref from iris_snapshot or iris_query."),
-      action: z14.string().describe("Action to perform: click | dblclick | hover | focus | fill | type | clear | select | check | uncheck | submit | press | scrollIntoView"),
-      args: z14.record(z14.unknown()).optional().describe("Action-specific arguments: { value } for fill/select, { text } for type/press."),
+      ref: z15.string().describe("Element ref from iris_snapshot or iris_query."),
+      action: z15.string().describe("Action to perform: click | dblclick | hover | focus | fill | type | clear | select | check | uncheck | submit | press | scrollIntoView"),
+      args: z15.record(z15.unknown()).optional().describe("Action-specific arguments: { value } for fill/select, { text } for type/press."),
       until: PredicateSchema.describe("Predicate to wait for after the action completes. Same shape accepted by iris_assert."),
-      timeout_ms: z14.number().optional().describe("Maximum wait time in milliseconds. 0 = evaluate once without waiting. Default: 4000."),
-      refuseWhenThrottled: z14.boolean().optional().describe("Throw if the tab is throttled. Default: false."),
+      timeout_ms: z15.number().optional().describe("Maximum wait time in milliseconds. 0 = evaluate once without waiting. Default: 4000."),
+      refuseWhenThrottled: z15.boolean().optional().describe("Throw if the tab is throttled. Default: false."),
       ...sessionIdShape6
     },
     outputSchema: {
-      effect: z14.unknown().describe("The iris_act result (dispatched, settled, inputMode, etc.)."),
-      verdict: z14.object({
-        pass: z14.boolean(),
-        evidence: z14.unknown().optional(),
-        failureReason: z14.string().optional()
+      effect: z15.unknown().describe("The iris_act result (dispatched, settled, inputMode, etc.)."),
+      verdict: z15.object({
+        pass: z15.boolean(),
+        evidence: z15.unknown().optional(),
+        failureReason: z15.string().optional()
       }),
-      trace: z14.unknown().describe("Reaction report (same shape as iris_observe summary)."),
-      session: z14.object({ lastSeenMs: z14.number(), throttled: z14.boolean(), focused: z14.boolean() }).optional()
+      trace: z15.unknown().describe("Reaction report (same shape as iris_observe summary)."),
+      session: z15.object({ lastSeenMs: z15.number(), throttled: z15.boolean(), focused: z15.boolean() }).optional()
     },
     handler: async (deps, args) => {
       const session = deps.sessions.resolve(asString4(args["sessionId"]));
@@ -4385,31 +4770,31 @@ var TOOLS = [
     name: IrisTool.OBSERVE,
     description: "Return the timeline of everything the app did in a window (DOM/network/route/console/animation/signal), with a summary. Use after an action. Pass `max_events` to cap the timeline to the most recent N (older events are dropped and counted in cost.droppedOldest). Every result carries a `cost:{events,bytes}` hint so you can self-budget your next call.",
     inputSchema: {
-      window_ms: z14.number().optional().describe("Time window to look back. Default: 2000ms. Ignored when `since` is provided."),
-      since: z14.number().optional().describe("Cursor from a prior iris_act or iris_observe call. Scopes the event window to exactly that span."),
-      filters: z14.array(z14.string()).optional().describe("Event type allowlist: dom | net | route | console | animation | signal. Omit to return all types."),
-      max_events: z14.number().optional().describe("Cap the timeline to the most recent N events. Older events are counted in cost.droppedOldest."),
+      window_ms: z15.number().optional().describe("Time window to look back. Default: 2000ms. Ignored when `since` is provided."),
+      since: z15.number().optional().describe("Cursor from a prior iris_act or iris_observe call. Scopes the event window to exactly that span."),
+      filters: z15.array(z15.string()).optional().describe("Event type allowlist: dom | net | route | console | animation | signal. Omit to return all types."),
+      max_events: z15.number().optional().describe("Cap the timeline to the most recent N events. Older events are counted in cost.droppedOldest."),
       ...sessionIdShape6
     },
     outputSchema: {
-      events: z14.array(z14.unknown()),
-      summary: z14.object({
-        total: z14.number(),
-        network: z14.number(),
-        domAdded: z14.number(),
-        domRemoved: z14.number(),
-        domChanged: z14.number(),
-        routeChanges: z14.number(),
-        consoleErrors: z14.number(),
-        animations: z14.number(),
-        signals: z14.number()
+      events: z15.array(z15.unknown()),
+      summary: z15.object({
+        total: z15.number(),
+        network: z15.number(),
+        domAdded: z15.number(),
+        domRemoved: z15.number(),
+        domChanged: z15.number(),
+        routeChanges: z15.number(),
+        consoleErrors: z15.number(),
+        animations: z15.number(),
+        signals: z15.number()
       }),
-      cost: z14.object({
-        events: z14.number(),
-        bytes: z14.number(),
-        droppedOldest: z14.number().optional()
+      cost: z15.object({
+        events: z15.number(),
+        bytes: z15.number(),
+        droppedOldest: z15.number().optional()
       }),
-      session: z14.object({ lastSeenMs: z14.number(), throttled: z14.boolean(), focused: z14.boolean() }).optional()
+      session: z15.object({ lastSeenMs: z15.number(), throttled: z15.boolean(), focused: z15.boolean() }).optional()
     },
     handler: (deps, args) => {
       const session = deps.sessions.resolve(asString4(args["sessionId"]));
@@ -4432,15 +4817,15 @@ var TOOLS = [
     description: "Block until a predicate is satisfied (or already true in the recent buffer), else time out. Returns matching evidence or a near-miss diagnosis. By default it only counts events since your last act, so a signal buffered BEFORE the action can never fake a pass; pass `since` (an observe/act cursor) to widen or narrow that window explicitly.",
     inputSchema: {
       predicate: PredicateSchema.describe("Predicate to wait for: { signal }, { net }, { element } or a combination."),
-      timeout_ms: z14.number().optional().describe("Maximum wait in milliseconds. Default: 4000."),
-      since: z14.number().optional().describe("Cursor from a prior iris_act \u2014 scopes the wait to events after that act."),
+      timeout_ms: z15.number().optional().describe("Maximum wait in milliseconds. Default: 4000."),
+      since: z15.number().optional().describe("Cursor from a prior iris_act \u2014 scopes the wait to events after that act."),
       ...sessionIdShape6
     },
     outputSchema: {
-      pass: z14.boolean(),
-      evidence: z14.unknown().optional(),
-      failureReason: z14.string().optional(),
-      session: z14.object({ lastSeenMs: z14.number(), throttled: z14.boolean(), focused: z14.boolean() }).optional()
+      pass: z15.boolean(),
+      evidence: z15.unknown().optional(),
+      failureReason: z15.string().optional(),
+      session: z15.object({ lastSeenMs: z15.number(), throttled: z15.boolean(), focused: z15.boolean() }).optional()
     },
     handler: async (deps, args) => {
       const session = deps.sessions.resolve(asString4(args["sessionId"]));
@@ -4455,15 +4840,15 @@ var TOOLS = [
     description: "Evaluate a predicate (optionally waiting up to timeout_ms). Returns { pass, evidence, failureReason? }. The end of every verify loop. By default it only counts events since your last act, so a stale buffered signal can never fake a pass; pass `since` (an observe/act cursor) to set the window explicitly.",
     inputSchema: {
       predicate: PredicateSchema.describe("Predicate to evaluate: { signal }, { net }, { element } or a combination."),
-      timeout_ms: z14.number().optional().describe("If > 0, wait up to this many milliseconds before failing. Default: 0 (evaluate once)."),
-      since: z14.number().optional().describe("Cursor from a prior iris_act \u2014 scopes the assertion to events after that act."),
+      timeout_ms: z15.number().optional().describe("If > 0, wait up to this many milliseconds before failing. Default: 0 (evaluate once)."),
+      since: z15.number().optional().describe("Cursor from a prior iris_act \u2014 scopes the assertion to events after that act."),
       ...sessionIdShape6
     },
     outputSchema: {
-      pass: z14.boolean(),
-      evidence: z14.unknown().optional(),
-      failureReason: z14.string().optional(),
-      session: z14.object({ lastSeenMs: z14.number(), throttled: z14.boolean(), focused: z14.boolean() }).optional()
+      pass: z15.boolean(),
+      evidence: z15.unknown().optional(),
+      failureReason: z15.string().optional(),
+      session: z15.object({ lastSeenMs: z15.number(), throttled: z15.boolean(), focused: z15.boolean() }).optional()
     },
     handler: async (deps, args) => {
       const session = deps.sessions.resolve(asString4(args["sessionId"]));
@@ -4478,15 +4863,15 @@ var TOOLS = [
     name: IrisTool.NETWORK,
     description: 'Filtered list of network calls. Fast path for "did POST /x return 200?". A zero-match filter returns a `hint` { totalInWindow, present[] } of the calls that DID fire, so a miss is diagnosable.',
     inputSchema: {
-      since: z14.number().optional().describe("Cursor from a prior iris_act \u2014 scopes the query to requests fired after that act."),
-      method: z14.string().optional().describe("HTTP method filter: GET | POST | PUT | DELETE | PATCH etc."),
-      urlContains: z14.string().optional().describe("Substring that the request URL must contain."),
-      status: z14.number().optional().describe("HTTP status code filter (e.g. 200, 404, 500)."),
+      since: z15.number().optional().describe("Cursor from a prior iris_act \u2014 scopes the query to requests fired after that act."),
+      method: z15.string().optional().describe("HTTP method filter: GET | POST | PUT | DELETE | PATCH etc."),
+      urlContains: z15.string().optional().describe("Substring that the request URL must contain."),
+      status: z15.number().optional().describe("HTTP status code filter (e.g. 200, 404, 500)."),
       ...sessionIdShape6
     },
     outputSchema: {
-      calls: z14.array(z14.unknown()),
-      hint: z14.object({ totalInWindow: z14.number(), present: z14.array(z14.string()) }).optional()
+      calls: z15.array(z15.unknown()),
+      hint: z15.object({ totalInWindow: z15.number(), present: z15.array(z15.string()) }).optional()
     },
     handler: (deps, args) => {
       const session = deps.sessions.resolve(asString4(args["sessionId"]));
@@ -4506,13 +4891,13 @@ var TOOLS = [
     name: IrisTool.CONSOLE,
     description: 'Console/error log. Fast path for "were there any errors during this flow?". When a level filter matches nothing, returns a `hint` { totalInWindow, byLevel } so 0 errors is distinguishable from a silent page.',
     inputSchema: {
-      level: z14.string().optional().describe("Log level filter: error | warn | info | log. Omit to return all levels."),
-      since: z14.number().optional().describe("Cursor from a prior iris_act \u2014 scopes the query to log entries after that act."),
+      level: z15.string().optional().describe("Log level filter: error | warn | info | log. Omit to return all levels."),
+      since: z15.number().optional().describe("Cursor from a prior iris_act \u2014 scopes the query to log entries after that act."),
       ...sessionIdShape6
     },
     outputSchema: {
-      logs: z14.array(z14.unknown()),
-      hint: z14.object({ totalInWindow: z14.number(), byLevel: z14.record(z14.number()) }).optional()
+      logs: z15.array(z15.unknown()),
+      hint: z15.object({ totalInWindow: z15.number(), byLevel: z15.record(z15.number()) }).optional()
     },
     handler: (deps, args) => {
       const session = deps.sessions.resolve(asString4(args["sessionId"]));
@@ -4531,7 +4916,7 @@ var TOOLS = [
     description: "Currently running + recently completed animations with targets/timing.",
     inputSchema: { ...sessionIdShape6 },
     outputSchema: {
-      animations: z14.array(z14.unknown())
+      animations: z15.array(z15.unknown())
     },
     handler: (deps, args) => commandOrThrow3(deps, asString4(args["sessionId"]), IrisCommand.ANIMATIONS, {})
   },
@@ -4539,12 +4924,12 @@ var TOOLS = [
     name: IrisTool.BASELINE_SAVE,
     description: "Snapshot the current semantic state under a name, to diff against later (regression detection).",
     inputSchema: {
-      name: z14.string().describe('Label for this baseline snapshot (e.g. "dashboard-initial"). Use the same name in iris_diff to compare.'),
+      name: z15.string().describe('Label for this baseline snapshot (e.g. "dashboard-initial"). Use the same name in iris_diff to compare.'),
       ...sessionIdShape6
     },
     outputSchema: {
-      baseline: z14.string().describe("Saved baseline name \u2014 pass to iris_diff to compare."),
-      lineCount: z14.number()
+      baseline: z15.string().describe("Saved baseline name \u2014 pass to iris_diff to compare."),
+      lineCount: z15.number()
     },
     handler: async (deps, args) => {
       const name = asString4(args["name"]) ?? "default";
@@ -4558,7 +4943,7 @@ var TOOLS = [
     description: "List saved baseline names.",
     inputSchema: {},
     outputSchema: {
-      baselines: z14.array(z14.string())
+      baselines: z15.array(z15.string())
     },
     handler: (deps) => Promise.resolve({ baselines: deps.baselines.list() })
   },
@@ -4566,15 +4951,15 @@ var TOOLS = [
     name: IrisTool.DIFF,
     description: 'Diff current semantic state vs a saved baseline: REMOVED/ADDED elements + console-error count. Call iris_baseline_list to list saved baselines, iris_baseline_save to create one. Pass `baseline` (name from iris_baseline_list). Answers "did anything silently go missing/break?".',
     inputSchema: {
-      baseline: z14.string().describe("Baseline name to compare against. Call iris_baseline_list to get available names; names are created by iris_baseline_save."),
+      baseline: z15.string().describe("Baseline name to compare against. Call iris_baseline_list to get available names; names are created by iris_baseline_save."),
       ...sessionIdShape6
     },
     outputSchema: {
-      baseline: z14.string(),
-      removed: z14.array(z14.string()),
-      added: z14.array(z14.string()),
-      consoleErrors: z14.number(),
-      routeChanged: z14.boolean()
+      baseline: z15.string(),
+      removed: z15.array(z15.string()),
+      added: z15.array(z15.string()),
+      consoleErrors: z15.number(),
+      routeChanged: z15.boolean()
     },
     handler: async (deps, args) => {
       const name = asString4(args["baseline"]) ?? "default";
@@ -4592,12 +4977,12 @@ var TOOLS = [
     name: IrisTool.RECORD_START,
     description: "Start recording the event timeline under a name (for replay / a flow report).",
     inputSchema: {
-      recordingName: z14.string().describe("Identifier for this recording. Pass the same name to iris_record_stop and iris_replay."),
+      recordingName: z15.string().describe("Identifier for this recording. Pass the same name to iris_record_stop and iris_replay."),
       ...sessionIdShape6
     },
     outputSchema: {
-      recordingName: z14.string(),
-      since: z14.number()
+      recordingName: z15.string(),
+      since: z15.number()
     },
     handler: (deps, args) => {
       const session = deps.sessions.resolve(asString4(args["sessionId"]));
@@ -4611,13 +4996,13 @@ var TOOLS = [
     name: IrisTool.RECORD_STOP,
     description: "Stop the recording identified by `recordingName` and return both the reaction report for the span and a compiled, replayable { program: { version, steps:[{tool,args,stable}] } } of the agent acts captured during it.",
     inputSchema: {
-      recordingName: z14.string().describe("Identifier of an active recording started with iris_record_start."),
+      recordingName: z15.string().describe("Identifier of an active recording started with iris_record_start."),
       ...sessionIdShape6
     },
     outputSchema: {
-      recordingName: z14.string(),
-      program: z14.unknown(),
-      warning: z14.string().optional()
+      recordingName: z15.string(),
+      program: z15.unknown(),
+      warning: z15.string().optional()
     },
     handler: (deps, args) => {
       const session = deps.sessions.resolve(asString4(args["sessionId"]));
@@ -4649,17 +5034,17 @@ var TOOLS = [
     name: IrisTool.REPLAY,
     description: "Re-execute a previously recorded program by recordingName. Re-resolves each step to its element by testid (falling back to the stored ref for unstable steps) and runs the actions in order against the live session. Stops at the first failure. Returns { ok, steps:[{tool,ok,error?,note?}] }.",
     inputSchema: {
-      recordingName: z14.string().describe("Name of a compiled recording (from iris_record_stop) to re-execute."),
+      recordingName: z15.string().describe("Name of a compiled recording (from iris_record_stop) to re-execute."),
       ...sessionIdShape6
     },
     outputSchema: {
-      recordingName: z14.string(),
-      ok: z14.boolean(),
-      steps: z14.array(z14.object({
-        tool: z14.string(),
-        ok: z14.boolean(),
-        error: z14.string().optional(),
-        note: z14.string().optional()
+      recordingName: z15.string(),
+      ok: z15.boolean(),
+      steps: z15.array(z15.object({
+        tool: z15.string(),
+        ok: z15.boolean(),
+        error: z15.string().optional(),
+        note: z15.string().optional()
       }))
     },
     handler: async (deps, args) => {
@@ -4677,30 +5062,31 @@ var TOOLS = [
     name: IrisTool.NARRATE,
     description: "Narrate your intent on the page (presenter HUD) so the human watching sees what you are about to do and why. Use a short sentence before a meaningful action.",
     inputSchema: {
-      text: z14.string().describe("Short sentence describing your next action, shown on the presenter HUD for the developer watching."),
-      level: z14.string().optional().describe("Display severity: info | warn | error. Default: info."),
+      text: z15.string().describe("Short sentence describing your next action, shown on the presenter HUD for the developer watching."),
+      level: z15.string().optional().describe("Display severity: info | warn | error. Default: info."),
       ...sessionIdShape6
     },
-    outputSchema: {
-      ok: z14.boolean()
-    },
-    handler: (deps, args) => commandOrThrow3(deps, asString4(args["sessionId"]), IrisCommand.NARRATE, {
-      text: args["text"],
-      level: args["level"]
-    })
+    outputSchema: { ok: z15.boolean() },
+    handler: async (deps, args) => {
+      const result = await commandOrThrow3(deps, asString4(args["sessionId"]), IrisCommand.NARRATE, {
+        text: args["text"],
+        level: args["level"]
+      });
+      return { ok: true, ...result };
+    }
   },
   {
     name: IrisTool.CLOCK,
     description: "Control a fake clock: { freeze:true } to freeze time, { advanceMs:N } to fast-forward timers (toasts, debounces, auto-dismiss), { reset:true } to restore. Lets you test time-gated UI deterministically.",
     inputSchema: {
-      freeze: z14.boolean().optional().describe("Freeze the fake clock. Time stops advancing until advanceMs or reset."),
-      advanceMs: z14.number().optional().describe("Fast-forward time by this many milliseconds \u2014 triggers debounces, toasts, auto-dismiss timers."),
-      reset: z14.boolean().optional().describe("Restore the real clock."),
+      freeze: z15.boolean().optional().describe("Freeze the fake clock. Time stops advancing until advanceMs or reset."),
+      advanceMs: z15.number().optional().describe("Fast-forward time by this many milliseconds \u2014 triggers debounces, toasts, auto-dismiss timers."),
+      reset: z15.boolean().optional().describe("Restore the real clock."),
       ...sessionIdShape6
     },
     outputSchema: {
-      ok: z14.boolean(),
-      elapsed: z14.number().optional()
+      ok: z15.boolean().optional(),
+      elapsed: z15.number().optional()
     },
     handler: (deps, args) => commandOrThrow3(deps, asString4(args["sessionId"]), IrisCommand.CLOCK, {
       freeze: args["freeze"],
@@ -4712,18 +5098,18 @@ var TOOLS = [
     name: IrisTool.STATE,
     description: "Read live framework state without the app pre-broadcasting it. PREFERRED/RELIABLE: `store` reads a registered store (e.g. 'workspace'); omit `store` to read all stores. To avoid paying for a huge store, scope the read: `path` extracts a dot-path sub-tree (e.g. 'captionCache.v3', with numeric array indices), and `depth` collapses anything deeper than N levels to a size marker. A wrong `path` returns { found:false, availableKeys } so it is diagnosable. `ref` attempts a best-effort read of the nearest React component's hook state and is BOUNDED \u2014 on failure it returns component: { ok: false, reason: 'component-state-unavailable' }. Without path/depth: returns { stores, storeNames, component? }.",
     inputSchema: {
-      ref: z14.string().optional().describe("Element ref \u2014 attempts a best-effort read of the nearest React component's hook state."),
-      store: z14.string().optional().describe("Registered store name (e.g. 'workspace'). Omit to read all stores."),
-      path: z14.string().optional().describe("Dot-path into the store (e.g. 'captionCache.v3'). Numeric array indices are supported."),
-      depth: z14.number().optional().describe("Collapse anything deeper than N levels to a size marker \u2014 avoids huge outputs for large stores."),
+      ref: z15.string().optional().describe("Element ref \u2014 attempts a best-effort read of the nearest React component's hook state."),
+      store: z15.string().optional().describe("Registered store name (e.g. 'workspace'). Omit to read all stores."),
+      path: z15.string().optional().describe("Dot-path into the store (e.g. 'captionCache.v3'). Numeric array indices are supported."),
+      depth: z15.number().optional().describe("Collapse anything deeper than N levels to a size marker \u2014 avoids huge outputs for large stores."),
       ...sessionIdShape6
     },
     outputSchema: {
-      stores: z14.record(z14.unknown()).optional(),
-      storeNames: z14.array(z14.string()).optional(),
-      found: z14.boolean().optional(),
-      value: z14.unknown().optional(),
-      component: z14.object({ ok: z14.boolean(), reason: z14.string().optional(), state: z14.unknown().optional() }).optional()
+      stores: z15.record(z15.unknown()).optional(),
+      storeNames: z15.array(z15.string()).optional(),
+      found: z15.boolean().optional(),
+      value: z15.unknown().optional(),
+      component: z15.object({ ok: z15.boolean(), reason: z15.string().optional(), state: z15.unknown().optional() }).optional()
     },
     handler: async (deps, args) => {
       const store = asString4(args["store"]);
@@ -4752,13 +5138,13 @@ var TOOLS = [
     name: IrisTool.EXPLORE,
     description: "Autonomous-exploration helper: list interactive elements (with refs) + current console-error count, so the agent can drive the app and report anomalies.",
     inputSchema: {
-      scope: z14.string().optional().describe("CSS selector or element ref to restrict the interactive element list to a subtree."),
+      scope: z15.string().optional().describe("CSS selector or element ref to restrict the interactive element list to a subtree."),
       ...sessionIdShape6
     },
     outputSchema: {
-      interactive: z14.array(z14.unknown()),
-      consoleErrors: z14.number(),
-      hint: z14.string()
+      interactive: z15.array(z15.unknown()),
+      consoleErrors: z15.number(),
+      hint: z15.string()
     },
     handler: async (deps, args) => {
       const session = deps.sessions.resolve(asString4(args["sessionId"]));
@@ -4796,7 +5182,9 @@ var TOOLS = [
   // Live-control: iris_end_session / iris_resume / iris_messages. See live-control-tools.ts.
   ...LIVE_CONTROL_TOOLS,
   // iris_navigate / iris_refresh — browser navigation tools. See browser-tools.ts.
-  ...BROWSER_TOOLS
+  ...BROWSER_TOOLS,
+  // iris_version_info / iris_apply_update / iris_rollback — update lifecycle tools.
+  ...UPDATE_TOOLS
 ];
 
 // ../server/dist/tools/profiles.js
@@ -4942,7 +5330,7 @@ async function runTool(tool, deps, args) {
 }
 
 // ../server/dist/mcp.js
-var SERVER_INFO = { name: "iris", version: "0.3.10" };
+var SERVER_INFO = { name: "iris", version: SERVER_VERSION };
 var ENCODING_ENV = "IRIS_ENCODING";
 var TOON_VALUE = "toon";
 function encodeResult(result, useToon) {
@@ -5043,6 +5431,55 @@ var SessionReaper = class {
   }
 };
 
+// ../server/dist/daemon.js
+import { join as join4 } from "path";
+import { homedir as homedir2 } from "os";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync3, unlinkSync, openSync } from "fs";
+import { spawn } from "child_process";
+var IRIS_HOME2 = join4(homedir2(), ".iris");
+function pidPath(port) {
+  return join4(IRIS_HOME2, `daemon-${port}.pid`);
+}
+function logPath(port) {
+  return join4(IRIS_HOME2, `daemon-${port}.log`);
+}
+function readPid(port) {
+  const path = pidPath(port);
+  if (!existsSync3(path))
+    return null;
+  const n = parseInt(readFileSync2(path, "utf8").trim(), 10);
+  return isNaN(n) ? null : n;
+}
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function removePid(port) {
+  const path = pidPath(port);
+  if (existsSync3(path))
+    unlinkSync(path);
+}
+function isRunning(port) {
+  const pid = readPid(port);
+  return pid !== null && isAlive(pid);
+}
+function spawnDaemon(nodeExec, scriptPath, args, port) {
+  mkdirSync2(IRIS_HOME2, { recursive: true });
+  const fd = openSync(logPath(port), "a");
+  const child = spawn(nodeExec, [scriptPath, ...args], {
+    detached: true,
+    stdio: ["ignore", fd, fd]
+  });
+  if (child.pid !== void 0) {
+    writeFileSync2(pidPath(port), String(child.pid), "utf8");
+  }
+  child.unref();
+}
+
 // ../server/dist/index.js
 async function start(options = {}) {
   const port = options.port ?? IRIS_DEFAULT_PORT;
@@ -5075,11 +5512,11 @@ async function start(options = {}) {
     }
   }
   if (options.mcp !== false) {
-    const fs = createNodeFileSystem();
-    const irisRoot = options.irisRoot ?? join2(process.cwd(), IrisDir.ROOT);
+    const fs2 = createNodeFileSystem();
+    const irisRoot = options.irisRoot ?? join5(process.cwd(), IrisDir.ROOT);
     const now = options.now ?? (() => Date.now());
-    const flows = new FlowStore(fs, irisRoot, { now });
-    const project = new ProjectStore(fs, irisRoot, { now });
+    const flows = new FlowStore(fs2, irisRoot, { now });
+    const project = new ProjectStore(fs2, irisRoot, { now });
     const annotations = new AnnotationStore();
     const deps = {
       sessions: bridge.sessions,
@@ -5088,7 +5525,7 @@ async function start(options = {}) {
       annotations,
       flows,
       project,
-      fs,
+      fs: fs2,
       irisRoot,
       now
     };
@@ -5110,42 +5547,455 @@ async function start(options = {}) {
     }
   };
 }
+async function startDaemon(options = {}) {
+  const port = options.port ?? IRIS_DEFAULT_PORT;
+  const shared = createSharedServer();
+  const bridge = new Bridge({ port, server: shared.httpServer });
+  const reaper = new SessionReaper(bridge.sessions);
+  reaper.start();
+  let owned;
+  let realInput;
+  const driveUrl = options.driveUrl;
+  if (driveUrl !== void 0 && driveUrl.length > 0) {
+    const headless = options.headless ?? true;
+    const factory = options.realInputFactory ?? ((opts) => new LaunchedRealInputProvider({ driveUrl: opts.driveUrl, headless: opts.headless }));
+    const launched = factory({ driveUrl, headless });
+    try {
+      await launched.navigate();
+    } catch (error) {
+      await shared.close();
+      throw error;
+    }
+    owned = launched;
+    realInput = launched;
+  } else {
+    const cdpUrl = options.cdpUrl ?? process.env["IRIS_CDP_URL"];
+    if (cdpUrl !== void 0 && cdpUrl.length > 0) {
+      const cdp = new CdpRealInputProvider({ cdpUrl });
+      owned = cdp;
+      realInput = cdp;
+    }
+  }
+  const fs2 = createNodeFileSystem();
+  const irisRoot = options.irisRoot ?? join5(process.cwd(), IrisDir.ROOT);
+  const now = options.now ?? (() => Date.now());
+  const flows = new FlowStore(fs2, irisRoot, { now });
+  const project = new ProjectStore(fs2, irisRoot, { now });
+  const annotations = new AnnotationStore();
+  const deps = {
+    sessions: bridge.sessions,
+    baselines: new BaselineStore(),
+    recordings: new RecordingStore(),
+    annotations,
+    flows,
+    project,
+    fs: fs2,
+    irisRoot,
+    now
+  };
+  const profile = resolveToolProfile(options.toolProfile);
+  const effectiveDeps = realInput !== void 0 ? { ...deps, realInput } : deps;
+  shared.attachMcp(() => createMcpServer(effectiveDeps, profile));
+  await new Promise((resolve) => {
+    shared.httpServer.once("listening", resolve);
+    shared.httpServer.listen(port, "127.0.0.1");
+  });
+  log("mcp_daemon_started", { port });
+  return {
+    bridge,
+    ...realInput !== void 0 ? { realInput } : {},
+    close: async () => {
+      reaper.stop();
+      await owned?.dispose();
+      await bridge.close();
+      await shared.close();
+    }
+  };
+}
+
+// ../server/dist/mcp-proxy.js
+import * as http3 from "http";
+import * as net from "net";
+var DAEMON_READY_TIMEOUT_MS = 1e4;
+var DAEMON_POLL_INTERVAL_MS = 100;
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function probeDaemon(port) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    socket.setTimeout(500);
+    socket.on("connect", () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.on("error", () => resolve(false));
+    socket.on("timeout", () => {
+      socket.destroy();
+      resolve(false);
+    });
+    socket.connect(port, "127.0.0.1");
+  });
+}
+async function waitForDaemon(port) {
+  const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const reachable = await probeDaemon(port);
+    if (reachable)
+      return;
+    await delay(DAEMON_POLL_INTERVAL_MS);
+  }
+  throw new Error(`iris daemon did not become ready on port ${port} within ${DAEMON_READY_TIMEOUT_MS}ms`);
+}
+function postToSession(url, body) {
+  return new Promise((resolve) => {
+    const parsed = new URL(url);
+    const bodyBuf = Buffer.from(body, "utf8");
+    const options = {
+      host: parsed.hostname,
+      port: parsed.port !== "" ? parseInt(parsed.port, 10) : 80,
+      path: `${parsed.pathname}${parsed.search}`,
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Content-Length": bodyBuf.byteLength
+      }
+    };
+    const req = http3.request(options, (res) => {
+      res.resume();
+      resolve();
+    });
+    req.on("error", (err) => {
+      log("iris_mcp_proxy_post_error", { error: err.message });
+      resolve();
+    });
+    req.write(bodyBuf);
+    req.end();
+  });
+}
+function buildSessionUrl(rawData, port) {
+  return rawData.startsWith("/") ? `http://127.0.0.1:${port}${rawData}` : rawData;
+}
+function startMcpProxy(port) {
+  return new Promise((_resolve, reject) => {
+    let postUrl = null;
+    const stdinQueue = [];
+    const req = http3.get({ host: "127.0.0.1", port, path: MCP_SSE_PATH }, (res) => {
+      res.setEncoding("utf8");
+      let sseBuffer = "";
+      let currentEvent = "";
+      let currentData = "";
+      res.on("data", (chunk) => {
+        sseBuffer += chunk;
+        const normalised = sseBuffer.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+        const lines = normalised.split("\n");
+        sseBuffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (line === "") {
+            if (currentData !== "") {
+              onSseEvent(currentEvent !== "" ? currentEvent : "message", currentData, port);
+            }
+            currentEvent = "";
+            currentData = "";
+          } else if (line.startsWith("event:")) {
+            currentEvent = line.slice(6).trim();
+          } else if (line.startsWith("data:")) {
+            const val = line.slice(5).trim();
+            currentData = currentData !== "" ? `${currentData}
+${val}` : val;
+          }
+        }
+      });
+      res.on("end", () => {
+        log("iris_mcp_proxy_sse_ended", { port });
+        process.exit(0);
+      });
+      res.on("error", (err) => {
+        log("iris_mcp_proxy_sse_error", { error: err.message });
+        process.exit(1);
+      });
+    });
+    req.on("error", (err) => reject(err));
+    function onSseEvent(event, data, p) {
+      if (event === "endpoint") {
+        const url = buildSessionUrl(data, p);
+        postUrl = url;
+        for (const queued of stdinQueue.splice(0)) {
+          void postToSession(url, queued);
+        }
+        return;
+      }
+      if (event === "message") {
+        process.stdout.write(`${data}
+`);
+      }
+    }
+    process.stdin.setEncoding("utf8");
+    let stdinBuffer = "";
+    process.stdin.on("data", (chunk) => {
+      stdinBuffer += chunk;
+      const lines = stdinBuffer.split("\n");
+      stdinBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === "")
+          continue;
+        if (postUrl === null) {
+          stdinQueue.push(trimmed);
+        } else {
+          void postToSession(postUrl, trimmed);
+        }
+      }
+    });
+    process.stdin.on("end", () => process.exit(0));
+  });
+}
 
 // ../server/dist/cli.js
-var DRIVE_USAGE = "usage: iris drive <url> [--headed]";
-var HEADED_FLAG = "--headed";
+var CLI_USAGE = `usage:
+  iris serve [--port N] [--drive <url>] [--headed]
+  iris stop  [--port N] [--quiet]
+  iris status [--port N]
+  iris drive <url> [--headed]                       (foreground mode \u2014 for debugging)
+  iris mcp   [--port N] [--drive <url>] [--headed]  (MCP stdio proxy \u2014 auto-starts daemon if needed)`;
+var SERVE_COMMAND = "serve";
+var STOP_COMMAND = "stop";
+var STATUS_COMMAND = "status";
 var DRIVE_COMMAND = "drive";
-function parseDriveArgs(argv, port) {
-  if (argv.length === 0 || argv[0] !== DRIVE_COMMAND) {
-    return { kind: "serve", port };
+var MCP_COMMAND = "mcp";
+var DAEMON_INNER_COMMAND = "_daemon";
+var HEADED_FLAG = "--headed";
+var PORT_FLAG = "--port";
+var DRIVE_FLAG = "--drive";
+var QUIET_FLAG = "--quiet";
+function parseServeFlags(args, defaultPort) {
+  let port = defaultPort;
+  let driveUrl;
+  let headless = true;
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === PORT_FLAG) {
+      i++;
+      const n = args[i];
+      if (n === void 0)
+        return { kind: "error", message: CLI_USAGE };
+      const parsed = parseInt(n, 10);
+      if (isNaN(parsed))
+        return { kind: "error", message: CLI_USAGE };
+      port = parsed;
+    } else if (arg === DRIVE_FLAG) {
+      i++;
+      driveUrl = args[i];
+      if (driveUrl === void 0)
+        return { kind: "error", message: CLI_USAGE };
+    } else if (arg === HEADED_FLAG) {
+      headless = false;
+    } else {
+      return { kind: "error", message: CLI_USAGE };
+    }
+    i++;
   }
-  const rest = argv.slice(1);
+  return { kind: "ok", port, headless, ...driveUrl !== void 0 ? { driveUrl } : {} };
+}
+function parsePortFlag(args, defaultPort) {
+  const idx = args.indexOf(PORT_FLAG);
+  if (idx === -1)
+    return defaultPort;
+  const n = args[idx + 1];
+  if (n === void 0)
+    return defaultPort;
+  const parsed = parseInt(n, 10);
+  return isNaN(parsed) ? defaultPort : parsed;
+}
+function parseDriveSuffix(args, port) {
   let headless = true;
   let driveUrl;
-  for (const arg of rest) {
+  for (const arg of args) {
     if (arg === HEADED_FLAG) {
       headless = false;
     } else if (arg.startsWith("--")) {
-      return { kind: "error", message: DRIVE_USAGE };
+      return { kind: "error", message: CLI_USAGE };
     } else if (driveUrl === void 0) {
       driveUrl = arg;
     } else {
-      return { kind: "error", message: DRIVE_USAGE };
+      return { kind: "error", message: CLI_USAGE };
     }
   }
   if (driveUrl === void 0)
-    return { kind: "error", message: DRIVE_USAGE };
-  return { kind: "drive", driveUrl, headless, port };
+    return { kind: "error", message: CLI_USAGE };
+  return { kind: "ok", port, driveUrl, headless };
+}
+function parseCliArgs(argv, defaultPort) {
+  if (argv.length === 0)
+    return { kind: "serve", port: defaultPort, headless: true };
+  const [cmd, ...rest] = argv;
+  switch (cmd) {
+    case SERVE_COMMAND: {
+      const r = parseServeFlags(rest, defaultPort);
+      if (r.kind === "error")
+        return r;
+      return {
+        kind: "serve",
+        port: r.port,
+        headless: r.headless,
+        ...r.driveUrl !== void 0 ? { driveUrl: r.driveUrl } : {}
+      };
+    }
+    case STOP_COMMAND: {
+      const port = parsePortFlag(rest, defaultPort);
+      const quiet = rest.includes(QUIET_FLAG);
+      return { kind: "stop", port, quiet };
+    }
+    case STATUS_COMMAND: {
+      const port = parsePortFlag(rest, defaultPort);
+      return { kind: "status", port };
+    }
+    case DRIVE_COMMAND: {
+      const r = parseDriveSuffix(rest, defaultPort);
+      if (r.kind === "error")
+        return r;
+      return { kind: "drive", port: r.port, driveUrl: r.driveUrl, headless: r.headless };
+    }
+    case DAEMON_INNER_COMMAND: {
+      const r = parseServeFlags(rest, defaultPort);
+      if (r.kind === "error")
+        return r;
+      return {
+        kind: "_daemon",
+        port: r.port,
+        headless: r.headless,
+        ...r.driveUrl !== void 0 ? { driveUrl: r.driveUrl } : {}
+      };
+    }
+    case MCP_COMMAND: {
+      const r = parseServeFlags(rest, defaultPort);
+      if (r.kind === "error")
+        return r;
+      return {
+        kind: "mcp",
+        port: r.port,
+        headless: r.headless,
+        ...r.driveUrl !== void 0 ? { driveUrl: r.driveUrl } : {}
+      };
+    }
+    default:
+      return { kind: "error", message: CLI_USAGE };
+  }
 }
-function main() {
-  const portEnv = process.env["IRIS_PORT"];
-  const port = portEnv === void 0 ? IRIS_DEFAULT_PORT : Number.parseInt(portEnv, 10);
-  const parsed = parseDriveArgs(process.argv.slice(2), port);
-  if (parsed.kind === "error") {
-    log("iris_usage_error", { message: parsed.message });
+function handleServe(parsed) {
+  if (isRunning(parsed.port)) {
+    log("iris_daemon_already_running", { port: parsed.port });
+    return;
+  }
+  const scriptPath = process.argv[1];
+  if (scriptPath === void 0) {
+    log("iris_serve_no_script", {});
     process.exit(1);
+    return;
+  }
+  const daemonArgs = [DAEMON_INNER_COMMAND, PORT_FLAG, String(parsed.port)];
+  if (parsed.driveUrl !== void 0) {
+    daemonArgs.push(DRIVE_FLAG, parsed.driveUrl);
+    if (!parsed.headless)
+      daemonArgs.push(HEADED_FLAG);
+  }
+  spawnDaemon(process.execPath, scriptPath, daemonArgs, parsed.port);
+  log("iris_daemon_spawned", { port: parsed.port });
+}
+function handleStop(port, quiet) {
+  const pid = readPid(port);
+  if (pid === null || !isAlive(pid)) {
+    removePid(port);
+    if (!quiet)
+      log("iris_daemon_not_running", { port });
+    return;
+  }
+  process.kill(pid, "SIGTERM");
+  const started = Date.now();
+  const poll = setInterval(() => {
+    if (!isAlive(pid)) {
+      clearInterval(poll);
+      removePid(port);
+      if (!quiet)
+        log("iris_daemon_stopped", { port, pid });
+      return;
+    }
+    if (Date.now() - started > 5e3) {
+      clearInterval(poll);
+      if (!quiet)
+        log("iris_daemon_stop_timeout", { port, pid });
+      process.exit(1);
+    }
+  }, 100);
+}
+function handleStatus(port) {
+  const pid = readPid(port);
+  if (pid === null || !isAlive(pid)) {
+    log("iris_status", { port, running: false });
+    return;
   }
-  const options = parsed.kind === "drive" ? { port: parsed.port, driveUrl: parsed.driveUrl, headless: parsed.headless } : { port: parsed.port };
+  log("iris_status", { port, running: true, pid });
+}
+function handleDaemonInner(parsed) {
+  const options = {
+    port: parsed.port,
+    ...parsed.driveUrl !== void 0 ? { driveUrl: parsed.driveUrl, headless: parsed.headless } : {}
+  };
+  startDaemon(options).then((server) => {
+    log("iris_daemon_ready", { port: parsed.port, pid: process.pid });
+    const shutdown = () => {
+      server.close().then(() => {
+        removePid(parsed.port);
+        process.exit(0);
+      }).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        log("iris_daemon_close_error", { error: message });
+        removePid(parsed.port);
+        process.exit(1);
+      });
+    };
+    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", shutdown);
+  }).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    log("iris_daemon_start_failed", { error: message });
+    removePid(parsed.port);
+    process.exit(1);
+  });
+}
+function handleMcp(opts) {
+  const { port, driveUrl, headless } = opts;
+  probeDaemon(port).then((listening) => {
+    if (!listening) {
+      const scriptPath = process.argv[1];
+      if (scriptPath === void 0) {
+        log("iris_mcp_no_script", {});
+        process.exit(1);
+        return;
+      }
+      const daemonArgs = [DAEMON_INNER_COMMAND, PORT_FLAG, String(port)];
+      if (driveUrl !== void 0) {
+        daemonArgs.push(DRIVE_FLAG, driveUrl);
+        if (!headless)
+          daemonArgs.push(HEADED_FLAG);
+      }
+      spawnDaemon(process.execPath, scriptPath, daemonArgs, port);
+      log("iris_mcp_daemon_started", { port, ...driveUrl !== void 0 ? { driveUrl } : {} });
+    }
+    return waitForDaemon(port).then(() => startMcpProxy(port));
+  }).catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    log("iris_mcp_proxy_error", { error: message });
+    process.exit(1);
+  });
+}
+function handleLegacyDrive(parsed) {
+  const options = {
+    port: parsed.port,
+    driveUrl: parsed.driveUrl,
+    headless: parsed.headless
+  };
   start(options).then(() => {
     log("iris_started", { port: parsed.port });
   }).catch((error) => {
@@ -5154,7 +6004,35 @@ function main() {
     process.exit(1);
   });
 }
-var invokedPath = process.argv[1];
-if (invokedPath !== void 0 && import.meta.url === pathToFileURL(invokedPath).href) {
+function main() {
+  const portEnv = process.env["IRIS_PORT"];
+  const defaultPort = portEnv === void 0 ? IRIS_DEFAULT_PORT : parseInt(portEnv, 10);
+  const parsed = parseCliArgs(process.argv.slice(2), defaultPort);
+  switch (parsed.kind) {
+    case "error":
+      log("iris_usage_error", { message: parsed.message });
+      process.exit(1);
+      break;
+    case "serve":
+      handleServe(parsed);
+      break;
+    case "stop":
+      handleStop(parsed.port, parsed.quiet);
+      break;
+    case "status":
+      handleStatus(parsed.port);
+      break;
+    case "drive":
+      handleLegacyDrive(parsed);
+      break;
+    case "mcp":
+      handleMcp(parsed);
+      break;
+    case "_daemon":
+      handleDaemonInner(parsed);
+      break;
+  }
+}
+if (process.argv[1] !== void 0 && import.meta.url === pathToFileURL(process.argv[1]).href) {
   main();
 }