@syrin/iris 0.5.0 → 0.6.10

package/dist/cli.js

@@ -2,10 +2,35 @@
 
 // ../server/dist/cli.js
 import { pathToFileURL } from "url";
+import { realpathSync } from "fs";
 
 // ../protocol/dist/constants.js
 var IRIS_DEFAULT_PORT = 4400;
 var IRIS_WS_PATH = "/iris";
+var IRIS_PROTOCOL_VERSION = 1;
+var TRANSPORT_LIMITS = {
+  MAX_MESSAGE_BYTES: 1024 * 1024,
+  MAX_MESSAGES_PER_SECOND: 1e3,
+  MAX_SESSIONS: 32,
+  MAX_PENDING_CONNECTIONS: 16,
+  HELLO_TIMEOUT_MS: 5e3,
+  MAX_BUFFER_BYTES: 8 * 1024 * 1024,
+  MAX_SESSION_ID_LENGTH: 128,
+  MAX_URL_LENGTH: 4096,
+  MAX_TITLE_LENGTH: 512,
+  MAX_ADAPTERS: 32,
+  MAX_ADAPTER_NAME_LENGTH: 128,
+  MAX_TOKEN_LENGTH: 512,
+  MAX_COMMAND_ID_LENGTH: 128,
+  MAX_COMMAND_NAME_LENGTH: 128,
+  MAX_REF_LENGTH: 128,
+  MAX_ERROR_LENGTH: 4096,
+  MAX_SERIALIZE_DEPTH: 8,
+  MAX_COLLECTION_ITEMS: 200,
+  MAX_OBJECT_KEYS: 200,
+  MAX_STRING_LENGTH: 64 * 1024
+};
+var DANGEROUS_ACTION_CONFIRM_ARG = "confirmDangerous";
 var REPLAY_PROGRAM_VERSION = 1;
 var IrisDir = {
   ROOT: ".iris",
@@ -107,7 +132,7 @@ var ReplayStatus = {
   DRIFT: "drift",
   // an anchor missed (testid renamed / signal not observed) — legible drift returned
   ERROR: "error"
-  // the flow file could not be loaded (missing/invalid) — no steps ran
+  // the flow could not load or a resolved action failed
 };
 var DriftReason = {
   TESTID_NOT_FOUND: "testid_not_found",
@@ -141,8 +166,10 @@ var HealStatus = {
   // drift exists but no proposal cleared the confidence floor
   NOTHING_TO_HEAL: "nothing_to_heal",
   // replay was green
+  CONSEQUENCE_BROKEN: "consequence_broken",
+  // rebind resolves a locator but the flow's success consequence no longer fires — REFUSED (file untouched)
   ERROR: "error"
-  // flow missing/malformed/invalid-name — no steps ran
+  // flow missing/malformed/invalid-name, or a resolved action failed
 };
 var HEAL_CONFIDENCE_MIN = 0.5;
 var AnnotationTarget = {
@@ -158,7 +185,8 @@ var AnnotationErrorCode = {
 var COMPILED_PREDICATE_PREFIX = "will";
 var RING_BUFFER_DEFAULTS = {
   MAX_EVENTS: 2e3,
-  MAX_AGE_MS: 6e4
+  MAX_AGE_MS: 6e4,
+  MAX_BYTES: TRANSPORT_LIMITS.MAX_BUFFER_BYTES
 };
 var EventType = {
   DOM_ADDED: "dom.added",
@@ -343,6 +371,8 @@ var MessageKind = {
 
 // ../protocol/dist/messages.js
 import { z } from "zod";
+var sessionIdSchema = z.string().min(1).max(TRANSPORT_LIMITS.MAX_SESSION_ID_LENGTH);
+var refSchema = z.string().max(TRANSPORT_LIMITS.MAX_REF_LENGTH);
 var HumanControlDataSchema = z.object({
   kind: z.nativeEnum(HumanControlKind),
   text: z.string().optional()
@@ -350,35 +380,37 @@ var HumanControlDataSchema = z.object({
 var IrisEventSchema = z.object({
   t: z.number(),
   type: z.nativeEnum(EventType),
-  sessionId: z.string(),
+  sessionId: sessionIdSchema,
   /** Stable element reference this event concerns, when applicable (e.g. "e7"). */
-  ref: z.string().optional(),
+  ref: refSchema.optional(),
   /** Event-type-specific payload. Kept open here; refined per observer at the edges. */
   data: z.record(z.unknown()).default({})
 });
 var HelloMessageSchema = z.object({
   kind: z.literal(MessageKind.HELLO),
-  protocolVersion: z.number(),
-  sessionId: z.string(),
-  url: z.string(),
-  title: z.string(),
-  adapters: z.array(z.string()),
+  protocolVersion: z.literal(IRIS_PROTOCOL_VERSION),
+  sessionId: sessionIdSchema,
+  url: z.string().max(TRANSPORT_LIMITS.MAX_URL_LENGTH),
+  title: z.string().max(TRANSPORT_LIMITS.MAX_TITLE_LENGTH),
+  adapters: z.array(z.string().max(TRANSPORT_LIMITS.MAX_ADAPTER_NAME_LENGTH)).max(TRANSPORT_LIMITS.MAX_ADAPTERS),
+  /** Optional browser/bridge pairing token. Required when the bridge configures one. */
+  token: z.string().max(TRANSPORT_LIMITS.MAX_TOKEN_LENGTH).optional(),
   /** Whether the app has advertised a capability registry (iris.describe). */
   hasCapabilities: z.boolean().optional()
 });
 var CommandMessageSchema = z.object({
   kind: z.literal(MessageKind.COMMAND),
-  id: z.string(),
-  sessionId: z.string().optional(),
-  name: z.string(),
+  id: z.string().min(1).max(TRANSPORT_LIMITS.MAX_COMMAND_ID_LENGTH),
+  sessionId: sessionIdSchema.optional(),
+  name: z.string().min(1).max(TRANSPORT_LIMITS.MAX_COMMAND_NAME_LENGTH),
   args: z.record(z.unknown()).default({})
 });
 var CommandResultSchema = z.object({
   kind: z.literal(MessageKind.COMMAND_RESULT),
-  id: z.string(),
+  id: z.string().min(1).max(TRANSPORT_LIMITS.MAX_COMMAND_ID_LENGTH),
   ok: z.boolean(),
   result: z.unknown().optional(),
-  error: z.string().optional()
+  error: z.string().max(TRANSPORT_LIMITS.MAX_ERROR_LENGTH).optional()
 });
 var EventMessageSchema = z.object({
   kind: z.literal(MessageKind.EVENT),
@@ -391,6 +423,25 @@ var IrisMessageSchema = z.discriminatedUnion("kind", [
   EventMessageSchema
 ]);
 
+// ../protocol/dist/security.js
+var DANGEROUS_ACTION = /\b(delete|remove|destroy|erase|drop|terminate|revoke|reset|logout|log out|sign out|close account|cancel subscription|purchase|buy|pay|place order|confirm order|deploy|publish|send|transfer|withdraw|refund)\b/i;
+function isLoopbackHostname(hostname) {
+  const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (normalized === "localhost" || normalized === "::1" || normalized === "0:0:0:0:0:0:0:1") {
+    return true;
+  }
+  const octets = normalized.split(".");
+  return octets.length === 4 && octets[0] === "127" && octets.every((octet) => {
+    if (!/^\d{1,3}$/.test(octet))
+      return false;
+    const value = Number(octet);
+    return value >= 0 && value <= 255;
+  });
+}
+function isDangerousActionText(text) {
+  return DANGEROUS_ACTION.test(text.replace(/[_-]+/g, " "));
+}
+
 // ../protocol/dist/toon.js
 var ROLE_MAP = {
   button: "btn",
@@ -742,6 +793,7 @@ function createSharedServer() {
 }
 
 // ../server/dist/bridge.js
+import { timingSafeEqual } from "crypto";
 import * as http2 from "http";
 import { WebSocketServer } from "ws";
 
@@ -749,14 +801,21 @@ import { WebSocketServer } from "ws";
 var RingBuffer = class {
   #maxEvents;
   #maxAgeMs;
+  #maxBytes;
   #events = [];
+  #eventBytes = [];
+  #totalBytes = 0;
   #droppedCount = 0;
   constructor(options = {}) {
     this.#maxEvents = options.maxEvents ?? RING_BUFFER_DEFAULTS.MAX_EVENTS;
     this.#maxAgeMs = options.maxAgeMs ?? RING_BUFFER_DEFAULTS.MAX_AGE_MS;
+    this.#maxBytes = options.maxBytes ?? RING_BUFFER_DEFAULTS.MAX_BYTES;
   }
   push(event, now) {
     this.#events.push(event);
+    const bytes = Buffer.byteLength(JSON.stringify(event), "utf8");
+    this.#eventBytes.push(bytes);
+    this.#totalBytes += bytes;
     this.#evict(now);
   }
   /** Events at or after a given timestamp cursor. */
@@ -782,10 +841,14 @@ var RingBuffer = class {
   #evict(now) {
     const before = this.#events.length;
     const cutoff = now - this.#maxAgeMs;
-    if (this.#events.length > this.#maxEvents) {
-      this.#events = this.#events.slice(this.#events.length - this.#maxEvents);
+    while (this.#events.length > this.#maxEvents || this.#totalBytes > this.#maxBytes && this.#events.length > 0) {
+      this.#events.shift();
+      this.#totalBytes -= this.#eventBytes.shift() ?? 0;
+    }
+    while ((this.#events[0]?.t ?? cutoff) < cutoff) {
+      this.#events.shift();
+      this.#totalBytes -= this.#eventBytes.shift() ?? 0;
     }
-    this.#events = this.#events.filter((e) => e.t >= cutoff);
     this.#droppedCount += before - this.#events.length;
   }
   /** Snapshot of buffer health for the agent — total events held and cumulative drops since connect. */
@@ -1022,6 +1085,14 @@ var Session = class {
       this.#pending.delete(id);
     }
   }
+  /** End this transport without letting a stale socket remove its replacement session. */
+  disconnect(reason) {
+    this.rejectAll(reason);
+    try {
+      this.#socket.close(1008, reason);
+    } catch {
+    }
+  }
   // ── Live-control: state machine + human→agent inbox (server-owned) ───────────────
   getState() {
     return this.#state;
@@ -1143,11 +1214,15 @@ var Session = class {
 var SessionManager = class {
   #sessions = /* @__PURE__ */ new Map();
   add(session) {
+    const previous = this.#sessions.get(session.id);
     this.#sessions.set(session.id, session);
+    return previous;
   }
-  remove(sessionId) {
-    this.#sessions.get(sessionId)?.rejectAll("session disconnected");
-    this.#sessions.delete(sessionId);
+  remove(session) {
+    if (this.#sessions.get(session.id) !== session)
+      return false;
+    session.rejectAll("session disconnected");
+    return this.#sessions.delete(session.id);
   }
   get(sessionId) {
     return this.#sessions.get(sessionId);
@@ -1215,6 +1290,20 @@ var SessionManager = class {
 };
 
 // ../server/dist/bridge.js
+function normalizeOrigin(origin) {
+  try {
+    return new URL(origin).origin;
+  } catch {
+    return null;
+  }
+}
+function tokensMatch(expected, received) {
+  if (received === void 0)
+    return false;
+  const expectedBytes = Buffer.from(expected);
+  const receivedBytes = Buffer.from(received);
+  return expectedBytes.length === receivedBytes.length && timingSafeEqual(expectedBytes, receivedBytes);
+}
 function rawToString(raw) {
   if (typeof raw === "string")
     return raw;
@@ -1230,11 +1319,41 @@ var Bridge = class {
   ready;
   #wss;
   #clock;
+  #token;
+  #allowedOrigins;
+  #maxMessagesPerSecond;
+  #maxSessions;
+  #maxPendingConnections;
+  #helloTimeoutMs;
+  #pendingConnections = 0;
   constructor(options) {
+    const host = options.host ?? "127.0.0.1";
+    if ((options.token?.length ?? 0) > TRANSPORT_LIMITS.MAX_TOKEN_LENGTH) {
+      throw new Error(`Iris pairing token exceeds ${String(TRANSPORT_LIMITS.MAX_TOKEN_LENGTH)} characters`);
+    }
+    if (!isLoopbackHostname(host) && (options.token === void 0 || options.token.length === 0)) {
+      throw new Error("a pairing token is required when the Iris bridge binds beyond localhost");
+    }
     this.#clock = options.clock ?? (() => Date.now());
+    this.#token = options.token !== void 0 && options.token.length > 0 ? options.token : void 0;
+    this.#allowedOrigins = new Set((options.allowedOrigins ?? []).map(normalizeOrigin).filter((origin) => origin !== null));
+    this.#maxMessagesPerSecond = options.maxMessagesPerSecond ?? TRANSPORT_LIMITS.MAX_MESSAGES_PER_SECOND;
+    this.#maxSessions = options.maxSessions ?? TRANSPORT_LIMITS.MAX_SESSIONS;
+    this.#maxPendingConnections = options.maxPendingConnections ?? TRANSPORT_LIMITS.MAX_PENDING_CONNECTIONS;
+    this.#helloTimeoutMs = options.helloTimeoutMs ?? TRANSPORT_LIMITS.HELLO_TIMEOUT_MS;
     if (options.server !== void 0) {
       const srv = options.server;
-      this.#wss = new WebSocketServer({ server: srv, path: IRIS_WS_PATH });
+      this.#wss = new WebSocketServer({
+        server: srv,
+        path: IRIS_WS_PATH,
+        maxPayload: TRANSPORT_LIMITS.MAX_MESSAGE_BYTES,
+        verifyClient: ({ origin }, done) => {
+          const allowed = this.#originAllowed(origin);
+          if (!allowed)
+            log("origin_rejected", { origin: origin ?? "missing" });
+          done(allowed, 403, "Forbidden");
+        }
+      });
       this.ready = new Promise((resolve) => {
         if (srv.listening) {
           resolve(srv.address().port);
@@ -1247,8 +1366,15 @@ var Bridge = class {
     } else {
       this.#wss = new WebSocketServer({
         port: options.port,
-        host: options.host ?? "127.0.0.1",
-        path: IRIS_WS_PATH
+        host,
+        path: IRIS_WS_PATH,
+        maxPayload: TRANSPORT_LIMITS.MAX_MESSAGE_BYTES,
+        verifyClient: ({ origin }, done) => {
+          const allowed = this.#originAllowed(origin);
+          if (!allowed)
+            log("origin_rejected", { origin: origin ?? "missing" });
+          done(allowed, 403, "Forbidden");
+        }
       });
       this.ready = new Promise((resolve) => {
         this.#wss.on("listening", () => {
@@ -1261,14 +1387,64 @@ var Bridge = class {
     });
   }
   #onConnection(socket) {
+    if (this.#pendingConnections >= this.#maxPendingConnections) {
+      socket.close(1013, "too many pending handshakes");
+      return;
+    }
+    this.#pendingConnections += 1;
+    let awaitingHello = true;
     let session;
+    let messageWindowStartedAt = this.#clock();
+    let messagesInWindow = 0;
+    const releasePending = () => {
+      if (!awaitingHello)
+        return;
+      awaitingHello = false;
+      this.#pendingConnections -= 1;
+    };
+    const helloTimer = setTimeout(() => {
+      if (!awaitingHello)
+        return;
+      releasePending();
+      socket.close(1008, "hello timeout");
+    }, this.#helloTimeoutMs);
     socket.on("message", (raw) => {
+      const now = this.#clock();
+      if (now - messageWindowStartedAt >= 1e3) {
+        messageWindowStartedAt = now;
+        messagesInWindow = 0;
+      }
+      messagesInWindow += 1;
+      if (messagesInWindow > this.#maxMessagesPerSecond) {
+        log("message_rate_exceeded", {});
+        socket.close(1008, "message rate exceeded");
+        return;
+      }
       const parsed = this.#parse(rawToString(raw));
-      if (parsed === null)
+      if (parsed === null) {
+        socket.close(1008, "invalid message");
         return;
+      }
       if (parsed.kind === MessageKind.HELLO) {
+        if (session !== void 0) {
+          socket.close(1008, "hello already received");
+          return;
+        }
+        if (this.#token !== void 0 && !tokensMatch(this.#token, parsed.token)) {
+          log("authentication_failed", {});
+          socket.close(1008, "authentication failed");
+          return;
+        }
+        const existing = this.sessions.get(parsed.sessionId);
+        if (existing === void 0 && this.sessions.count() >= this.#maxSessions) {
+          socket.close(1013, "session limit reached");
+          return;
+        }
+        clearTimeout(helloTimer);
+        releasePending();
         session = new Session(parsed, socket, this.#clock);
-        this.sessions.add(session);
+        const replaced = this.sessions.add(session);
+        replaced?.disconnect("session replaced by a newer connection");
         log("session_connected", { sessionId: session.id, url: session.url });
         return;
       }
@@ -1282,15 +1458,28 @@ var Bridge = class {
       }
     });
     socket.on("close", () => {
+      clearTimeout(helloTimer);
+      releasePending();
       if (session !== void 0) {
-        this.sessions.remove(session.id);
-        log("session_disconnected", { sessionId: session.id });
+        if (this.sessions.remove(session)) {
+          log("session_disconnected", { sessionId: session.id });
+        }
       }
     });
     socket.on("error", (err) => {
       log("socket_error", { error: err.message });
     });
   }
+  #originAllowed(origin) {
+    if (origin === void 0)
+      return true;
+    const normalized = normalizeOrigin(origin);
+    if (normalized === null)
+      return false;
+    if (this.#allowedOrigins.has(normalized))
+      return true;
+    return isLoopbackHostname(new URL(normalized).hostname);
+  }
   #parse(text) {
     let json;
     try {
@@ -1307,6 +1496,8 @@ var Bridge = class {
   }
   close() {
     return new Promise((resolve) => {
+      for (const client of this.#wss.clients)
+        client.terminate();
       this.#wss.close(() => {
         resolve();
       });
@@ -1421,6 +1612,7 @@ var IrisTool = {
   STATE: "iris_state",
   CAPABILITIES: "iris_capabilities",
   CONTRACT_SAVE: "iris_contract_save",
+  DOMAIN: "iris_domain",
   FLOW_SAVE: "iris_flow_save",
   FLOW_LIST: "iris_flow_list",
   FLOW_LOAD: "iris_flow_load",
@@ -1463,189 +1655,558 @@ var IrisTool = {
   ROLLBACK: "iris_rollback"
 };
 
-// ../server/dist/project/iris-dir.js
-import { join } from "path";
-function irisDirPaths(root) {
-  return {
-    root,
-    contract: join(root, IrisDir.CONTRACT_FILE),
-    flows: join(root, IrisDir.FLOWS_SUBDIR),
-    baselines: join(root, IrisDir.BASELINES_SUBDIR),
-    project: join(root, IrisDir.PROJECT_FILE),
-    visual: join(root, IrisDir.VISUAL_SUBDIR)
-  };
-}
-function visualPath(root, name) {
-  return join(root, IrisDir.VISUAL_SUBDIR, `${name}.png`);
-}
-function visualDiffPath(root, name) {
-  return join(root, IrisDir.VISUAL_SUBDIR, `${name}.diff.png`);
-}
-function flowPath(root, name) {
-  return join(root, IrisDir.FLOWS_SUBDIR, `${name}.json`);
-}
-function isValidFlowName(name) {
-  return FLOW_NAME_PATTERN.test(name) && !name.includes("..");
-}
-async function ensureIrisDir(fs2, root) {
-  const p = irisDirPaths(root);
-  await fs2.mkdir(p.root);
-  await fs2.mkdir(p.flows);
-  await fs2.mkdir(p.baselines);
-}
-var JSON_INDENT = 2;
-function stableSerialize(capabilities, generatedAt) {
-  const envelope = {
-    version: CONTRACT_FILE_VERSION,
-    generatedAt,
-    capabilities: {
-      testids: [...capabilities.testids].sort(),
-      signals: [...capabilities.signals].sort(),
-      stores: [...capabilities.stores].sort(),
-      flows: [...capabilities.flows].map((f) => ({ name: f.name, steps: [...f.steps] })).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+// ../server/dist/tools/tools-helpers.js
+function parseInteractive(tree) {
+  const items = [];
+  for (const line of tree.split("\n")) {
+    const match = /\(ref=(e\d+)\)/.exec(line);
+    if (match !== null) {
+      items.push({ ref: match[1] ?? "", desc: line.replace(/\s*\(ref=e\d+\)/, "").trim() });
     }
-  };
-  return `${JSON.stringify(envelope, null, JSON_INDENT)}
-`;
-}
-async function writeContract(fs2, root, capabilities, now) {
-  await ensureIrisDir(fs2, root);
-  await fs2.writeFile(irisDirPaths(root).contract, stableSerialize(capabilities, now()));
-}
-async function readContract(fs2, root) {
-  const path = irisDirPaths(root).contract;
-  if (!await fs2.exists(path))
-    return { ok: false, reason: ContractReadError.MISSING };
-  let text;
-  try {
-    text = await fs2.readFile(path);
-  } catch (error) {
-    return {
-      ok: false,
-      reason: fs2.isNotFound(error) ? ContractReadError.MISSING : ContractReadError.MALFORMED
-    };
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    return { ok: false, reason: ContractReadError.MALFORMED };
   }
-  const result = ContractFileSchema.safeParse(parsed);
-  if (!result.success)
-    return { ok: false, reason: ContractReadError.MALFORMED };
-  return { ok: true, capabilities: result.data.capabilities, generatedAt: result.data.generatedAt };
+  return items;
 }
-
-// ../server/dist/flows/flows.js
 function asString(value) {
   return typeof value === "string" ? value : void 0;
 }
+function asNumber(value) {
+  return typeof value === "number" ? value : void 0;
+}
 function asRecord(value) {
   return typeof value === "object" && value !== null ? value : {};
 }
-function degradedAnchor() {
-  return { kind: AnchorKind.ROLE, role: DEGRADED_ANCHOR_ROLE };
+
+// ../server/dist/flows/replay.js
+function asString2(value) {
+  return typeof value === "string" ? value : void 0;
 }
-function subStepToFlowStep(raw) {
-  const sub = asRecord(raw);
-  const by = asString(sub["by"]);
-  const value = asString(sub["value"]);
-  const action = asString(sub["action"]);
-  const args = asRecord(sub["args"]);
-  if (by === QueryBy.TESTID && value !== void 0) {
-    return buildStep(IrisTool.ACT, { kind: AnchorKind.TESTID, value }, action, args, false);
-  }
-  return buildStep(IrisTool.ACT, degradedAnchor(), action, args, true);
+function asRecord2(value) {
+  return typeof value === "object" && value !== null ? value : {};
 }
-function buildStep(tool, anchor, action, args, degraded) {
-  const step = { tool, anchor, args };
-  if (action !== void 0)
-    step.action = action;
-  if (degraded)
-    step.degraded = true;
-  return step;
+function replayActionArgs(value, confirmDangerous = false) {
+  const args = { ...asRecord2(value) };
+  delete args[DANGEROUS_ACTION_CONFIRM_ARG];
+  if (confirmDangerous)
+    args[DANGEROUS_ACTION_CONFIRM_ARG] = true;
+  return args;
 }
-function recordedStepToFlowStep(step) {
-  if (step.tool === IrisTool.ACT_SEQUENCE) {
-    const rawSubs = Array.isArray(step.args["steps"]) ? step.args["steps"] : [];
-    const subs = rawSubs.map(subStepToFlowStep);
-    const degraded = subs.some((s) => s.degraded === true);
-    const anchor = subs[0]?.anchor ?? degradedAnchor();
-    const out2 = { tool: IrisTool.ACT_SEQUENCE, anchor, steps: subs };
-    if (degraded)
-      out2.degraded = true;
-    if (step.expect !== void 0)
-      out2.expect = step.expect;
-    return out2;
+function compileActStep(args, res) {
+  const testid = asString2(asRecord2(res)["testid"]);
+  const action = asString2(args["action"]) ?? "";
+  const actArgs = replayActionArgs(args["args"]);
+  if (testid !== void 0) {
+    return {
+      tool: IrisTool.ACT,
+      stable: true,
+      args: { by: QueryBy.TESTID, value: testid, action, args: actArgs }
+    };
   }
-  const by = asString(step.args["by"]);
-  const value = asString(step.args["value"]);
-  const action = asString(step.args["action"]);
-  const args = asRecord(step.args["args"]);
-  const out = by === QueryBy.TESTID && value !== void 0 ? buildStep(step.tool, { kind: AnchorKind.TESTID, value }, action, args, false) : buildStep(step.tool, degradedAnchor(), action, args, true);
-  if (step.expect !== void 0)
-    out.expect = step.expect;
-  return out;
+  return {
+    tool: IrisTool.ACT,
+    stable: false,
+    args: { ref: asString2(args["ref"]) ?? "", action, args: actArgs }
+  };
 }
-function withAnnotations(flow, ann) {
-  if (ann === void 0)
-    return flow;
-  const steps = flow.steps.map((step, i) => {
-    const expect = ann.stepExpect.get(i);
-    return expect === void 0 ? step : { ...step, expect };
+function compileSequenceStep(args, res) {
+  const inputSteps = Array.isArray(args["steps"]) ? args["steps"] : [];
+  const resolved = Array.isArray(asRecord2(res)["steps"]) ? asRecord2(res)["steps"] : [];
+  let stable = inputSteps.length > 0;
+  const subSteps = inputSteps.map((raw, i) => {
+    const step = asRecord2(raw);
+    const action = asString2(step["action"]) ?? "";
+    const stepArgs = replayActionArgs(step["args"]);
+    const testid = asString2(asRecord2(resolved[i])["testid"]);
+    if (testid !== void 0) {
+      return { by: QueryBy.TESTID, value: testid, action, args: stepArgs };
+    }
+    stable = false;
+    return { ref: asString2(step["ref"]) ?? "", action, args: stepArgs };
   });
-  const out = { ...flow, steps };
-  if (ann.dynamic.length > 0) {
-    out.dynamic = ann.dynamic.map((value) => ({ kind: AnchorKind.TESTID, value }));
-  }
-  if (ann.success !== void 0)
-    out.success = ann.success;
-  return out;
+  return { tool: IrisTool.ACT_SEQUENCE, stable, args: { steps: subSteps } };
 }
-var JSON_INDENT2 = 2;
-var FLOW_SUFFIX = ".json";
-var FlowStore = class {
-  #fs;
-  #root;
-  #clock;
-  constructor(fs2, root, clock) {
-    this.#fs = fs2;
-    this.#root = root;
-    this.#clock = clock;
-  }
-  /**
-   * The single byte-stable flow serializer: 2-space indent + one trailing newline. save(),
-   * saveFlow() and heal() all route through it so an unchanged flow that round-trips through any
-   * of them produces byte-identical on-disk content (locked by the byte-stability tests).
-   */
-  #serialize(flow) {
-    return `${JSON.stringify(flow, null, JSON_INDENT2)}
-`;
+async function resolveRef(session, step) {
+  const by = asString2(step.by);
+  const value = asString2(step.value);
+  if (by === QueryBy.TESTID && value !== void 0) {
+    const result = await session.command(IrisCommand.QUERY, { by, value });
+    if (!result.ok)
+      throw new Error(result.error ?? "query failed");
+    const elements = Array.isArray(asRecord2(result.result)["elements"]) ? asRecord2(result.result)["elements"] : [];
+    const ref2 = asString2(asRecord2(elements[0])["ref"]);
+    if (ref2 === void 0)
+      throw new Error(`testid '${value}' did not resolve in current page`);
+    return elements.length > 1 ? { ref: ref2, note: `ambiguous testid '${value}', used first match` } : { ref: ref2 };
   }
-  /**
-   * Convert a CompiledProgram (testid-normalized) into an anchored, on-disk flow + write it.
-   * Optionally fold structured annotations (per-step expect, dynamic[], success) onto
-   * the flow before writing. Omitting `annotations` reproduces the same bytes.
-   */
-  async save(program, annotations) {
-    if (!isValidFlowName(program.name)) {
-      return { ok: false, code: FlowErrorCode.INVALID_NAME };
-    }
-    const steps = program.steps.map(recordedStepToFlowStep);
-    const base = {
-      version: FLOW_FILE_VERSION,
-      name: program.name,
-      createdAt: this.#clock.now(),
-      steps
-    };
-    const flow = withAnnotations(base, annotations);
-    await this.#fs.mkdir(irisDirPaths(this.#root).flows);
-    await this.#fs.writeFile(flowPath(this.#root, program.name), this.#serialize(flow));
-    const degraded = flow.steps.filter((s) => s.degraded === true).length;
-    return {
-      ok: true,
-      value: {
+  const ref = asString2(step.ref);
+  if (ref === void 0 || ref.length === 0)
+    throw new Error("step has no testid or ref to resolve");
+  return { ref, note: "replayed by stale ref (not portable across sessions)" };
+}
+async function replayProgram(session, program, confirmDangerous = false) {
+  const results = [];
+  for (const step of program.steps) {
+    try {
+      if (step.tool === IrisTool.ACT_SEQUENCE) {
+        const subs = Array.isArray(step.args["steps"]) ? step.args["steps"] : [];
+        const notes = [];
+        const liveSteps = [];
+        for (const raw of subs) {
+          const sub = asRecord2(raw);
+          const { ref, note } = await resolveRef(session, sub);
+          if (note !== void 0)
+            notes.push(note);
+          liveSteps.push({
+            ref,
+            action: asString2(sub["action"]) ?? "",
+            args: replayActionArgs(sub["args"], confirmDangerous)
+          });
+        }
+        const r = await session.command(IrisCommand.ACT_SEQUENCE, { steps: liveSteps });
+        results.push(buildResult(step.tool, r.ok, r.error, notes));
+        if (!r.ok)
+          break;
+      } else {
+        const { ref, note } = await resolveRef(session, step.args);
+        const r = await session.command(IrisCommand.ACT, {
+          ref,
+          action: asString2(step.args["action"]) ?? "",
+          args: replayActionArgs(step.args["args"], confirmDangerous)
+        });
+        results.push(buildResult(step.tool, r.ok, r.error, note !== void 0 ? [note] : []));
+        if (!r.ok)
+          break;
+      }
+    } catch (e) {
+      results.push({
+        tool: step.tool,
+        ok: false,
+        error: e instanceof Error ? e.message : String(e)
+      });
+      break;
+    }
+  }
+  return results;
+}
+function buildResult(tool, ok, error, notes) {
+  const base = { tool, ok };
+  if (!ok)
+    base.error = error ?? "command failed";
+  if (notes.length > 0)
+    base.note = notes.join("; ");
+  return base;
+}
+
+// ../server/dist/flows/flow-replay.js
+function editDistance(a, b) {
+  const s = a.toLowerCase();
+  const t = b.toLowerCase();
+  const rows = s.length + 1;
+  const cols = t.length + 1;
+  const prev = new Array(cols);
+  const curr = new Array(cols);
+  for (let j = 0; j < cols; j++)
+    prev[j] = j;
+  for (let i = 1; i < rows; i++) {
+    curr[0] = i;
+    for (let j = 1; j < cols; j++) {
+      const cost = s[i - 1] === t[j - 1] ? 0 : 1;
+      curr[j] = Math.min((prev[j] ?? 0) + 1, (curr[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+    }
+    for (let j = 0; j < cols; j++)
+      prev[j] = curr[j] ?? 0;
+  }
+  return prev[cols - 1] ?? 0;
+}
+function nearestTestid(missing, present) {
+  let best = null;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const candidate of present) {
+    const distance = editDistance(missing, candidate);
+    if (distance < bestDistance || distance === bestDistance && best !== null && candidate.length < best.length || distance === bestDistance && best !== null && candidate.length === best.length && candidate < best) {
+      best = candidate;
+      bestDistance = distance;
+    }
+  }
+  return best;
+}
+function readQuery(result) {
+  if (!result.ok)
+    return { refs: [] };
+  const payload = asRecord(result.result);
+  const elements = Array.isArray(payload["elements"]) ? payload["elements"] : [];
+  const refs = elements.map((e) => asString(asRecord(e)["ref"]) ?? "").filter((r) => r.length > 0);
+  const rawHint = payload["hint"];
+  if (typeof rawHint === "object" && rawHint !== null) {
+    const hint = asRecord(rawHint);
+    const present = Array.isArray(hint["presentTestids"]) ? hint["presentTestids"].filter((t) => typeof t === "string") : [];
+    return {
+      refs,
+      hint: {
+        route: asString(hint["route"]) ?? "",
+        presentTestids: present,
+        presentRegions: [],
+        knownEmptyState: hint["knownEmptyState"] === true
+      }
+    };
+  }
+  return { refs };
+}
+function nearestIsAmbiguous(missing, present) {
+  if (present.length < 2)
+    return false;
+  let min = Number.POSITIVE_INFINITY;
+  let count = 0;
+  for (const candidate of present) {
+    const distance = editDistance(missing, candidate);
+    if (distance < min) {
+      min = distance;
+      count = 1;
+    } else if (distance === min) {
+      count += 1;
+    }
+  }
+  return count >= 2;
+}
+function testidDrift(value, hint) {
+  const present = hint?.presentTestids ?? [];
+  const drift = {
+    reasonKind: DriftReason.TESTID_NOT_FOUND,
+    reason: `testid "${value}" not found`,
+    anchor: value,
+    nearest: nearestTestid(value, present)
+  };
+  if (nearestIsAmbiguous(value, present))
+    drift.ambiguous = true;
+  return drift;
+}
+function anchorLabel(anchor) {
+  if (anchor.kind === AnchorKind.TESTID)
+    return anchor.value;
+  if (anchor.kind === AnchorKind.SIGNAL)
+    return anchor.name;
+  return anchor.name ?? anchor.role;
+}
+async function runTestidStep(session, step, index, value, dynamic, confirmDangerous) {
+  const queryResult = await session.command(IrisCommand.QUERY, { by: QueryBy.TESTID, value });
+  const { refs, hint } = readQuery(queryResult);
+  if (refs.length === 0) {
+    return {
+      step: index,
+      tool: step.tool,
+      anchor: value,
+      ok: false,
+      drift: testidDrift(value, hint)
+    };
+  }
+  const ref = refs[0] ?? "";
+  const note = refs.length > 1 ? `ambiguous testid '${value}', used first match` : void 0;
+  const act = await session.command(IrisCommand.ACT, {
+    ref,
+    action: step.action ?? "",
+    args: replayActionArgs(step.args, confirmDangerous)
+  });
+  const result = { step: index, tool: step.tool, anchor: value, ok: act.ok };
+  if (!act.ok) {
+    result.error = act.error ?? "command failed";
+    if (note !== void 0)
+      result.note = note;
+    return result;
+  }
+  const expectTestid = step.expect?.element?.testid;
+  if (expectTestid !== void 0 && !dynamic.has(expectTestid)) {
+    const expectQuery = await session.command(IrisCommand.QUERY, {
+      by: QueryBy.TESTID,
+      value: expectTestid
+    });
+    const expectRefs = readQuery(expectQuery);
+    if (expectRefs.refs.length === 0) {
+      return {
+        step: index,
+        tool: step.tool,
+        anchor: expectTestid,
+        ok: false,
+        drift: testidDrift(expectTestid, expectRefs.hint)
+      };
+    }
+  }
+  if (note !== void 0)
+    result.note = note;
+  return result;
+}
+async function runSignalStep(session, step, index, name, waitForSignal, signalTimeoutMs) {
+  const verdict = await waitForSignal(session, { kind: "signal", name }, signalTimeoutMs);
+  if (verdict.pass)
+    return { step: index, tool: step.tool, anchor: name, ok: true };
+  return {
+    step: index,
+    tool: step.tool,
+    anchor: name,
+    ok: false,
+    drift: {
+      reasonKind: DriftReason.SIGNAL_NOT_OBSERVED,
+      reason: `signal "${name}" not observed`,
+      anchor: name,
+      nearest: null
+    }
+  };
+}
+async function replayFlow(session, flow, waitForSignal, signalTimeoutMs, confirmDangerous = false) {
+  const results = [];
+  const dynamic = new Set((flow.dynamic ?? []).filter((a) => a.kind === AnchorKind.TESTID).map((a) => a.kind === AnchorKind.TESTID ? a.value : ""));
+  let index = 0;
+  for (const step of flow.steps) {
+    const label = anchorLabel(step.anchor);
+    let result;
+    if (step.anchor.kind === AnchorKind.SIGNAL) {
+      result = await runSignalStep(session, step, index, label, waitForSignal, signalTimeoutMs);
+    } else {
+      result = await runTestidStep(session, step, index, label, dynamic, confirmDangerous);
+    }
+    results.push(result);
+    if (result.drift !== void 0 || !result.ok)
+      break;
+    index += 1;
+  }
+  return results;
+}
+
+// ../server/dist/flows/heal.js
+function confidenceFor(from, to) {
+  if (from === to)
+    return 1;
+  const span = Math.max(from.length, to.length);
+  if (span === 0)
+    return 1;
+  const raw = 1 - editDistance(from, to) / span;
+  if (raw >= 1)
+    return 1;
+  if (raw <= 0)
+    return Number.EPSILON;
+  return raw;
+}
+function applyHealChanges(flow, changes) {
+  const byStep = /* @__PURE__ */ new Map();
+  for (const change of changes)
+    byStep.set(change.step, change);
+  const applied = [];
+  const steps = flow.steps.map((step, index) => {
+    const change = byStep.get(index);
+    if (change === void 0 || step.anchor.kind !== AnchorKind.TESTID || step.anchor.value !== change.from) {
+      return step;
+    }
+    applied.push(change);
+    return { ...step, anchor: { kind: AnchorKind.TESTID, value: change.to } };
+  });
+  return { flow: { ...flow, steps }, applied };
+}
+function proposeRebindWith(drift, step, minConfidence) {
+  if (drift.reasonKind !== DriftReason.TESTID_NOT_FOUND)
+    return void 0;
+  if (drift.ambiguous === true)
+    return void 0;
+  const to = drift.nearest;
+  if (to === null)
+    return void 0;
+  const confidence = confidenceFor(drift.anchor, to);
+  if (confidence < minConfidence)
+    return void 0;
+  return { step, from: drift.anchor, to, confidence };
+}
+function collectProposals(steps, minConfidence = HEAL_CONFIDENCE_MIN) {
+  const proposals = [];
+  for (const step of steps) {
+    if (step.drift === void 0)
+      continue;
+    const proposal = proposeRebindWith(step.drift, step.step, minConfidence);
+    if (proposal !== void 0)
+      proposals.push(proposal);
+  }
+  return proposals;
+}
+
+// ../server/dist/project/iris-dir.js
+import { join } from "path";
+function irisDirPaths(root) {
+  return {
+    root,
+    contract: join(root, IrisDir.CONTRACT_FILE),
+    flows: join(root, IrisDir.FLOWS_SUBDIR),
+    baselines: join(root, IrisDir.BASELINES_SUBDIR),
+    project: join(root, IrisDir.PROJECT_FILE),
+    visual: join(root, IrisDir.VISUAL_SUBDIR)
+  };
+}
+function visualPath(root, name) {
+  return join(root, IrisDir.VISUAL_SUBDIR, `${name}.png`);
+}
+function visualDiffPath(root, name) {
+  return join(root, IrisDir.VISUAL_SUBDIR, `${name}.diff.png`);
+}
+function flowPath(root, name) {
+  return join(root, IrisDir.FLOWS_SUBDIR, `${name}.json`);
+}
+function isValidFlowName(name) {
+  return FLOW_NAME_PATTERN.test(name) && !name.includes("..");
+}
+async function ensureIrisDir(fs2, root) {
+  const p = irisDirPaths(root);
+  await fs2.mkdir(p.root);
+  await fs2.mkdir(p.flows);
+  await fs2.mkdir(p.baselines);
+}
+var JSON_INDENT = 2;
+function stableSerialize(capabilities, generatedAt) {
+  const envelope = {
+    version: CONTRACT_FILE_VERSION,
+    generatedAt,
+    capabilities: {
+      testids: [...capabilities.testids].sort(),
+      signals: [...capabilities.signals].sort(),
+      stores: [...capabilities.stores].sort(),
+      flows: [...capabilities.flows].map((f) => ({ name: f.name, steps: [...f.steps] })).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+    }
+  };
+  return `${JSON.stringify(envelope, null, JSON_INDENT)}
+`;
+}
+async function writeContract(fs2, root, capabilities, now) {
+  await ensureIrisDir(fs2, root);
+  await fs2.writeFile(irisDirPaths(root).contract, stableSerialize(capabilities, now()));
+}
+async function readContract(fs2, root) {
+  const path = irisDirPaths(root).contract;
+  if (!await fs2.exists(path))
+    return { ok: false, reason: ContractReadError.MISSING };
+  let text;
+  try {
+    text = await fs2.readFile(path);
+  } catch (error) {
+    return {
+      ok: false,
+      reason: fs2.isNotFound(error) ? ContractReadError.MISSING : ContractReadError.MALFORMED
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { ok: false, reason: ContractReadError.MALFORMED };
+  }
+  const result = ContractFileSchema.safeParse(parsed);
+  if (!result.success)
+    return { ok: false, reason: ContractReadError.MALFORMED };
+  return { ok: true, capabilities: result.data.capabilities, generatedAt: result.data.generatedAt };
+}
+
+// ../server/dist/flows/flows.js
+function asString3(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function asRecord3(value) {
+  return typeof value === "object" && value !== null ? value : {};
+}
+function degradedAnchor() {
+  return { kind: AnchorKind.ROLE, role: DEGRADED_ANCHOR_ROLE };
+}
+function subStepToFlowStep(raw) {
+  const sub = asRecord3(raw);
+  const by = asString3(sub["by"]);
+  const value = asString3(sub["value"]);
+  const action = asString3(sub["action"]);
+  const args = asRecord3(sub["args"]);
+  if (by === QueryBy.TESTID && value !== void 0) {
+    return buildStep(IrisTool.ACT, { kind: AnchorKind.TESTID, value }, action, args, false);
+  }
+  return buildStep(IrisTool.ACT, degradedAnchor(), action, args, true);
+}
+function buildStep(tool, anchor, action, args, degraded) {
+  const step = { tool, anchor, args };
+  if (action !== void 0)
+    step.action = action;
+  if (degraded)
+    step.degraded = true;
+  return step;
+}
+function recordedStepToFlowStep(step) {
+  if (step.tool === IrisTool.ACT_SEQUENCE) {
+    const rawSubs = Array.isArray(step.args["steps"]) ? step.args["steps"] : [];
+    const subs = rawSubs.map(subStepToFlowStep);
+    const degraded = subs.some((s) => s.degraded === true);
+    const anchor = subs[0]?.anchor ?? degradedAnchor();
+    const out2 = { tool: IrisTool.ACT_SEQUENCE, anchor, steps: subs };
+    if (degraded)
+      out2.degraded = true;
+    if (step.expect !== void 0)
+      out2.expect = step.expect;
+    return out2;
+  }
+  const by = asString3(step.args["by"]);
+  const value = asString3(step.args["value"]);
+  const action = asString3(step.args["action"]);
+  const args = asRecord3(step.args["args"]);
+  const out = by === QueryBy.TESTID && value !== void 0 ? buildStep(step.tool, { kind: AnchorKind.TESTID, value }, action, args, false) : buildStep(step.tool, degradedAnchor(), action, args, true);
+  if (step.expect !== void 0)
+    out.expect = step.expect;
+  return out;
+}
+function withAnnotations(flow, ann) {
+  if (ann === void 0)
+    return flow;
+  const steps = flow.steps.map((step, i) => {
+    const expect = ann.stepExpect.get(i);
+    return expect === void 0 ? step : { ...step, expect };
+  });
+  const out = { ...flow, steps };
+  if (ann.dynamic.length > 0) {
+    out.dynamic = ann.dynamic.map((value) => ({ kind: AnchorKind.TESTID, value }));
+  }
+  if (ann.success !== void 0)
+    out.success = ann.success;
+  return out;
+}
+var JSON_INDENT2 = 2;
+var FLOW_SUFFIX = ".json";
+var FlowStore = class {
+  #fs;
+  #root;
+  #clock;
+  constructor(fs2, root, clock) {
+    this.#fs = fs2;
+    this.#root = root;
+    this.#clock = clock;
+  }
+  /**
+   * The single byte-stable flow serializer: 2-space indent + one trailing newline. save(),
+   * saveFlow() and heal() all route through it so an unchanged flow that round-trips through any
+   * of them produces byte-identical on-disk content (locked by the byte-stability tests).
+   */
+  #serialize(flow) {
+    return `${JSON.stringify(flow, null, JSON_INDENT2)}
+`;
+  }
+  /**
+   * Convert a CompiledProgram (testid-normalized) into an anchored, on-disk flow + write it.
+   * Optionally fold structured annotations (per-step expect, dynamic[], success) onto
+   * the flow before writing. Omitting `annotations` reproduces the same bytes.
+   */
+  async save(program, annotations) {
+    if (!isValidFlowName(program.name)) {
+      return { ok: false, code: FlowErrorCode.INVALID_NAME };
+    }
+    const steps = program.steps.map(recordedStepToFlowStep);
+    const base = {
+      version: FLOW_FILE_VERSION,
+      name: program.name,
+      createdAt: this.#clock.now(),
+      steps
+    };
+    const flow = withAnnotations(base, annotations);
+    await this.#fs.mkdir(irisDirPaths(this.#root).flows);
+    await this.#fs.writeFile(flowPath(this.#root, program.name), this.#serialize(flow));
+    const degraded = flow.steps.filter((s) => s.degraded === true).length;
+    return {
+      ok: true,
+      value: {
         name: program.name,
         stepCount: flow.steps.length,
         degraded,
@@ -1696,19 +2257,7 @@ var FlowStore = class {
     if (!loaded.ok)
       return { ok: false, code: loaded.code };
     const flow = loaded.value;
-    const byStep = /* @__PURE__ */ new Map();
-    for (const change of changes)
-      byStep.set(change.step, change);
-    const applied = [];
-    const steps = flow.steps.map((step, index) => {
-      const change = byStep.get(index);
-      if (change === void 0 || step.anchor.kind !== AnchorKind.TESTID || step.anchor.value !== change.from) {
-        return step;
-      }
-      applied.push(change);
-      return { ...step, anchor: { kind: AnchorKind.TESTID, value: change.to } };
-    });
-    const next = { ...flow, steps };
+    const { flow: next, applied } = applyHealChanges(flow, changes);
     await this.#fs.writeFile(flowPath(this.#root, name), this.#serialize(next));
     return { ok: true, value: { name, changed: applied } };
   }
@@ -1936,10 +2485,10 @@ function createNodeFileSystem() {
 
 // ../server/dist/mcp.js
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 
 // ../server/dist/tools/tools.js
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 
 // ../server/dist/input/real-input.js
 var DriveError = class extends Error {
@@ -2000,8 +2549,10 @@ async function performGesture(page, action, box, args, sleep) {
   }
   return { performed: false, center };
 }
+var HIDE_IRIS_CHROME_CSS = "[data-iris-overlay]{display:none !important}";
+var SCREENSHOT_DETERMINISM = { style: HIDE_IRIS_CHROME_CSS, animations: "disabled" };
 async function capturePage(page, opts) {
-  const buf = await page.screenshot(opts.clip !== void 0 ? { clip: opts.clip } : opts.fullPage === true ? { fullPage: true } : {});
+  const buf = await page.screenshot(opts.clip !== void 0 ? { ...SCREENSHOT_DETERMINISM, clip: opts.clip } : opts.fullPage === true ? { ...SCREENSHOT_DETERMINISM, fullPage: true } : { ...SCREENSHOT_DETERMINISM });
   return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
 }
 var nodeSleep = (ms) => new Promise((resolve) => {
@@ -2236,6 +2787,7 @@ var PredicateSchema = z3.lazy(() => z3.discriminatedUnion("kind", [
     name: z3.string().optional(),
     dataMatches: z3.record(z3.unknown()).optional()
   }),
+  z3.object({ kind: z3.literal("settled"), quietMs: z3.number().positive().optional() }),
   z3.object({ kind: z3.literal("allOf"), predicates: z3.array(PredicateSchema) }),
   z3.object({ kind: z3.literal("anyOf"), predicates: z3.array(PredicateSchema) }),
   z3.object({ kind: z3.literal("not"), predicate: PredicateSchema })
@@ -2432,6 +2984,39 @@ function evalSignal(events, p) {
     evidence: sameName.length > 0 ? { nearMiss: sameName } : void 0
   };
 }
+var SETTLE_ACTIVITY = /* @__PURE__ */ new Set([
+  EventType.NET_REQUEST,
+  EventType.DOM_ADDED,
+  EventType.DOM_REMOVED,
+  EventType.DOM_ATTR
+]);
+var DEFAULT_QUIET_MS = 500;
+function evalSettled(events, p, now) {
+  const quietMs = p.quietMs ?? DEFAULT_QUIET_MS;
+  let lastT = -1;
+  let lastType;
+  for (const e of events) {
+    if (SETTLE_ACTIVITY.has(e.type) && e.t > lastT) {
+      lastT = e.t;
+      lastType = e.type;
+    }
+  }
+  if (lastT < 0) {
+    return {
+      pass: true,
+      evidence: { settled: true, quietForMs: null, note: "no activity to settle" }
+    };
+  }
+  const quietForMs = now - lastT;
+  if (quietForMs >= quietMs) {
+    return { pass: true, evidence: { settled: true, quietForMs, lastActivity: lastType } };
+  }
+  return {
+    pass: false,
+    failureReason: `not settled: last activity (${String(lastType)}) ${String(quietForMs)}ms ago, need ${String(quietMs)}ms quiet`,
+    evidence: { quietForMs, lastActivity: lastType }
+  };
+}
 async function evaluatePredicate(session, predicate, since = 0) {
   const events = session.eventsSince(since);
   switch (predicate.kind) {
@@ -2449,6 +3034,8 @@ async function evaluatePredicate(session, predicate, since = 0) {
       return evalAnimation(events, predicate);
     case "signal":
       return evalSignal(events, predicate);
+    case "settled":
+      return evalSettled(events, predicate, session.elapsed());
     case "allOf": {
       const results = await Promise.all(predicate.predicates.map((p) => evaluatePredicate(session, p, since)));
       const failed = results.find((r) => !r.pass);
@@ -2474,6 +3061,10 @@ async function evaluatePredicate(session, predicate, since = 0) {
 function waitForPredicate(session, predicate, timeoutMs, since = 0) {
   return new Promise((resolve) => {
     let done = false;
+    const failed = (error) => ({
+      pass: false,
+      failureReason: error instanceof Error ? error.message : String(error)
+    });
     const finish = (result) => {
       if (done)
         return;
@@ -2487,6 +3078,8 @@ function waitForPredicate(session, predicate, timeoutMs, since = 0) {
       void evaluatePredicate(session, predicate, since).then((r) => {
         if (r.pass)
           finish(r);
+      }).catch((error) => {
+        finish(failed(error));
       });
     };
     const unsub = session.onEvent(() => {
@@ -2500,141 +3093,30 @@ function waitForPredicate(session, predicate, timeoutMs, since = 0) {
           evidence: r.evidence,
           failureReason: r.failureReason ?? "timed out waiting for predicate"
         });
+      }).catch((error) => {
+        finish(failed(error));
       });
     }, timeoutMs);
     check();
   });
 }
 
-// ../server/dist/flows/replay.js
-function asString2(value) {
-  return typeof value === "string" ? value : void 0;
-}
-function asRecord2(value) {
-  return typeof value === "object" && value !== null ? value : {};
-}
-function compileActStep(args, res) {
-  const testid = asString2(asRecord2(res)["testid"]);
-  const action = asString2(args["action"]) ?? "";
-  const actArgs = asRecord2(args["args"]);
-  if (testid !== void 0) {
-    return {
-      tool: IrisTool.ACT,
-      stable: true,
-      args: { by: QueryBy.TESTID, value: testid, action, args: actArgs }
-    };
-  }
-  return {
-    tool: IrisTool.ACT,
-    stable: false,
-    args: { ref: asString2(args["ref"]) ?? "", action, args: actArgs }
-  };
-}
-function compileSequenceStep(args, res) {
-  const inputSteps = Array.isArray(args["steps"]) ? args["steps"] : [];
-  const resolved = Array.isArray(asRecord2(res)["steps"]) ? asRecord2(res)["steps"] : [];
-  let stable = inputSteps.length > 0;
-  const subSteps = inputSteps.map((raw, i) => {
-    const step = asRecord2(raw);
-    const action = asString2(step["action"]) ?? "";
-    const stepArgs = asRecord2(step["args"]);
-    const testid = asString2(asRecord2(resolved[i])["testid"]);
-    if (testid !== void 0) {
-      return { by: QueryBy.TESTID, value: testid, action, args: stepArgs };
-    }
-    stable = false;
-    return { ref: asString2(step["ref"]) ?? "", action, args: stepArgs };
-  });
-  return { tool: IrisTool.ACT_SEQUENCE, stable, args: { steps: subSteps } };
-}
-async function resolveRef(session, step) {
-  const by = asString2(step.by);
-  const value = asString2(step.value);
-  if (by === QueryBy.TESTID && value !== void 0) {
-    const result = await session.command(IrisCommand.QUERY, { by, value });
-    if (!result.ok)
-      throw new Error(result.error ?? "query failed");
-    const elements = Array.isArray(asRecord2(result.result)["elements"]) ? asRecord2(result.result)["elements"] : [];
-    const ref2 = asString2(asRecord2(elements[0])["ref"]);
-    if (ref2 === void 0)
-      throw new Error(`testid '${value}' did not resolve in current page`);
-    return elements.length > 1 ? { ref: ref2, note: `ambiguous testid '${value}', used first match` } : { ref: ref2 };
-  }
-  const ref = asString2(step.ref);
-  if (ref === void 0 || ref.length === 0)
-    throw new Error("step has no testid or ref to resolve");
-  return { ref, note: "replayed by stale ref (not portable across sessions)" };
-}
-async function replayProgram(session, program) {
-  const results = [];
-  for (const step of program.steps) {
-    try {
-      if (step.tool === IrisTool.ACT_SEQUENCE) {
-        const subs = Array.isArray(step.args["steps"]) ? step.args["steps"] : [];
-        const notes = [];
-        const liveSteps = [];
-        for (const raw of subs) {
-          const sub = asRecord2(raw);
-          const { ref, note } = await resolveRef(session, sub);
-          if (note !== void 0)
-            notes.push(note);
-          liveSteps.push({
-            ref,
-            action: asString2(sub["action"]) ?? "",
-            args: asRecord2(sub["args"])
-          });
-        }
-        const r = await session.command(IrisCommand.ACT_SEQUENCE, { steps: liveSteps });
-        results.push(buildResult(step.tool, r.ok, r.error, notes));
-        if (!r.ok)
-          break;
-      } else {
-        const { ref, note } = await resolveRef(session, step.args);
-        const r = await session.command(IrisCommand.ACT, {
-          ref,
-          action: asString2(step.args["action"]) ?? "",
-          args: asRecord2(step.args["args"])
-        });
-        results.push(buildResult(step.tool, r.ok, r.error, note !== void 0 ? [note] : []));
-        if (!r.ok)
-          break;
-      }
-    } catch (e) {
-      results.push({
-        tool: step.tool,
-        ok: false,
-        error: e instanceof Error ? e.message : String(e)
-      });
-      break;
-    }
-  }
-  return results;
-}
-function buildResult(tool, ok, error, notes) {
-  const base = { tool, ok };
-  if (!ok)
-    base.error = error ?? "command failed";
-  if (notes.length > 0)
-    base.note = notes.join("; ");
-  return base;
-}
-
 // ../server/dist/events/event-filters.js
-function asString3(value) {
+function asString4(value) {
   return typeof value === "string" ? value : void 0;
 }
-function asNumber(value) {
+function asNumber2(value) {
   return typeof value === "number" ? value : void 0;
 }
 function matchNet(e, method, urlContains, status) {
   const d = e.data;
-  if (method !== void 0 && asString3(d["method"])?.toUpperCase() !== method.toUpperCase()) {
+  if (method !== void 0 && asString4(d["method"])?.toUpperCase() !== method.toUpperCase()) {
     return false;
   }
-  if (urlContains !== void 0 && !(asString3(d["url"]) ?? "").includes(urlContains)) {
+  if (urlContains !== void 0 && !(asString4(d["url"]) ?? "").includes(urlContains)) {
     return false;
   }
-  if (status !== void 0 && asNumber(d["status"]) !== status)
+  if (status !== void 0 && asNumber2(d["status"]) !== status)
     return false;
   return true;
 }
@@ -2651,8 +3133,8 @@ function matchConsole(e, level) {
 var HINT_SAMPLE_MAX = 5;
 function netEmptyHint(allNet) {
   const present = allNet.slice(-HINT_SAMPLE_MAX).reverse().map((e) => {
-    const status = asNumber(e.data["status"]);
-    const base = { method: asString3(e.data["method"]) ?? "", url: asString3(e.data["url"]) ?? "" };
+    const status = asNumber2(e.data["status"]);
+    const base = { method: asString4(e.data["method"]) ?? "", url: asString4(e.data["url"]) ?? "" };
     return status === void 0 ? base : { ...base, status };
   });
   return { totalInWindow: allNet.length, present };
@@ -2683,6 +3165,8 @@ function refuseIfThrottled(session, refuse) {
 }
 
 // ../server/dist/session/output-budget.js
+var LARGE_TIMELINE_EVENTS = 80;
+var LARGE_TIMELINE_BYTES = 8e3;
 function applyEventBudget(events, maxEvents) {
   if (maxEvents === void 0 || maxEvents < 0 || events.length <= maxEvents) {
     return { events, droppedOldest: 0 };
@@ -2693,8 +3177,92 @@ function applyEventBudget(events, maxEvents) {
   };
 }
 function costHint(payload, events, droppedOldest = 0) {
-  const bytes = JSON.stringify(payload)?.length ?? 0;
-  return droppedOldest > 0 ? { events, bytes, droppedOldest } : { events, bytes };
+  const json = JSON.stringify(payload) ?? "";
+  const bytes = json.length;
+  const base = droppedOldest > 0 ? { events, bytes, droppedOldest } : { events, bytes };
+  if (events >= LARGE_TIMELINE_EVENTS || bytes >= LARGE_TIMELINE_BYTES) {
+    base.recommendation = `large timeline (${String(events)} events, ~${String(estimateTokens(json))} tokens) \u2014 pass filters:[...] (e.g. ["signal","net"]) or max_events to scope your next call and cut tokens`;
+  }
+  return base;
+}
+var CHARS_PER_TOKEN = 4;
+function estimateTokens(text) {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+function sizeCost(payload) {
+  const json = JSON.stringify(payload) ?? "";
+  return { bytes: json.length, tokens: estimateTokens(json) };
+}
+function withSizeCost(result) {
+  if (typeof result !== "object" || result === null)
+    return result;
+  return { ...result, cost: sizeCost(result) };
+}
+
+// ../server/dist/tools/snapshot-delta.js
+var SnapshotDeltaMode = {
+  FULL: "full",
+  DELTA: "delta",
+  UNCHANGED: "unchanged"
+};
+function snapshotDelta(prevTree, nextTree) {
+  if (prevTree === void 0)
+    return { mode: SnapshotDeltaMode.FULL };
+  const { added, removed } = diffLines(normalizeLines(prevTree), normalizeLines(nextTree));
+  if (added.length === 0 && removed.length === 0)
+    return { mode: SnapshotDeltaMode.UNCHANGED };
+  return {
+    mode: SnapshotDeltaMode.DELTA,
+    delta: { added, removed, addedCount: added.length, removedCount: removed.length }
+  };
+}
+var DEFAULT_MAX_ENTRIES = 50;
+var SnapshotCache = class {
+  #map = /* @__PURE__ */ new Map();
+  #max;
+  constructor(max = DEFAULT_MAX_ENTRIES) {
+    this.#max = max;
+  }
+  /** Last tree for this key IF the route still matches; undefined when absent or route changed. */
+  recall(key, route) {
+    const entry = this.#map.get(key);
+    return entry !== void 0 && entry.route === route ? entry.tree : void 0;
+  }
+  remember(key, route, tree) {
+    if (this.#map.size >= this.#max && !this.#map.has(key)) {
+      const oldest = this.#map.keys().next().value;
+      if (oldest !== void 0)
+        this.#map.delete(oldest);
+    }
+    this.#map.set(key, { route, tree });
+  }
+};
+function snapshotCacheKey(sessionId, scope, mode) {
+  return `${sessionId}\0${scope}\0${mode}`;
+}
+function applySnapshotDelta(raw, opts, cache) {
+  if (typeof raw !== "object" || raw === null)
+    return raw;
+  const r = raw;
+  if (typeof r["tree"] !== "string")
+    return raw;
+  const tree = r["tree"];
+  const status = typeof r["status"] === "object" && r["status"] !== null ? r["status"] : {};
+  const route = typeof status["route"] === "string" ? status["route"] : "";
+  const key = snapshotCacheKey(opts.sessionId, opts.scope, opts.mode);
+  if (!opts.diff) {
+    cache.remember(key, route, tree);
+    return raw;
+  }
+  const prev = cache.recall(key, route);
+  cache.remember(key, route, tree);
+  const decision = snapshotDelta(prev, tree);
+  if (decision.mode === SnapshotDeltaMode.FULL)
+    return raw;
+  if (decision.mode === SnapshotDeltaMode.UNCHANGED) {
+    return { mode: SnapshotDeltaMode.UNCHANGED, status: r["status"] };
+  }
+  return { mode: SnapshotDeltaMode.DELTA, delta: decision.delta, status: r["status"] };
 }
 
 // ../server/dist/session/state-select.js
@@ -2745,25 +3313,55 @@ function capDepth(value, maxDepth) {
   return value;
 }
 
-// ../server/dist/tools/tools-helpers.js
-function parseInteractive(tree) {
-  const items = [];
-  for (const line of tree.split("\n")) {
-    const match = /\(ref=(e\d+)\)/.exec(line);
-    if (match !== null) {
-      items.push({ ref: match[1] ?? "", desc: line.replace(/\s*\(ref=e\d+\)/, "").trim() });
+// ../server/dist/tools/query-paginate.js
+function paginateQueryResult(result, limit, countOnly) {
+  if (typeof result !== "object" || result === null)
+    return result;
+  const record = result;
+  const elements = record["elements"];
+  if (!Array.isArray(elements))
+    return result;
+  const total = elements.length;
+  if (countOnly) {
+    const { elements: _dropped, ...rest } = record;
+    return { ...rest, count: total };
+  }
+  if (limit !== void 0 && limit >= 0 && total > limit) {
+    return { ...record, elements: elements.slice(0, limit), total, truncated: true };
+  }
+  return result;
+}
+
+// ../server/dist/tools/assert-grade.js
+var PRESENCE_ONLY_ADVICE = "This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion \u2014 or allOf it with one \u2014 so green means the feature actually worked.";
+function walk(predicate) {
+  switch (predicate.kind) {
+    case "signal":
+    case "net":
+      return { consequence: true, presence: false };
+    case "element":
+    case "text":
+      return { consequence: false, presence: true };
+    case "route":
+    case "console":
+    case "animation":
+    case "settled":
+      return { consequence: false, presence: false };
+    case "allOf":
+    case "anyOf": {
+      const subs = predicate.predicates.map(walk);
+      return {
+        consequence: subs.some((s) => s.consequence),
+        presence: subs.some((s) => s.presence)
+      };
     }
+    case "not":
+      return walk(predicate.predicate);
   }
-  return items;
-}
-function asString4(value) {
-  return typeof value === "string" ? value : void 0;
-}
-function asNumber2(value) {
-  return typeof value === "number" ? value : void 0;
 }
-function asRecord3(value) {
-  return typeof value === "object" && value !== null ? value : {};
+function isPresenceOnlyAssertion(predicate) {
+  const kinds = walk(predicate);
+  return kinds.presence && !kinds.consequence;
 }
 
 // ../server/dist/tools/contract-tools.js
@@ -2797,7 +3395,7 @@ var CONTRACT_TOOLS = [
           throw new Error(r.reason === ContractReadError.MISSING ? "no .iris/contract.json on disk \u2014 run iris_contract_save first (or omit fromDisk to read the live session)" : ".iris/contract.json is malformed \u2014 fix or regenerate it with iris_contract_save");
         return { ...r.capabilities, source: "disk", generatedAt: r.generatedAt };
       }
-      const caps = await commandOrThrow(deps, asString4(args["sessionId"]), IrisCommand.CAPABILITIES, {});
+      const caps = await commandOrThrow(deps, asString(args["sessionId"]), IrisCommand.CAPABILITIES, {});
       return { ...caps, source: "live" };
     }
   },
@@ -2812,7 +3410,7 @@ var CONTRACT_TOOLS = [
       signalCount: z4.number()
     },
     handler: async (deps, args) => {
-      const res = await commandOrThrow(deps, asString4(args["sessionId"]), IrisCommand.CAPABILITIES, {});
+      const res = await commandOrThrow(deps, asString(args["sessionId"]), IrisCommand.CAPABILITIES, {});
       const caps = CapabilitiesSchema.parse(res);
       await writeContract(deps.fs, deps.irisRoot, caps, deps.now);
       return {
@@ -2825,253 +3423,399 @@ var CONTRACT_TOOLS = [
   }
 ];
 
-// ../server/dist/tools/browser-tools.js
+// ../server/dist/domain/domain-tools.js
 import { z as z5 } from "zod";
-var sessionIdShape2 = {
-  sessionId: z5.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
+
+// ../server/dist/flows/flow-classify.js
+var FlowAssertionGrade = {
+  /** At least one step (or the success end-condition) asserts a signal/network consequence. */
+  ASSERTED: "asserted",
+  /** Only element-presence checks — a healed-but-wrong locator could still pass. */
+  PRESENCE_ONLY: "presence-only",
+  /** Performs actions but asserts nothing observable — passes even if the feature is broken. */
+  ASSERTION_FREE: "assertion-free"
 };
-async function commandOrThrow2(deps, sessionId, name, args) {
-  const session = deps.sessions.resolve(sessionId);
-  const result = await session.command(name, args);
-  if (!result.ok)
-    throw new Error(result.error ?? `command '${name}' failed`);
-  return result.result;
+var ASSERTION_FREE_WARNING = "This flow performs actions but asserts no observable consequence \u2014 it will pass even if the feature is broken. Add a consequence assertion with iris_annotate (assert-signal / assert-net) or a success-state.";
+var PRESENCE_ONLY_WARNING = "This flow only checks element presence, not an observable consequence (signal/network). A locator healed to the wrong element can still pass it. Add a consequence assertion (assert-signal / assert-net / success-state).";
+function expectIsConsequence(e) {
+  return e !== void 0 && (e.signal !== void 0 || e.net !== void 0);
 }
-var BROWSER_TOOLS = [
-  {
-    name: IrisTool.NAVIGATE,
-    description: "Navigate the connected browser tab to a URL. The SDK reconnects automatically after the page loads. Use iris_sessions to confirm the new tab is connected before acting.",
-    inputSchema: {
-      url: z5.string().describe("The URL to navigate to."),
-      ...sessionIdShape2
-    },
-    outputSchema: {
-      ok: z5.boolean(),
-      url: z5.string().optional(),
-      reason: z5.string().optional()
-    },
-    handler: async (deps, args) => {
-      const url = asString4(args["url"]);
-      if (url === void 0 || url.length === 0)
-        return { ok: false, reason: "url required" };
-      await commandOrThrow2(deps, asString4(args["sessionId"]), IrisCommand.NAVIGATE, { url });
-      return { ok: true, url };
-    }
-  },
-  {
-    name: IrisTool.REFRESH,
-    description: "Reload the connected browser tab. Pass { hard: true } to bypass the browser cache (equivalent to Cmd+Shift+R). The SDK reconnects automatically after the reload.",
-    inputSchema: {
-      hard: z5.boolean().optional().describe("Set true to bypass the browser cache. Default: false (normal reload)."),
-      ...sessionIdShape2
-    },
-    outputSchema: {
-      ok: z5.boolean()
-    },
-    handler: async (deps, args) => {
-      await commandOrThrow2(deps, asString4(args["sessionId"]), IrisCommand.REFRESH, {
-        hard: args["hard"] === true
-      });
-      return { ok: true };
-    }
+function expectIsWeak(e) {
+  return e !== void 0 && e.element !== void 0 && e.signal === void 0 && e.net === void 0;
+}
+function flattenSteps(steps) {
+  const out = [];
+  for (const s of steps) {
+    out.push(s);
+    if (s.steps !== void 0)
+      out.push(...flattenSteps(s.steps));
   }
-];
-
-// ../server/dist/flows/flow-tools.js
-import { z as z6 } from "zod";
+  return out;
+}
+function classifyFlowAssertions(flow) {
+  const all = flattenSteps(flow.steps);
+  let consequenceSteps = 0;
+  let weakSteps = 0;
+  for (const s of all) {
+    if (expectIsConsequence(s.expect))
+      consequenceSteps++;
+    else if (expectIsWeak(s.expect))
+      weakSteps++;
+  }
+  const successIsConsequence = expectIsConsequence(flow.success);
+  const successIsWeak = expectIsWeak(flow.success);
+  const hasConsequenceAssertion = consequenceSteps > 0 || successIsConsequence;
+  const hasAnyAssertion = hasConsequenceAssertion || weakSteps > 0 || successIsWeak;
+  let grade;
+  let warning;
+  if (hasConsequenceAssertion) {
+    grade = FlowAssertionGrade.ASSERTED;
+  } else if (hasAnyAssertion) {
+    grade = FlowAssertionGrade.PRESENCE_ONLY;
+    warning = PRESENCE_ONLY_WARNING;
+  } else {
+    grade = FlowAssertionGrade.ASSERTION_FREE;
+    warning = ASSERTION_FREE_WARNING;
+  }
+  return {
+    grade,
+    hasConsequenceAssertion,
+    totalSteps: all.length,
+    consequenceSteps,
+    weakSteps,
+    successIsConsequence,
+    ...warning !== void 0 ? { warning } : {}
+  };
+}
 
-// ../server/dist/flows/flow-replay.js
-function editDistance(a, b) {
-  const s = a.toLowerCase();
-  const t = b.toLowerCase();
-  const rows = s.length + 1;
-  const cols = t.length + 1;
-  const prev = new Array(cols);
-  const curr = new Array(cols);
-  for (let j = 0; j < cols; j++)
-    prev[j] = j;
-  for (let i = 1; i < rows; i++) {
-    curr[0] = i;
-    for (let j = 1; j < cols; j++) {
-      const cost = s[i - 1] === t[j - 1] ? 0 : 1;
-      curr[j] = Math.min((prev[j] ?? 0) + 1, (curr[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+// ../server/dist/flows/flow-success.js
+function dynamicTestids(flow) {
+  return new Set((flow.dynamic ?? []).filter((a) => a.kind === AnchorKind.TESTID).map((a) => a.kind === AnchorKind.TESTID ? a.value : ""));
+}
+function successLabel(success) {
+  if (success.signal !== void 0)
+    return success.signal;
+  if (success.net !== void 0)
+    return success.net.urlContains ?? success.net.method ?? "net";
+  return success.element?.testid ?? success.element?.name ?? success.element?.role ?? "success";
+}
+function successToPredicate(success, dynamic) {
+  const parts = [];
+  if (success.signal !== void 0) {
+    parts.push(success.signalData !== void 0 ? { kind: "signal", name: success.signal, dataMatches: success.signalData } : { kind: "signal", name: success.signal });
+  }
+  if (success.net !== void 0) {
+    const net2 = { kind: "net" };
+    if (success.net.method !== void 0)
+      net2.method = success.net.method;
+    if (success.net.urlContains !== void 0)
+      net2.urlContains = success.net.urlContains;
+    if (success.net.status !== void 0)
+      net2.status = success.net.status;
+    parts.push(net2);
+  }
+  const element = success.element;
+  if (element !== void 0) {
+    const testid = element.testid;
+    if (testid === void 0 || !dynamic.has(testid)) {
+      const query = {};
+      if (testid !== void 0)
+        query["testid"] = testid;
+      if (element.role !== void 0)
+        query["role"] = element.role;
+      if (element.name !== void 0)
+        query["name"] = element.name;
+      if (Object.keys(query).length > 0)
+        parts.push({ kind: "element", query });
     }
-    for (let j = 0; j < cols; j++)
-      prev[j] = curr[j] ?? 0;
   }
-  return prev[cols - 1] ?? 0;
+  const [first] = parts;
+  if (parts.length === 0)
+    return void 0;
+  if (parts.length === 1 && first !== void 0)
+    return first;
+  return { kind: "allOf", predicates: parts };
+}
+async function assertSuccess(session, success, dynamic, waitForSignal, timeoutMs, since = 0) {
+  if (success === void 0)
+    return { pass: true };
+  const predicate = successToPredicate(success, dynamic);
+  if (predicate === void 0)
+    return { pass: true };
+  return waitForSignal(session, predicate, timeoutMs, since);
 }
-function nearestTestid(missing, present) {
-  let best = null;
-  let bestDistance = Number.POSITIVE_INFINITY;
-  for (const candidate of present) {
-    const distance = editDistance(missing, candidate);
-    if (distance < bestDistance || distance === bestDistance && best !== null && candidate.length < best.length || distance === bestDistance && best !== null && candidate.length === best.length && candidate < best) {
-      best = candidate;
-      bestDistance = distance;
-    }
+
+// ../server/dist/domain/flow-risk.js
+var RiskLevel = {
+  HIGH: "high",
+  MEDIUM: "medium",
+  LOW: "low",
+  UNKNOWN: "unknown"
+};
+var RANK = {
+  [RiskLevel.HIGH]: 3,
+  [RiskLevel.MEDIUM]: 2,
+  [RiskLevel.UNKNOWN]: 1,
+  [RiskLevel.LOW]: 0
+};
+function latestRun(name, runs) {
+  let best;
+  for (const run of runs) {
+    if (run.name === name && (best === void 0 || run.at > best.at))
+      best = run;
   }
   return best;
 }
-function readQuery(result) {
-  if (!result.ok)
-    return { refs: [] };
-  const payload = asRecord3(result.result);
-  const elements = Array.isArray(payload["elements"]) ? payload["elements"] : [];
-  const refs = elements.map((e) => asString4(asRecord3(e)["ref"]) ?? "").filter((r) => r.length > 0);
-  const rawHint = payload["hint"];
-  if (typeof rawHint === "object" && rawHint !== null) {
-    const hint = asRecord3(rawHint);
-    const present = Array.isArray(hint["presentTestids"]) ? hint["presentTestids"].filter((t) => typeof t === "string") : [];
+function runRisk(run) {
+  if (run === void 0)
+    return { level: RiskLevel.UNKNOWN, reason: "never run" };
+  if (run.status === RunStatus.ERROR || run.status === RunStatus.FAIL) {
+    return { level: RiskLevel.HIGH, reason: "last run failed" };
+  }
+  if (run.status === RunStatus.DRIFT)
+    return { level: RiskLevel.HIGH, reason: "last run drifted" };
+  const errors = (run.evidence?.consoleErrors ?? 0) + (run.evidence?.networkErrors ?? 0);
+  if (errors > 0) {
     return {
-      refs,
-      hint: {
-        route: asString4(hint["route"]) ?? "",
-        presentTestids: present,
-        presentRegions: [],
-        knownEmptyState: hint["knownEmptyState"] === true
-      }
+      level: RiskLevel.MEDIUM,
+      reason: `last run passed but logged ${String(errors)} error(s)`
     };
   }
-  return { refs };
-}
-function testidDrift(value, hint) {
-  return {
-    reasonKind: DriftReason.TESTID_NOT_FOUND,
-    reason: `testid "${value}" not found`,
-    anchor: value,
-    nearest: nearestTestid(value, hint?.presentTestids ?? [])
-  };
-}
-function anchorLabel(anchor) {
-  if (anchor.kind === AnchorKind.TESTID)
-    return anchor.value;
-  if (anchor.kind === AnchorKind.SIGNAL)
-    return anchor.name;
-  return anchor.name ?? anchor.role;
+  return { level: RiskLevel.LOW, reason: "last run passed clean" };
 }
-async function runTestidStep(session, step, index, value, dynamic) {
-  const queryResult = await session.command(IrisCommand.QUERY, { by: QueryBy.TESTID, value });
-  const { refs, hint } = readQuery(queryResult);
-  if (refs.length === 0) {
+function gradeRisk(grade) {
+  if (grade === FlowAssertionGrade.ASSERTION_FREE) {
     return {
-      step: index,
-      tool: step.tool,
-      anchor: value,
-      ok: false,
-      drift: testidDrift(value, hint)
+      level: RiskLevel.MEDIUM,
+      reason: "asserts no consequence \u2014 a green run proves little"
     };
   }
-  const ref = refs[0] ?? "";
-  const note = refs.length > 1 ? `ambiguous testid '${value}', used first match` : void 0;
-  const act = await session.command(IrisCommand.ACT, {
-    ref,
-    action: step.action ?? "",
-    args: step.args ?? {}
-  });
-  const result = { step: index, tool: step.tool, anchor: value, ok: act.ok };
-  if (!act.ok) {
-    result.error = act.error ?? "command failed";
-    if (note !== void 0)
-      result.note = note;
-    return result;
+  if (grade === FlowAssertionGrade.PRESENCE_ONLY) {
+    return { level: RiskLevel.LOW, reason: "presence-only assertion" };
   }
-  const expectTestid = step.expect?.element?.testid;
-  if (expectTestid !== void 0 && !dynamic.has(expectTestid)) {
-    const expectQuery = await session.command(IrisCommand.QUERY, {
-      by: QueryBy.TESTID,
-      value: expectTestid
-    });
-    const expectRefs = readQuery(expectQuery);
-    if (expectRefs.refs.length === 0) {
-      return {
-        step: index,
-        tool: step.tool,
-        anchor: expectTestid,
-        ok: false,
-        drift: testidDrift(expectTestid, expectRefs.hint)
-      };
-    }
+  return { level: RiskLevel.LOW, reason: "asserts a consequence" };
+}
+function flowRisk(grade, run) {
+  const r = runRisk(run);
+  const g = gradeRisk(grade);
+  const top = RANK[r.level] >= RANK[g.level] ? r : g;
+  return run === void 0 ? { level: top.level, reason: top.reason } : { level: top.level, reason: top.reason, lastStatus: run.status };
+}
+function rankByRisk(entries) {
+  return [...entries].sort((a, b) => RANK[b.risk.level] - RANK[a.risk.level] || a.name.localeCompare(b.name)).map((e) => e.name);
+}
+
+// ../server/dist/domain/domain-model.js
+function flatten(steps) {
+  const out = [];
+  for (const s of steps) {
+    out.push(s);
+    if (s.steps !== void 0)
+      out.push(...flatten(s.steps));
   }
-  if (note !== void 0)
-    result.note = note;
-  return result;
+  return out;
 }
-async function runSignalStep(session, step, index, name, waitForSignal, signalTimeoutMs) {
-  const verdict = await waitForSignal(session, { kind: "signal", name }, signalTimeoutMs);
-  if (verdict.pass)
-    return { step: index, tool: step.tool, anchor: name, ok: true };
+function flowSignals(flow) {
+  const set = /* @__PURE__ */ new Set();
+  for (const step of flatten(flow.steps)) {
+    if (step.anchor.kind === AnchorKind.SIGNAL)
+      set.add(step.anchor.name);
+    if (step.expect?.signal !== void 0)
+      set.add(step.expect.signal);
+  }
+  if (flow.success?.signal !== void 0)
+    set.add(flow.success.signal);
+  return [...set];
+}
+function flowTestids(flow) {
+  const set = /* @__PURE__ */ new Set();
+  for (const step of flatten(flow.steps)) {
+    if (step.anchor.kind === AnchorKind.TESTID)
+      set.add(step.anchor.value);
+    if (step.expect?.element?.testid !== void 0)
+      set.add(step.expect.element.testid);
+  }
+  if (flow.success?.element?.testid !== void 0)
+    set.add(flow.success.element.testid);
+  return [...set];
+}
+var EMPTY_CONTRACT = { testids: [], signals: [], stores: [], flows: [] };
+function buildDomainModel(flows, contract, runs = []) {
+  const caps = contract ?? EMPTY_CONTRACT;
+  const hasHistory = runs.length > 0;
+  const flowSummaries = flows.map((flow) => {
+    const c = classifyFlowAssertions(flow);
+    const summary = {
+      name: flow.name,
+      steps: c.totalSteps,
+      grade: c.grade,
+      asserts: c.hasConsequenceAssertion,
+      signals: flowSignals(flow),
+      testids: flowTestids(flow)
+    };
+    if (flow.success !== void 0)
+      summary.mustHold = successLabel(flow.success);
+    if (c.warning !== void 0)
+      summary.warning = c.warning;
+    if (hasHistory)
+      summary.risk = flowRisk(c.grade, latestRun(flow.name, runs));
+    return summary;
+  });
+  const testedSignals = new Set(flowSummaries.flatMap((f) => f.signals));
+  const testedTestids = new Set(flowSummaries.flatMap((f) => f.testids));
+  const coverage = {
+    asserted: flowSummaries.filter((f) => f.grade === FlowAssertionGrade.ASSERTED).length,
+    presenceOnly: flowSummaries.filter((f) => f.grade === FlowAssertionGrade.PRESENCE_ONLY).length,
+    assertionFree: flowSummaries.filter((f) => f.grade === FlowAssertionGrade.ASSERTION_FREE).length
+  };
+  const gaps = {
+    unassertedFlows: flowSummaries.filter((f) => !f.asserts).map((f) => f.name),
+    declaredUntestedSignals: caps.signals.filter((s) => !testedSignals.has(s)),
+    declaredUntestedTestids: caps.testids.filter((t) => !testedTestids.has(t))
+  };
+  const riskRanked = hasHistory ? rankByRisk(flowSummaries.filter((f) => f.risk !== void 0).map((f) => ({ name: f.name, risk: f.risk }))) : [];
+  const top = riskRanked[0];
+  const topFlow = top === void 0 ? void 0 : flowSummaries.find((f) => f.name === top);
+  const topRisk = topFlow?.risk !== void 0 && (topFlow.risk.level === RiskLevel.HIGH || topFlow.risk.level === RiskLevel.MEDIUM) ? { name: topFlow.name, reason: topFlow.risk.reason } : void 0;
   return {
-    step: index,
-    tool: step.tool,
-    anchor: name,
-    ok: false,
-    drift: {
-      reasonKind: DriftReason.SIGNAL_NOT_OBSERVED,
-      reason: `signal "${name}" not observed`,
-      anchor: name,
-      nearest: null
-    }
+    flowCount: flows.length,
+    flows: flowSummaries,
+    declared: { testids: caps.testids.length, signals: caps.signals, stores: caps.stores },
+    coverage,
+    gaps,
+    riskRanked,
+    summary: buildSummary(flows.length, coverage, gaps, topRisk)
   };
 }
-async function replayFlow(session, flow, waitForSignal, signalTimeoutMs) {
-  const results = [];
-  const dynamic = new Set((flow.dynamic ?? []).filter((a) => a.kind === AnchorKind.TESTID).map((a) => a.kind === AnchorKind.TESTID ? a.value : ""));
-  let index = 0;
-  for (const step of flow.steps) {
-    const label = anchorLabel(step.anchor);
-    let result;
-    if (step.anchor.kind === AnchorKind.SIGNAL) {
-      result = await runSignalStep(session, step, index, label, waitForSignal, signalTimeoutMs);
-    } else {
-      result = await runTestidStep(session, step, index, label, dynamic);
-    }
-    results.push(result);
-    if (result.drift !== void 0 || !result.ok)
-      break;
-    index += 1;
+function buildSummary(flowCount, coverage, gaps, topRisk) {
+  if (flowCount === 0) {
+    return "No saved flows yet \u2014 record the critical journeys (iris_record_start) so the agent learns the app.";
   }
-  return results;
+  const parts = [
+    `${String(flowCount)} flow${flowCount === 1 ? "" : "s"}: ${String(coverage.asserted)} asserted, ${String(coverage.presenceOnly)} presence-only, ${String(coverage.assertionFree)} assertion-free`
+  ];
+  if (topRisk !== void 0) {
+    parts.push(`test first: ${topRisk.name} (${topRisk.reason})`);
+  }
+  if (gaps.declaredUntestedSignals.length > 0) {
+    parts.push(`${String(gaps.declaredUntestedSignals.length)} declared signal(s) no flow asserts (${gaps.declaredUntestedSignals.join(", ")})`);
+  }
+  if (gaps.unassertedFlows.length > 0) {
+    parts.push(`${String(gaps.unassertedFlows.length)} flow(s) assert no consequence`);
+  }
+  return parts.join(". ") + ".";
 }
 
-// ../server/dist/flows/heal.js
-function confidenceFor(from, to) {
-  if (from === to)
-    return 1;
-  const span = Math.max(from.length, to.length);
-  if (span === 0)
-    return 1;
-  const raw = 1 - editDistance(from, to) / span;
-  if (raw >= 1)
-    return 1;
-  if (raw <= 0)
-    return Number.EPSILON;
-  return raw;
-}
-function proposeRebindWith(drift, step, minConfidence) {
-  if (drift.reasonKind !== DriftReason.TESTID_NOT_FOUND)
-    return void 0;
-  const to = drift.nearest;
-  if (to === null)
-    return void 0;
-  const confidence = confidenceFor(drift.anchor, to);
-  if (confidence < minConfidence)
-    return void 0;
-  return { step, from: drift.anchor, to, confidence };
+// ../server/dist/domain/domain-tools.js
+var DOMAIN_TOOLS = [
+  {
+    name: IrisTool.DOMAIN,
+    description: "Read the app domain model BEFORE testing: every saved flow with its assertion grade, the consequence that MUST hold for it (mustHold = what it actually tests), the anchors/signals it exercises, plus GAPS \u2014 declared signals/testids that NO flow asserts (untested intent), and flows that assert no observable consequence. Use this to decide what to test and where the real risk is, instead of crawling the whole app. Reads .iris/flows/ + .iris/contract.json (no browser needed).",
+    inputSchema: {},
+    outputSchema: {
+      flowCount: z5.number(),
+      flows: z5.array(z5.object({
+        name: z5.string(),
+        steps: z5.number(),
+        grade: z5.string(),
+        asserts: z5.boolean(),
+        mustHold: z5.string().optional().describe("The success consequence that must hold for this flow (what it actually tests)."),
+        warning: z5.string().optional(),
+        signals: z5.array(z5.string()),
+        testids: z5.array(z5.string())
+      })),
+      declared: z5.object({
+        testids: z5.number(),
+        signals: z5.array(z5.string()),
+        stores: z5.array(z5.string())
+      }),
+      coverage: z5.object({
+        asserted: z5.number(),
+        presenceOnly: z5.number(),
+        assertionFree: z5.number()
+      }),
+      gaps: z5.object({
+        unassertedFlows: z5.array(z5.string()),
+        declaredUntestedSignals: z5.array(z5.string()),
+        declaredUntestedTestids: z5.array(z5.string())
+      }),
+      riskRanked: z5.array(z5.string()).describe("Flow names worst-risk first (run history + assertion quality). Test these first."),
+      summary: z5.string()
+    },
+    handler: async (deps) => {
+      const names = await deps.flows.list();
+      const flows = [];
+      for (const name of names) {
+        const loaded = await deps.flows.load(name);
+        if (loaded.ok)
+          flows.push(loaded.value);
+      }
+      const contract = await readContract(deps.fs, deps.irisRoot);
+      const project = await deps.project.read();
+      const runs = project.ok ? project.file.runs : [];
+      return buildDomainModel(flows, contract.ok ? contract.capabilities : null, runs);
+    }
+  }
+];
+
+// ../server/dist/tools/browser-tools.js
+import { z as z6 } from "zod";
+var sessionIdShape2 = {
+  sessionId: z6.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
+};
+async function commandOrThrow2(deps, sessionId, name, args) {
+  const session = deps.sessions.resolve(sessionId);
+  const result = await session.command(name, args);
+  if (!result.ok)
+    throw new Error(result.error ?? `command '${name}' failed`);
+  return result.result;
 }
-function collectProposals(steps, minConfidence = HEAL_CONFIDENCE_MIN) {
-  const proposals = [];
-  for (const step of steps) {
-    if (step.drift === void 0)
-      continue;
-    const proposal = proposeRebindWith(step.drift, step.step, minConfidence);
-    if (proposal !== void 0)
-      proposals.push(proposal);
+var BROWSER_TOOLS = [
+  {
+    name: IrisTool.NAVIGATE,
+    description: "Navigate the connected browser tab to a URL. The SDK reconnects automatically after the page loads. Use iris_sessions to confirm the new tab is connected before acting.",
+    inputSchema: {
+      url: z6.string().describe("The URL to navigate to."),
+      ...sessionIdShape2
+    },
+    outputSchema: {
+      ok: z6.boolean(),
+      url: z6.string().optional(),
+      reason: z6.string().optional()
+    },
+    handler: async (deps, args) => {
+      const url = asString(args["url"]);
+      if (url === void 0 || url.length === 0)
+        return { ok: false, reason: "url required" };
+      const result = await commandOrThrow2(deps, asString(args["sessionId"]), IrisCommand.NAVIGATE, { url });
+      return {
+        ok: result.ok === true,
+        ...typeof result.url === "string" ? { url: result.url } : {},
+        ...typeof result.reason === "string" ? { reason: result.reason } : {}
+      };
+    }
+  },
+  {
+    name: IrisTool.REFRESH,
+    description: "Reload the connected browser tab. Pass { hard: true } to bypass the browser cache (equivalent to Cmd+Shift+R). The SDK reconnects automatically after the reload.",
+    inputSchema: {
+      hard: z6.boolean().optional().describe("Set true to bypass the browser cache. Default: false (normal reload)."),
+      ...sessionIdShape2
+    },
+    outputSchema: {
+      ok: z6.boolean()
+    },
+    handler: async (deps, args) => {
+      await commandOrThrow2(deps, asString(args["sessionId"]), IrisCommand.REFRESH, {
+        hard: args["hard"] === true
+      });
+      return { ok: true };
+    }
   }
-  return proposals;
-}
+];
 
 // ../server/dist/flows/flow-tools.js
+import { z as z7 } from "zod";
 function latestRecordedFlow(events) {
   for (let i = events.length - 1; i >= 0; i--) {
     const event = events[i];
@@ -3117,18 +3861,26 @@ async function recordReplayRun(deps, name, status, driftSteps, durationMs) {
 var FLOW_TOOLS = [
   {
     name: IrisTool.FLOW_SAVE,
-    description: 'Persist the last/active recording (by name) as a git-checked, anchor-resolved flow at .iris/flows/<name>.json. Each step is bound to a SEMANTIC anchor (testid/role/signal), never a volatile ref; steps without a resolvable testid are kept with degraded:true (a "add a data-testid here" marker) rather than dropped. Returns { name, stepCount, degraded, empty } or { error, code }.',
+    description: 'Persist the last/active recording (by name) as a git-checked, anchor-resolved flow at .iris/flows/<name>.json. Each step is bound to a SEMANTIC anchor (testid/role/signal), never a volatile ref; steps without a resolvable testid are kept with degraded:true (a "add a data-testid here" marker) rather than dropped. Returns { name, stepCount, degraded, empty, assertions } \u2014 `assertions.grade` is asserted | presence-only | assertion-free: a flow that only acts (or only checks element presence) will pass even if the feature breaks, so when grade is not "asserted" follow assertions.warning and add a consequence assertion via iris_annotate (assert-signal / assert-net / success-state).',
     inputSchema: {
-      flowName: z6.string().describe("Name for the flow file (saved to .iris/flows/<flowName>.json). Use again in iris_flow_load/iris_flow_replay.")
+      flowName: z7.string().describe("Name for the flow file (saved to .iris/flows/<flowName>.json). Use again in iris_flow_load/iris_flow_replay.")
     },
     outputSchema: {
-      saved: z6.boolean(),
-      path: z6.string(),
-      stepCount: z6.number().optional(),
-      degraded: z6.number().optional()
+      saved: z7.boolean(),
+      path: z7.string(),
+      stepCount: z7.number().optional(),
+      degraded: z7.number().optional(),
+      assertions: z7.object({
+        grade: z7.string().describe("asserted | presence-only | assertion-free"),
+        hasConsequenceAssertion: z7.boolean(),
+        totalSteps: z7.number(),
+        consequenceSteps: z7.number(),
+        weakSteps: z7.number(),
+        warning: z7.string().optional()
+      }).optional()
     },
     handler: (deps, args) => {
-      const name = asString4(args["flowName"]) ?? "";
+      const name = asString(args["flowName"]) ?? "";
       const program = deps.recordings.getCompiled(name);
       if (program === void 0) {
         return Promise.resolve({
@@ -3142,10 +3894,12 @@ var FLOW_TOOLS = [
         dynamic: deps.annotations.dynamic(name),
         ...success !== void 0 ? { success } : {}
       };
-      return deps.flows.save(program, annotations).then((res) => {
-        if (res.ok)
-          deps.annotations.clear(name);
-        return res.ok ? res.value : { error: flowErrorMessage(res.code), code: res.code };
+      return deps.flows.save(program, annotations).then(async (res) => {
+        if (!res.ok)
+          return { error: flowErrorMessage(res.code), code: res.code };
+        deps.annotations.clear(name);
+        const loaded = await deps.flows.load(res.value.name);
+        return loaded.ok ? { ...res.value, assertions: classifyFlowAssertions(loaded.value) } : res.value;
       });
     }
   },
@@ -3154,22 +3908,27 @@ var FLOW_TOOLS = [
     description: "List saved flow names under .iris/flows (a fresh agent learns the demonstrated journeys without a browser).",
     inputSchema: {},
     outputSchema: {
-      flows: z6.array(z6.object({ name: z6.string(), path: z6.string(), createdAt: z6.number().optional() }))
+      flows: z7.array(z7.object({ name: z7.string(), path: z7.string(), createdAt: z7.number().optional() }))
     },
-    handler: (deps) => deps.flows.list().then((flows) => ({ flows }))
+    // Return {name, path} objects to MATCH the declared outputSchema. Returning bare name strings
+    // (the prior bug) made schema-validating MCP clients reject the result ("expected object,
+    // received string") — caught driving the live demo.
+    handler: (deps) => deps.flows.list().then((names) => ({
+      flows: names.map((name) => ({ name, path: flowPath(deps.irisRoot, name) }))
+    }))
   },
   {
     name: IrisTool.FLOW_LOAD,
     description: "Read + validate a saved flow by flowName from .iris/flows/<flowName>.json. Returns the FlowFile (version, flowName, createdAt, anchored steps) or a structured { error, code }.",
     inputSchema: {
-      flowName: z6.string().describe("Flow file name (without .json extension) from iris_flow_list.")
+      flowName: z7.string().describe("Flow file name (without .json extension) from iris_flow_list.")
     },
     outputSchema: {
-      flowName: z6.string(),
-      steps: z6.array(z6.unknown()),
-      createdAt: z6.number().optional()
+      flowName: z7.string(),
+      steps: z7.array(z7.unknown()),
+      createdAt: z7.number().optional()
     },
-    handler: (deps, args) => deps.flows.load(asString4(args["flowName"]) ?? "").then((res) => {
+    handler: (deps, args) => deps.flows.load(asString(args["flowName"]) ?? "").then((res) => {
       if (!res.ok)
         return { error: flowErrorMessage(res.code), code: res.code };
       const { name, ...rest } = res.value;
@@ -3178,20 +3937,21 @@ var FLOW_TOOLS = [
   },
   {
     name: IrisTool.FLOW_REPLAY,
-    description: `Replay a git-checked flow from .iris/flows/<name>.json. RE-RESOLVES each step's semantic anchor (testid via iris_query; signal via predicate) against the LIVE DOM \u2014 never reuses a stale ref. On an anchor MISS returns legible DRIFT { step, anchor, drift:{ reasonKind, reason, nearest } } (the closest surviving testid) and stops \u2014 the "whose fault is it" contract. Returns { name, status: ok|drift|error, steps:[...] }; a missing/malformed file is status:error with a structured code (distinct from a contract-changed drift).`,
+    description: `Replay a git-checked flow from .iris/flows/<name>.json. RE-RESOLVES each step's semantic anchor (testid via iris_query; signal via predicate) against the LIVE DOM \u2014 never reuses a stale ref. On an anchor MISS returns legible DRIFT { step, anchor, drift:{ reasonKind, reason, nearest } } (the closest surviving testid) and stops \u2014 the "whose fault is it" contract. Returns { name, status: ok|drift|error, steps:[...] }; missing/malformed files and action failures are status:error with a structured code (distinct from contract-changed drift).`,
     inputSchema: {
-      flowName: z6.string().describe("Flow file name (without .json extension) from iris_flow_list."),
-      sessionId: z6.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
+      flowName: z7.string().describe("Flow file name (without .json extension) from iris_flow_list."),
+      confirmDangerous: z7.boolean().optional().describe("Set true to allow destructive controls during this replay only."),
+      sessionId: z7.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
     },
     outputSchema: {
-      status: z6.string().describe("ok | drift | error"),
-      steps: z6.array(z6.unknown()),
-      proposals: z6.array(z6.unknown()).optional(),
-      error: z6.object({ code: z6.string(), message: z6.string() }).optional()
+      status: z7.string().describe("ok | drift | error"),
+      steps: z7.array(z7.unknown()),
+      proposals: z7.array(z7.unknown()).optional(),
+      error: z7.object({ code: z7.string(), message: z7.string() }).optional()
     },
     handler: async (deps, args) => {
       const startedAt = deps.now();
-      const name = asString4(args["flowName"]) ?? "";
+      const name = asString(args["flowName"]) ?? "";
       const loaded = await deps.flows.load(name);
       if (!loaded.ok) {
         await recordReplayRun(deps, name, ReplayStatus.ERROR, 0, deps.now() - startedAt);
@@ -3202,12 +3962,35 @@ var FLOW_TOOLS = [
           error: { code: loaded.code, message: flowErrorMessage(loaded.code) }
         };
       }
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
-      const steps = await replayFlow(session, loaded.value, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS);
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
+      const replayFloor = session.elapsed();
+      const steps = await replayFlow(session, loaded.value, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, args["confirmDangerous"] === true);
+      const stepsClean = steps.length > 0 && steps.every((s) => s.ok && s.drift === void 0);
+      if (stepsClean && loaded.value.success !== void 0) {
+        const verdict = await assertSuccess(session, loaded.value.success, dynamicTestids(loaded.value), waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, replayFloor);
+        const row = {
+          step: steps.length,
+          tool: "success",
+          anchor: successLabel(loaded.value.success),
+          ok: verdict.pass,
+          ...verdict.pass ? {} : { error: verdict.failureReason ?? "flow.success not satisfied" }
+        };
+        steps.push(row);
+      }
       const driftSteps = steps.filter((s) => s.drift !== void 0).length;
       const allOk = steps.every((s) => s.ok);
-      const status = driftSteps > 0 ? ReplayStatus.DRIFT : allOk ? ReplayStatus.OK : ReplayStatus.DRIFT;
+      const status = driftSteps > 0 ? ReplayStatus.DRIFT : allOk ? ReplayStatus.OK : ReplayStatus.ERROR;
       await recordReplayRun(deps, name, status, driftSteps, deps.now() - startedAt);
+      const failed = steps.find((step) => !step.ok && step.drift === void 0);
+      if (failed !== void 0) {
+        const message = failed.error ?? "flow action failed";
+        return {
+          name,
+          status,
+          steps,
+          error: { code: ReplayStatus.ERROR, message }
+        };
+      }
       return { name, status, steps };
     }
   },
@@ -3215,20 +3998,20 @@ var FLOW_TOOLS = [
     name: IrisTool.FLOW_SAVE_RECORDED,
     description: "Persist the HUMAN-recorded flow from the live tab. The recorder toolbar compiles the human's real clicks/inputs into a semantically anchored FlowFile in-page and emits it; this tool reads the LATEST recorded-flow from the session and writes it to .iris/flows/<name>.json (no recompilation \u2014 the browser already resolved every anchor). Pass `name` to override the recorded name. Returns { name, stepCount, degraded, empty } or { error, code } (code flow_no_recorded when no recording is present).",
     inputSchema: {
-      flowName: z6.string().optional().describe("Override the flow name embedded in the recorded flow. Omit to use the recorder-assigned name."),
+      flowName: z7.string().optional().describe("Override the flow name embedded in the recorded flow. Omit to use the recorder-assigned name."),
       ...{
-        sessionId: z6.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
+        sessionId: z7.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
       }
     },
     outputSchema: {
-      flowName: z6.string().optional(),
-      stepCount: z6.number().optional(),
-      degraded: z6.number().optional(),
-      error: z6.string().optional(),
-      code: z6.string().optional()
+      flowName: z7.string().optional(),
+      stepCount: z7.number().optional(),
+      degraded: z7.number().optional(),
+      error: z7.string().optional(),
+      code: z7.string().optional()
     },
     handler: async (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
       const recorded = latestRecordedFlow(session.eventsSince(0));
       if (recorded === void 0) {
         return {
@@ -3236,7 +4019,7 @@ var FLOW_TOOLS = [
           code: RecordedSaveError.NO_RECORDED_FLOW
         };
       }
-      const override = asString4(args["flowName"]);
+      const override = asString(args["flowName"]);
       const flow = override !== void 0 ? { ...recorded.flow, name: override } : recorded.flow;
       const res = await deps.flows.saveFlow(flow);
       if (!res.ok)
@@ -3247,35 +4030,38 @@ var FLOW_TOOLS = [
   },
   {
     name: IrisTool.FLOW_HEAL,
-    description: "Self-healing replay. Re-runs iris_flow_replay; on testid DRIFT computes confidence-scored nearest-match rebind PROPOSALS. With apply:false (default) returns the proposed diff WITHOUT writing. With apply:true, writes the confident rebind(s) back into .iris/flows/<name>.json and returns what changed \u2014 never silently. A drift with no proposal above the confidence floor is status:unhealable (file untouched). Returns { name, status: healed|drift|unhealable|nothing_to_heal|error, applied, proposals[], changed[], message }.",
+    description: "Self-healing replay. Re-runs iris_flow_replay; on testid DRIFT computes confidence-scored nearest-match rebind PROPOSALS. With apply:false (default) returns the proposed diff WITHOUT writing. With apply:true, writes the confident rebind(s) back into .iris/flows/<name>.json and returns what changed \u2014 never silently. Before writing, apply re-replays the healed flow and re-asserts its success consequence: if the rebound locator resolves but the consequence no longer fires, the write is REFUSED (status:consequence_broken) \u2014 it heals the locator, never the intent. A drift with no proposal above the confidence floor is status:unhealable (file untouched). Returns { name, status: healed|drift|unhealable|consequence_broken|nothing_to_heal|error, applied, proposals[], changed[], message }.",
     inputSchema: {
-      flowName: z6.string().describe("Flow file name to heal (from iris_flow_list)."),
-      apply: z6.boolean().optional(),
-      sessionId: z6.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
+      flowName: z7.string().describe("Flow file name to heal (from iris_flow_list)."),
+      apply: z7.boolean().optional(),
+      confirmDangerous: z7.boolean().optional().describe("Set true to allow destructive controls during this heal replay only."),
+      sessionId: z7.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
     },
     outputSchema: {
-      flowName: z6.string(),
-      status: z6.string(),
-      applied: z6.boolean(),
-      proposals: z6.array(z6.unknown()),
-      changed: z6.array(z6.unknown()),
-      message: z6.string(),
-      error: z6.object({ code: z6.string(), message: z6.string() }).optional()
+      flowName: z7.string(),
+      status: z7.string(),
+      applied: z7.boolean(),
+      proposals: z7.array(z7.unknown()),
+      changed: z7.array(z7.unknown()),
+      message: z7.string(),
+      error: z7.object({ code: z7.string(), message: z7.string() }).optional()
     },
     handler: (deps, args) => healFlow(deps, args).then(({ name, ...rest }) => ({ flowName: name, ...rest }))
   }
 ];
 var HEAL_MESSAGES = {
   NOTHING: "nothing to heal \u2014 every anchor resolved on replay",
-  HEALED: "rewrote drifted testid anchors to their nearest surviving match",
+  HEALED: "rewrote drifted testid anchors to their nearest surviving match and re-verified the flow's success consequence still fires",
   DRIFT_DRY: "confident rebind(s) proposed \u2014 re-run with apply:true to write them to disk",
-  UNHEALABLE: `drift found, but no nearest match cleared the confidence floor (HEAL_CONFIDENCE_MIN=${HEAL_CONFIDENCE_MIN}); file left untouched \u2014 add a data-testid or fix the flow by hand`
+  UNHEALABLE: `drift found, but no nearest match cleared the confidence floor (HEAL_CONFIDENCE_MIN=${HEAL_CONFIDENCE_MIN}); file left untouched \u2014 add a data-testid or fix the flow by hand`,
+  HEALED_UNVERIFIED: "rewrote drifted testid anchors \u2014 but this flow declares no success consequence, so the rebind resolves a locator without proving the intent still holds. Add a success-state assertion (iris_annotate) so future heals can be verified.",
+  CONSEQUENCE_BROKEN: "rebind resolves the drifted locator to a surviving element, but the healed flow no longer satisfies its success consequence \u2014 refusing to write (a heal that loses the intent would ship a green-but-dead test). Fix by hand and verify"
 };
 function toChange(proposal) {
   return { step: proposal.step, from: proposal.from, to: proposal.to };
 }
 async function healFlow(deps, args) {
-  const name = asString4(args["flowName"]) ?? "";
+  const name = asString(args["flowName"]) ?? "";
   const apply = args["apply"] === true;
   const loaded = await deps.flows.load(name);
   if (!loaded.ok) {
@@ -3289,9 +4075,22 @@ async function healFlow(deps, args) {
       error: { code: loaded.code, message: flowErrorMessage(loaded.code) }
     };
   }
-  const session = deps.sessions.resolve(asString4(args["sessionId"]));
-  const steps = await replayFlow(session, loaded.value, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS);
+  const session = deps.sessions.resolve(asString(args["sessionId"]));
+  const steps = await replayFlow(session, loaded.value, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, args["confirmDangerous"] === true);
   const drifted = steps.some((s) => s.drift !== void 0);
+  const failed = steps.find((s) => !s.ok && s.drift === void 0);
+  if (failed !== void 0) {
+    const message = failed.error ?? "flow replay failed before an anchor could be healed";
+    return {
+      name,
+      status: HealStatus.ERROR,
+      applied: false,
+      proposals: [],
+      changed: [],
+      message,
+      error: { code: ReplayStatus.ERROR, message }
+    };
+  }
   if (!drifted) {
     return {
       name,
@@ -3323,6 +4122,23 @@ async function healFlow(deps, args) {
       message: HEAL_MESSAGES.DRIFT_DRY
     };
   }
+  const { flow: healed } = applyHealChanges(loaded.value, proposals.map(toChange));
+  if (healed.success !== void 0) {
+    const verifyFloor = session.elapsed();
+    const verifySteps = await replayFlow(session, healed, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, args["confirmDangerous"] === true);
+    const verifyClean = verifySteps.length > 0 && verifySteps.every((s) => s.ok && s.drift === void 0);
+    const verdict = verifyClean ? await assertSuccess(session, healed.success, dynamicTestids(healed), waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, verifyFloor) : { pass: false, failureReason: "healed flow did not replay cleanly" };
+    if (!verdict.pass) {
+      return {
+        name,
+        status: HealStatus.CONSEQUENCE_BROKEN,
+        applied: false,
+        proposals,
+        changed: [],
+        message: `${HEAL_MESSAGES.CONSEQUENCE_BROKEN} (${successLabel(healed.success)}: ${verdict.failureReason ?? "not satisfied"})`
+      };
+    }
+  }
   const written = await deps.flows.heal(name, proposals.map(toChange));
   if (!written.ok) {
     return {
@@ -3341,14 +4157,14 @@ async function healFlow(deps, args) {
     applied: written.value.changed.length > 0,
     proposals,
     changed: written.value.changed,
-    message: HEAL_MESSAGES.HEALED
+    message: loaded.value.success !== void 0 ? HEAL_MESSAGES.HEALED : HEAL_MESSAGES.HEALED_UNVERIFIED
   };
 }
 
 // ../server/dist/project/project-tools.js
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 var sessionIdShape3 = {
-  sessionId: z7.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
+  sessionId: z8.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
 };
 var REGRESSION_STATUSES = /* @__PURE__ */ new Set([
   RunStatus.FAIL,
@@ -3389,12 +4205,12 @@ var PROJECT_TOOLS = [
     name: IrisTool.PROJECT,
     description: 'Read cross-run history from .iris/project.json \u2014 the memory of how past runs behaved. With { name } it also returns the last run for that flow plus a diff-vs-last summary (status change, regressed flag, consoleErrors/driftSteps deltas) so you can answer "did it behave like last time?". Returns { runs, learned?, lastRun?, diff? } or { error, reason } when no/invalid history exists.',
     inputSchema: {
-      name: z7.string().optional().describe("Filter runs by this name. Omit to return all runs."),
+      name: z8.string().optional().describe("Filter runs by this name. Omit to return all runs."),
       ...sessionIdShape3
     },
     outputSchema: {
-      runs: z7.array(z7.unknown()),
-      diff: z7.unknown().optional()
+      runs: z8.array(z8.unknown()),
+      diff: z8.unknown().optional()
     },
     handler: async (deps, args) => {
       const read = await deps.project.read();
@@ -3404,7 +4220,7 @@ var PROJECT_TOOLS = [
           reason: read.reason
         };
       }
-      const name = asString4(args["name"]);
+      const name = asString(args["name"]);
       if (name === void 0) {
         return { runs: read.file.runs, learned: read.file.learned };
       }
@@ -3422,22 +4238,22 @@ var PROJECT_TOOLS = [
     name: IrisTool.RUN_RECORD,
     description: "Explicitly record a run outcome into .iris/project.json (the manual companion to the auto-record on iris_flow_replay). Use it to log the result of an assertion sequence or a manual journey so future runs can diff against it. Returns { recorded:true, name, status }.",
     inputSchema: {
-      name: z7.string().describe("Run name for grouping in iris_project history."),
-      status: z7.nativeEnum(RunStatus).describe("Outcome: pass | fail | drift | error"),
-      kind: z7.nativeEnum(RunKind).optional(),
-      summary: z7.string().optional().describe("One-line human summary of what this run covered."),
+      name: z8.string().describe("Run name for grouping in iris_project history."),
+      status: z8.nativeEnum(RunStatus).describe("Outcome: pass | fail | drift | error"),
+      kind: z8.nativeEnum(RunKind).optional(),
+      summary: z8.string().optional().describe("One-line human summary of what this run covered."),
       ...sessionIdShape3
     },
     outputSchema: {
-      recorded: z7.boolean(),
-      runName: z7.string(),
-      status: z7.string()
+      recorded: z8.boolean(),
+      runName: z8.string(),
+      status: z8.string()
     },
     handler: async (deps, args) => {
-      const name = asString4(args["name"]) ?? "";
+      const name = asString(args["name"]) ?? "";
       const status = args["status"];
       const kindArg = args["kind"];
-      const summary = asString4(args["summary"]);
+      const summary = asString(args["summary"]);
       await deps.project.recordRun({
         kind: typeof kindArg === "string" ? kindArg : RunKind.MANUAL,
         name,
@@ -3450,7 +4266,7 @@ var PROJECT_TOOLS = [
 ];
 
 // ../server/dist/visual/visual-tools.js
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 
 // ../server/dist/visual/visual-diff.js
 async function loadDeps() {
@@ -3601,13 +4417,13 @@ var VisualStore = class {
 
 // ../server/dist/visual/visual-tools.js
 var sessionIdShape4 = {
-  sessionId: z8.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
+  sessionId: z9.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
 };
-var rectShape = z8.object({
-  x: z8.number(),
-  y: z8.number(),
-  width: z8.number(),
-  height: z8.number()
+var rectShape = z9.object({
+  x: z9.number(),
+  y: z9.number(),
+  width: z9.number(),
+  height: z9.number()
 });
 function screenshotProvider(deps) {
   const p = deps.realInput;
@@ -3619,11 +4435,11 @@ var noProvider = {
   recommendation: VISUAL_NO_PROVIDER_RECOMMENDATION
 };
 function asBox(value) {
-  const b = asRecord3(asRecord3(value)["box"]);
-  const x = asNumber2(b["x"]);
-  const y = asNumber2(b["y"]);
-  const w = asNumber2(b["width"]);
-  const h = asNumber2(b["height"]);
+  const b = asRecord(asRecord(value)["box"]);
+  const x = asNumber(b["x"]);
+  const y = asNumber(b["y"]);
+  const w = asNumber(b["width"]);
+  const h = asNumber(b["height"]);
   if (x === void 0 || y === void 0 || w === void 0 || h === void 0)
     return void 0;
   if (w <= 0 || h <= 0)
@@ -3633,12 +4449,12 @@ function asBox(value) {
 async function buildOpts(deps, sessionId, args) {
   const clipArg = args["clip"];
   if (clipArg !== void 0) {
-    const c = asRecord3(clipArg);
+    const c = asRecord(clipArg);
     const box = asBox({ box: c });
     if (box !== void 0)
       return { clip: box };
   }
-  const ref = asString4(args["ref"]);
+  const ref = asString(args["ref"]);
   if (ref !== void 0) {
     const session = deps.sessions.resolve(sessionId);
     const res = await session.command(IrisCommand.INSPECT, { ref });
@@ -3664,31 +4480,31 @@ var VISUAL_TOOLS = [
     name: IrisTool.SCREENSHOT,
     description: "Capture a pixel screenshot of the DRIVEN page (needs `iris drive`/IRIS_CDP_URL \u2014 the SDK has no screenshotter) and save it as a visual baseline at .iris/visual/<name>.png. { fullPage } for the whole scroll height, { ref } or { clip:{x,y,width,height} } for one element/region. Returns { saved:true, name, path, bytes } or { ok:false, reason } when no driven browser is attached.",
     inputSchema: {
-      name: z8.string().describe("Baseline name \u2014 saved as .iris/visual/<name>.png. Use the same name in iris_visual_diff to compare."),
-      fullPage: z8.boolean().optional().describe("Capture the full scroll height. Default: viewport only."),
-      ref: z8.string().optional().describe("Element ref to screenshot (scopes to element bounding box). Omit for full page."),
+      name: z9.string().describe("Baseline name \u2014 saved as .iris/visual/<name>.png. Use the same name in iris_visual_diff to compare."),
+      fullPage: z9.boolean().optional().describe("Capture the full scroll height. Default: viewport only."),
+      ref: z9.string().optional().describe("Element ref to screenshot (scopes to element bounding box). Omit for full page."),
       clip: rectShape.optional().describe("Explicit { x, y, width, height } clip rectangle in page coordinates."),
       ...sessionIdShape4
     },
     outputSchema: {
-      ok: z8.boolean(),
-      saved: z8.boolean().optional(),
-      name: z8.string().optional(),
-      path: z8.string().optional(),
-      bytes: z8.number().optional(),
-      reason: z8.string().optional(),
-      recommendation: z8.string().optional()
+      ok: z9.boolean(),
+      saved: z9.boolean().optional(),
+      name: z9.string().optional(),
+      path: z9.string().optional(),
+      bytes: z9.number().optional(),
+      reason: z9.string().optional(),
+      recommendation: z9.string().optional()
     },
     handler: async (deps, args) => {
       const provider = screenshotProvider(deps);
       if (provider === void 0)
         return noProvider;
-      const sessionId = asString4(args["sessionId"]);
+      const sessionId = asString(args["sessionId"]);
       const session = deps.sessions.resolve(sessionId);
       const png = await provider.screenshot(session.url, await buildOpts(deps, sessionId, args));
       if (png === void 0)
         return { ok: false, reason: VisualReason.CAPTURE_FAILED };
-      const name = asString4(args["name"]) ?? "default";
+      const name = asString(args["name"]) ?? "default";
       const store = new VisualStore(deps.fs, deps.irisRoot);
       const path = await store.saveBaseline(name, png);
       return { ok: true, saved: true, name, path, bytes: png.length };
@@ -3698,39 +4514,39 @@ var VISUAL_TOOLS = [
     name: IrisTool.VISUAL_DIFF,
     description: "Perceptually diff the DRIVEN page against a saved visual baseline (see iris_screenshot). { masks:[{x,y,width,height}] } neutralizes volatile regions; { maxRatio } sets the pass tolerance (default 0). Returns { matched, changedPixels, totalPixels, ratio, region?, diffPath, dimensionMismatch } \u2014 the overlay diff is written to .iris/visual/<baseline>.diff.png \u2014 or { ok:false, reason } (no-provider / baseline-missing).",
     inputSchema: {
-      baseline: z8.string().describe("Baseline screenshot name (from iris_screenshot). Used to compare with the current screenshot."),
-      fullPage: z8.boolean().optional(),
-      ref: z8.string().optional(),
+      baseline: z9.string().describe("Baseline screenshot name (from iris_screenshot). Used to compare with the current screenshot."),
+      fullPage: z9.boolean().optional(),
+      ref: z9.string().optional(),
       clip: rectShape.optional(),
-      masks: z8.array(rectShape).optional(),
-      maxRatio: z8.number().optional(),
-      threshold: z8.number().optional().describe("Pixel difference threshold (0\u20131). Default: 0.01."),
+      masks: z9.array(rectShape).optional(),
+      maxRatio: z9.number().optional(),
+      threshold: z9.number().optional().describe("Pixel difference threshold (0\u20131). Default: 0.01."),
       ...sessionIdShape4
     },
     outputSchema: {
-      ok: z8.boolean(),
-      match: z8.boolean().optional(),
-      diffPct: z8.number().optional(),
-      diffPath: z8.string().optional(),
-      reason: z8.string().optional()
+      ok: z9.boolean(),
+      match: z9.boolean().optional(),
+      diffPct: z9.number().optional(),
+      diffPath: z9.string().optional(),
+      reason: z9.string().optional()
     },
     handler: async (deps, args) => {
       const provider = screenshotProvider(deps);
       if (provider === void 0)
         return noProvider;
-      const baseline = asString4(args["baseline"]) ?? "";
+      const baseline = asString(args["baseline"]) ?? "";
       const store = new VisualStore(deps.fs, deps.irisRoot);
       const baselineBytes = await store.readBaseline(baseline);
       if (baselineBytes === void 0)
         return { ok: false, reason: VisualReason.BASELINE_MISSING };
-      const sessionId = asString4(args["sessionId"]);
+      const sessionId = asString(args["sessionId"]);
       const session = deps.sessions.resolve(sessionId);
       const current = await provider.screenshot(session.url, await buildOpts(deps, sessionId, args));
       if (current === void 0)
         return { ok: false, reason: VisualReason.CAPTURE_FAILED };
       const masks = rectsFrom(args["masks"]);
-      const threshold = asNumber2(args["threshold"]);
-      const maxRatio = asNumber2(args["maxRatio"]);
+      const threshold = asNumber(args["threshold"]);
+      const maxRatio = asNumber(args["maxRatio"]);
       const result = await diffPng(baselineBytes, current, {
         ...threshold !== void 0 ? { threshold } : {},
         ...maxRatio !== void 0 ? { maxRatio } : {},
@@ -3747,7 +4563,7 @@ var VISUAL_TOOLS = [
 ];
 
 // ../server/dist/crawl/crawl-tools.js
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 
 // ../server/dist/crawl/crawl.js
 function isActivity(e) {
@@ -3760,7 +4576,7 @@ function failedRequests(events, floor) {
   return events.filter((e) => {
     if (e.type !== EventType.NET_REQUEST)
       return false;
-    const status = asNumber2(e.data["status"]);
+    const status = asNumber(e.data["status"]);
     return status !== void 0 && status >= floor;
   });
 }
@@ -3790,7 +4606,7 @@ async function crawl(session, opts, sleep) {
     const act = await session.command(IrisCommand.ACT, {
       ref: item.ref,
       action: ActionType.CLICK,
-      args: {}
+      args: opts.confirmDangerous === true ? { [DANGEROUS_ACTION_CONFIRM_ARG]: true } : {}
     });
     await sleep(settleMs);
     const events = session.eventsSince(since);
@@ -3801,14 +4617,14 @@ async function crawl(session, opts, sleep) {
         kind: CrawlAnomalyKind.CONSOLE_ERROR,
         ref: item.ref,
         desc: item.desc,
-        detail: asString4(e.data["message"]) ?? e.type
+        detail: asString(e.data["message"]) ?? e.type
       });
     }
     for (const e of failedRequests(events, CRAWL_DEFAULTS.FAILED_STATUS)) {
       counts.failedRequests += 1;
-      const method = asString4(e.data["method"]) ?? "";
-      const url = asString4(e.data["url"]) ?? "";
-      const status = asNumber2(e.data["status"]);
+      const method = asString(e.data["method"]) ?? "";
+      const url = asString(e.data["url"]) ?? "";
+      const status = asNumber(e.data["status"]);
       anomalies.push({
         kind: CrawlAnomalyKind.FAILED_REQUEST,
         ref: item.ref,
@@ -3816,7 +4632,7 @@ async function crawl(session, opts, sleep) {
         detail: `${method} ${url} \u2192 ${status ?? ""}`.trim()
       });
     }
-    const dispatched = asRecord3(act.result)["dispatched"] !== false && act.ok;
+    const dispatched = asRecord(act.result)["dispatched"] !== false && act.ok;
     if (dispatched && errs.length === 0 && !events.some(isActivity)) {
       counts.deadControls += 1;
       anomalies.push({
@@ -3844,32 +4660,34 @@ var CRAWL_TOOLS = [
     name: IrisTool.CRAWL,
     description: "Autonomously click every reachable interactive control (bounded by maxSteps, default 25) and report anomalies WITHOUT a script: console errors, failed requests (status \u2265 400), and DEAD controls (dispatched but the app did nothing). DESTRUCTIVE \u2014 it really clicks (may navigate/mutate state); use iris_explore first for a non-destructive list. Returns { interactiveFound, stepsRun, anomalies[{kind,ref,desc,detail}], counts, visited, truncated }.",
     inputSchema: {
-      maxSteps: z9.number().optional().describe("Maximum number of controls to click. Default: 25."),
-      settleMs: z9.number().optional().describe("Milliseconds to wait after each click for the app to react. Default: 500."),
-      scope: z9.string().optional().describe("CSS selector or element ref to restrict crawling to a subtree."),
-      sessionId: z9.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
+      maxSteps: z10.number().optional().describe("Maximum number of controls to click. Default: 25."),
+      settleMs: z10.number().optional().describe("Milliseconds to wait after each click for the app to react. Default: 500."),
+      scope: z10.string().optional().describe("CSS selector or element ref to restrict crawling to a subtree."),
+      confirmDangerous: z10.boolean().optional().describe("Set true to allow controls classified as destructive. Default false; those controls are blocked by the browser."),
+      sessionId: z10.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
     },
     outputSchema: {
-      interactiveFound: z9.number(),
-      stepsRun: z9.number(),
-      anomalies: z9.array(z9.object({
-        kind: z9.string(),
-        ref: z9.string(),
-        desc: z9.string(),
-        detail: z9.string().optional()
+      interactiveFound: z10.number(),
+      stepsRun: z10.number(),
+      anomalies: z10.array(z10.object({
+        kind: z10.string(),
+        ref: z10.string(),
+        desc: z10.string(),
+        detail: z10.string().optional()
       })),
-      counts: z9.record(z9.number()),
-      truncated: z9.boolean()
+      counts: z10.record(z10.number()),
+      truncated: z10.boolean()
     },
     handler: (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
-      const maxSteps = asNumber2(args["maxSteps"]);
-      const settleMs = asNumber2(args["settleMs"]);
-      const scope = asString4(args["scope"]);
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
+      const maxSteps = asNumber(args["maxSteps"]);
+      const settleMs = asNumber(args["settleMs"]);
+      const scope = asString(args["scope"]);
       const opts = {
         ...maxSteps !== void 0 ? { maxSteps } : {},
         ...settleMs !== void 0 ? { settleMs } : {},
-        ...scope !== void 0 ? { scope } : {}
+        ...scope !== void 0 ? { scope } : {},
+        ...args["confirmDangerous"] === true ? { confirmDangerous: true } : {}
       };
       return crawl(session, opts, nodeSleep2);
     }
@@ -3877,7 +4695,7 @@ var CRAWL_TOOLS = [
 ];
 
 // ../server/dist/input/scroll-tools.js
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 
 // ../server/dist/input/scroll-find.js
 async function queryFirst(session, q) {
@@ -3886,9 +4704,9 @@ async function queryFirst(session, q) {
     value: q.value,
     ...q.name !== void 0 ? { name: q.name } : {}
   });
-  const elements = asRecord3(res.result)["elements"];
+  const elements = asRecord(res.result)["elements"];
   if (Array.isArray(elements) && elements.length > 0)
-    return asRecord3(elements[0]);
+    return asRecord(elements[0]);
   return void 0;
 }
 async function scrollToFind(session, q, opts = {}) {
@@ -3907,7 +4725,7 @@ async function scrollToFind(session, q, opts = {}) {
     const hit = await queryFirst(session, q);
     if (hit !== void 0)
       return { found: true, element: hit, scrolls, exhausted: false };
-    const data = asRecord3(sr.result);
+    const data = asRecord(sr.result);
     if (data["atEnd"] === true || data["scrolled"] === false) {
       return { found: false, scrolls, exhausted: true };
     }
@@ -3915,7 +4733,7 @@ async function scrollToFind(session, q, opts = {}) {
   for (let i = 0; i < max; i += 1) {
     const sr = await session.command(IrisCommand.SCROLL, q.container !== void 0 ? { ref: q.container } : {});
     scrolls += 1;
-    const data = asRecord3(sr.result);
+    const data = asRecord(sr.result);
     const hit = await queryFirst(session, q);
     if (hit !== void 0)
       return { found: true, element: hit, scrolls, exhausted: false };
@@ -3932,58 +4750,58 @@ var SCROLL_TOOLS = [
     name: IrisTool.SCROLL_TO,
     description: "Find an element in a VIRTUALIZED list that has not rendered yet. Pass `by` (role|text|testid|label|placeholder|alt) and `value` (query string) to identify the target row. Scrolls the container until the row mounts, the list ends, or maxScrolls (default 20) is spent. Pass targetIndex + totalCount for bisection \u2014 jumps directly to the estimated offset in one scroll (e.g. targetIndex:800 totalCount:1000 jumps to 80% of scrollHeight). Returns { found, element?, scrolls, exhausted }.",
     inputSchema: {
-      by: z10.string().describe("Query strategy for finding the target: role | text | testid | label | placeholder | alt"),
-      value: z10.string().describe("Query value for the selected strategy (the element to scroll into view)."),
-      name: z10.string().optional().describe("Optional accessible name filter when using by=role."),
-      container: z10.string().optional().describe("Element ref for the scrollable container. Omit to scroll the document."),
-      maxScrolls: z10.number().optional().describe("Maximum number of scroll steps before giving up. Default: 20."),
-      targetIndex: z10.number().optional().describe("Known row index of the target in the list. Combine with totalCount for bisection \u2014 jumps directly to the estimated offset."),
-      totalCount: z10.number().optional().describe("Total item count in the virtualized list. Required for bisection with targetIndex."),
-      sessionId: z10.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
+      by: z11.string().describe("Query strategy for finding the target: role | text | testid | label | placeholder | alt"),
+      value: z11.string().describe("Query value for the selected strategy (the element to scroll into view)."),
+      name: z11.string().optional().describe("Optional accessible name filter when using by=role."),
+      container: z11.string().optional().describe("Element ref for the scrollable container. Omit to scroll the document."),
+      maxScrolls: z11.number().optional().describe("Maximum number of scroll steps before giving up. Default: 20."),
+      targetIndex: z11.number().optional().describe("Known row index of the target in the list. Combine with totalCount for bisection \u2014 jumps directly to the estimated offset."),
+      totalCount: z11.number().optional().describe("Total item count in the virtualized list. Required for bisection with targetIndex."),
+      sessionId: z11.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
     },
     outputSchema: {
-      found: z10.boolean(),
-      element: z10.object({ ref: z10.string(), role: z10.string(), name: z10.string() }).optional(),
-      scrolls: z10.number(),
-      exhausted: z10.boolean()
+      found: z11.boolean(),
+      element: z11.object({ ref: z11.string(), role: z11.string(), name: z11.string() }).optional(),
+      scrolls: z11.number(),
+      exhausted: z11.boolean()
     },
     handler: (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
-      const name = asString4(args["name"]);
-      const container = asString4(args["container"]);
-      const targetIndex = asNumber2(args["targetIndex"]);
-      const totalCount = asNumber2(args["totalCount"]);
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
+      const name = asString(args["name"]);
+      const container = asString(args["container"]);
+      const targetIndex = asNumber(args["targetIndex"]);
+      const totalCount = asNumber(args["totalCount"]);
       const q = {
-        by: asString4(args["by"]) ?? "",
-        value: asString4(args["value"]) ?? "",
+        by: asString(args["by"]) ?? "",
+        value: asString(args["value"]) ?? "",
         ...name !== void 0 ? { name } : {},
         ...container !== void 0 ? { container } : {},
         ...targetIndex !== void 0 ? { targetIndex } : {},
         ...totalCount !== void 0 ? { totalCount } : {}
       };
-      const maxScrolls = asNumber2(args["maxScrolls"]);
+      const maxScrolls = asNumber(args["maxScrolls"]);
       return scrollToFind(session, q, maxScrolls !== void 0 ? { maxScrolls } : {});
     }
   }
 ];
 
 // ../server/dist/session/session-tools.js
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 var SESSION_TOOLS = [
   {
     name: IrisTool.SESSION,
     description: "Tune the presenter session for this app. { idleEndMs } sets how long the session stays open after you go quiet before it AUTO-ENDS (page glow off, the floating panel is kept so the human can read + Copy/Export the run). Default 5min. Raise it for slow apps, lower it for quick checks. The auto-end is enforced SERVER-SIDE (immune to background-tab throttling) and also fires if you (the MCP client) disconnect \u2014 so a forgotten or crashed session never leaves the HUD running forever. If you go quiet and then act again, the session revives automatically. Returns { applied, idleEndMs }.",
     inputSchema: {
-      idleEndMs: z11.number().optional().describe("Idle window in milliseconds after which the presenter session auto-ends. Default: 300000 (5 min). Raise for slow apps."),
-      sessionId: z11.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
+      idleEndMs: z12.number().optional().describe("Idle window in milliseconds after which the presenter session auto-ends. Default: 300000 (5 min). Raise for slow apps."),
+      sessionId: z12.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
     },
     outputSchema: {
-      applied: z11.boolean(),
-      idleEndMs: z11.number().optional()
+      applied: z12.boolean(),
+      idleEndMs: z12.number().optional()
     },
     handler: async (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
-      const idleEndMs = asNumber2(args["idleEndMs"]);
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
+      const idleEndMs = asNumber(args["idleEndMs"]);
       if (idleEndMs !== void 0)
         session.setIdleEndMs(idleEndMs);
       const res = await session.command(IrisCommand.SESSION_CONFIG, idleEndMs !== void 0 ? { idleEndMs } : {});
@@ -3995,7 +4813,7 @@ var SESSION_TOOLS = [
 ];
 
 // ../server/dist/flows/annotate-tools.js
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 
 // ../server/dist/flows/annotate.js
 function compileAnnotation(a, stepCount) {
@@ -4072,23 +4890,23 @@ var ANNOTATE_TOOLS = [
     description: "Attach a STRUCTURED annotation to the active recording, compiling it into the flow. kind: assert-signal { name, dataMatches? } \u2192 the last step asserts that signal; assert-visible { testid } \u2192 the last step asserts that element is present; mark-dynamic { testid } \u2192 the flow records that region as LLM-dynamic (replay won't assert its content); success-state { signal | testid } \u2192 the flow golden end-condition. Folded onto disk by iris_flow_save. Returns { ok:true, target:step|flow, compiled } (e.g. \"will assert signal diff:shown\") or { ok:false, code } (annotate_no_recording | annotate_no_step | annotate_unknown_kind | annotate_missing_field). FIRST CUT: structured only \u2014 a free natural-language string is rejected (annotate_unknown_kind), never guessed into a predicate. Pass `flow` to target a named recording (defaults to 'default'); `name` is the assert-signal's SIGNAL name, not the recording.",
     inputSchema: {
       // `flow` selects the recording; `name`/`signal`/`testid`/`dataMatches` are the annotation fields.
-      flow: z12.string().optional().describe("Named recording to annotate. Defaults to 'default'."),
-      kind: z12.string().describe("Annotation kind: assert-signal | assert-visible | mark-dynamic | success-state."),
-      name: z12.string().optional().describe("Signal name for assert-signal annotations."),
-      testid: z12.string().optional().describe("data-testid value for assert-visible / mark-dynamic / success-state annotations."),
-      signal: z12.string().optional().describe("Signal name for success-state annotations."),
-      dataMatches: z12.record(z12.unknown()).optional().describe("Key/value pairs the signal payload must match (assert-signal only)."),
-      sessionId: z12.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open."),
-      annotation: z12.unknown().optional().describe("Structured annotation: { kind, name, dataMatches? } for assert-signal; { kind, testid } for assert-visible / mark-dynamic; { kind, signal?, testid? } for success-state.")
+      flow: z13.string().optional().describe("Named recording to annotate. Defaults to 'default'."),
+      kind: z13.string().describe("Annotation kind: assert-signal | assert-visible | mark-dynamic | success-state."),
+      name: z13.string().optional().describe("Signal name for assert-signal annotations."),
+      testid: z13.string().optional().describe("data-testid value for assert-visible / mark-dynamic / success-state annotations."),
+      signal: z13.string().optional().describe("Signal name for success-state annotations."),
+      dataMatches: z13.record(z13.unknown()).optional().describe("Key/value pairs the signal payload must match (assert-signal only)."),
+      sessionId: z13.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open."),
+      annotation: z13.unknown().optional().describe("Structured annotation: { kind, name, dataMatches? } for assert-signal; { kind, testid } for assert-visible / mark-dynamic; { kind, signal?, testid? } for success-state.")
     },
     outputSchema: {
-      ok: z12.boolean(),
-      target: z12.string().optional(),
-      compiled: z12.string().optional(),
-      code: z12.string().optional()
+      ok: z13.boolean(),
+      target: z13.string().optional(),
+      compiled: z13.string().optional(),
+      code: z13.string().optional()
     },
     handler: (deps, args) => {
-      const name = asString4(args["flow"]) ?? DEFAULT_RECORDING;
+      const name = asString(args["flow"]) ?? DEFAULT_RECORDING;
       const parsed = AnnotationSchema.safeParse(args);
       if (!parsed.success) {
         return Promise.resolve({ ok: false, code: AnnotationErrorCode.UNKNOWN_KIND });
@@ -4117,19 +4935,19 @@ var ANNOTATE_TOOLS = [
 ];
 
 // ../server/dist/session/live-control-tools.js
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 var sessionIdShape5 = {
-  sessionId: z13.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
+  sessionId: z14.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open.")
 };
 var LIVE_CONTROL_TOOLS = [
   {
     name: IrisTool.END_SESSION,
     description: 'End this live testing session. Sets the server state to "ended", tells the human panel (PRESENTER), and stops driving. Optional `summary` is shown in the panel. Idempotent.',
-    inputSchema: { summary: z13.string().optional(), ...sessionIdShape5 },
-    outputSchema: { ended: z13.boolean(), sessionId: z13.string() },
+    inputSchema: { summary: z14.string().optional(), ...sessionIdShape5 },
+    outputSchema: { ended: z14.boolean(), sessionId: z14.string() },
     handler: (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
-      session.setState(SessionState.ENDED, asString4(args["summary"]));
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
+      session.setState(SessionState.ENDED, asString(args["summary"]));
       return Promise.resolve({ ended: true, sessionId: session.id });
     }
   },
@@ -4137,9 +4955,9 @@ var LIVE_CONTROL_TOOLS = [
     name: IrisTool.RESUME,
     description: 'Clear a human pause and resume driving the page. Sets state "active" and syncs the panel (PRESENTER). Call after you have addressed the human guidance returned by a paused iris_act.',
     inputSchema: { ...sessionIdShape5 },
-    outputSchema: { ok: z13.boolean() },
+    outputSchema: { ok: z14.boolean() },
     handler: (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
       session.setState(SessionState.ACTIVE);
       return Promise.resolve({ ok: true });
     }
@@ -4148,9 +4966,9 @@ var LIVE_CONTROL_TOOLS = [
     name: IrisTool.MESSAGES,
     description: "Drain and return any messages the human queued from the panel since the last poll. Use to explicitly check for human guidance without acting.",
     inputSchema: { ...sessionIdShape5 },
-    outputSchema: { messages: z13.array(z13.unknown()) },
+    outputSchema: { messages: z14.array(z14.unknown()) },
     handler: (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
       return Promise.resolve({ messages: session.drainInbox() });
     }
   }
@@ -4176,7 +4994,7 @@ function withControl(session, result) {
 }
 
 // ../server/dist/update/update-tools.js
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 
 // ../server/dist/update/update-checker.js
 import * as fs from "fs";
@@ -4370,14 +5188,14 @@ var UPDATE_TOOLS = [
     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.")
+      currentVersion: z15.string().describe("The Iris server version currently running."),
+      latestVersion: z15.string().optional().describe("Latest published version on npm."),
+      updateAvailable: z15.boolean().describe("True when a newer version is available to install."),
+      executionKind: z15.string().describe('How iris was launched: "npx" (no install needed \u2014 restart applies update), "global" (npm install -g), or "local" (project node_modules).'),
+      changelog: z15.string().optional().describe("Release notes for the latest version."),
+      breakingChanges: z15.array(z15.string()).optional().describe("Breaking changes in the latest version that may affect your scripts."),
+      rollbackAvailable: z15.boolean().describe("True when a previous version is stored and can be restored."),
+      previousVersion: z15.string().optional().describe("The version that would be restored on rollback.")
     },
     handler: async (_deps) => {
       const manifest = await checkForUpdate(SERVER_VERSION);
@@ -4397,11 +5215,11 @@ var UPDATE_TOOLS = [
     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.")
+      confirm: z15.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()
+      ok: z15.boolean(),
+      message: z15.string().optional()
     },
     handler: async (_deps, args) => {
       if (args["confirm"] !== true) {
@@ -4419,11 +5237,11 @@ var UPDATE_TOOLS = [
     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.")
+      confirm: z15.boolean().describe("Set to true to confirm the rollback. Required to prevent accidental downgrades.")
     },
     outputSchema: {
-      ok: z14.boolean(),
-      message: z14.string().optional()
+      ok: z15.boolean(),
+      message: z15.string().optional()
     },
     handler: async (_deps, args) => {
       if (args["confirm"] !== true) {
@@ -4445,7 +5263,7 @@ async function snapshotTree(deps, sessionId) {
   return { lines: normalizeLines(snap.tree ?? ""), route: snap.status?.route ?? "" };
 }
 var sessionIdShape6 = {
-  sessionId: z15.string().optional().describe("Active session ID from iris_sessions. Omit when only one browser session is open \u2014 Iris resolves it automatically.")
+  sessionId: z16.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);
@@ -4455,11 +5273,11 @@ async function commandOrThrow3(deps, sessionId, name, args) {
   return result.result;
 }
 function asBox2(value) {
-  const b = asRecord3(asRecord3(value)["box"]);
-  const x = asNumber2(b["x"]);
-  const y = asNumber2(b["y"]);
-  const w = asNumber2(b["width"]);
-  const h = asNumber2(b["height"]);
+  const b = asRecord(asRecord(value)["box"]);
+  const x = asNumber(b["x"]);
+  const y = asNumber(b["y"]);
+  const w = asNumber(b["width"]);
+  const h = asNumber(b["height"]);
   if (x === void 0 || y === void 0 || w === void 0 || h === void 0)
     return void 0;
   if (w <= 0 || h <= 0)
@@ -4475,29 +5293,51 @@ async function tryRealInput(deps, session, ref, action, args) {
     return synthetic();
   if (!isPointerAction(action))
     return synthetic(InputModeReason.NOT_POINTER);
-  const inner = asRecord3(args["args"]);
+  const inner = asRecord(args["args"]);
   if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) && inner["native"] !== true) {
     return synthetic(InputModeReason.SYNTHETIC_CLICK_PREFERRED);
   }
   if (!await provider.isAvailableFor(session.url))
     return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
-  const box = asBox2(await commandOrThrow3(deps, session.id, IrisCommand.INSPECT, { ref }));
+  const inspected = await commandOrThrow3(deps, session.id, IrisCommand.INSPECT, { ref });
+  const confirmed = inner[DANGEROUS_ACTION_CONFIRM_ARG] === true;
+  const dangerousDescriptorText = (value2) => {
+    const descriptor = asRecord(value2);
+    return [
+      asString(descriptor["name"]) ?? "",
+      asString(descriptor["text"]) ?? "",
+      asString(descriptor["value"]) ?? "",
+      asString(descriptor["href"]) ?? "",
+      asString(descriptor["formAction"]) ?? "",
+      asString(descriptor["formText"]) ?? ""
+    ].join(" ");
+  };
+  if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) && !confirmed && isDangerousActionText(dangerousDescriptorText(inspected))) {
+    throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
+  }
+  const box = asBox2(inspected);
   if (box === void 0)
     return synthetic(InputModeReason.ELEMENT_NOT_LOCATABLE);
   let toBox;
   if (action === ActionType.DRAG) {
-    const toRef = asString4(inner["toRef"]);
+    const toRef = asString(inner["toRef"]);
     if (toRef === void 0)
       return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
-    toBox = asBox2(await commandOrThrow3(deps, session.id, IrisCommand.INSPECT, { ref: toRef }));
+    const targetInspected = await commandOrThrow3(deps, session.id, IrisCommand.INSPECT, {
+      ref: toRef
+    });
+    if (!confirmed && isDangerousActionText(`${dangerousDescriptorText(inspected)} ${dangerousDescriptorText(targetInspected)}`)) {
+      throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
+    }
+    toBox = asBox2(targetInspected);
     if (toBox === void 0)
       return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
   }
   const performArgs = {};
-  const value = asString4(inner["value"]);
+  const value = asString(inner["value"]);
   if (value !== void 0)
     performArgs.value = value;
-  const text = asString4(inner["text"]);
+  const text = asString(inner["text"]);
   if (text !== void 0)
     performArgs.text = text;
   if (toBox !== void 0)
@@ -4516,23 +5356,24 @@ async function tryRealInput(deps, session, ref, action, args) {
     };
   }
 }
+var SNAPSHOT_CACHE = new SnapshotCache();
 var TOOLS = [
   {
     name: IrisTool.SESSIONS,
     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: 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()
+      sessions: z16.array(z16.object({
+        sessionId: z16.string(),
+        url: z16.string(),
+        title: z16.string().optional(),
+        lastSeenMs: z16.number(),
+        throttled: z16.boolean(),
+        focused: z16.boolean(),
+        hidden: z16.boolean(),
+        realInputAvailable: z16.boolean().optional(),
+        stale: z16.boolean().optional(),
+        recommendation: z16.string().optional()
       })).describe("Connected browser sessions with health state.")
     },
     handler: async (deps) => {
@@ -4546,71 +5387,95 @@ 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.",
+    description: "Semantic accessibility snapshot of the page or a subtree. mode: full|interactive|status. Use to see what is on screen right now. The result carries cost:{ bytes, tokens } (estimated) \u2014 if it is large, re-scope (pass `scope`) or use mode:interactive/status instead of reading the whole tree. Pass diff:true after your first snapshot to get back ONLY what changed since your last look (mode:delta with added/removed, or mode:unchanged) \u2014 far fewer tokens and no stale tree to mis-read; a route change resets it to a full snapshot automatically.",
     inputSchema: {
-      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."),
+      scope: z16.string().optional().describe("CSS selector or element ref to restrict the snapshot to a subtree. Omit to snapshot the whole page."),
+      mode: z16.nativeEnum(SnapshotMode).optional().describe("full = all elements; interactive = only clickable/focusable elements; status = only route + title. Default: full."),
+      diff: z16.boolean().optional().describe("Return only what changed since your last snapshot of the same scope/mode (mode:delta|unchanged). First call (or after a route change) still returns the full tree."),
       ...sessionIdShape6
     },
     outputSchema: {
-      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()
+      tree: z16.string().optional().describe("Indented ARIA tree of every element on the page (or the scoped subtree)."),
+      status: z16.object({ route: z16.string(), title: z16.string().optional() }).optional(),
+      mode: z16.string().optional().describe("delta | unchanged when diff:true returned a change set."),
+      delta: z16.object({
+        added: z16.array(z16.string()),
+        removed: z16.array(z16.string()),
+        addedCount: z16.number(),
+        removedCount: z16.number()
+      }).optional().describe("Only present on a diff:true call that found changes."),
+      cost: z16.object({ bytes: z16.number(), tokens: z16.number() }).optional().describe("Estimated size of this result \u2014 re-scope if large.")
     },
-    handler: (deps, args) => commandOrThrow3(deps, asString4(args["sessionId"]), IrisCommand.SNAPSHOT, {
-      scope: args["scope"],
-      mode: args["mode"] ?? SnapshotMode.FULL
-    })
+    handler: (deps, args) => {
+      const sessionId = asString(args["sessionId"]);
+      const mode = asString(args["mode"]) ?? SnapshotMode.FULL;
+      return commandOrThrow3(deps, sessionId, IrisCommand.SNAPSHOT, {
+        scope: args["scope"],
+        mode
+      }).then((raw) => withSizeCost(applySnapshotDelta(raw, {
+        sessionId: sessionId ?? "default",
+        scope: asString(args["scope"]) ?? "",
+        mode,
+        diff: args["diff"] === true
+      }, SNAPSHOT_CACHE)));
+    }
   },
   {
     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.",
+    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. Pass `limit` to cap descriptors (broad role queries can be large) or `count_only:true` for just the match count \u2014 both cut tokens. 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: 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."),
+      by: z16.string().describe("Query strategy: role | text | label | placeholder | testid | alt"),
+      value: z16.string().describe("Query value for the selected strategy (e.g. by=role value=button, or by=testid value=submit-btn)."),
+      name: z16.string().optional().describe("Accessible name filter \u2014 narrows results when `by` is role and the page has many elements of that role."),
+      scope: z16.string().optional().describe("CSS selector or element ref to restrict the search to a subtree."),
+      limit: z16.number().optional().describe("Cap the returned descriptors to the first N (cuts tokens on broad queries). If more matched, the result carries total + truncated:true so the trim is never silent \u2014 narrow with name/scope."),
+      count_only: z16.boolean().optional().describe('Return just { count } (no element descriptors) \u2014 use when you only need "how many match?" and not their refs.'),
       ...sessionIdShape6
     },
     outputSchema: {
-      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: 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.")
+      elements: z16.array(z16.object({
+        ref: z16.string(),
+        role: z16.string(),
+        name: z16.string(),
+        value: z16.string().optional(),
+        states: z16.array(z16.string()),
+        visible: z16.boolean()
+      })).optional(),
+      count: z16.number().optional().describe("Match count \u2014 present when count_only is set."),
+      total: z16.number().optional().describe("Total matches before `limit` truncation \u2014 present only when truncated."),
+      truncated: z16.boolean().optional().describe("True when `limit` dropped some matches."),
+      hint: z16.object({
+        route: z16.string(),
+        presentTestids: z16.array(z16.string()),
+        knownEmptyState: z16.boolean()
+      }).optional().describe("Present only on zero matches \u2014 tells you what IS on the page so you can diagnose the miss."),
+      cost: z16.object({ bytes: z16.number(), tokens: z16.number() }).optional().describe("Estimated size of this result \u2014 narrow with `name`/`scope`/`limit` if large.")
     },
-    handler: (deps, args) => commandOrThrow3(deps, asString4(args["sessionId"]), IrisCommand.QUERY, {
+    handler: (deps, args) => commandOrThrow3(deps, asString(args["sessionId"]), IrisCommand.QUERY, {
       by: args["by"],
       value: args["value"],
       name: args["name"],
       scope: args["scope"]
-    })
+    }).then((result) => withSizeCost(paginateQueryResult(result, asNumber(args["limit"]), args["count_only"] === true)))
   },
   {
     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: z15.string().describe("Element ref from iris_snapshot or iris_query (e.g. 'e42')."),
+      ref: z16.string().describe("Element ref from iris_snapshot or iris_query (e.g. 'e42')."),
       ...sessionIdShape6
     },
     outputSchema: {
-      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()
+      ref: z16.string(),
+      role: z16.string(),
+      name: z16.string(),
+      value: z16.string().optional(),
+      states: z16.array(z16.string()),
+      visible: z16.boolean(),
+      box: z16.object({ x: z16.number(), y: z16.number(), width: z16.number(), height: z16.number() }).optional(),
+      component: z16.object({ name: z16.string().optional(), sourceFile: z16.string().optional() }).optional()
     },
-    handler: (deps, args) => commandOrThrow3(deps, asString4(args["sessionId"]), IrisCommand.INSPECT, {
+    handler: (deps, args) => commandOrThrow3(deps, asString(args["sessionId"]), IrisCommand.INSPECT, {
       ref: args["ref"]
     })
   },
@@ -4618,30 +5483,30 @@ 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: 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)."),
+      ref: z16.string().describe("Element ref from iris_snapshot or iris_query (e.g. 'e42')."),
+      action: z16.string().describe("Action to perform: click | dblclick | hover | focus | fill | type | clear | select | check | uncheck | submit | press | scrollIntoView"),
+      args: z16.record(z16.unknown()).optional().describe("Action-specific arguments: { value } for fill/select, { text } for type/press, { native: true } to force a trusted native click, { confirmDangerous: true } to allow a potentially destructive control."),
+      refuseWhenThrottled: z16.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: 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()
+      since: z16.number().describe("Cursor \u2014 pass to iris_observe/iris_wait_for/iris_assert to scope reaction queries to this act."),
+      dispatched: z16.boolean(),
+      settled: z16.boolean().nullable(),
+      inputMode: z16.string(),
+      result: z16.unknown().optional(),
+      session: z16.object({ lastSeenMs: z16.number(), throttled: z16.boolean(), focused: z16.boolean() }).optional()
     },
     handler: async (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
       const paused = pausedShortCircuit(session);
       if (paused !== void 0)
         return paused;
       refuseIfThrottled(session, args["refuseWhenThrottled"]);
       const since = session.elapsed();
       session.markActCursor(since);
-      const ref = asString4(args["ref"]) ?? "";
-      const action = asString4(args["action"]) ?? "";
+      const ref = asString(args["ref"]) ?? "";
+      const action = asString(args["action"]) ?? "";
       const real = await tryRealInput(deps, session, ref, action, args);
       if (real.result !== void 0) {
         if (deps.recordings.active().length > 0) {
@@ -4667,7 +5532,7 @@ var TOOLS = [
       if (deps.recordings.active().length > 0) {
         deps.recordings.capture(compileActStep(args, result.result));
       }
-      const r = asRecord3(result.result);
+      const r = asRecord(result.result);
       return withControl(session, {
         since,
         inputMode: InputMode.SYNTHETIC,
@@ -4686,17 +5551,17 @@ 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: z15.array(z15.record(z15.unknown())).describe("Ordered list of { ref, action, args? } objects. Each step is equivalent to one iris_act call."),
+      steps: z16.array(z16.record(z16.unknown())).describe("Ordered list of { ref, action, args? } objects. Each step is equivalent to one iris_act call; put confirmDangerous:true in a destructive step args object."),
       ...sessionIdShape6
     },
     outputSchema: {
-      since: z15.number(),
-      dispatched: z15.boolean(),
-      result: z15.unknown().optional(),
-      session: z15.object({ lastSeenMs: z15.number(), throttled: z15.boolean(), focused: z15.boolean() }).optional()
+      since: z16.number(),
+      dispatched: z16.boolean(),
+      result: z16.unknown().optional(),
+      session: z16.object({ lastSeenMs: z16.number(), throttled: z16.boolean(), focused: z16.boolean() }).optional()
     },
     handler: async (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
       const paused = pausedShortCircuit(session);
       if (paused !== void 0)
         return paused;
@@ -4708,7 +5573,7 @@ var TOOLS = [
       if (deps.recordings.active().length > 0) {
         deps.recordings.capture(compileSequenceStep(args, result.result));
       }
-      const r = asRecord3(result.result);
+      const r = asRecord(result.result);
       return withControl(session, {
         since,
         dispatched: r["count"] !== void 0,
@@ -4719,34 +5584,34 @@ 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.",
+    description: "Act on a ref, then wait for a predicate to hold \u2014 one hop for the act->observe->assert loop. Omit `until` to wait for the page to settle (network + DOM idle) \u2014 use this instead of a fixed sleep. 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: 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: 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."),
+      ref: z16.string().describe("Element ref from iris_snapshot or iris_query."),
+      action: z16.string().describe("Action to perform: click | dblclick | hover | focus | fill | type | clear | select | check | uncheck | submit | press | scrollIntoView"),
+      args: z16.record(z16.unknown()).optional().describe("Action-specific arguments: { value } for fill/select, { text } for type/press, { confirmDangerous: true } for a potentially destructive control."),
+      until: PredicateSchema.optional().describe('Predicate to wait for after the action completes (same shape as iris_assert). OMIT to wait for the page to SETTLE \u2014 network + DOM idle \u2014 the deterministic default instead of a sleep. To assert a consequence AND settle, allOf them: { kind: "allOf", predicates: [<your predicate>, { kind: "settled" }] }.'),
+      timeout_ms: z16.number().optional().describe("Maximum wait time in milliseconds. 0 = evaluate once without waiting. Default: 4000."),
+      refuseWhenThrottled: z16.boolean().optional().describe("Throw if the tab is throttled. Default: false."),
       ...sessionIdShape6
     },
     outputSchema: {
-      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()
+      effect: z16.unknown().describe("The iris_act result (dispatched, settled, inputMode, etc.)."),
+      verdict: z16.object({
+        pass: z16.boolean(),
+        evidence: z16.unknown().optional(),
+        failureReason: z16.string().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()
+      trace: z16.unknown().describe("Reaction report (same shape as iris_observe summary)."),
+      session: z16.object({ lastSeenMs: z16.number(), throttled: z16.boolean(), focused: z16.boolean() }).optional()
     },
     handler: async (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
       const paused = pausedShortCircuit(session);
       if (paused !== void 0)
         return paused;
       refuseIfThrottled(session, args["refuseWhenThrottled"]);
-      const until = PredicateSchema.parse(args["until"]);
-      const timeout = asNumber2(args["timeout_ms"]) ?? 4e3;
+      const until = args["until"] !== void 0 ? PredicateSchema.parse(args["until"]) : { kind: "settled" };
+      const timeout = asNumber(args["timeout_ms"]) ?? 4e3;
       const since = session.elapsed();
       session.markActCursor(since);
       const actResult = await session.command(IrisCommand.ACT, {
@@ -4770,44 +5635,45 @@ 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: 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."),
+      window_ms: z16.number().optional().describe("Time window to look back. Default: 2000ms. Ignored when `since` is provided."),
+      since: z16.number().optional().describe("Cursor from a prior iris_act or iris_observe call. Scopes the event window to exactly that span."),
+      filters: z16.array(z16.string()).optional().describe("Event type allowlist: dom | net | route | console | animation | signal. Omit to return all types."),
+      max_events: z16.number().optional().describe("Cap the timeline to the most recent N events. Older events are counted in cost.droppedOldest."),
       ...sessionIdShape6
     },
     outputSchema: {
-      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()
+      events: z16.array(z16.unknown()),
+      summary: z16.object({
+        total: z16.number(),
+        network: z16.number(),
+        domAdded: z16.number(),
+        domRemoved: z16.number(),
+        domChanged: z16.number(),
+        routeChanges: z16.number(),
+        consoleErrors: z16.number(),
+        animations: z16.number(),
+        signals: z16.number()
       }),
-      cost: z15.object({
-        events: z15.number(),
-        bytes: z15.number(),
-        droppedOldest: z15.number().optional()
+      cost: z16.object({
+        events: z16.number(),
+        bytes: z16.number(),
+        droppedOldest: z16.number().optional(),
+        recommendation: z16.string().optional().describe("Present when the timeline is large \u2014 scope your next call (filters/max_events).")
       }),
-      session: z15.object({ lastSeenMs: z15.number(), throttled: z15.boolean(), focused: z15.boolean() }).optional()
+      session: z16.object({ lastSeenMs: z16.number(), throttled: z16.boolean(), focused: z16.boolean() }).optional()
     },
     handler: (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
-      const since = asNumber2(args["since"]);
-      const windowMs = asNumber2(args["window_ms"]) ?? 2e3;
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
+      const since = asNumber(args["since"]);
+      const windowMs = asNumber(args["window_ms"]) ?? 2e3;
       const events = since !== void 0 ? session.eventsSince(since) : session.eventsInWindow(windowMs);
       const filters = Array.isArray(args["filters"]) ? args["filters"] : void 0;
       const filtered = filters === void 0 ? events : events.filter((e) => filters.includes(e.type));
-      const { events: budgeted, droppedOldest } = applyEventBudget(filtered, asNumber2(args["max_events"]));
-      const report = buildReactionReport(budgeted, windowMs);
+      const { events: budgeted, droppedOldest } = applyEventBudget(filtered, asNumber(args["max_events"]));
+      const report2 = buildReactionReport(budgeted, windowMs);
       return Promise.resolve(withControl(session, {
-        ...report,
-        cost: costHint(report, budgeted.length, droppedOldest),
+        ...report2,
+        cost: costHint(report2, budgeted.length, droppedOldest),
         ...healthEnvelope(session)
       }));
     }
@@ -4816,99 +5682,113 @@ var TOOLS = [
     name: IrisTool.WAIT_FOR,
     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: 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."),
+      predicate: PredicateSchema.describe('Predicate to wait for: { signal }, { net }, { element }, { kind: "settled", quietMs } (deterministic network + DOM idle \u2014 prefer this over a fixed sleep), or a combination via allOf/anyOf.'),
+      timeout_ms: z16.number().optional().describe("Maximum wait in milliseconds. Default: 4000."),
+      since: z16.number().optional().describe("Cursor from a prior iris_act \u2014 scopes the wait to events after that act."),
       ...sessionIdShape6
     },
     outputSchema: {
-      pass: z15.boolean(),
-      evidence: z15.unknown().optional(),
-      failureReason: z15.string().optional(),
-      session: z15.object({ lastSeenMs: z15.number(), throttled: z15.boolean(), focused: z15.boolean() }).optional()
+      pass: z16.boolean(),
+      evidence: z16.unknown().optional(),
+      failureReason: z16.string().optional(),
+      session: z16.object({ lastSeenMs: z16.number(), throttled: z16.boolean(), focused: z16.boolean() }).optional()
     },
     handler: async (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
       const predicate = PredicateSchema.parse(args["predicate"]);
-      const since = asNumber2(args["since"]) ?? session.lastActCursor() ?? 0;
-      const verdict = await waitForPredicate(session, predicate, asNumber2(args["timeout_ms"]) ?? 4e3, since);
+      const since = asNumber(args["since"]) ?? session.lastActCursor() ?? 0;
+      const verdict = await waitForPredicate(session, predicate, asNumber(args["timeout_ms"]) ?? 4e3, since);
       return withControl(session, { ...verdict, ...healthEnvelope(session) });
     }
   },
   {
     name: IrisTool.ASSERT,
-    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.",
+    description: "Evaluate a predicate (optionally waiting up to timeout_ms). Returns { pass, evidence, failureReason? }. The end of every verify loop. Prefer a { signal } or { net } consequence over { element }/{ text } presence \u2014 a passing presence-only assertion returns `advice` because a wrong/healed element can fake it. 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: 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."),
+      timeout_ms: z16.number().optional().describe("If > 0, wait up to this many milliseconds before failing. Default: 0 (evaluate once)."),
+      since: z16.number().optional().describe("Cursor from a prior iris_act \u2014 scopes the assertion to events after that act."),
       ...sessionIdShape6
     },
     outputSchema: {
-      pass: z15.boolean(),
-      evidence: z15.unknown().optional(),
-      failureReason: z15.string().optional(),
-      session: z15.object({ lastSeenMs: z15.number(), throttled: z15.boolean(), focused: z15.boolean() }).optional()
+      pass: z16.boolean(),
+      evidence: z16.unknown().optional(),
+      failureReason: z16.string().optional(),
+      advice: z16.string().optional().describe("Present on a PASSING presence-only assertion \u2014 nudges toward a consequence."),
+      session: z16.object({ lastSeenMs: z16.number(), throttled: z16.boolean(), focused: z16.boolean() }).optional()
     },
     handler: async (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
       const predicate = PredicateSchema.parse(args["predicate"]);
-      const timeout = asNumber2(args["timeout_ms"]) ?? 0;
-      const since = asNumber2(args["since"]) ?? session.lastActCursor() ?? 0;
+      const timeout = asNumber(args["timeout_ms"]) ?? 0;
+      const since = asNumber(args["since"]) ?? session.lastActCursor() ?? 0;
       const verdict = timeout > 0 ? await waitForPredicate(session, predicate, timeout, since) : await evaluatePredicate(session, predicate, since);
-      return withControl(session, { ...verdict, ...healthEnvelope(session) });
+      const advice = verdict.pass && isPresenceOnlyAssertion(predicate) ? { advice: PRESENCE_ONLY_ADVICE } : {};
+      return withControl(session, { ...verdict, ...advice, ...healthEnvelope(session) });
     }
   },
   {
     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: 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)."),
+      since: z16.number().optional().describe("Cursor from a prior iris_act \u2014 scopes the query to requests fired after that act."),
+      method: z16.string().optional().describe("HTTP method filter: GET | POST | PUT | DELETE | PATCH etc."),
+      urlContains: z16.string().optional().describe("Substring that the request URL must contain."),
+      status: z16.number().optional().describe("HTTP status code filter (e.g. 200, 404, 500)."),
+      limit: z16.number().optional().describe("Keep only the most recent N matching calls (older are dropped and counted in droppedOldest) \u2014 cuts tokens on a wide window."),
       ...sessionIdShape6
     },
     outputSchema: {
-      calls: z15.array(z15.unknown()),
-      hint: z15.object({ totalInWindow: z15.number(), present: z15.array(z15.string()) }).optional()
+      calls: z16.array(z16.unknown()),
+      total: z16.number().optional().describe("Total matches before `limit` \u2014 present only when capped."),
+      droppedOldest: z16.number().optional().describe("How many older matches `limit` dropped."),
+      hint: z16.object({ totalInWindow: z16.number(), present: z16.array(z16.string()) }).optional(),
+      cost: z16.object({ bytes: z16.number(), tokens: z16.number() }).optional()
     },
     handler: (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
-      const since = asNumber2(args["since"]) ?? 0;
-      const method = asString4(args["method"]);
-      const urlContains = asString4(args["urlContains"]);
-      const status = asNumber2(args["status"]);
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
+      const since = asNumber(args["since"]) ?? 0;
+      const method = asString(args["method"]);
+      const urlContains = asString(args["urlContains"]);
+      const status = asNumber(args["status"]);
+      const limit = asNumber(args["limit"]);
       const allNet = session.eventsSince(since).filter((e) => e.type === EventType.NET_REQUEST);
-      const calls = allNet.filter((e) => matchNet(e, method, urlContains, status));
-      if (calls.length === 0 && allNet.length > 0) {
-        return Promise.resolve({ calls, hint: netEmptyHint(allNet) });
+      const matched = allNet.filter((e) => matchNet(e, method, urlContains, status));
+      if (matched.length === 0 && allNet.length > 0) {
+        return Promise.resolve(withSizeCost({ calls: matched, hint: netEmptyHint(allNet) }));
       }
-      return Promise.resolve({ calls });
+      const { events: calls, droppedOldest } = applyEventBudget(matched, limit);
+      return Promise.resolve(withSizeCost(droppedOldest > 0 ? { calls, total: matched.length, droppedOldest } : { calls }));
     }
   },
   {
     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: 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."),
+      level: z16.string().optional().describe("Log level filter: error | warn | info | log. Omit to return all levels."),
+      since: z16.number().optional().describe("Cursor from a prior iris_act \u2014 scopes the query to log entries after that act."),
+      limit: z16.number().optional().describe("Keep only the most recent N matching entries (older are dropped and counted in droppedOldest) \u2014 cuts tokens when a page spams the console."),
       ...sessionIdShape6
     },
     outputSchema: {
-      logs: z15.array(z15.unknown()),
-      hint: z15.object({ totalInWindow: z15.number(), byLevel: z15.record(z15.number()) }).optional()
+      logs: z16.array(z16.unknown()),
+      total: z16.number().optional().describe("Total matches before `limit` \u2014 present only when capped."),
+      droppedOldest: z16.number().optional().describe("How many older matches `limit` dropped."),
+      hint: z16.object({ totalInWindow: z16.number(), byLevel: z16.record(z16.number()) }).optional(),
+      cost: z16.object({ bytes: z16.number(), tokens: z16.number() }).optional()
     },
     handler: (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
-      const since = asNumber2(args["since"]) ?? 0;
-      const level = asString4(args["level"]);
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
+      const since = asNumber(args["since"]) ?? 0;
+      const level = asString(args["level"]);
+      const limit = asNumber(args["limit"]);
       const allConsole = session.eventsSince(since).filter(isConsoleEvent);
-      const logs = allConsole.filter((e) => matchConsole(e, level));
-      if (logs.length === 0 && allConsole.length > 0) {
-        return Promise.resolve({ logs, hint: consoleEmptyHint(allConsole) });
+      const matched = allConsole.filter((e) => matchConsole(e, level));
+      if (matched.length === 0 && allConsole.length > 0) {
+        return Promise.resolve(withSizeCost({ logs: matched, hint: consoleEmptyHint(allConsole) }));
       }
-      return Promise.resolve({ logs });
+      const { events: logs, droppedOldest } = applyEventBudget(matched, limit);
+      return Promise.resolve(withSizeCost(droppedOldest > 0 ? { logs, total: matched.length, droppedOldest } : { logs }));
     }
   },
   {
@@ -4916,24 +5796,24 @@ var TOOLS = [
     description: "Currently running + recently completed animations with targets/timing.",
     inputSchema: { ...sessionIdShape6 },
     outputSchema: {
-      animations: z15.array(z15.unknown())
+      animations: z16.array(z16.unknown())
     },
-    handler: (deps, args) => commandOrThrow3(deps, asString4(args["sessionId"]), IrisCommand.ANIMATIONS, {})
+    handler: (deps, args) => commandOrThrow3(deps, asString(args["sessionId"]), IrisCommand.ANIMATIONS, {})
   },
   {
     name: IrisTool.BASELINE_SAVE,
     description: "Snapshot the current semantic state under a name, to diff against later (regression detection).",
     inputSchema: {
-      name: z15.string().describe('Label for this baseline snapshot (e.g. "dashboard-initial"). Use the same name in iris_diff to compare.'),
+      name: z16.string().describe('Label for this baseline snapshot (e.g. "dashboard-initial"). Use the same name in iris_diff to compare.'),
       ...sessionIdShape6
     },
     outputSchema: {
-      baseline: z15.string().describe("Saved baseline name \u2014 pass to iris_diff to compare."),
-      lineCount: z15.number()
+      baseline: z16.string().describe("Saved baseline name \u2014 pass to iris_diff to compare."),
+      lineCount: z16.number()
     },
     handler: async (deps, args) => {
-      const name = asString4(args["name"]) ?? "default";
-      const { lines, route } = await snapshotTree(deps, asString4(args["sessionId"]));
+      const name = asString(args["name"]) ?? "default";
+      const { lines, route } = await snapshotTree(deps, asString(args["sessionId"]));
       deps.baselines.save({ name, lines, route });
       return { baseline: name, lineCount: lines.length };
     }
@@ -4943,7 +5823,7 @@ var TOOLS = [
     description: "List saved baseline names.",
     inputSchema: {},
     outputSchema: {
-      baselines: z15.array(z15.string())
+      baselines: z16.array(z16.string())
     },
     handler: (deps) => Promise.resolve({ baselines: deps.baselines.list() })
   },
@@ -4951,23 +5831,23 @@ 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: z15.string().describe("Baseline name to compare against. Call iris_baseline_list to get available names; names are created by iris_baseline_save."),
+      baseline: z16.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: z15.string(),
-      removed: z15.array(z15.string()),
-      added: z15.array(z15.string()),
-      consoleErrors: z15.number(),
-      routeChanged: z15.boolean()
+      baseline: z16.string(),
+      removed: z16.array(z16.string()),
+      added: z16.array(z16.string()),
+      consoleErrors: z16.number(),
+      routeChanged: z16.boolean()
     },
     handler: async (deps, args) => {
-      const name = asString4(args["baseline"]) ?? "default";
+      const name = asString(args["baseline"]) ?? "default";
       const base = deps.baselines.get(name);
       if (base === void 0)
         throw new Error(`no baseline named '${name}'`);
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
-      const { lines, route } = await snapshotTree(deps, asString4(args["sessionId"]));
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
+      const { lines, route } = await snapshotTree(deps, asString(args["sessionId"]));
       const { removed, added } = diffLines(base.lines, lines);
       const consoleErrors = session.eventsSince(0).filter((e) => e.type === EventType.CONSOLE_ERROR || e.type === EventType.ERROR_UNCAUGHT).length;
       return { baseline: name, removed, added, consoleErrors, routeChanged: base.route !== route };
@@ -4977,16 +5857,16 @@ var TOOLS = [
     name: IrisTool.RECORD_START,
     description: "Start recording the event timeline under a name (for replay / a flow report).",
     inputSchema: {
-      recordingName: z15.string().describe("Identifier for this recording. Pass the same name to iris_record_stop and iris_replay."),
+      recordingName: z16.string().describe("Identifier for this recording. Pass the same name to iris_record_stop and iris_replay."),
       ...sessionIdShape6
     },
     outputSchema: {
-      recordingName: z15.string(),
-      since: z15.number()
+      recordingName: z16.string(),
+      since: z16.number()
     },
     handler: (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
-      const name = asString4(args["recordingName"]) ?? "default";
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
+      const name = asString(args["recordingName"]) ?? "default";
       const cursor = session.elapsed();
       deps.recordings.start(name, cursor);
       return Promise.resolve({ recordingName: name, since: cursor });
@@ -4996,17 +5876,17 @@ 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: z15.string().describe("Identifier of an active recording started with iris_record_start."),
+      recordingName: z16.string().describe("Identifier of an active recording started with iris_record_start."),
       ...sessionIdShape6
     },
     outputSchema: {
-      recordingName: z15.string(),
-      program: z15.unknown(),
-      warning: z15.string().optional()
+      recordingName: z16.string(),
+      program: z16.unknown(),
+      warning: z16.string().optional()
     },
     handler: (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
-      const name = asString4(args["recordingName"]) ?? "default";
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
+      const name = asString(args["recordingName"]) ?? "default";
       const rec = deps.recordings.stop(name);
       if (rec === void 0)
         throw new Error(`no active recording named '${name}'`);
@@ -5018,43 +5898,44 @@ var TOOLS = [
       };
       deps.recordings.saveCompiled(program);
       const unstable = rec.steps.filter((s) => !s.stable).length;
-      const report = buildReactionReport(events, session.elapsed() - rec.cursor);
+      const report2 = buildReactionReport(events, session.elapsed() - rec.cursor);
       return Promise.resolve({
         recordingName: name,
         program,
         ...unstable > 0 ? {
           warning: `${String(unstable)} step(s) not bound to a testid; replay may be brittle (in-session only)`
         } : {},
-        ...report,
-        cost: costHint(report, events.length)
+        ...report2,
+        cost: costHint(report2, events.length)
       });
     }
   },
   {
     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?}] }.",
+    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. Destructive controls require confirmDangerous:true on every replay; confirmation is never persisted. Returns { ok, steps:[{tool,ok,error?,note?}] }.",
     inputSchema: {
-      recordingName: z15.string().describe("Name of a compiled recording (from iris_record_stop) to re-execute."),
+      recordingName: z16.string().describe("Name of a compiled recording (from iris_record_stop) to re-execute."),
+      confirmDangerous: z16.boolean().optional().describe("Set true to allow destructive controls during this replay only."),
       ...sessionIdShape6
     },
     outputSchema: {
-      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()
+      recordingName: z16.string(),
+      ok: z16.boolean(),
+      steps: z16.array(z16.object({
+        tool: z16.string(),
+        ok: z16.boolean(),
+        error: z16.string().optional(),
+        note: z16.string().optional()
       }))
     },
     handler: async (deps, args) => {
-      const name = asString4(args["recordingName"]) ?? "default";
+      const name = asString(args["recordingName"]) ?? "default";
       const program = deps.recordings.getCompiled(name);
       if (program === void 0)
         throw new Error(`no compiled recording named '${name}'`);
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
       const since = session.elapsed();
-      const steps = await replayProgram(session, program);
+      const steps = await replayProgram(session, program, args["confirmDangerous"] === true);
       return { recordingName: name, since, steps, ok: steps.every((s) => s.ok) };
     }
   },
@@ -5062,13 +5943,13 @@ 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: 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."),
+      text: z16.string().describe("Short sentence describing your next action, shown on the presenter HUD for the developer watching."),
+      level: z16.string().optional().describe("Display severity: info | warn | error. Default: info."),
       ...sessionIdShape6
     },
-    outputSchema: { ok: z15.boolean() },
+    outputSchema: { ok: z16.boolean() },
     handler: async (deps, args) => {
-      const result = await commandOrThrow3(deps, asString4(args["sessionId"]), IrisCommand.NARRATE, {
+      const result = await commandOrThrow3(deps, asString(args["sessionId"]), IrisCommand.NARRATE, {
         text: args["text"],
         level: args["level"]
       });
@@ -5079,16 +5960,16 @@ var TOOLS = [
     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: 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."),
+      freeze: z16.boolean().optional().describe("Freeze the fake clock. Time stops advancing until advanceMs or reset."),
+      advanceMs: z16.number().optional().describe("Fast-forward time by this many milliseconds \u2014 triggers debounces, toasts, auto-dismiss timers."),
+      reset: z16.boolean().optional().describe("Restore the real clock."),
       ...sessionIdShape6
     },
     outputSchema: {
-      ok: z15.boolean().optional(),
-      elapsed: z15.number().optional()
+      ok: z16.boolean().optional(),
+      elapsed: z16.number().optional()
     },
-    handler: (deps, args) => commandOrThrow3(deps, asString4(args["sessionId"]), IrisCommand.CLOCK, {
+    handler: (deps, args) => commandOrThrow3(deps, asString(args["sessionId"]), IrisCommand.CLOCK, {
       freeze: args["freeze"],
       advanceMs: args["advanceMs"],
       reset: args["reset"]
@@ -5098,27 +5979,27 @@ 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: 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."),
+      ref: z16.string().optional().describe("Element ref \u2014 attempts a best-effort read of the nearest React component's hook state."),
+      store: z16.string().optional().describe("Registered store name (e.g. 'workspace'). Omit to read all stores."),
+      path: z16.string().optional().describe("Dot-path into the store (e.g. 'captionCache.v3'). Numeric array indices are supported."),
+      depth: z16.number().optional().describe("Collapse anything deeper than N levels to a size marker \u2014 avoids huge outputs for large stores."),
       ...sessionIdShape6
     },
     outputSchema: {
-      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()
+      stores: z16.record(z16.unknown()).optional(),
+      storeNames: z16.array(z16.string()).optional(),
+      found: z16.boolean().optional(),
+      value: z16.unknown().optional(),
+      component: z16.object({ ok: z16.boolean(), reason: z16.string().optional(), state: z16.unknown().optional() }).optional()
     },
     handler: async (deps, args) => {
-      const store = asString4(args["store"]);
-      const result = await commandOrThrow3(deps, asString4(args["sessionId"]), IrisCommand.STATE_READ, {
+      const store = asString(args["store"]);
+      const result = await commandOrThrow3(deps, asString(args["sessionId"]), IrisCommand.STATE_READ, {
         ref: args["ref"],
         store
       });
-      const path = asString4(args["path"]);
-      const depth = asNumber2(args["depth"]);
+      const path = asString(args["path"]);
+      const depth = asNumber(args["depth"]);
       if (path === void 0 && depth === void 0)
         return result;
       const root = result;
@@ -5138,16 +6019,16 @@ 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: z15.string().optional().describe("CSS selector or element ref to restrict the interactive element list to a subtree."),
+      scope: z16.string().optional().describe("CSS selector or element ref to restrict the interactive element list to a subtree."),
       ...sessionIdShape6
     },
     outputSchema: {
-      interactive: z15.array(z15.unknown()),
-      consoleErrors: z15.number(),
-      hint: z15.string()
+      interactive: z16.array(z16.unknown()),
+      consoleErrors: z16.number(),
+      hint: z16.string()
     },
     handler: async (deps, args) => {
-      const session = deps.sessions.resolve(asString4(args["sessionId"]));
+      const session = deps.sessions.resolve(asString(args["sessionId"]));
       const result = await session.command(IrisCommand.SNAPSHOT, {
         mode: SnapshotMode.INTERACTIVE,
         scope: args["scope"]
@@ -5165,6 +6046,7 @@ var TOOLS = [
   },
   // iris_capabilities (live | fromDisk) + iris_contract_save. See contract-tools.ts.
   ...CONTRACT_TOOLS,
+  ...DOMAIN_TOOLS,
   // iris_flow_save / iris_flow_list / iris_flow_load. See flow-tools.ts.
   ...FLOW_TOOLS,
   // iris_project (read history + diff-vs-last) / iris_run_record. See project-tools.ts.
@@ -5318,7 +6200,7 @@ async function runTool(tool, deps, args) {
     return result;
   if (!isPlainObject(result) || "session" in result)
     return result;
-  const session = deps.sessions.resolve(asString4(args["sessionId"]));
+  const session = deps.sessions.resolve(asString(args["sessionId"]));
   const envelope = { ...healthEnvelope(session) };
   const lease = session.takeSessionLease();
   if (lease !== void 0)
@@ -5483,7 +6365,17 @@ function spawnDaemon(nodeExec, scriptPath, args, port) {
 // ../server/dist/index.js
 async function start(options = {}) {
   const port = options.port ?? IRIS_DEFAULT_PORT;
-  const bridge = new Bridge({ port });
+  const envToken = process.env["IRIS_TOKEN"];
+  const envOrigins = process.env["IRIS_ALLOWED_ORIGINS"];
+  const host = options.host ?? process.env["IRIS_HOST"];
+  const token = options.token ?? (envToken !== void 0 && envToken.length > 0 ? envToken : void 0);
+  const allowedOrigins = options.allowedOrigins ?? envOrigins?.split(",").map((origin) => origin.trim()).filter((origin) => origin.length > 0);
+  const bridge = new Bridge({
+    port,
+    ...host === void 0 ? {} : { host },
+    ...token === void 0 ? {} : { token },
+    ...allowedOrigins === void 0 ? {} : { allowedOrigins }
+  });
   const reaper = new SessionReaper(bridge.sessions);
   reaper.start();
   const baselines = new BaselineStore();
@@ -5751,13 +6643,619 @@ ${val}` : val;
   });
 }
 
+// ../server/dist/init/detect.js
+var Framework = {
+  NEXT: "next",
+  VITE: "vite",
+  HTML: "html"
+};
+var PackageManager = {
+  PNPM: "pnpm",
+  YARN: "yarn",
+  BUN: "bun",
+  NPM: "npm"
+};
+var NEXT_CONFIGS = ["next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs"];
+var VITE_CONFIGS = ["vite.config.js", "vite.config.ts", "vite.config.mjs", "vite.config.mts"];
+function depVersion(pkg, name) {
+  return pkg.dependencies?.[name] ?? pkg.devDependencies?.[name] ?? pkg.peerDependencies?.[name];
+}
+function hasAnyConfig(files, candidates) {
+  return candidates.some((c) => files.has(c));
+}
+function parseMajor(range) {
+  if (range === void 0)
+    return void 0;
+  const match = range.match(/(\d+)/);
+  if (match === null || match[1] === void 0)
+    return void 0;
+  const major = parseInt(match[1], 10);
+  return isNaN(major) ? void 0 : major;
+}
+function detectPackageManager(lockfiles) {
+  if (lockfiles.has("pnpm-lock.yaml"))
+    return PackageManager.PNPM;
+  if (lockfiles.has("yarn.lock"))
+    return PackageManager.YARN;
+  if (lockfiles.has("bun.lockb") || lockfiles.has("bun.lock"))
+    return PackageManager.BUN;
+  return PackageManager.NPM;
+}
+function detectFramework(input) {
+  const { pkg, configFiles } = input;
+  if (depVersion(pkg, "next") !== void 0 || hasAnyConfig(configFiles, NEXT_CONFIGS)) {
+    return Framework.NEXT;
+  }
+  if (depVersion(pkg, "vite") !== void 0 || hasAnyConfig(configFiles, VITE_CONFIGS)) {
+    return Framework.VITE;
+  }
+  return Framework.HTML;
+}
+function detect(input) {
+  const reactMajor = parseMajor(depVersion(input.pkg, "react"));
+  return {
+    framework: detectFramework(input),
+    reactMajor,
+    needsSourceMapping: reactMajor !== void 0 && reactMajor >= 19,
+    packageManager: detectPackageManager(input.lockfiles)
+  };
+}
+var INSTALL_ARGS = {
+  [PackageManager.PNPM]: ["add", "-D"],
+  [PackageManager.YARN]: ["add", "-D"],
+  [PackageManager.BUN]: ["add", "-d"],
+  [PackageManager.NPM]: ["i", "-D"]
+};
+function installCommandParts(pm, pkg) {
+  return { command: pm, args: [...INSTALL_ARGS[pm], pkg] };
+}
+function installCommand(pm, pkg) {
+  const { command, args } = installCommandParts(pm, pkg);
+  return `${command} ${args.join(" ")}`;
+}
+
+// ../server/dist/init/mcp.js
+var MCP_SERVER_NAME = "iris";
+var NPX = "npx";
+var IRIS_PACKAGE = "@syrin/iris";
+var MCP_SUBCOMMAND = "mcp";
+var PORT_FLAG = "--port";
+var CLAUDE_CLI = "claude";
+function npxServerArgs(port) {
+  return port === void 0 ? [IRIS_PACKAGE, MCP_SUBCOMMAND] : [IRIS_PACKAGE, MCP_SUBCOMMAND, PORT_FLAG, String(port)];
+}
+function serverInvocation(port) {
+  return [NPX, ...npxServerArgs(port)];
+}
+function claudeAddCommand(port) {
+  const tail = serverInvocation(port);
+  const args = [MCP_SUBCOMMAND, "add", MCP_SERVER_NAME, "-s", "user", "--", ...tail];
+  return { command: CLAUDE_CLI, args, display: `${CLAUDE_CLI} ${args.join(" ")}` };
+}
+function claudeExistsProbe() {
+  return { command: CLAUDE_CLI, args: [MCP_SUBCOMMAND, "get", MCP_SERVER_NAME] };
+}
+function claudeAvailableProbe() {
+  return { command: CLAUDE_CLI, args: ["--version"] };
+}
+function mcpManual(port) {
+  const tail = serverInvocation(port).join(" ");
+  return `Register the Iris MCP server ONCE, globally (so every project gets it):
+
+  ${CLAUDE_CLI} ${MCP_SUBCOMMAND} add ${MCP_SERVER_NAME} -s user -- ${tail}
+
+Or, for another agent, add this to its global MCP config (e.g. Cursor's ~/.cursor/mcp.json):
+
+  "${MCP_SERVER_NAME}": { "command": "${NPX}", "args": ${JSON.stringify(serverInvocation(port).slice(1))} }`;
+}
+
+// ../server/dist/init/cursor.js
+var CURSOR_MCP_RELPATH = ".cursor/mcp.json";
+var CURSOR_DIR_RELPATH = ".cursor";
+var CursorMergeStatus = {
+  APPLY: "apply",
+  ALREADY: "already",
+  MANUAL: "manual"
+};
+function cursorServerEntry(port) {
+  return { command: NPX, args: npxServerArgs(port) };
+}
+function parseConfig(existing) {
+  if (existing === null || existing.trim().length === 0)
+    return { ok: true, config: {} };
+  try {
+    const parsed = JSON.parse(existing);
+    if (typeof parsed !== "object" || parsed === null)
+      return { ok: true, config: {} };
+    return { ok: true, config: parsed };
+  } catch {
+    return { ok: false };
+  }
+}
+function mergeCursorConfig(existing, port) {
+  const parsed = parseConfig(existing);
+  if (!parsed.ok) {
+    return { status: CursorMergeStatus.MANUAL, content: existing ?? "" };
+  }
+  const config = parsed.config;
+  const servers = config.mcpServers ?? {};
+  if (Object.prototype.hasOwnProperty.call(servers, MCP_SERVER_NAME)) {
+    return { status: CursorMergeStatus.ALREADY, content: existing ?? "" };
+  }
+  const merged = {
+    ...config,
+    mcpServers: { ...servers, [MCP_SERVER_NAME]: cursorServerEntry(port) }
+  };
+  return { status: CursorMergeStatus.APPLY, content: `${JSON.stringify(merged, null, 2)}
+` };
+}
+
+// ../server/dist/init/vite-config.js
+var VITE_IMPORT = "import { iris } from '@syrin/iris/vite';";
+var IRIS_MARKER = "@syrin/iris/vite";
+function irisPluginCall(port) {
+  return port === void 0 ? "iris()" : `iris({ port: ${String(port)} })`;
+}
+var PLUGINS_ARRAY = /plugins\s*:\s*\[/;
+var IMPORT_LINE = /^import\s.+from\s+['"][^'"]+['"];?\s*$/gm;
+var VitePatchKind = {
+  APPLY: "apply",
+  ALREADY: "already",
+  MANUAL: "manual"
+};
+var NO_PLUGINS_REASON = "couldn't find a `plugins: [...]` array to extend";
+function insertImport(source) {
+  const matches = [...source.matchAll(IMPORT_LINE)];
+  const last = matches[matches.length - 1];
+  if (last?.index === void 0) {
+    return `${VITE_IMPORT}
+${source}`;
+  }
+  const end = last.index + last[0].length;
+  return `${source.slice(0, end)}
+${VITE_IMPORT}${source.slice(end)}`;
+}
+function insertPlugin(source, port) {
+  return source.replace(PLUGINS_ARRAY, (match) => `${match}${irisPluginCall(port)}, `);
+}
+function patchViteConfig(source, port) {
+  if (source.includes(IRIS_MARKER)) {
+    return { kind: VitePatchKind.ALREADY };
+  }
+  if (!PLUGINS_ARRAY.test(source)) {
+    return { kind: VitePatchKind.MANUAL, reason: NO_PLUGINS_REASON };
+  }
+  return { kind: VitePatchKind.APPLY, code: insertImport(insertPlugin(source, port)) };
+}
+
+// ../server/dist/init/snippets.js
+function connectArg(port) {
+  if (port === void 0 || port === IRIS_DEFAULT_PORT)
+    return "";
+  return `{ url: 'ws://localhost:${String(port)}${IRIS_WS_PATH}' }`;
+}
+function viteManual(port) {
+  const call = port === void 0 ? "iris()" : `iris({ port: ${String(port)} })`;
+  return `Add the Iris plugin to your Vite config:
+
+  import { iris } from '@syrin/iris/vite';
+
+  export default defineConfig({
+    plugins: [react(), ${call}],
+  });
+
+The plugin only applies during \`vite\` (dev) \u2014 it is dropped from \`vite build\`.`;
+}
+function nextConfigManual(configFile) {
+  return `Wrap your ${configFile} export with withIris (keeps SWC, dev-only):
+
+  import { withIris } from '@syrin/iris/next';
+
+  export default withIris(nextConfig);`;
+}
+function nextIrisDevFile(port) {
+  return `'use client';
+import { useEffect } from 'react';
+
+/** Dev-only: connect Iris + install the React adapter, after hydration. */
+export function IrisDev() {
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'development') return;
+    void import('@syrin/iris').then(({ iris, install }) => {
+      install();
+      iris.connect(${connectArg(port)});
+    });
+  }, []);
+  return null;
+}
+`;
+}
+var NEXT_LAYOUT_MANUAL = `Mount <IrisDev /> in your root layout (app/layout.tsx), dev-only:
+
+  import { IrisDev } from './iris-dev';
+  // inside <body>:
+  {process.env.NODE_ENV === 'development' ? <IrisDev /> : null}`;
+function htmlManual(port) {
+  return `Add a dev-gated module script at app boot:
+
+  <script type="module">
+    if (location.hostname === 'localhost') {
+      const { iris, install } = await import('@syrin/iris');
+      install();
+      iris.connect(${connectArg(port)});
+    }
+  </script>`;
+}
+var NEXT_IRIS_DEV_PATH = "app/iris-dev.tsx";
+
+// ../server/dist/init/plan.js
+var IRIS_PACKAGE2 = "@syrin/iris";
+var MCP_TARGET = "global (claude user scope)";
+var StepStatus = {
+  APPLY: "apply",
+  MANUAL: "manual",
+  ALREADY: "already",
+  SKIP: "skip"
+};
+var CLAUDE_MCP_TITLE = "MCP server (Claude, global)";
+var CURSOR_MCP_TITLE = "MCP server (Cursor, global)";
+function claudeMcpStep(input) {
+  if (!input.claudeCli)
+    return null;
+  if (input.mcpExists) {
+    return {
+      title: CLAUDE_MCP_TITLE,
+      target: MCP_TARGET,
+      status: StepStatus.ALREADY,
+      detail: "iris already registered (install once, used by every project)"
+    };
+  }
+  const cmd = claudeAddCommand(input.options.port);
+  return {
+    title: CLAUDE_MCP_TITLE,
+    target: MCP_TARGET,
+    status: StepStatus.APPLY,
+    detail: "register iris globally for all projects",
+    exec: { command: cmd.command, args: cmd.args, fallback: cmd.display }
+  };
+}
+function cursorMcpStep(input) {
+  if (!input.cursorPresent)
+    return null;
+  const r = mergeCursorConfig(input.cursorConfig, input.options.port);
+  if (r.status === CursorMergeStatus.ALREADY) {
+    return {
+      title: CURSOR_MCP_TITLE,
+      target: input.cursorConfigPath,
+      status: StepStatus.ALREADY,
+      detail: "iris already in Cursor global config"
+    };
+  }
+  if (r.status === CursorMergeStatus.MANUAL) {
+    return {
+      title: CURSOR_MCP_TITLE,
+      target: input.cursorConfigPath,
+      status: StepStatus.MANUAL,
+      detail: `couldn't parse ${input.cursorConfigPath} \u2014 add this server by hand:
+  "iris": ${JSON.stringify(cursorServerEntry(input.options.port))}`
+    };
+  }
+  return {
+    title: CURSOR_MCP_TITLE,
+    target: input.cursorConfigPath,
+    status: StepStatus.APPLY,
+    detail: "register iris in Cursor global config",
+    write: { path: input.cursorConfigPath, content: r.content }
+  };
+}
+function mcpSteps(input) {
+  if (!input.options.mcp) {
+    return [
+      {
+        title: "MCP server (global)",
+        target: MCP_TARGET,
+        status: StepStatus.SKIP,
+        detail: "--no-mcp"
+      }
+    ];
+  }
+  const steps = [claudeMcpStep(input), cursorMcpStep(input)].filter((s) => s !== null);
+  if (steps.length > 0)
+    return steps;
+  return [
+    {
+      title: "MCP server (global)",
+      target: MCP_TARGET,
+      status: StepStatus.MANUAL,
+      detail: mcpManual(input.options.port)
+    }
+  ];
+}
+function installStep(input) {
+  const pm = input.detection.packageManager;
+  const command = installCommand(pm, IRIS_PACKAGE2);
+  if (!input.options.install) {
+    return {
+      title: "Install dependency",
+      target: "package.json",
+      status: StepStatus.MANUAL,
+      detail: command
+    };
+  }
+  const parts = installCommandParts(pm, IRIS_PACKAGE2);
+  return {
+    title: "Install dependency",
+    target: "package.json",
+    status: StepStatus.APPLY,
+    detail: command,
+    exec: { command: parts.command, args: parts.args, fallback: command }
+  };
+}
+function viteSteps(input) {
+  const cfg = input.viteConfig;
+  const port = input.options.port;
+  if (cfg === null) {
+    return [
+      {
+        title: "Vite plugin",
+        target: "vite.config",
+        status: StepStatus.MANUAL,
+        detail: viteManual(port)
+      }
+    ];
+  }
+  const patch = patchViteConfig(cfg.source, port);
+  if (patch.kind === VitePatchKind.ALREADY) {
+    return [
+      {
+        title: "Vite plugin",
+        target: cfg.path,
+        status: StepStatus.ALREADY,
+        detail: "iris() already in plugins"
+      }
+    ];
+  }
+  if (patch.kind === VitePatchKind.MANUAL) {
+    return [
+      {
+        title: "Vite plugin",
+        target: cfg.path,
+        status: StepStatus.MANUAL,
+        detail: `${patch.reason}
+
+${viteManual(port)}`
+      }
+    ];
+  }
+  return [
+    {
+      title: "Vite plugin",
+      target: cfg.path,
+      status: StepStatus.APPLY,
+      detail: "add iris() to plugins (also injects connect())",
+      write: { path: cfg.path, content: patch.code }
+    }
+  ];
+}
+function nextSteps(input) {
+  const configFile = input.nextConfigFile ?? "next.config.mjs";
+  const devFile = input.nextIrisDevExists ? {
+    title: "IrisDev component",
+    target: NEXT_IRIS_DEV_PATH,
+    status: StepStatus.ALREADY,
+    detail: "file exists"
+  } : {
+    title: "IrisDev component",
+    target: NEXT_IRIS_DEV_PATH,
+    status: StepStatus.APPLY,
+    detail: "create dev-only connect component",
+    write: { path: NEXT_IRIS_DEV_PATH, content: nextIrisDevFile(input.options.port) }
+  };
+  return [
+    devFile,
+    {
+      title: "Next config (withIris)",
+      target: configFile,
+      status: StepStatus.MANUAL,
+      detail: nextConfigManual(configFile)
+    },
+    {
+      title: "Mount IrisDev",
+      target: "app/layout.tsx",
+      status: StepStatus.MANUAL,
+      detail: NEXT_LAYOUT_MANUAL
+    }
+  ];
+}
+function buildPlan(input) {
+  const steps = [...mcpSteps(input), installStep(input)];
+  if (input.detection.framework === Framework.VITE) {
+    steps.push(...viteSteps(input));
+  } else if (input.detection.framework === Framework.NEXT) {
+    steps.push(...nextSteps(input));
+  } else {
+    steps.push({
+      title: "Connect snippet",
+      target: "index.html",
+      status: StepStatus.MANUAL,
+      detail: htmlManual(input.options.port)
+    });
+  }
+  return { framework: input.detection.framework, steps };
+}
+
+// ../server/dist/init/run.js
+var PACKAGE_JSON = "package.json";
+var NEXT_IRIS_DEV = "app/iris-dev.tsx";
+var VITE_CONFIG_CANDIDATES = [
+  "vite.config.ts",
+  "vite.config.js",
+  "vite.config.mjs",
+  "vite.config.mts"
+];
+var NEXT_CONFIG_CANDIDATES = [
+  "next.config.mjs",
+  "next.config.js",
+  "next.config.ts",
+  "next.config.cjs"
+];
+var STATUS_SYMBOL = {
+  [StepStatus.APPLY]: "\u2713",
+  [StepStatus.MANUAL]: "\u26A0",
+  [StepStatus.ALREADY]: "\xB7",
+  [StepStatus.SKIP]: "\u2013"
+};
+function firstPresent(files, candidates) {
+  for (const c of candidates)
+    if (files.has(c))
+      return c;
+  return null;
+}
+function gatherPlanInput(options, io, pkgRaw) {
+  const pkg = JSON.parse(pkgRaw);
+  const rootFiles = new Set(io.rootFiles());
+  const detectInput = {
+    pkg: typeof pkg === "object" && pkg !== null ? pkg : {},
+    configFiles: rootFiles,
+    lockfiles: rootFiles
+  };
+  const detection = detect(detectInput);
+  const vitePath = firstPresent(rootFiles, VITE_CONFIG_CANDIDATES);
+  const viteSource = vitePath === null ? null : io.readFile(vitePath);
+  const viteConfig = vitePath !== null && viteSource !== null ? { path: vitePath, source: viteSource } : null;
+  const availableProbe = claudeAvailableProbe();
+  const claudeCli = options.mcp ? io.probe(availableProbe.command, availableProbe.args) : false;
+  const existsProbe = claudeExistsProbe();
+  const mcpExists = claudeCli ? io.probe(existsProbe.command, existsProbe.args) : false;
+  const cursorDir = `${io.homeDir()}/${CURSOR_DIR_RELPATH}`;
+  const cursorConfigPath = `${io.homeDir()}/${CURSOR_MCP_RELPATH}`;
+  const cursorPresent = options.mcp && io.exists(cursorDir);
+  const cursorConfig = cursorPresent ? io.readFile(cursorConfigPath) : null;
+  return {
+    detection,
+    claudeCli,
+    mcpExists,
+    cursorPresent,
+    cursorConfig,
+    cursorConfigPath,
+    viteConfig,
+    nextConfigFile: firstPresent(rootFiles, NEXT_CONFIG_CANDIDATES),
+    nextIrisDevExists: io.exists(NEXT_IRIS_DEV),
+    options: { port: options.port, mcp: options.mcp, install: options.install }
+  };
+}
+function restartHint(framework) {
+  if (framework === Framework.NEXT)
+    return 'Restart `next dev`, then ask your agent: "List Iris sessions".';
+  if (framework === Framework.VITE)
+    return 'Restart `vite`, then ask your agent: "List Iris sessions".';
+  return 'Reload your app on localhost, then ask your agent: "List Iris sessions".';
+}
+function report(plan, dryRun, failed, io) {
+  io.print(dryRun ? "iris init (dry run \u2014 no files written)" : "iris init");
+  io.print("");
+  let applied = 0;
+  let manual = 0;
+  for (const s of plan.steps) {
+    const downgraded = failed.has(s.target);
+    const status = downgraded ? StepStatus.MANUAL : s.status;
+    const detail = downgraded && s.exec !== void 0 ? `step failed \u2014 run manually: ${s.exec.fallback}` : s.detail;
+    io.print(`  [${STATUS_SYMBOL[status]}] ${s.title} \u2192 ${s.target}`);
+    if (status === StepStatus.APPLY)
+      applied++;
+    if (status === StepStatus.MANUAL) {
+      manual++;
+      for (const line of detail.split("\n"))
+        io.print(`      ${line}`);
+    } else if (detail.length > 0) {
+      io.print(`      ${detail}`);
+    }
+  }
+  io.print("");
+  io.print(restartHint(plan.framework));
+  return { ok: true, applied, manual };
+}
+function applyEffects(plan, io) {
+  const failed = /* @__PURE__ */ new Set();
+  for (const s of plan.steps) {
+    if (s.status !== StepStatus.APPLY)
+      continue;
+    if (s.write !== void 0)
+      io.writeFile(s.write.path, s.write.content);
+    if (s.exec !== void 0 && !io.exec(s.exec.command, s.exec.args))
+      failed.add(s.target);
+  }
+  return failed;
+}
+function runInit(options, io) {
+  const pkgRaw = io.readFile(PACKAGE_JSON);
+  if (pkgRaw === null) {
+    io.print("No package.json found. Run `iris init` from your project root.");
+    return { ok: false, applied: 0, manual: 0 };
+  }
+  const plan = buildPlan(gatherPlanInput(options, io, pkgRaw));
+  const failed = options.dryRun ? /* @__PURE__ */ new Set() : applyEffects(plan, io);
+  return report(plan, options.dryRun, failed, io);
+}
+
+// ../server/dist/init/node-io.js
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync3, existsSync as existsSync4, mkdirSync as mkdirSync3, readdirSync, statSync } from "fs";
+import { join as join6, dirname as dirname2, isAbsolute } from "path";
+import { homedir as homedir3 } from "os";
+import { spawnSync } from "child_process";
+function buildNodeIo(cwd) {
+  const abs = (rel) => isAbsolute(rel) ? rel : join6(cwd, rel);
+  return {
+    readFile(rel) {
+      const path = abs(rel);
+      if (!existsSync4(path))
+        return null;
+      return readFileSync3(path, "utf8");
+    },
+    writeFile(rel, content) {
+      const path = abs(rel);
+      mkdirSync3(dirname2(path), { recursive: true });
+      writeFileSync3(path, content, "utf8");
+    },
+    exists(rel) {
+      return existsSync4(abs(rel));
+    },
+    homeDir() {
+      return homedir3();
+    },
+    rootFiles() {
+      return readdirSync(cwd).filter((name) => {
+        try {
+          return statSync(join6(cwd, name)).isFile();
+        } catch {
+          return false;
+        }
+      });
+    },
+    exec(command, args) {
+      const result = spawnSync(command, [...args], { cwd, stdio: "inherit", shell: true });
+      return result.status === 0;
+    },
+    probe(command, args) {
+      const result = spawnSync(command, [...args], { cwd, stdio: "ignore", shell: true });
+      return result.status === 0;
+    },
+    print(line) {
+      process.stdout.write(`${line}
+`);
+    }
+  };
+}
+
 // ../server/dist/cli.js
 var CLI_USAGE = `usage:
+  iris init  [--yes] [--dry-run] [--port N] [--no-mcp] [--no-install]  (wire Iris into the project in this directory)
   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 INIT_COMMAND = "init";
 var SERVE_COMMAND = "serve";
 var STOP_COMMAND = "stop";
 var STATUS_COMMAND = "status";
@@ -5765,9 +7263,13 @@ var DRIVE_COMMAND = "drive";
 var MCP_COMMAND = "mcp";
 var DAEMON_INNER_COMMAND = "_daemon";
 var HEADED_FLAG = "--headed";
-var PORT_FLAG = "--port";
+var PORT_FLAG2 = "--port";
 var DRIVE_FLAG = "--drive";
 var QUIET_FLAG = "--quiet";
+var DRY_RUN_FLAG = "--dry-run";
+var YES_FLAG = "--yes";
+var NO_MCP_FLAG = "--no-mcp";
+var NO_INSTALL_FLAG = "--no-install";
 function parseServeFlags(args, defaultPort) {
   let port = defaultPort;
   let driveUrl;
@@ -5775,7 +7277,7 @@ function parseServeFlags(args, defaultPort) {
   let i = 0;
   while (i < args.length) {
     const arg = args[i];
-    if (arg === PORT_FLAG) {
+    if (arg === PORT_FLAG2) {
       i++;
       const n = args[i];
       if (n === void 0)
@@ -5799,7 +7301,7 @@ function parseServeFlags(args, defaultPort) {
   return { kind: "ok", port, headless, ...driveUrl !== void 0 ? { driveUrl } : {} };
 }
 function parsePortFlag(args, defaultPort) {
-  const idx = args.indexOf(PORT_FLAG);
+  const idx = args.indexOf(PORT_FLAG2);
   if (idx === -1)
     return defaultPort;
   const n = args[idx + 1];
@@ -5826,11 +7328,48 @@ function parseDriveSuffix(args, port) {
     return { kind: "error", message: CLI_USAGE };
   return { kind: "ok", port, driveUrl, headless };
 }
+function parseInitFlags(args) {
+  let port;
+  let mcp = true;
+  let dryRun = false;
+  let install = true;
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === PORT_FLAG2) {
+      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 === NO_MCP_FLAG) {
+      mcp = false;
+    } else if (arg === NO_INSTALL_FLAG) {
+      install = false;
+    } else if (arg === DRY_RUN_FLAG) {
+      dryRun = true;
+    } else if (arg === YES_FLAG) {
+    } else {
+      return { kind: "error", message: CLI_USAGE };
+    }
+    i++;
+  }
+  return { kind: "ok", port, mcp, dryRun, install };
+}
 function parseCliArgs(argv, defaultPort) {
   if (argv.length === 0)
     return { kind: "serve", port: defaultPort, headless: true };
   const [cmd, ...rest] = argv;
   switch (cmd) {
+    case INIT_COMMAND: {
+      const r = parseInitFlags(rest);
+      if (r.kind === "error")
+        return r;
+      return { kind: "init", port: r.port, mcp: r.mcp, dryRun: r.dryRun, install: r.install };
+    }
     case SERVE_COMMAND: {
       const r = parseServeFlags(rest, defaultPort);
       if (r.kind === "error")
@@ -5883,6 +7422,12 @@ function parseCliArgs(argv, defaultPort) {
       return { kind: "error", message: CLI_USAGE };
   }
 }
+function handleInit(parsed) {
+  const cwd = process.cwd();
+  const result = runInit({ cwd, port: parsed.port, mcp: parsed.mcp, dryRun: parsed.dryRun, install: parsed.install }, buildNodeIo(cwd));
+  if (!result.ok)
+    process.exit(1);
+}
 function handleServe(parsed) {
   if (isRunning(parsed.port)) {
     log("iris_daemon_already_running", { port: parsed.port });
@@ -5894,7 +7439,7 @@ function handleServe(parsed) {
     process.exit(1);
     return;
   }
-  const daemonArgs = [DAEMON_INNER_COMMAND, PORT_FLAG, String(parsed.port)];
+  const daemonArgs = [DAEMON_INNER_COMMAND, PORT_FLAG2, String(parsed.port)];
   if (parsed.driveUrl !== void 0) {
     daemonArgs.push(DRIVE_FLAG, parsed.driveUrl);
     if (!parsed.headless)
@@ -5974,7 +7519,7 @@ function handleMcp(opts) {
         process.exit(1);
         return;
       }
-      const daemonArgs = [DAEMON_INNER_COMMAND, PORT_FLAG, String(port)];
+      const daemonArgs = [DAEMON_INNER_COMMAND, PORT_FLAG2, String(port)];
       if (driveUrl !== void 0) {
         daemonArgs.push(DRIVE_FLAG, driveUrl);
         if (!headless)
@@ -6013,6 +7558,9 @@ function main() {
       log("iris_usage_error", { message: parsed.message });
       process.exit(1);
       break;
+    case "init":
+      handleInit(parsed);
+      break;
     case "serve":
       handleServe(parsed);
       break;
@@ -6033,6 +7581,18 @@ function main() {
       break;
   }
 }
-if (process.argv[1] !== void 0 && import.meta.url === pathToFileURL(process.argv[1]).href) {
+function isEntryPoint() {
+  const argv1 = process.argv[1];
+  if (argv1 === void 0)
+    return false;
+  if (import.meta.url === pathToFileURL(argv1).href)
+    return true;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(argv1)).href;
+  } catch {
+    return false;
+  }
+}
+if (isEntryPoint()) {
   main();
 }