@buoy-gg/mcp 7.0.20 → 7.0.22

package/dist/index.js

@@ -72,7 +72,12 @@ var import_sync_broker = require("@buoy-gg/sync-broker");
 var BROKER_PORT = import_sync_broker.DEFAULT_BROKER_PORT;
 var BROKER_URL = `http://localhost:${BROKER_PORT}`;
 var DEFAULT_ACTION_TIMEOUT_MS = 15e3;
+var UNRESPONSIVE_ACTION_TIMEOUT_MS = 2500;
+var UNRESPONSIVE_SNAPSHOT_TIMEOUT_MS = 1200;
+var RECOVERY_PROBE_MS = 2e4;
+var UNRESPONSIVE_AFTER_MS = 3e4;
 var DEFAULT_SNAPSHOT_TIMEOUT_MS = 5e3;
+var DEVICE_RETENTION_MS = 15 * 6e4;
 var DASHBOARD_NAME = "Dashboard";
 var ALL_DEVICES = "All";
 
@@ -97,6 +102,16 @@ var SyncClient = class {
     this.pendingActions = /* @__PURE__ */ new Map();
     /** Callbacks waiting for the next snapshot of `${deviceId}::${toolId}`. */
     this.snapshotWaiters = /* @__PURE__ */ new Map();
+    /** When each cached snapshot arrived, keyed by snapKey (staleness reporting). */
+    this.snapshotAt = /* @__PURE__ */ new Map();
+    /** Liveness per device — see {@link noteTimeout}. */
+    this.health = /* @__PURE__ */ new Map();
+    /** Dev-server origin per device — see {@link noteDevServerOrigin}. */
+    this.devServerOrigins = /* @__PURE__ */ new Map();
+    /** Devices whose origin probe already ran (a production bundle has none). */
+    this.originProbed = /* @__PURE__ */ new Set();
+    /** Last time each device appeared in the broker's device list. */
+    this.lastSeen = /* @__PURE__ */ new Map();
     this.port = opts.port ?? BROKER_PORT;
     this.url = opts.url ?? (opts.port ? `http://localhost:${opts.port}` : BROKER_URL);
     this.actionTimeoutMs = opts.actionTimeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS;
@@ -156,13 +171,19 @@ var SyncClient = class {
       });
       socket.on("devtool-capabilities", (msg) => {
         this.capabilities.set(msg.persistentDeviceId, msg);
+        void this.learnDevServerOrigin(msg.persistentDeviceId);
       });
       socket.on("all-devices-update", (list) => {
-        if (Array.isArray(list)) this.devices = list;
+        if (!Array.isArray(list)) return;
+        this.devices = list;
+        const now = Date.now();
+        for (const d of list) if (d.deviceId) this.lastSeen.set(d.deviceId, now);
+        this.pruneStaleDevices();
       });
       socket.on("devtool-sync", (msg) => {
         const key = snapKey(msg.persistentDeviceId, msg.toolId);
         this.snapshots.set(key, msg.payload);
+        this.snapshotAt.set(key, Date.now());
         const waiters = this.snapshotWaiters.get(key);
         if (waiters && waiters.length) {
           this.snapshotWaiters.set(key, []);
@@ -178,6 +199,37 @@ var SyncClient = class {
       });
     });
   }
+  /**
+   * Drop everything remembered about devices that have been gone a while.
+   *
+   * Deliberately NOT on disconnect: a crashed app often drops off the broker,
+   * and its cached console snapshot is the crash evidence — throwing that away
+   * the instant it disconnects would delete the answer. But device ids change
+   * with every simulator erase and fresh dev client, and each one can hold
+   * multi-MB snapshots, so a long-lived server has to forget eventually.
+   */
+  pruneStaleDevices() {
+    const cutoff = Date.now() - DEVICE_RETENTION_MS;
+    for (const [deviceId, seen] of this.lastSeen) {
+      if (seen > cutoff) continue;
+      if (this.devices.some((d) => d.deviceId === deviceId)) continue;
+      this.lastSeen.delete(deviceId);
+      this.capabilities.delete(deviceId);
+      this.health.delete(deviceId);
+      this.devServerOrigins.delete(deviceId);
+      this.originProbed.delete(deviceId);
+      const prefix = `${deviceId}::`;
+      for (const key of [...this.snapshots.keys()]) {
+        if (key.startsWith(prefix)) {
+          this.snapshots.delete(key);
+          this.snapshotAt.delete(key);
+        }
+      }
+      for (const key of [...this.watching.keys()]) {
+        if (key.startsWith(prefix)) this.watching.delete(key);
+      }
+    }
+  }
   /** Disconnect and tear down a spawned broker, if any. */
   async stop() {
     for (const [, p] of this.pendingActions) {
@@ -185,6 +237,8 @@ var SyncClient = class {
       p.reject(new Error("SyncClient stopped"));
     }
     this.pendingActions.clear();
+    for (const [, waiters] of this.snapshotWaiters) for (const w of waiters) w(void 0);
+    this.snapshotWaiters.clear();
     this.socket?.close();
     this.socket = null;
     if (this.broker) {
@@ -228,11 +282,19 @@ var SyncClient = class {
   resolveDevice(deviceId) {
     if (deviceId) return deviceId;
     const connected = this.connectedDevices();
-    if (connected.length === 1) return connected[0].deviceId;
     if (connected.length === 0) {
       throw new Error("No devices are connected to the broker. Open the app with Buoy devtools running.");
     }
-    const list = connected.map((d) => `${d.deviceName} (${d.deviceId})`).join(", ");
+    if (connected.length === 1) return connected[0].deviceId;
+    const usable = connected.filter((d) => d.tools.length > 0);
+    if (usable.length === 1) return usable[0].deviceId;
+    if (usable.length === 0) {
+      const names = connected.map((d) => d.deviceName).join(", ");
+      throw new Error(
+        `Connected devices (${names}) are not exposing any Buoy tools yet. Make sure the app is in the foreground with devtools mounted, then retry.`
+      );
+    }
+    const list = usable.map((d) => `${d.deviceName} (${d.deviceId})`).join(", ");
     throw new Error(`Multiple devices connected \u2014 specify deviceId. Connected: ${list}`);
   }
   /**
@@ -257,6 +319,136 @@ var SyncClient = class {
     return target;
   }
   // ----------------------------------------------------------------
+  // Device liveness
+  // ----------------------------------------------------------------
+  healthOf(deviceId) {
+    let h = this.health.get(deviceId);
+    if (!h) {
+      h = { consecutiveTimeouts: 0, lastOkAt: 0, lastFullBudgetAt: 0 };
+      this.health.set(deviceId, h);
+    }
+    return h;
+  }
+  /** The device answered — it's alive. */
+  noteOk(deviceId) {
+    const h = this.healthOf(deviceId);
+    h.consecutiveTimeouts = 0;
+    h.lastOkAt = Date.now();
+  }
+  /**
+   * The device didn't answer. A crashed app never answers again, so after the
+   * first miss we stop paying the full timeout on every subsequent call.
+   */
+  noteTimeout(deviceId) {
+    this.healthOf(deviceId).consecutiveTimeouts += 1;
+  }
+  /** True once a device has missed a call and hasn't answered since. */
+  isUnresponsive(deviceId) {
+    return this.healthOf(deviceId).consecutiveTimeouts > 0;
+  }
+  /**
+   * Full timeout normally; a short one for a device already not answering.
+   *
+   * With one escape hatch: every RECOVERY_PROBE_MS a flagged device gets the
+   * full budget again. Without it the flag is self-sustaining — a device whose
+   * work legitimately takes longer than the short budget (a big snapshot, a
+   * slow simulator) can never answer, so it can never clear the flag, and every
+   * later reply is a confident "most likely CRASHED" about a healthy app.
+   */
+  timeoutFor(deviceId) {
+    if (!this.isUnresponsive(deviceId)) return this.actionTimeoutMs;
+    const h = this.healthOf(deviceId);
+    if (Date.now() - h.lastFullBudgetAt > RECOVERY_PROBE_MS) {
+      h.lastFullBudgetAt = Date.now();
+      return this.actionTimeoutMs;
+    }
+    return UNRESPONSIVE_ACTION_TIMEOUT_MS;
+  }
+  /**
+   * Plain-language diagnosis for a device that isn't answering, including the
+   * app's last words if the console tool got a crash flush out in time.
+   *
+   * A silent timeout is the worst possible answer here: the app is on a redbox,
+   * the reason is already captured, and without this the caller reads "timed
+   * out" and keeps retrying the same dead device.
+   */
+  unresponsiveNote(deviceId) {
+    const h = this.healthOf(deviceId);
+    const since = h.lastOkAt ? Math.round((Date.now() - h.lastOkAt) / 1e3) : null;
+    const crashed = h.consecutiveTimeouts >= 2 || h.lastOkAt === 0 || Date.now() - h.lastOkAt > UNRESPONSIVE_AFTER_MS;
+    const lines = [
+      `The app on "${deviceId}" is not responding (${h.consecutiveTimeouts} call${h.consecutiveTimeouts === 1 ? "" : "s"} unanswered${since != null ? `, last answered ${since}s ago` : ""}).`,
+      crashed ? "It is most likely CRASHED \u2014 a fatal render error unmounts the React tree, and the dev tools live in that tree, so nothing on-device can answer until the app is reloaded." : "It may be busy, mid-reload, or crashing."
+    ];
+    const fatal = this.lastFatalFor(deviceId);
+    if (fatal) lines.push(`Last captured error: ${fatal}`);
+    lines.push(
+      fatal ? "Read the crash state with get_console / get_storage (served from the last sync), then reload_app to recover." : "Try get_console (served from the last sync) for the app's last words, then reload_app to recover."
+    );
+    return lines.join(" ");
+  }
+  /**
+   * The newest error line the console tool synced for this device, if any.
+   * Reads the cached console snapshot rather than the device (which, by the
+   * time this matters, is not answering).
+   */
+  lastFatalFor(deviceId) {
+    const snap = this.snapshots.get(snapKey(deviceId, "console"));
+    const entries = snap?.entries;
+    if (!Array.isArray(entries)) return null;
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const e = entries[i];
+      if (e?.fatal || e?.level === "error") {
+        const msg = (e.message ?? "").split("\n")[0];
+        if (msg) return msg.length > 300 ? `${msg.slice(0, 300)}\u2026` : msg;
+      }
+    }
+    return null;
+  }
+  /** Age of the cached snapshot for a tool, in ms (null = never received). */
+  snapshotAgeMs(toolId, deviceId) {
+    const at = this.snapshotAt.get(snapKey(deviceId, toolId));
+    return at ? Date.now() - at : null;
+  }
+  /**
+   * Remember where a device's bundle came from, reported by core's `app`
+   * adapter while the app is healthy. It is the only way to reload an app that
+   * has crashed: the in-app reload needs the React tree that the crash
+   * destroyed, but the dev server's reload is handled natively.
+   */
+  noteDevServerOrigin(deviceId, origin) {
+    if (typeof origin === "string" && /^https?:\/\//.test(origin)) {
+      this.devServerOrigins.set(deviceId, origin);
+    }
+  }
+  /**
+   * Ask a freshly-announced device where its bundle came from, once.
+   *
+   * Deliberately eager: this is the piece of information that can ONLY be
+   * collected while the app is healthy, and is only ever needed after it has
+   * stopped answering. One cheap round-trip per device buys the ability to
+   * recover a crashed app instead of telling the caller to go do it by hand.
+   */
+  async learnDevServerOrigin(deviceId) {
+    if (this.devServerOrigins.has(deviceId) || this.originProbed.has(deviceId)) return;
+    this.originProbed.add(deviceId);
+    const hasApp = this.capabilities.get(deviceId)?.tools?.some((t) => t.toolId === "app");
+    if (!hasApp) return;
+    try {
+      const { payload } = await this.getSnapshot("app", deviceId, { timeoutMs: 4e3, silent: true });
+      this.noteDevServerOrigin(deviceId, payload?.devServerOrigin);
+    } catch {
+    }
+  }
+  /** The dev-server origin last reported by this device, if any. */
+  devServerOrigin(deviceId) {
+    const known = this.devServerOrigins.get(deviceId);
+    if (known) return known;
+    const snap = this.snapshots.get(snapKey(deviceId, "app"));
+    if (typeof snap?.devServerOrigin === "string") return snap.devServerOrigin;
+    return null;
+  }
+  // ----------------------------------------------------------------
   // Watch + snapshots
   // ----------------------------------------------------------------
   /**
@@ -327,13 +519,36 @@ var SyncClient = class {
     const target = this.resolveDevice(deviceId);
     const key = snapKey(target, toolId);
     this.ensureWatching(toolId, target);
-    const next = this.waitForSnapshot(key, opts.timeoutMs ?? DEFAULT_SNAPSHOT_TIMEOUT_MS);
+    let budget = opts.timeoutMs ?? DEFAULT_SNAPSHOT_TIMEOUT_MS;
+    if (opts.timeoutMs === void 0 && this.isUnresponsive(target)) {
+      const h = this.healthOf(target);
+      if (Date.now() - h.lastFullBudgetAt > RECOVERY_PROBE_MS) {
+        h.lastFullBudgetAt = Date.now();
+      } else {
+        budget = UNRESPONSIVE_SNAPSHOT_TIMEOUT_MS;
+      }
+    }
+    const next = this.waitForSnapshot(key, budget);
     this.socket?.emit("request-devtool-state", { toolId, targetDeviceId: target });
     const payload = await next;
-    if (payload !== void 0) return { deviceId: target, payload };
+    if (payload !== void 0) {
+      if (!opts.silent) this.noteOk(target);
+      return { deviceId: target, payload };
+    }
+    if (!opts.silent) this.noteTimeout(target);
     const cached = this.snapshots.get(key);
-    if (cached !== void 0) return { deviceId: target, payload: cached };
-    throw new Error(`Timed out waiting for "${toolId}" state from ${target} (is the tool active?)`);
+    if (cached !== void 0) {
+      return { deviceId: target, payload: cached, stale: this.staleNote(toolId, target) };
+    }
+    throw new Error(
+      `Timed out waiting for "${toolId}" state from ${target} (is the tool active?). ${this.unresponsiveNote(target)}`
+    );
+  }
+  /** Header line for data served from cache because the device went quiet. */
+  staleNote(toolId, deviceId) {
+    const age = this.snapshotAgeMs(toolId, deviceId);
+    const ageText = age == null ? "an earlier sync" : `${Math.round(age / 1e3)}s ago`;
+    return `\u26A0\uFE0F Served from the last sync (${ageText}) \u2014 ${this.unresponsiveNote(deviceId)}`;
   }
   waitForSnapshot(key, timeoutMs) {
     return new Promise((resolve) => {
@@ -362,11 +577,16 @@ var SyncClient = class {
     const target = deviceId === ALL_DEVICES ? ALL_DEVICES : this.resolveDevice(deviceId);
     if (!this.socket) throw new Error("SyncClient is not connected");
     const requestId = (0, import_node_crypto.randomUUID)();
-    const timeoutMs = opts.timeoutMs ?? this.actionTimeoutMs;
+    const timeoutMs = opts.timeoutMs ?? this.timeoutFor(target);
     const result = await new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pendingActions.delete(requestId);
-        reject(new Error(`Action "${toolId}.${action}" timed out after ${timeoutMs}ms`));
+        if (target !== ALL_DEVICES && !opts.silent) this.noteTimeout(target);
+        reject(
+          new Error(
+            `Action "${toolId}.${action}" got no answer in ${timeoutMs}ms. ` + (target === ALL_DEVICES ? "No device responded." : this.unresponsiveNote(target))
+          )
+        );
       }, timeoutMs);
       this.pendingActions.set(requestId, { resolve, reject, timer });
       this.socket.emit("devtool-action", {
@@ -377,6 +597,7 @@ var SyncClient = class {
         params: params ?? {}
       });
     });
+    if (target !== ALL_DEVICES && !opts.silent) this.noteOk(target);
     if (!result.ok) {
       throw new Error(result.error || `Action "${toolId}.${action}" failed on device`);
     }
@@ -408,7 +629,7 @@ var delay = (ms) => new Promise((r) => setTimeout(r, ms));
 
 // src/server.ts
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
-var import_zod19 = require("zod");
+var import_zod22 = require("zod");
 
 // src/tools/generic.ts
 var import_zod = require("zod");
@@ -419,7 +640,7 @@ var import_node_os = __toESM(require("os"));
 var import_node_path = __toESM(require("path"));
 
 // src/version.ts
-var VERSION = "7.0.20" ? "7.0.20" : "0.0.0-dev";
+var VERSION = "7.0.22" ? "7.0.22" : "0.0.0-dev";
 var PACKAGE_NAME = "@buoy-gg/mcp";
 
 // src/update/checkForUpdate.ts
@@ -726,6 +947,7 @@ function rankBatchFromIndex(index, batchId, casesOrder, failures = []) {
       deltaUiFps: null,
       deltaJsFps: null,
       renderCommits: num(median?.renderCommits),
+      renderWasted: median?.renderWasted,
       topRenderers: median?.topRenderers ?? []
     };
     return { ...base, flags: failed ? [] : computeFlags(base) };
@@ -816,13 +1038,18 @@ function formatRankingMarkdown(ranking) {
     );
   }
   const renderLines = ranking.rows.filter((r) => !r.failed && (r.renderCommits != null || r.topRenderers.length > 0)).map((r) => {
-    const top = r.topRenderers.map((t) => `${t.name} \xD7${t.renders} (${t.totalMs}ms)`).join(", ");
+    const top = r.topRenderers.map(
+      (t) => `${t.name} \xD7${t.renders} (${t.totalMs}ms${t.cause ? `, ${t.cause}` : ""})`
+    ).join(", ");
     const commits = r.renderCommits != null ? `${r.renderCommits} commits` : "";
-    return `- **${r.caseName}** \u2014 ${[commits, top].filter(Boolean).join(": ")}`;
+    const wasted = r.renderWasted != null ? `${r.renderWasted} wasted` : "";
+    return `- **${r.caseName}** \u2014 ${[commits, wasted, top].filter(Boolean).join(": ")}`;
   });
   if (renderLines.length) {
     lines.push("");
-    lines.push("**Renders (median run)** \u2014 heaviest components by render self-time:");
+    lines.push(
+      "**Renders (median run)** \u2014 `wasted` = parent cascades + identity-only prop churn (removable). Cause per component: `propsUnstable` means a parent handed it a fresh function/object with unchanged values \u2014 fix upstream."
+    );
     lines.push(...renderLines);
   }
   lines.push("");
@@ -845,7 +1072,20 @@ function compareReportStats(a, b) {
     cpuUsage: ch(a.stats.cpuUsage, b.stats.cpuUsage),
     memoryUsage: ch(a.stats.memoryUsage, b.stats.memoryUsage),
     jsJankFrames: { a: a.stats.jsJankFrames, b: b.stats.jsJankFrames, delta: b.stats.jsJankFrames - a.stats.jsJankFrames },
-    uiJankFrames: { a: a.stats.uiJankFrames, b: b.stats.uiJankFrames, delta: b.stats.uiJankFrames - a.stats.uiJankFrames }
+    uiJankFrames: { a: a.stats.uiJankFrames, b: b.stats.uiJankFrames, delta: b.stats.uiJankFrames - a.stats.uiJankFrames },
+    ...compareRenders(a.renders, b.renders)
+  };
+}
+function compareRenders(a, b) {
+  if (!a && !b) return null;
+  const n = (v) => v ?? 0;
+  return {
+    renders: {
+      total: { a: n(a?.totalRenders), b: n(b?.totalRenders), delta: n(b?.totalRenders) - n(a?.totalRenders) },
+      commits: { a: n(a?.totalCommits), b: n(b?.totalCommits), delta: n(b?.totalCommits) - n(a?.totalCommits) },
+      wasted: { a: n(a?.wastedRenders), b: n(b?.wastedRenders), delta: n(b?.wastedRenders) - n(a?.wastedRenders) },
+      causes: { a: a?.causes ?? {}, b: b?.causes ?? {} }
+    }
   };
 }
 function round(n, d) {
@@ -1095,7 +1335,7 @@ ${JSON.stringify(summary, null, 2)}
     async ({ deviceId, maxWaitMs }) => {
       const log = (m) => process.stderr.write(`[buoy-mcp] ${m}
 `);
-      const cap = maxWaitMs ?? 6e5;
+      const cap3 = maxWaitMs ?? 6e5;
       try {
         const target = sync.requireProDevice(deviceId);
         const start = Date.now();
@@ -1103,7 +1343,7 @@ ${JSON.stringify(summary, null, 2)}
         let idleStreak = 0;
         let lastCount = -1;
         let resolved = null;
-        while (Date.now() - start < cap) {
+        while (Date.now() - start < cap3) {
           let snap2;
           try {
             snap2 = await readPerfSnapshot(sync, target);
@@ -1188,7 +1428,7 @@ ${JSON.stringify(ranking, null, 2)}
   server.registerTool(
     "compare_reports",
     {
-      description: "Compare two saved benchmark runs head-to-head (avg + p95 for FPS/CPU/memory, jank, with deltas).",
+      description: "Compare two saved benchmark runs head-to-head: avg + p95 for FPS/CPU/memory, jank, AND render counts \u2014 total, commits, and wasted (parent cascades + identity-only prop churn) \u2014 each with deltas. Use this to prove a memoization or re-render fix actually landed: the wasted-render delta is the number that says so.",
       inputSchema: {
         reportIdA: import_zod2.z.string().describe("First (baseline) report id."),
         reportIdB: import_zod2.z.string().describe("Second report id to compare against the baseline."),
@@ -1206,8 +1446,8 @@ ${JSON.stringify(ranking, null, 2)}
         if (!b) return fail2(`Report "${reportIdB}" not found.`);
         return json2(
           compareReportStats(
-            { name: a.metadata.name, stats: a.stats },
-            { name: b.metadata.name, stats: b.stats }
+            { name: a.metadata.name, stats: a.stats, renders: a.renders },
+            { name: b.metadata.name, stats: b.stats, renders: b.renders }
           )
         );
       } catch (e) {
@@ -1325,7 +1565,7 @@ function registerEventsTools(server, sync) {
   server.registerTool(
     "get_events",
     {
-      description: "The UNIVERSAL, token-bounded activity reader for what's happening in the app across ALL Buoy tools. The events tool aggregates every source \u2014 network requests, redux/zustand/jotai actions, react-query query/mutation updates, storage writes, route changes, renders \u2014 so filter to one with `sources`: ['network'] lists HTTP requests, ['redux'] dispatched actions, ['react-query'] query updates, ['storage'] writes, ['route'] navigation. Returns a compact one-line summary per event (source \xB7 status \xB7 title \xB7 timing) by DEFAULT \u2014 not the heavy raw payloads \u2014 so it's cheap. Re-call with includeData:true, a bigger limit, or specific sources only when you need detail. PREFER this over get_snapshot (and over reading source code) for any 'what happened' / 'show me the requests/actions' question; get_snapshot is the raw heavy current-state escape hatch.",
+      description: "The UNIVERSAL, token-bounded activity reader for what's happening in the app across ALL Buoy tools. Check this timeline BEFORE driving the UI to reproduce a bug \u2014 the failure is usually already recorded here. The events tool aggregates every source \u2014 network requests, redux/zustand/jotai actions, react-query query/mutation updates, storage writes, route changes, renders \u2014 so filter to one with `sources`: ['network'] lists HTTP requests, ['redux'] dispatched actions, ['react-query'] query updates, ['storage'] writes, ['route'] navigation. Returns a compact one-line summary per event (source \xB7 status \xB7 title \xB7 timing) by DEFAULT \u2014 not the heavy raw payloads \u2014 so it's cheap. Re-call with includeData:true, a bigger limit, or specific sources only when you need detail. PREFER this over get_snapshot (and over reading source code) for any 'what happened' / 'show me the requests/actions' question; get_snapshot is the raw heavy current-state escape hatch.",
       inputSchema: {
         limit: import_zod3.z.number().optional().describe("Most-recent N events to include. Default 25."),
         sources: import_zod3.z.array(import_zod3.z.string()).optional().describe('Only these sources. Coarse names accepted: "network", "redux", "react-query", "storage", "route", "render", "zustand", "jotai". Omit for all.'),
@@ -1490,7 +1730,7 @@ function registerNetworkTools(server, sync) {
   server.registerTool(
     "get_network_requests",
     {
-      description: "List captured HTTP requests WITH their request ids, plus which ones are pinned/saved. Use this (not get_events) when you need to ACT on a request \u2014 every network action is keyed by the id, and get_events does not emit ids. Compact by default: one line per request (id \xB7 status \xB7 method \xB7 path \xB7 timing \xB7 size). Set flagged:'pinned'|'saved'|'any' to read the developer's KEPT requests \u2014 those are snapshots that outlive Clear, the 500-request cap and app restarts, so treat a pinned request as 'a human flagged this as the problem'. Filter with status:'errors' to go straight to failures, or `pattern` to match a URL substring. includeBodies:true adds truncated request/response payloads (heavier).",
+      description: "List captured HTTP requests WITH their request ids, plus which ones are pinned/saved. API data wrong or calls failing \u2192 read the actual request+response bodies here instead of guessing from code; capture starts at app launch, so boot-time requests (session bootstrap, first queries) are included. Use this (not get_events) when you need to ACT on a request \u2014 every network action is keyed by the id, and get_events does not emit ids. Compact by default: one line per request (id \xB7 status \xB7 method \xB7 path \xB7 timing \xB7 size). Set flagged:'pinned'|'saved'|'any' to read the developer's KEPT requests \u2014 those are snapshots that outlive Clear, the 500-request cap and app restarts, so treat a pinned request as 'a human flagged this as the problem'. Filter with status:'errors' to go straight to failures, or `pattern` to match a URL substring. includeBodies:true adds truncated request/response payloads (heavier).",
       inputSchema: {
         limit: import_zod4.z.number().optional().describe("Most-recent N requests. Default 25."),
         pattern: import_zod4.z.string().optional().describe("Only requests whose URL contains this substring (case-insensitive)."),
@@ -2207,7 +2447,7 @@ function registerStorageTools(server, sync) {
   server.registerTool(
     "get_storage",
     {
-      description: "Read the app's storage keys across ALL backends: AsyncStorage, MMKV (per instance), and Expo SecureStore. Compact by DEFAULT \u2014 keys only \u2014 so it's token-cheap; pass includeValues:true for the values (truncated), or a `pattern` substring to narrow. Buoy's own internal keys are already filtered out. Use for 'what's in storage / read this key'.",
+      description: "Read the app's storage keys across ALL backends: AsyncStorage, MMKV (per instance), and Expo SecureStore. Data wrong or missing after an app restart \u2192 read the persisted values here FIRST \u2014 the bug is usually a stale, missing, or malformed stored value, and reading it beats hunting for it in code. Compact by DEFAULT \u2014 keys only \u2014 so it's token-cheap; pass includeValues:true for the values (truncated), or a `pattern` substring to narrow. Buoy's own internal keys are already filtered out.",
       inputSchema: {
         pattern: import_zod9.z.string().optional().describe("Only keys containing this substring (case-insensitive)."),
         includeValues: import_zod9.z.boolean().optional().describe("Include each key's value (truncated). Default false (keys only)."),
@@ -2220,13 +2460,13 @@ function registerStorageTools(server, sync) {
         const target = sync.requireProDevice(args.deviceId);
         const pattern = args.pattern?.toLowerCase();
         const limit = typeof args.limit === "number" && args.limit > 0 ? args.limit : 100;
-        const matches = (k) => !pattern || k.toLowerCase().includes(pattern);
+        const matches2 = (k) => !pattern || k.toLowerCase().includes(pattern);
         const sections = [];
         const allKeys = await sync.callAction(STORAGE_TOOL_ID, "async.getAllKeys", {}, target);
         if (!Array.isArray(allKeys)) {
           return fail9("No storage result from the device. The storage tool may be inactive.");
         }
-        const asyncKeys = allKeys.filter(matches).slice(0, limit);
+        const asyncKeys = allKeys.filter(matches2).slice(0, limit);
         if (asyncKeys.length > 0) {
           let lines;
           if (args.includeValues) {
@@ -2241,7 +2481,7 @@ ${lines.join("\n")}`);
         }
         const mmkv = await sync.callAction(STORAGE_TOOL_ID, "mmkv.snapshot", {}, target).catch(() => null);
         for (const inst of mmkv ?? []) {
-          const entries = inst.entries.filter((e) => matches(e.key)).slice(0, limit);
+          const entries = inst.entries.filter((e) => matches2(e.key)).slice(0, limit);
           if (entries.length === 0) continue;
           const lines = entries.map(
             (e) => args.includeValues ? `- \`${e.key}\` (${e.valueType}) = ${truncate2(e.value)}` : `- \`${e.key}\``
@@ -2251,7 +2491,7 @@ ${lines.join("\n")}`);
 ${lines.join("\n")}`);
         }
         const secure = await sync.callAction(STORAGE_TOOL_ID, "secure.keys", {}, target).catch(() => null);
-        const secureKeys = (secure ?? []).filter((d) => matches(d.key)).slice(0, limit);
+        const secureKeys = (secure ?? []).filter((d) => matches2(d.key)).slice(0, limit);
         if (secureKeys.length > 0) {
           const lines = await Promise.all(
             secureKeys.map(async (d) => {
@@ -2408,7 +2648,7 @@ function registerConsoleTools(server, sync) {
   server.registerTool(
     "get_console",
     {
-      description: "Read the app's captured console logs (console.log/warn/error/\u2026) as a compact tail \u2014 time \xB7 level \xB7 message. Token-cheap (uses each entry's pre-rendered message, not raw args). Filter by minimum level (e.g. level:'warning' for warnings+errors) or a message substring. Use for 'what's logging / any console errors'. For full args/stack of an entry, fall back to get_snapshot('console').",
+      description: "Read the app's captured console logs (console.log/warn/error/\u2026) as a compact tail \u2014 time \xB7 level \xB7 message. App crashing or erroring \u2192 read this FIRST: it captures crashes and errors including FATAL uncaught JS errors (tagged [FATAL], hooked from RN's global error handler), so a dead app's last words are here, not in the code. Token-cheap (uses each entry's pre-rendered message, not raw args). Filter by minimum level (e.g. level:'warning' for warnings+errors) or a message substring. For full args/stack of an entry, fall back to get_snapshot('console').",
       inputSchema: {
         level: import_zod11.z.enum(["verbose", "info", "warning", "error"]).optional().describe("Minimum level to include (severity threshold). e.g. 'warning' = warnings + errors. Default all."),
         limit: import_zod11.z.number().optional().describe("Most-recent N entries. Default 50."),
@@ -2419,7 +2659,10 @@ function registerConsoleTools(server, sync) {
     async (args) => {
       try {
         const target = sync.requireProDevice(args.deviceId);
-        const { payload } = await sync.getSnapshot(CONSOLE_TOOL_ID, target);
+        const { payload, stale } = await sync.getSnapshot(CONSOLE_TOOL_ID, target);
+        const staleHeader = stale ? `${stale}
+
+` : "";
         const p = Array.isArray(payload) ? { entries: payload } : payload ?? {};
         const all = Array.isArray(p.entries) ? p.entries : [];
         const minSev = args.level ? SEVERITY[args.level] : 0;
@@ -2431,12 +2674,12 @@ function registerConsoleTools(server, sync) {
         const limit = typeof args.limit === "number" && args.limit > 0 ? args.limit : 50;
         const shown = sorted.slice(-limit);
         if (shown.length === 0) {
-          return text10(`No console entries${args.level ? ` at level \u2265 ${args.level}` : ""}${pattern ? ` matching "${args.pattern}"` : ""} (${all.length} total captured).`);
+          return text10(`${staleHeader}No console entries${args.level ? ` at level \u2265 ${args.level}` : ""}${pattern ? ` matching "${args.pattern}"` : ""} (${all.length} total captured).`);
         }
         const lines = shown.map((e) => `${hhmmss(e.timestamp)} [${TAG[e.level] ?? e.level}] ${e.message}`);
         const levelNote = args.level ? `, level \u2265 ${args.level}` : "";
         const header = `**Console \u2014 ${all.length} entries (showing ${shown.length}${levelNote}):**`;
-        return text10(`${header}
+        return text10(`${staleHeader}${header}
 
 \`\`\`
 ${lines.join("\n")}
@@ -2460,13 +2703,19 @@ function kb(bytes) {
   return bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
 }
 function formatOutcome(outcome) {
-  const lines = Object.entries(outcome.results).map(([sid, r]) => {
-    const skips = r.skipped.slice(0, 3).map((s) => `
+  const lines = Object.entries(outcome.results).map(([sid, r2]) => {
+    const skips = r2.skipped.slice(0, 3).map((s) => `
     \xB7 ${s.id}: ${s.reason}`).join("");
-    const warns = r.warnings.slice(0, 3).map((w) => `
+    const warns = r2.warnings.slice(0, 3).map((w) => `
     \u26A0 ${w}`).join("");
-    return `  ${r.ok ? "\u2713" : "\u2715"} ${sid} \u2014 applied ${r.applied}${r.skipped.length ? `, skipped ${r.skipped.length}` : ""}${skips}${warns}`;
+    return `  ${r2.ok ? "\u2713" : "\u2715"} ${sid} \u2014 applied ${r2.applied}${r2.skipped.length ? `, skipped ${r2.skipped.length}` : ""}${skips}${warns}`;
   });
+  const r = outcome.route;
+  if (r) {
+    lines.push(
+      r.status === "navigated" ? `  \u2713 route \u2014 navigated to ${r.href}` : r.status === "deferred" ? `  \u21BB route \u2014 ${r.href} will be opened after the reload` : `  \u2715 route \u2014 ${r.error ?? r.status}`
+    );
+  }
   return `Restored "${outcome.snapshotName}" (${outcome.mode}${outcome.willReload ? ", app reloading" : ""}):
 ${lines.join("\n")}`;
 }
@@ -2474,7 +2723,7 @@ function registerTimeMachineTools(server, sync) {
   server.registerTool(
     "get_time_machine",
     {
-      description: "List the app's Time Machine state snapshots (restore points) and which state sources (storage/redux/zustand/jotai/react-query) can currently be captured/restored. Use time_machine_action to capture a snapshot before driving a flow, then restore it to re-run the flow from the same state.",
+      description: "List the app's Time Machine state snapshots (restore points) and which state sources (storage/redux/zustand/jotai/react-query) can currently be captured/restored. Each snapshot also records the route it was captured on (shown as `route`), which a restore can navigate back to. Use time_machine_action to capture a snapshot before driving a flow, then restore it to re-run the flow from the same state.",
       inputSchema: {
         deviceId: import_zod12.z.string().optional().describe("Target device id (auto-selected if one is connected).")
       }
@@ -2487,13 +2736,19 @@ function registerTimeMachineTools(server, sync) {
         const snapshots = p.snapshots ?? [];
         const providers = p.providers ?? [];
         const providerLines = providers.map((pr) => {
-          const cap = pr.canCapture ? pr.canRestore ? "capture+restore" : "capture only" : "unavailable";
-          return `- ${pr.label} (${pr.id}): ${cap}${pr.detail ? ` \u2014 ${pr.detail}` : ""}`;
+          const cap3 = pr.canCapture ? pr.canRestore ? "capture+restore" : "capture only" : "unavailable";
+          return `- ${pr.label} (${pr.id}): ${cap3}${pr.detail ? ` \u2014 ${pr.detail}` : ""}`;
         });
+        if (p.route) {
+          providerLines.push(
+            p.route.available ? `- Route (route): capture+restore \u2014 recorded with every snapshot; pass restoreRoute:true to return to it${p.route.current ? ` (now ${p.route.current})` : ""}` : "- Route (route): unavailable \u2014 no Expo Router on this device, snapshots record no route"
+          );
+        }
         const snapLines = snapshots.map((s) => {
           const warnings = Object.values(s.sources).reduce((n, src) => n + src.warnings.length, 0);
           const desc = s.baseline ? "baseline \u2014 restore wipes to fresh install (always reloads)" : `${kb(s.sizeBytes)} \xB7 ${Object.keys(s.sources).join(", ")}`;
-          return `- \`${s.id}\` **${s.name}** \u2014 ${new Date(s.createdAt).toISOString()} \xB7 ${desc}${warnings ? ` \xB7 \u26A0 ${warnings}` : ""}`;
+          const route = s.route ? ` \xB7 route ${s.route.href}` : "";
+          return `- \`${s.id}\` **${s.name}** \u2014 ${new Date(s.createdAt).toISOString()} \xB7 ${desc}${route}${warnings ? ` \xB7 \u26A0 ${warnings}` : ""}`;
         });
         const parts = [
           `**Time Machine \u2014 ${snapshots.length} snapshot(s):**`,
@@ -2512,13 +2767,14 @@ ${formatOutcome(p.lastOutcome)}`);
   server.registerTool(
     "time_machine_action",
     {
-      description: "Manage Time Machine state snapshots: capture the app's current state as a named restore point, preview what restoring one would change (per-item added/removed/changed/won't-apply verdicts \u2014 check the blast radius BEFORE restoring), restore one (mode 'live' replaces state in place; 'reload' restores persisted storage then reloads the JS bundle \u2014 baselines always reload), capture_baseline (an empty wipe-to-fresh-install restore point), delete, or rename. The restore result reports per-source applied/skipped counts \u2014 check them rather than assuming success.",
+      description: "Manage Time Machine state snapshots: capture the app's current state as a named restore point, preview what restoring one would change (per-item added/removed/changed/won't-apply verdicts \u2014 check the blast radius BEFORE restoring), restore one (mode 'live' replaces state in place; 'reload' restores persisted storage then reloads the JS bundle \u2014 baselines always reload; pass restoreRoute:true to also return to the screen the snapshot was captured on), capture_baseline (an empty wipe-to-fresh-install restore point), delete, or rename. The restore result reports per-source applied/skipped counts \u2014 check them rather than assuming success.",
       inputSchema: {
         action: import_zod12.z.enum(["capture", "capture_baseline", "preview", "restore", "delete", "rename"]).describe("What to do."),
         id: import_zod12.z.string().optional().describe("Snapshot id (required for restore/delete/rename; from get_time_machine)."),
         name: import_zod12.z.string().optional().describe("Snapshot name (for capture and rename)."),
         mode: import_zod12.z.enum(["live", "reload"]).optional().describe("Restore mode. Default 'live'."),
         excludeKeys: import_zod12.z.array(import_zod12.z.string()).optional().describe('Restore only: item keys to LEAVE UNTOUCHED, as "sourceId::itemKey" (itemKey = the key shown by the preview action, e.g. "query::[\\"pokemon\\"]" or "storage::async:@cart").'),
+        restoreRoute: import_zod12.z.boolean().optional().describe("Restore only: also navigate back to the route the snapshot was captured on (shown as `route` by get_time_machine). With mode 'reload' the navigation happens automatically on the next boot. Default false \u2014 state is restored but the app stays on the current screen."),
         sourceIds: import_zod12.z.array(import_zod12.z.string()).optional().describe("Capture/restore only these source ids (default all)."),
         deviceId: import_zod12.z.string().optional().describe("Target device id (auto-selected if one is connected).")
       }
@@ -2567,7 +2823,8 @@ ${lines.join("\n")}`);
             const outcome = await call("restore", {
               id: args.id,
               mode: args.mode ?? "live",
-              excludeKeys: args.excludeKeys
+              excludeKeys: args.excludeKeys,
+              restoreRoute: args.restoreRoute
             });
             return text11(formatOutcome(outcome));
           }
@@ -2785,11 +3042,14 @@ function formatElement(e) {
   if (e.nativeTag != null) line += ` #${e.nativeTag}`;
   return line;
 }
+var tapCount = 0;
+var FLOW_TIP_EVERY = 3;
+var FLOW_TIP = "\n\nTip: driving several steps? `run_flow` does a whole tap/type/wait/assert sequence in ONE call and reports the final screen plus the network and console output it produced.";
 function registerInteractTools(server, sync) {
   server.registerTool(
     "describe_screen",
     {
-      description: "List the interactive / labeled elements currently on screen \u2014 the app's live accessibility-style tree walked from the React fiber tree. Each row shows the component name, visible text/label, role, testID, a normalized tap point (tap: x,y in 0\u20131), and its #nativeTag. Rows marked with \u2022 are tappable (have an onPress). Use this to see what's on screen and pick something to tap with tap_element \u2014 no screenshot needed. Re-run after navigating or when the screen changes, since positions move. Requires Buoy Pro.",
+      description: "List the interactive / labeled elements currently on screen \u2014 the app's live accessibility-style tree walked from the React fiber tree. Each row shows the component name, visible text/label, role, testID, a normalized tap point (tap: x,y in 0\u20131), and its #nativeTag. Rows marked with \u2022 are tappable (have an onPress). Use this to see what's on screen and pick something to tap with tap_element \u2014 no screenshot needed. If you already know the sequence you want to drive, `run_flow` does the whole thing (taps, waits, assertions) in one call instead. Re-run after navigating or when the screen changes, since positions move. Requires Buoy Pro.",
       inputSchema: {
         interactiveOnly: import_zod14.z.boolean().optional().describe("Only return tappable (onPress) elements. Default false (include labels/text for context)."),
         deviceId: import_zod14.z.string().optional().describe("Target device id (auto-selected if one is connected).")
@@ -2818,7 +3078,7 @@ ${elements.map(formatElement).join("\n")}`);
   server.registerTool(
     "tap_element",
     {
-      description: "Interact with an on-screen element by invoking its handler directly in JS (no screenshot, no coordinate math, works on real devices). Handles buttons (onPress + onLongPress), toggles/switches and sliders (onValueChange), and text inputs (onChangeText) \u2014 see each element's `control` in describe_screen. Identify the target with an exact `nativeTag` or `testID`, or a fuzzy `query`. Pass `longPress:true` to invoke onLongPress instead of onPress (elements that support it show {long-press} in describe_screen). For a toggle, pass `value:true/false` (omit to flip); for a slider, pass a numeric `value` (omit to jump to the far end); for a text input, pass `text`. If the element is off-screen it's scrolled into view first (scrollIntoView:false to skip). Call describe_screen first to see options + current values. Requires Buoy Pro.",
+      description: "Interact with an on-screen element by invoking its handler directly in JS (no screenshot, no coordinate math, works on real devices). Handles buttons (onPress + onLongPress), toggles/switches and sliders (onValueChange), and text inputs (onChangeText) \u2014 see each element's `control` in describe_screen. Identify the target with an exact `nativeTag` or `testID`, or a fuzzy `query`. Pass `longPress:true` to invoke onLongPress instead of onPress (elements that support it show {long-press} in describe_screen). For a toggle, pass `value:true/false` (omit to flip); for a slider, pass a numeric `value` (omit to jump to the far end); for a text input, pass `text`. If the element is off-screen it's scrolled into view first (scrollIntoView:false to skip). Call describe_screen first to see options + current values. Driving MORE THAN ONE step (reproducing a bug, verifying a fix)? Use `run_flow` instead \u2014 it runs the whole sequence in one call. Requires Buoy Pro.",
       inputSchema: {
         nativeTag: import_zod14.z.number().optional().describe("Exact nativeTag from describe_screen (most precise)."),
         testID: import_zod14.z.string().optional().describe("Exact testID of the element."),
@@ -2850,13 +3110,15 @@ ${elements.map(formatElement).join("\n")}`);
           },
           target
         );
+        tapCount += 1;
+        const flowTip = tapCount >= FLOW_TIP_EVERY && tapCount % FLOW_TIP_EVERY === 0 ? FLOW_TIP : "";
         if (res?.tapped && res.matched) {
           const m = res.matched;
           const label = m.text ?? m.label ?? m.name;
           const id = m.testID ? ` [testID=${m.testID}]` : m.nativeTag != null ? ` #${m.nativeTag}` : "";
           const scrolledNote = res.scrolled ? " (scrolled into view)" : "";
           const verb = m.via === "onValueChange" ? `Set "${label}"${id} \u2192 ${JSON.stringify(m.value)}` : m.via === "onChangeText" ? `Typed ${JSON.stringify(m.value)} into "${label}"${id}` : m.via === "onLongPress" ? `Long-pressed "${label}"${id}` : `Tapped "${label}"${id}`;
-          return text12(`${verb}${scrolledNote}.`);
+          return text12(`${verb}${scrolledNote}.${flowTip}`);
         }
         let msg = res?.reason ?? "Tap failed.";
         if (res?.candidates?.length) {
@@ -2944,7 +3206,7 @@ function registerJsThreadTools(server, sync) {
   server.registerTool(
     "get_js_thread_top",
     {
-      description: "Task Manager for the React Native JS thread: sample for a few seconds and return a ranked table of which task origins (timers, Promise chains, rAF callbacks, bridge call-ins) consumed JS-thread time \u2014 plus thread busy% and freeze (50ms+ block) attribution. Use when JS FPS is low and you need to know WHAT is eating the thread. To profile one specific interaction, pass clearFirst:true, then drive the UI with tap_element while the sample runs. Drill into a row with get_js_thread_origin_detail. Requires @buoy-gg/js-top on the device.",
+      description: 'Task Manager for the React Native JS thread: sample for a few seconds and return a ranked table of which task origins (timers, Promise chains, rAF callbacks, bridge call-ins) consumed JS-thread time \u2014 plus thread busy% and freeze (50ms+ block) attribution. Use when JS FPS is low and you need to know WHAT is eating the thread. To profile one specific interaction, pass clearFirst:true, then drive the UI with tap_element while the sample runs. Drill into a row with get_js_thread_origin_detail. NOT the tool for React components re-rendering too often \u2014 this measures TASKS on the thread, not renders; for "the page re-renders constantly / typing lags / tapping one button re-renders everything" use measure_renders. Requires @buoy-gg/js-top on the device.',
       inputSchema: {
         deviceId: import_zod15.z.string().optional().describe("Target device id (auto-selected if one is connected)."),
         durationMs: import_zod15.z.number().optional().describe("How long to sample before reading the table. Default 3000, max 30000."),
@@ -3524,6 +3786,62 @@ ${JSON.stringify(slim)}
 
 // src/tools/packs/reload.ts
 var import_zod18 = require("zod");
+
+// src/capture/devServerReload.ts
+var import_ws = require("ws");
+var CONNECT_TIMEOUT_MS = 3e3;
+function messageSocketUrl(origin) {
+  return `${origin.replace(/^http/, "ws").replace(/\/+$/, "")}/message`;
+}
+function reloadViaDevServer(origin) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+    let socket;
+    try {
+      socket = new import_ws.WebSocket(messageSocketUrl(origin));
+    } catch (e) {
+      done({ ok: false, error: e.message });
+      return;
+    }
+    const timer = setTimeout(() => {
+      try {
+        socket.close();
+      } catch {
+      }
+      done({ ok: false, error: `dev server at ${origin} did not accept a connection` });
+    }, CONNECT_TIMEOUT_MS);
+    let sent = false;
+    socket.on("open", () => {
+      try {
+        socket.send(JSON.stringify({ version: 2, method: "reload" }));
+        sent = true;
+        clearTimeout(timer);
+        setTimeout(() => {
+          try {
+            socket.close();
+          } catch {
+          }
+          done({ ok: true });
+        }, 250);
+      } catch (e) {
+        clearTimeout(timer);
+        done({ ok: false, error: e.message });
+      }
+    });
+    socket.on("error", (e) => {
+      clearTimeout(timer);
+      if (sent) return;
+      done({ ok: false, error: e.message });
+    });
+  });
+}
+
+// src/tools/packs/reload.ts
 var APP_TOOL_ID = "app";
 var RELOAD_ACTION = "reloadApp";
 var DEFAULT_WAIT_MS = 3e4;
@@ -3536,7 +3854,11 @@ var errMsg18 = (e) => e instanceof Error ? e.message : String(e);
 var delay3 = (ms) => new Promise((r) => setTimeout(r, ms));
 async function ping(sync, deviceId, timeoutMs) {
   try {
-    const pong = await sync.callAction(APP_TOOL_ID, "ping", {}, deviceId, { timeoutMs });
+    const pong = await sync.callAction(APP_TOOL_ID, "ping", {}, deviceId, {
+      timeoutMs,
+      silent: true
+    });
+    sync.noteDevServerOrigin(deviceId, pong?.devServerOrigin);
     return typeof pong?.startedAt === "number" ? pong.startedAt : null;
   } catch {
     return null;
@@ -3565,7 +3887,7 @@ function registerReloadTools(server, sync) {
   server.registerTool(
     "reload_app",
     {
-      description: "Reload the running app's JS bundle (Expo Go, dev client, or RN CLI) \u2014 the equivalent of shaking the device and hitting Reload, but from here. Use it to pick up a change Fast Refresh didn't apply, to clear leaked in-memory state before a measurement, or to re-run app startup. In dev builds it uses React Native's DevSettings.reload(); otherwise it falls back to expo-updates (if the app installs it). All in-memory state is lost. By default this waits for the app to come back up and reports how long the reload took. Works on any app running @buoy-gg/core \u2014 no particular tool package needed. Requires Buoy Pro.",
+      description: "Reload the running app's JS bundle (Expo Go, dev client, or RN CLI) \u2014 the equivalent of shaking the device and hitting Reload, but from here. Use it to pick up a change Fast Refresh didn't apply, to clear leaked in-memory state before a measurement, to re-run app startup, or to RECOVER A CRASHED APP: after a fatal error the other tools stop answering, and reloading is how you get them back (it falls through to the dev server when the app is too broken to reload itself). In dev builds it uses React Native's DevSettings.reload(); otherwise it falls back to expo-updates (if the app installs it). All in-memory state is lost \u2014 read anything you need from get_console/get_storage BEFORE reloading. By default this waits for the app to come back up and reports how long the reload took. Works on any app running @buoy-gg/core \u2014 no particular tool package needed. Requires Buoy Pro.",
       inputSchema: {
         strategy: import_zod18.z.enum(["auto", "dev-settings", "expo-updates"]).optional().describe(
           "Reload mechanism. 'auto' (default) uses DevSettings in dev builds and expo-updates otherwise. Force one only when debugging the reload itself."
@@ -3580,13 +3902,27 @@ function registerReloadTools(server, sync) {
         const target = sync.requireProDevice(args.deviceId);
         assertReloadSupported(sync, target);
         const previousRealm = args.wait === false ? null : await ping(sync, target, PROBE_TIMEOUT_MS);
-        const ack = await sync.callAction(
-          APP_TOOL_ID,
-          RELOAD_ACTION,
-          { strategy: args.strategy ?? "auto" },
-          target
-        );
-        const via = ack?.strategy ? ` via ${ack.strategy}` : "";
+        let ack = null;
+        let recovered = false;
+        try {
+          ack = await sync.callAction(
+            APP_TOOL_ID,
+            RELOAD_ACTION,
+            { strategy: args.strategy ?? "auto" },
+            target
+          );
+        } catch (inAppError) {
+          const origin = sync.devServerOrigin(target);
+          if (!origin) throw inAppError;
+          const res = await reloadViaDevServer(origin);
+          if (!res.ok) {
+            throw new Error(
+              `The app is not answering (it looks crashed) and the dev server at ${origin} could not be reached either: ${res.error}. Reload the app by hand.`
+            );
+          }
+          recovered = true;
+        }
+        const via = recovered ? ` via the dev server (the app was unresponsive \u2014 its own reload could not be reached)` : ack?.strategy ? ` via ${ack.strategy}` : "";
         if (args.wait === false) {
           return text16(`Reload requested${via}. The app is restarting \u2014 its in-memory state is gone; re-read anything you cached.`);
         }
@@ -3606,12 +3942,836 @@ function registerReloadTools(server, sync) {
   );
 }
 
+// src/tools/packs/triage.ts
+var import_zod19 = require("zod");
+var text17 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail19 = (message) => ({
+  isError: true,
+  content: [{ type: "text", text: message }]
+});
+var errMsg19 = (e) => e instanceof Error ? e.message : String(e);
+var PROBE_TIMEOUT_MS2 = 5e3;
+var MAX_STORAGE_KEYS = 20;
+var MAX_STORAGE_VALUE = 400;
+var STORAGE_VALUE_BUDGET = 1600;
+var MAX_LINE = 160;
+var cap = (s, n = MAX_LINE) => s.length > n ? `${s.slice(0, n)}\u2026` : s;
+function hhmmss2(ts) {
+  if (!ts) return "--:--:--";
+  const d = new Date(ts);
+  const p = (n) => String(n).padStart(2, "0");
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+async function otherBackends(sync, target, opts) {
+  const notes = [];
+  try {
+    const mmkv = await sync.callAction("storage", "mmkv.snapshot", {}, target, opts);
+    for (const inst of mmkv ?? []) {
+      const n = inst.entries?.length ?? 0;
+      if (n > 0) notes.push(`MMKV "${inst.id}": ${n} key${n === 1 ? "" : "s"}`);
+    }
+  } catch {
+  }
+  try {
+    const secure = await sync.callAction("storage", "secure.keys", {}, target, opts);
+    if (secure?.length) notes.push(`SecureStore: ${secure.length} key${secure.length === 1 ? "" : "s"}`);
+  } catch {
+  }
+  return notes.length ? `
+${notes.join(" \xB7 ")} \u2014 read with get_storage` : "";
+}
+async function section(title, run) {
+  try {
+    const body = await run();
+    return body ? `${title}
+${body}` : null;
+  } catch (e) {
+    const msg = errMsg19(e);
+    if (/not responding|timed out|got no answer/i.test(msg)) {
+      return `${title}
+(no answer \u2014 see the note above)`;
+    }
+    return `${title}
+(unavailable: ${cap(msg, 120)})`;
+  }
+}
+function registerTriageTools(server, sync) {
+  server.registerTool(
+    "get_triage",
+    {
+      description: "START HERE when debugging a running app. One call = the app's current runtime state: connected device, recent console errors (including [FATAL] crashes), recent network requests with statuses, persisted storage values, and what's on screen right now. Use it as the first step for ANY 'why is the app doing X' question \u2014 it is far cheaper than calling get_console + get_network_requests + get_storage + describe_screen separately, and it tells you which of those to drill into next. If the app has crashed it says so and shows the crash. Requires Buoy Pro.",
+      inputSchema: {
+        deviceId: import_zod19.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const device = sync.connectedDevices().find((d) => d.deviceId === target);
+        const toolIds = new Set((device?.tools ?? []).map((t) => t.toolId));
+        const head = `**${device?.deviceName ?? target}** (${device?.platform ?? "?"}, id \`${target}\`) \u2014 tools: ${[...toolIds].join(", ") || "none"}`;
+        const opts = { timeoutMs: PROBE_TIMEOUT_MS2 };
+        const [consoleSec, netSec, storeSec, screenSec] = await Promise.all([
+          section("**Console \u2014 recent errors/warnings:**", async () => {
+            if (!toolIds.has("console")) return null;
+            const { payload } = await sync.getSnapshot("console", target, opts);
+            const p = payload;
+            const entries = Array.isArray(p) ? p : p?.entries ?? [];
+            const bad = entries.filter(
+              (e) => e.level === "error" || e.level === "warning"
+            );
+            const shown = bad.slice(-8);
+            if (shown.length === 0) {
+              return `(none \u2014 ${entries.length} entries captured)`;
+            }
+            return shown.map(
+              (e) => `${hhmmss2(e.timestamp)} [${e.level === "error" ? "ERR" : "warn"}] ${cap(
+                (e.message ?? "").split("\n").map((l) => l.trim()).filter(Boolean).slice(0, 3).join(" \u23CE "),
+                220
+              )}`
+            ).join("\n");
+          }),
+          section("**Network \u2014 recent requests:**", async () => {
+            if (!toolIds.has("network")) return null;
+            const { payload } = await sync.getSnapshot("network", target, opts);
+            const events = Array.isArray(payload) ? payload : payload?.events ?? [];
+            if (events.length === 0) return "(no requests captured yet)";
+            const shown = events.slice(-8);
+            return shown.map((e) => {
+              const mark = e.error || (e.status ?? 0) >= 400 ? "\u274C" : "\u2705";
+              const where = e.path ?? e.url ?? "?";
+              const status = e.error ?? e.status ?? "pending";
+              return `${mark} ${e.method ?? "GET"} ${cap(String(where), 80)} \u2192 ${status}${e.duration ? ` (${Math.round(e.duration)}ms)` : ""}`;
+            }).join("\n");
+          }),
+          section("**Storage \u2014 persisted values:**", async () => {
+            if (!toolIds.has("storage")) return null;
+            const keys = await sync.callAction(
+              "storage",
+              "async.getAllKeys",
+              {},
+              target,
+              opts
+            );
+            if (!Array.isArray(keys) || keys.length === 0) {
+              return "(no app keys)";
+            }
+            const head2 = keys.slice(0, MAX_STORAGE_KEYS);
+            let pairs = [];
+            try {
+              pairs = await sync.callAction(
+                "storage",
+                "async.multiGet",
+                { keys: head2 },
+                target,
+                opts
+              ) ?? [];
+            } catch {
+              return `${head2.map((k) => `\`${k}\``).join(", ")}
+_Values: get_storage includeValues:true_`;
+            }
+            const byKey = new Map(pairs);
+            let budget = STORAGE_VALUE_BUDGET;
+            const lines = head2.map((k) => {
+              const v = byKey.get(k);
+              if (v == null) return `- \`${k}\` = (null)`;
+              if (v.length > MAX_STORAGE_VALUE) {
+                return `- \`${k}\` = (${(v.length / 1024).toFixed(1)} KB \u2014 read with get_storage)`;
+              }
+              if (budget <= 0) return `- \`${k}\` = (not shown \u2014 triage budget spent; read with get_storage)`;
+              budget -= v.length;
+              return `- \`${k}\` = ${v}`;
+            });
+            const more = keys.length - head2.length;
+            const others = await otherBackends(sync, target, opts);
+            return `${lines.join("\n")}${more > 0 ? `
+\u2026+${more} more keys` : ""}${others}`;
+          }),
+          section("**Screen \u2014 what's visible now:**", async () => {
+            if (!toolIds.has("highlight-updates")) return null;
+            const res = await sync.callAction(
+              "highlight-updates",
+              "describeScreen",
+              {},
+              target,
+              opts
+            );
+            const els = (res?.elements ?? []).filter((e) => e.interactive);
+            if (els.length === 0) return "(nothing interactive on screen)";
+            return els.slice(0, 20).map(
+              (e) => `\u2022 ${e.name}${e.text || e.label ? ` "${cap(e.text ?? e.label ?? "", 60)}"` : ""}${e.testID ? ` [testID=${e.testID}]` : ""}`
+            ).join("\n");
+          })
+        ]);
+        const crashed = sync.isUnresponsive(target);
+        const banner = crashed ? `
+
+\u{1F6D1} ${sync.unresponsiveNote(target)}` : "";
+        const body = [consoleSec, netSec, storeSec, screenSec].filter(Boolean).join("\n\n");
+        return text17(
+          `${head}${banner}
+
+${body}
+
+_Drill in with get_console, get_network_requests (includeBodies:true for response bodies), get_storage (includeValues:true), describe_screen._`
+        );
+      } catch (e) {
+        return fail19(errMsg19(e));
+      }
+    }
+  );
+}
+
+// src/tools/packs/flow.ts
+var import_zod20 = require("zod");
+var UI_TOOL_ID = "highlight-updates";
+var APP_TOOL_ID2 = "app";
+var text18 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail20 = (message) => ({
+  isError: true,
+  content: [{ type: "text", text: message }]
+});
+var errMsg20 = (e) => e instanceof Error ? e.message : String(e);
+var delay4 = (ms) => new Promise((r) => setTimeout(r, ms));
+var POLL_MS = 250;
+var DEFAULT_WAIT_MS2 = 5e3;
+var ASSERT_SETTLE_MS = 2e3;
+var TEARDOWN_GRACE_MS2 = 1200;
+var REALM_PROBE_MS = 1500;
+var MAX_FLOW_MS = 12e4;
+function matches(e, needle) {
+  if (e.testID && e.testID === needle) return true;
+  const n = needle.toLowerCase();
+  return [e.testID, e.text, e.label, e.name].filter(Boolean).some((v) => String(v).toLowerCase().includes(n));
+}
+function formatElement2(e) {
+  const display = e.text ?? e.label;
+  return `${e.interactive ? "\u2022 " : "  "}${e.name}${display ? ` "${display}"` : ""}${e.testID ? ` [testID=${e.testID}]` : ""}`;
+}
+var stepSchema = import_zod20.z.object({
+  tap: import_zod20.z.string().optional().describe("Tap this element: exact testID, or fuzzy visible text."),
+  longPress: import_zod20.z.boolean().optional().describe("Make `tap` a long-press instead."),
+  type: import_zod20.z.string().optional().describe("Text to type (needs `into`)."),
+  into: import_zod20.z.string().optional().describe("Target text input for `type`: testID or fuzzy text."),
+  set: import_zod20.z.union([import_zod20.z.number(), import_zod20.z.boolean()]).optional().describe("Set a toggle (true/false) or slider (number) \u2014 pair with `tap` as the target."),
+  reload: import_zod20.z.boolean().optional().describe("Reload the JS bundle before this step's action."),
+  waitMs: import_zod20.z.number().min(0).max(3e4).optional().describe("Fixed pause after the action, in ms (max 30000)."),
+  waitFor: import_zod20.z.string().optional().describe("Wait until an element matching this appears (default 5s)."),
+  waitGone: import_zod20.z.string().optional().describe("Wait until no element matches this (default 5s)."),
+  expect: import_zod20.z.string().optional().describe("Assert an element matching this IS on screen (waits up to 2s for it); fails the flow if not."),
+  expectGone: import_zod20.z.string().optional().describe("Assert nothing matches this (waits up to 2s for it to go); fails the flow if something does."),
+  timeoutMs: import_zod20.z.number().min(0).max(6e4).optional().describe("Budget for this step's waitFor/waitGone/expect, max 60000. Default 5000 (2000 for expect).")
+}).describe("One flow step. Order within a step: reload \u2192 tap/type/set \u2192 waitMs \u2192 waitFor/waitGone \u2192 expect.");
+function registerFlowTools(server, sync) {
+  server.registerTool(
+    "run_flow",
+    {
+      description: "Run a scripted sequence of UI interactions in ONE call and report what happened: per-step results, the final screen, plus the network requests and console errors the flow produced. Use this instead of alternating describe_screen/tap_element \u2014 reproducing a bug ('open cart, checkout, submit') or verifying a fix after an edit is one call, not a dozen. Steps run in order and stop at the first failure, returning the screen at that point so you can see WHERE it broke. Each step can tap, type, set a toggle/slider, reload, wait for an element, and assert. Requires Buoy Pro.",
+      inputSchema: {
+        steps: import_zod20.z.array(stepSchema).min(1).describe("Steps to run, in order."),
+        include: import_zod20.z.enum(["all", "screen", "none"]).optional().describe("What to report after the flow: 'all' (default) = final screen + network/console produced by the flow; 'screen' = final screen only; 'none' = step results only."),
+        continueOnFailure: import_zod20.z.boolean().optional().describe("Keep going after a failed step instead of stopping. Default false."),
+        deviceId: import_zod20.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      const started = Date.now();
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const include = args.include ?? "all";
+        const describe = async () => {
+          const res = await sync.callAction(UI_TOOL_ID, "describeScreen", {}, target);
+          return res?.elements ?? [];
+        };
+        const realmId = async () => {
+          try {
+            const pong = await sync.callAction(APP_TOOL_ID2, "ping", {}, target, {
+              timeoutMs: REALM_PROBE_MS,
+              silent: true
+              // probes across a reload are expected to fail
+            });
+            return typeof pong?.startedAt === "number" ? pong.startedAt : null;
+          } catch {
+            return null;
+          }
+        };
+        const untilNewRealm = async (previous, budgetMs) => {
+          const t0 = Date.now();
+          while (Date.now() - t0 < budgetMs) {
+            const realm = await realmId();
+            if (realm !== null && realm !== previous) return Date.now() - t0;
+            await delay4(POLL_MS);
+          }
+          return null;
+        };
+        const beforeConsole = /* @__PURE__ */ new Set();
+        const beforeNetwork = /* @__PURE__ */ new Set();
+        const toolIds = new Set(
+          (sync.connectedDevices().find((d) => d.deviceId === target)?.tools ?? []).map((t) => t.toolId)
+        );
+        if (include === "all") {
+          if (toolIds.has("console")) {
+            const { payload } = await sync.getSnapshot("console", target).catch(() => ({ payload: null }));
+            const entries = payload?.entries ?? [];
+            for (const e of entries) beforeConsole.add(e.id);
+          }
+          if (toolIds.has("network")) {
+            const { payload } = await sync.getSnapshot("network", target).catch(() => ({ payload: null }));
+            const events = Array.isArray(payload) ? payload : payload?.events ?? [];
+            for (const e of events) beforeNetwork.add(e.id);
+          }
+        }
+        const until = async (predicate, budgetMs) => {
+          const t0 = Date.now();
+          for (; ; ) {
+            if (Date.now() - t0 >= budgetMs || Date.now() - started > MAX_FLOW_MS) {
+              return { ok: false, ms: Date.now() - t0 };
+            }
+            let els = [];
+            try {
+              els = await describe();
+            } catch {
+            }
+            if (predicate(els)) return { ok: true, ms: Date.now() - t0 };
+            await delay4(POLL_MS);
+          }
+        };
+        const lines = [];
+        let failedAt = null;
+        let okCount = 0;
+        for (let i = 0; i < args.steps.length; i++) {
+          const step = args.steps[i];
+          const label = `${i + 1}`;
+          const budget = step.timeoutMs ?? DEFAULT_WAIT_MS2;
+          if (Date.now() - started > MAX_FLOW_MS) {
+            lines.push(`${label} \u2717 flow exceeded ${MAX_FLOW_MS / 1e3}s \u2014 stopped here`);
+            failedAt = i;
+            break;
+          }
+          const stepErrors = [];
+          const done = [];
+          const actionable = step.reload || step.tap || step.type !== void 0 || step.waitMs || step.waitFor || step.waitGone || step.expect || step.expectGone;
+          if (!actionable) {
+            lines.push(`${i + 1} \u2717 step does nothing \u2014 give it a tap/type/wait/expect${step.set !== void 0 ? " (`set` needs `tap` naming the control)" : ""}`);
+            failedAt = failedAt ?? i;
+            if (!args.continueOnFailure) break;
+            continue;
+          }
+          try {
+            if (step.reload) {
+              const previousRealm = await realmId();
+              await sync.callAction(APP_TOOL_ID2, "reloadApp", { strategy: "auto" }, target);
+              await delay4(TEARDOWN_GRACE_MS2);
+              const back = await untilNewRealm(previousRealm, Math.max(budget, 2e4));
+              if (back == null) {
+                stepErrors.push("app did not come back after reload");
+              } else {
+                done.push(`reloaded (${back}ms)`);
+                await until((els) => els.length > 0, 1e4);
+              }
+            }
+            if (step.type !== void 0) {
+              const targetSel = step.into ?? step.tap;
+              if (!targetSel) {
+                stepErrors.push("`type` needs `into` (which input to type into)");
+              } else {
+                const res = await sync.callAction(
+                  UI_TOOL_ID,
+                  "tapElement",
+                  { ...selector(targetSel), text: step.type },
+                  target
+                );
+                if (!res?.tapped) {
+                  stepErrors.push(res?.reason ?? `could not type into "${targetSel}"`);
+                } else if (res.matched?.via && res.matched.via !== "onChangeText") {
+                  stepErrors.push(
+                    `"${targetSel}" is not a text input \u2014 it ran ${res.matched.via} instead, and the text was not entered`
+                  );
+                } else {
+                  done.push(`typed ${JSON.stringify(step.type)} into "${targetSel}"`);
+                }
+              }
+            } else if (step.tap) {
+              const params = { ...selector(step.tap) };
+              if (step.longPress) params.longPress = true;
+              if (step.set !== void 0) params.value = step.set;
+              const res = await sync.callAction(UI_TOOL_ID, "tapElement", params, target);
+              if (!res?.tapped) {
+                stepErrors.push(res?.reason ?? `no element matched "${step.tap}"`);
+              } else {
+                const m = res.matched;
+                const what = m?.text ?? m?.label ?? m?.name ?? step.tap;
+                if (step.set !== void 0 && m?.via && m.via !== "onValueChange") {
+                  stepErrors.push(
+                    `"${what}" is not a toggle/slider \u2014 it ran ${m.via} instead, so it was not set to ${JSON.stringify(step.set)}`
+                  );
+                } else {
+                  done.push(
+                    step.set !== void 0 ? `set "${what}" \u2192 ${JSON.stringify(m?.value ?? step.set)}` : `${step.longPress ? "long-pressed" : "tapped"} "${what}"`
+                  );
+                }
+              }
+            }
+            if (!stepErrors.length && step.waitMs) {
+              await delay4(step.waitMs);
+              done.push(`waited ${step.waitMs}ms`);
+            }
+            if (!stepErrors.length && step.waitFor) {
+              const r = await until((els) => els.some((e) => matches(e, step.waitFor)), budget);
+              if (r.ok) done.push(`"${step.waitFor}" appeared (${r.ms}ms)`);
+              else stepErrors.push(`"${step.waitFor}" never appeared within ${budget}ms`);
+            }
+            if (!stepErrors.length && step.waitGone) {
+              const r = await until((els) => !els.some((e) => matches(e, step.waitGone)), budget);
+              if (r.ok) done.push(`"${step.waitGone}" gone (${r.ms}ms)`);
+              else stepErrors.push(`"${step.waitGone}" was still there after ${budget}ms`);
+            }
+            if (!stepErrors.length && step.expect) {
+              const r = await until(
+                (els) => els.some((e) => matches(e, step.expect)),
+                step.timeoutMs ?? ASSERT_SETTLE_MS
+              );
+              if (r.ok) done.push(`"${step.expect}" is on screen`);
+              else stepErrors.push(`expected "${step.expect}" on screen \u2014 not found`);
+            }
+            if (!stepErrors.length && step.expectGone) {
+              const r = await until(
+                (els) => !els.some((e) => matches(e, step.expectGone)),
+                step.timeoutMs ?? ASSERT_SETTLE_MS
+              );
+              if (r.ok) done.push(`"${step.expectGone}" is gone`);
+              else stepErrors.push(`expected "${step.expectGone}" to be gone \u2014 still on screen`);
+            }
+          } catch (e) {
+            stepErrors.push(errMsg20(e));
+          }
+          if (stepErrors.length) {
+            lines.push(`${label} \u2717 ${describeStep(step)} \u2014 ${stepErrors.join("; ")}`);
+            failedAt = failedAt ?? i;
+            if (!args.continueOnFailure) break;
+          } else {
+            okCount++;
+            lines.push(`${label} \u2713 ${done.join(", ") || describeStep(step)}`);
+          }
+        }
+        const elapsed = ((Date.now() - started) / 1e3).toFixed(1);
+        const header = failedAt === null ? `**Flow: ${okCount}/${args.steps.length} steps OK (${elapsed}s)**` : `**Flow FAILED at step ${failedAt + 1} \u2014 ${okCount}/${args.steps.length} steps OK (${elapsed}s)**`;
+        const parts = [header, lines.join("\n")];
+        if (include !== "none") {
+          try {
+            const els = await describe();
+            const shown = els.filter((e) => e.interactive).slice(0, 30);
+            parts.push(
+              `**Screen now (${shown.length} interactive of ${els.length}):**
+${shown.map(formatElement2).join("\n")}`
+            );
+          } catch (e) {
+            parts.push(`**Screen now:** unavailable \u2014 ${cap2(errMsg20(e))}`);
+          }
+        }
+        if (include === "all") {
+          if (toolIds.has("network")) {
+            const { payload } = await sync.getSnapshot("network", target).catch(() => ({ payload: null }));
+            const events = Array.isArray(payload) ? payload : payload?.events ?? [];
+            const fresh = events.filter((e) => !beforeNetwork.has(e.id)).slice(-15);
+            if (fresh.length) {
+              parts.push(
+                `**Network during this flow (${fresh.length}):**
+` + fresh.map(
+                  (e) => `${e.error || (e.status ?? 0) >= 400 ? "\u274C" : "\u2705"} ${e.method ?? "GET"} ${e.path ?? e.url ?? "?"} \u2192 ${e.error ?? e.status ?? "pending"}`
+                ).join("\n")
+              );
+            }
+          }
+          if (toolIds.has("console")) {
+            const { payload } = await sync.getSnapshot("console", target).catch(() => ({ payload: null }));
+            const entries = payload?.entries ?? [];
+            const fresh = entries.filter((e) => !beforeConsole.has(e.id) && (e.level === "error" || e.level === "warning")).slice(-10);
+            if (fresh.length) {
+              parts.push(
+                `**Console during this flow (${fresh.length}):**
+` + fresh.map((e) => `[${e.level === "error" ? "ERR" : "warn"}] ${cap2(firstLines(e.message ?? ""), 220)}`).join("\n")
+              );
+            }
+          }
+        }
+        return text18(parts.join("\n\n"));
+      } catch (e) {
+        return fail20(errMsg20(e));
+      }
+    }
+  );
+}
+function selector(needle) {
+  return /\s/.test(needle) ? { query: needle } : { testID: needle, query: needle };
+}
+function describeStep(step) {
+  if (step.tap) return `tap "${step.tap}"`;
+  if (step.type !== void 0) return `type into "${step.into ?? "?"}"`;
+  if (step.reload) return "reload";
+  if (step.waitFor) return `waitFor "${step.waitFor}"`;
+  if (step.waitGone) return `waitGone "${step.waitGone}"`;
+  if (step.expect) return `expect "${step.expect}"`;
+  return "step";
+}
+var cap2 = (s, n = 160) => s.length > n ? `${s.slice(0, n)}\u2026` : s;
+var firstLines = (s, n = 3) => s.split("\n").map((l) => l.trim()).filter(Boolean).slice(0, n).join(" \u23CE ");
+
+// src/tools/packs/renders.ts
+var import_zod21 = require("zod");
+var UI_TOOL_ID2 = "highlight-updates";
+var text19 = (s) => ({ content: [{ type: "text", text: s }] });
+var fail21 = (message) => ({
+  isError: true,
+  content: [{ type: "text", text: message }]
+});
+var errMsg21 = (e) => e instanceof Error ? e.message : String(e);
+var delay5 = (ms) => new Promise((r) => setTimeout(r, ms));
+var DEFAULT_IDLE_MS = 3e3;
+var SETTLE_MS = 400;
+var DEFAULT_TOP = 12;
+var lastCapture = /* @__PURE__ */ new Map();
+var stepSchema2 = import_zod21.z.object({
+  tap: import_zod21.z.string().optional().describe("Tap this element: exact testID, or fuzzy visible text."),
+  type: import_zod21.z.string().optional().describe("Text to type (needs `into`)."),
+  into: import_zod21.z.string().optional().describe("Target text input for `type`: testID or fuzzy text."),
+  waitMs: import_zod21.z.number().min(0).max(1e4).optional().describe("Pause after the action, in ms."),
+  repeat: import_zod21.z.number().min(1).max(20).optional().describe("Do this step N times (default 1). Useful for 'tap it five times'.")
+}).describe("One interaction to measure. Keep it to the thing you're asking about.");
+function selector2(needle) {
+  return /\s/.test(needle) ? { query: needle } : { testID: needle, query: needle };
+}
+function dominant(causes) {
+  if (!causes) return "unknown";
+  let best = "unknown";
+  let n = -1;
+  for (const [k, v] of Object.entries(causes)) {
+    if ((v ?? 0) > n) {
+      n = v ?? 0;
+      best = k;
+    }
+  }
+  return best;
+}
+var CAUSE_HINT = {
+  propsUnstable: "props changed by IDENTITY only (a fresh function/object from the parent) \u2014 fix upstream, not in the child",
+  parent: "parent re-rendered and nothing of its own changed \u2014 a pure cascade",
+  props: "props genuinely changed value",
+  hooks: "its own state/hooks changed",
+  mount: "first render"
+};
+function formatCapture(c, top) {
+  const s = c.summary;
+  const wasted = s.wastedRenders ?? 0;
+  const pct = s.totalRenders > 0 ? Math.round(wasted / s.totalRenders * 100) : 0;
+  const lines = [];
+  const ms = s.totalRenderMs ?? 0;
+  lines.push(
+    `**${s.totalRenders} component renders across ${s.totalCommits} commits in ${(c.windowMs / 1e3).toFixed(1)}s**` + (ms > 0 ? ` \xB7 ${ms.toFixed(1)}ms of render work` : "") + ` \xB7 ${wasted} wasted (${pct}%)`
+  );
+  const causeLine = Object.entries(s.causes ?? {}).filter(([, v]) => (v ?? 0) > 0).sort((a, b) => (b[1] ?? 0) - (a[1] ?? 0)).map(([k, v]) => `${k} ${v}`).join(" \xB7 ");
+  if (causeLine) lines.push(`causes: ${causeLine}`);
+  lines.push("");
+  lines.push("| component | self ms | renders | cause | dragged along by | changed props |");
+  lines.push("|---|---:|---:|---|---|---|");
+  const rows = [...s.topComponents].sort((a, b) => (b.totalMs ?? 0) - (a.totalMs ?? 0) || b.renders - a.renders).slice(0, top);
+  for (const r of rows) {
+    lines.push(
+      `| ${r.name} | ${(r.totalMs ?? 0).toFixed(1)} | ${r.renders} | ${dominant(r.causes)} | ${r.parentName ?? "\u2014"} | ${(r.changedProps ?? []).join(", ") || "\u2014"} |`
+    );
+  }
+  if (s.topComponents.length > top) {
+    lines.push(`_\u2026+${s.topComponents.length - top} more components_`);
+  }
+  const seen = new Set(rows.map((r) => dominant(r.causes)));
+  const hints = [...seen].filter((k) => CAUSE_HINT[k]).map((k) => `\`${k}\` = ${CAUSE_HINT[k]}`);
+  if (hints.length) {
+    lines.push("");
+    lines.push(hints.join("  \xB7  "));
+  }
+  lines.push("");
+  lines.push(
+    "`wasted` = renders that produced nothing new (parent cascades + identity-only prop changes) \u2014 the removable part. Sorted by **self ms**: fix what costs time, not what renders often. Cheap components re-rendering is usually fine, and blanket `memo()` trades real code clarity for a number that was never the problem."
+  );
+  return lines.join("\n");
+}
+function formatDelta(before, after) {
+  const d = (a, b) => {
+    const diff = b - a;
+    return `${a} \u2192 ${b} (${diff > 0 ? "+" : ""}${diff})`;
+  };
+  const bs = before.summary;
+  const as_ = after.summary;
+  const lines = [`**vs "${before.label}"**`];
+  lines.push(`- total renders: ${d(bs.totalRenders, as_.totalRenders)}`);
+  lines.push(`- wasted: ${d(bs.wastedRenders ?? 0, as_.wastedRenders ?? 0)}`);
+  const beforeByName = new Map(bs.topComponents.map((r) => [r.name, r.renders]));
+  const moved = [];
+  for (const r of as_.topComponents.slice(0, 20)) {
+    const was = beforeByName.get(r.name) ?? 0;
+    if (was !== r.renders) moved.push(`${r.name} ${d(was, r.renders)}`);
+    beforeByName.delete(r.name);
+  }
+  for (const [name, was] of beforeByName) {
+    if (was > 0) moved.push(`${name} ${d(was, 0)}`);
+  }
+  if (moved.length) lines.push(`- per component: ${moved.slice(0, 10).join(" \xB7 ")}`);
+  const fewer = as_.totalRenders < bs.totalRenders;
+  const more = as_.totalRenders > bs.totalRenders;
+  lines.push(
+    more ? "\n\u26A0\uFE0F MORE renders than before \u2014 this change made this interaction worse. Re-render fixes routinely move cost instead of removing it; check the other interactions too before moving on." : fewer ? "\n\u2705 Fewer renders than before on this interaction. Measure the OTHER interactions too \u2014 a fix that helps typing can cost taps." : "\n\u2796 No change on this interaction."
+  );
+  return lines.join("\n");
+}
+function registerRenderTools(server, sync) {
+  server.registerTool(
+    "measure_renders",
+    {
+      description: "Find out WHAT re-rendered on the current screen and WHY, in one call \u2014 no test route, no scaffolding. THE tool for 'this page is slow/laggy/janky', 'typing lags', 'the whole page re-renders when I tap one button'. Give it `steps` to measure a specific interaction (tap a button, type in a field) \u2014 measuring an idle window instead tells you nothing about what taps cost, which is how re-render fixes usually go wrong. Returns per-component render COST in ms (sorted by it \u2014 a component rendering 40x for 0.4ms is noise, one rendering 4x for 38ms is the answer), the CAUSE of each (parent cascade / own state / changed props), which parent dragged it along, and which props changed. `wasted` counts renders that produced nothing new \u2014 that's the removable part. AFTER YOU EDIT, call it again with the same steps and compareToPrevious:true to prove the fix landed and didn't move the cost somewhere else. (For choosing between several implementations of a screen, use run_benchmark_batch instead \u2014 that ranks variants; this explains one screen.) Requires Buoy Pro and @buoy-gg/highlight-updates.",
+      inputSchema: {
+        steps: import_zod21.z.array(stepSchema2).max(20).optional().describe(
+          "The interaction to measure, e.g. [{tap:'favorite-deal-2', repeat:5}] or [{type:'bench', into:'deals-search'}]. Omit to sample the screen idle \u2014 only useful for churn that happens with nobody touching it."
+        ),
+        idleMs: import_zod21.z.number().min(500).max(2e4).optional().describe(`Idle sample length when no steps are given. Default ${DEFAULT_IDLE_MS}.`),
+        label: import_zod21.z.string().optional().describe('Name this measurement, e.g. "before fix". Shown in the next comparison.'),
+        compareToPrevious: import_zod21.z.boolean().optional().describe("Diff against the previous measure_renders on this device. Use after an edit to prove the fix."),
+        top: import_zod21.z.number().min(1).max(40).optional().describe(`Components to list. Default ${DEFAULT_TOP}.`),
+        deviceId: import_zod21.z.string().optional().describe("Target device id (auto-selected if one is connected).")
+      }
+    },
+    async (args) => {
+      try {
+        const target = sync.requireProDevice(args.deviceId);
+        const device = sync.connectedDevices().find((d) => d.deviceId === target);
+        const uiTool = (device?.tools ?? []).find((t) => t.toolId === UI_TOOL_ID2);
+        if (!uiTool) {
+          return fail21(
+            "This app doesn't expose the highlight-updates tool, so renders can't be measured. Install @buoy-gg/highlight-updates."
+          );
+        }
+        if (!(uiTool.actions ?? []).includes("beginMeasurement")) {
+          return fail21(
+            "This app's @buoy-gg/highlight-updates is too old to measure renders (needs the version with beginMeasurement). Upgrade it, then try again. Meanwhile run_benchmark_batch with captureRenders can still give counts if you have a test route."
+          );
+        }
+        const began = await sync.callAction(UI_TOOL_ID2, "beginMeasurement", {}, target);
+        if (began && began.ok === false) {
+          return fail21(`Can't measure renders: ${began.reason ?? "capture unavailable"}`);
+        }
+        await delay5(SETTLE_MS);
+        const startedAt = Date.now();
+        const notes = [];
+        if (args.steps?.length) {
+          for (const step of args.steps) {
+            const times = step.repeat ?? 1;
+            for (let i = 0; i < times; i++) {
+              if (step.type !== void 0) {
+                const sel = step.into ?? step.tap;
+                if (!sel) {
+                  notes.push("a `type` step needs `into`");
+                  continue;
+                }
+                const res = await sync.callAction(
+                  UI_TOOL_ID2,
+                  "tapElement",
+                  { ...selector2(sel), text: step.type },
+                  target
+                );
+                if (!res?.tapped) notes.push(res?.reason ?? `could not type into "${sel}"`);
+                else if (res.matched?.via && res.matched.via !== "onChangeText") {
+                  notes.push(`"${sel}" is not a text input \u2014 it ran ${res.matched.via}, nothing was typed`);
+                }
+              } else if (step.tap) {
+                const res = await sync.callAction(
+                  UI_TOOL_ID2,
+                  "tapElement",
+                  selector2(step.tap),
+                  target
+                );
+                if (!res?.tapped) notes.push(res?.reason ?? `no element matched "${step.tap}"`);
+              }
+              if (step.waitMs) await delay5(step.waitMs);
+            }
+          }
+          await delay5(SETTLE_MS);
+        } else {
+          await delay5(args.idleMs ?? DEFAULT_IDLE_MS);
+        }
+        const windowMs = Date.now() - startedAt;
+        const ended = await sync.callAction(UI_TOOL_ID2, "endMeasurement", {}, target);
+        const summary = ended?.summary;
+        if (!summary) {
+          return fail21(
+            "The capture window closed without returning anything. If the app reloaded mid-measurement, try again."
+          );
+        }
+        const capture = {
+          label: args.label ?? (args.steps?.length ? "interaction" : "idle"),
+          windowMs,
+          summary
+        };
+        const prev = lastCapture.get(target);
+        lastCapture.set(target, capture);
+        const what = args.steps?.length ? args.steps.map((s) => (s.type !== void 0 ? `type "${s.type}"` : `tap "${s.tap}"`) + (s.repeat ? ` \xD7${s.repeat}` : "")).join(", ") : `idle ${(windowMs / 1e3).toFixed(1)}s`;
+        const parts = [`**measure_renders \u2014 ${what}**`, "", formatCapture(capture, args.top ?? DEFAULT_TOP)];
+        if (args.compareToPrevious) {
+          parts.push("", prev ? formatDelta(prev, capture) : "_No previous measurement on this device to compare against._");
+        }
+        if (notes.length) parts.push("", `\u26A0\uFE0F ${notes.join("; ")}`);
+        if (summary.totalRenders === 0) {
+          parts.push(
+            "",
+            "_Nothing re-rendered in this window. If you expected renders, check the app is on the screen you meant and that the steps actually hit something._"
+          );
+        } else if (!args.compareToPrevious) {
+          parts.push("", "_Fixed something? Call this again with the same steps and `compareToPrevious:true` to prove it landed._");
+        }
+        return text19(parts.join("\n"));
+      } catch (e) {
+        return fail21(errMsg21(e));
+      }
+    }
+  );
+}
+
+// src/verify/editWatcher.ts
+var import_node_fs3 = __toESM(require("fs"));
+var import_node_path3 = __toESM(require("path"));
+var WATCHED_EXT = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".json"
+]);
+var IGNORED_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  ".expo",
+  "ios",
+  "android",
+  "dist",
+  "lib",
+  "build",
+  ".next",
+  "coverage",
+  "__snapshots__"
+]);
+var DEBOUNCE_MS = 400;
+function resolveMode(raw) {
+  const v = (raw ?? "").trim().toLowerCase();
+  if (v === "always" || v === "never" || v === "auto") return v;
+  return "auto";
+}
+var EditWatcher = class {
+  constructor() {
+    this.watcher = null;
+    this.changed = /* @__PURE__ */ new Set();
+    this.lastEditAt = 0;
+    this.nudgedForCurrentBatch = false;
+    this.mode = "auto";
+    this.started = false;
+  }
+  start(rootDir, mode) {
+    this.mode = mode;
+    if (mode === "never" || this.started) return;
+    this.started = true;
+    try {
+      this.watcher = import_node_fs3.default.watch(
+        rootDir,
+        { recursive: true },
+        (_event, filename) => {
+          if (!filename) return;
+          const rel2 = String(filename);
+          if (rel2.split(import_node_path3.default.sep).some((seg) => IGNORED_DIRS.has(seg))) return;
+          if (!WATCHED_EXT.has(import_node_path3.default.extname(rel2))) return;
+          this.noteEdit(rel2);
+        }
+      );
+      this.watcher.on("error", () => this.stop());
+    } catch {
+      this.stop();
+    }
+  }
+  /** Record an edit. Public so the nudge policy can be tested without fs.watch. */
+  noteEdit(rel2) {
+    const now = Date.now();
+    if (now - this.lastEditAt > DEBOUNCE_MS) this.nudgedForCurrentBatch = false;
+    this.lastEditAt = now;
+    if (this.changed.size < 50) this.changed.add(rel2);
+  }
+  stop() {
+    try {
+      this.watcher?.close();
+    } catch {
+    }
+    this.watcher = null;
+  }
+  /** Something on the device was actually checked — the edits are accounted for. */
+  markVerified() {
+    this.changed.clear();
+    this.nudgedForCurrentBatch = false;
+  }
+  hasUnverifiedEdits() {
+    return this.changed.size > 0;
+  }
+  /**
+   * The line to append to a tool result, or null to stay quiet.
+   *
+   * `auto` says it once per burst of edits, so it lands when the agent is
+   * mid-loop and then gets out of the way. `always` repeats while anything is
+   * unverified, for people who want the belt and braces.
+   */
+  nudge() {
+    if (this.mode === "never" || !this.hasUnverifiedEdits()) return null;
+    if (this.mode === "auto") {
+      if (this.nudgedForCurrentBatch) return null;
+      this.nudgedForCurrentBatch = true;
+    }
+    const files = [...this.changed];
+    const shown = files.slice(0, 3).join(", ");
+    const more = files.length > 3 ? ` +${files.length - 3} more` : "";
+    return `
+
+---
+\u26A0\uFE0F **${files.length} source file${files.length === 1 ? "" : "s"} changed since anything was last checked on the device** (${shown}${more}).
+Before reporting this as fixed, observe it working: re-run the same interaction with \`measure_renders\` (\`compareToPrevious: true\`) or \`run_flow\`, and say what the numbers did. A fix nobody watched work is a guess \u2014 and re-render fixes in particular tend to move cost somewhere else rather than remove it.`;
+  }
+};
+var editWatcher = new EditWatcher();
+
 // src/server.ts
 var SERVER_INSTRUCTIONS = `Buoy MCP \u2014 drive Buoy dev tools running in a React Native app from your editor.
 
 Buoy tools live inside the app and sync to a local broker; this server connects to that
-broker as a dashboard client. Start by calling \`list_devices\` to see which device(s) are
-connected and which tools (e.g. "perf-monitor", "network", "react-query") they expose.
+broker as a dashboard client.
+
+DEBUGGING A RUNNING APP? Call \`get_triage\` FIRST \u2014 one call returns the connected device,
+recent console errors (including [FATAL] crashes), recent network requests with statuses,
+persisted storage keys, and what's on screen. It replaces the usual five-call opening
+sequence and tells you which tool to drill into. Read runtime facts before hypothesizing
+from source: the app's actual state beats a guess about what the code should do.
+
+Routing after triage \u2014 match the SYMPTOM to the tool:
+- Value wrong/stale/NaN, or broken only after an upgrade \u2192 \`get_storage includeValues:true\`
+  (a bad persisted value is a top root cause, and it survives reinstalls of the JS).
+- Failed request, wrong data from the API, auth/session bug \u2192 \`get_network_requests
+  includeBodies:true\` and read the response BODY.
+- Crash or redbox \u2192 \`get_console\` (fatals are captured, and still readable after the app
+  dies), then \`get_storage\` for the state that triggered it.
+- Data on screen doesn't match the API \u2192 \`get_react_query\` / \`get_zustand_state\` /
+  \`get_redux_state\` / \`get_jotai_state\` for the cache or store between them.
+
+AFTER YOU EDIT, PROVE IT on the device \u2014 the most common way a fix fails is being incomplete,
+not being wrong. Reload (\`run_flow\` step \`{reload:true}\`, or \`reload_app\`) and re-drive EVERY
+screen the symptom could appear on, asserting the corrected value: a price shown in three places
+has to be right in all three, and a migration only counts if it survives a restart. A fix you
+haven't watched work is a guess.
+
+Use \`list_devices\` when you need the full tool/action inventory or several devices are
+connected (\`get_triage\` already names the active one).
 
 To inspect what's HAPPENING at runtime \u2014 network requests, state changes (redux/zustand/jotai),
 react-query updates, storage writes, route changes, renders \u2014 use \`get_events\` with a \`sources\`
@@ -3630,15 +4790,28 @@ Need to SEE a component (verify a UI change, check styling/layout)? Use \`screen
 a testID/name \u2014 it locates the live component on-device and returns a cropped screenshot inline.
 iOS Simulator only, and only works when this MCP server runs on the same Mac as the booted Simulator.
 
-Need to DRIVE the UI (tap a button, follow a flow)? Use \`describe_screen\` to list the on-screen
-elements (accessibility-style tree with tap points + testIDs, no screenshot), then \`tap_element\`
-({ testID | query | nativeTag }) to tap one \u2014 it invokes the element's onPress directly in JS, so
-it's fast and works on physical devices too. Re-run \`describe_screen\` after the screen changes.
+Need to DRIVE the UI? Reach for \`run_flow\` FIRST: it runs a whole scripted sequence
+(tap / type / set / reload / waitFor / expect) in ONE call and reports the per-step result, the
+final screen, and the network + console output the flow produced. Reproducing a bug and verifying
+a fix are one call each instead of a dozen alternating reads and taps, and a failed step reports
+the screen at the point it broke. Drop to \`describe_screen\` (list on-screen elements with testIDs
+and tap points) + \`tap_element\` only for one-off pokes or when you don't yet know what's there.
+
+Screen slow / laggy / janky / stutters, typing lags, or "the whole page re-renders when I tap
+one thing"? Start with \`measure_renders\` \u2014 one call, no test route needed. Pass \`steps\` for the
+interaction you're actually asking about (a tap, some typing); an idle sample says nothing about
+what a tap costs. It returns per-component render counts, WHY each rendered (parent cascade / own
+state / changed props), which parent dragged it along, and \`wasted\` \u2014 the renders that produced
+nothing new. After you edit, call it again with the same steps and \`compareToPrevious:true\`:
+re-render fixes routinely move the cost somewhere else instead of removing it, and only a second
+measurement catches that.
 
 JS FPS low / app hitching and you need to know WHAT is eating the JS thread? Use
 \`get_js_thread_top\` (a live "Task Manager" of timers, Promise chains, rAF callbacks and
 freezes, ranked by thread time), then \`get_js_thread_origin_detail\` to drill into a row.
 Pass clearFirst:true and drive the UI with \`tap_element\` mid-sample to profile one interaction.
+This is about TASKS on the thread \u2014 for React components re-rendering too often, it's
+\`measure_renders\`, not this.
 
 Debugging images (not loading, slow, stale cache, memory)? \`get_images\` lists every RN <Image> /
 expo-image load with cache verdicts and oversize audits; \`image_action\` reloads, retries, or
@@ -3674,11 +4847,46 @@ If no device is connected, open the app with Buoy devtools running and try again
 The Buoy MCP is a Pro feature: \`list_devices\` is always available, but data/action tools
 require the connected app to have an active Buoy Pro license. If they error with "Buoy Pro
 required", tell the user to upgrade to Buoy Pro in the app \u2014 don't try to work around it.`;
+var VERIFYING_TOOLS = /* @__PURE__ */ new Set([
+  "measure_renders",
+  "run_flow",
+  "run_benchmark_batch",
+  "get_triage",
+  "tap_element",
+  "describe_screen",
+  "get_console",
+  "get_network_requests",
+  "get_events",
+  "get_snapshot"
+]);
 function createMcpServer(sync) {
   const server = new import_mcp.McpServer(
     { name: "buoy", version: VERSION },
     { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
   );
+  editWatcher.start(process.cwd(), resolveMode(process.env.BUOY_VERIFY));
+  const originalRegister = server.registerTool.bind(server);
+  server.registerTool = ((name, config, handler) => originalRegister(name, config, (async (...args) => {
+    const result = await handler(...args);
+    const errored = result?.isError === true;
+    if (VERIFYING_TOOLS.has(name) && !errored) {
+      editWatcher.markVerified();
+      return result;
+    }
+    const note = editWatcher.nudge();
+    if (!note) return result;
+    const r = result;
+    if (Array.isArray(r?.content)) {
+      return {
+        ...r,
+        content: [...r.content, { type: "text", text: note }]
+      };
+    }
+    return result;
+  })));
+  registerTriageTools(server, sync);
+  registerFlowTools(server, sync);
+  registerRenderTools(server, sync);
   registerGenericTools(server, sync);
   registerPerfMonitorTools(server, sync);
   registerEventsTools(server, sync);
@@ -3700,32 +4908,37 @@ function createMcpServer(sync) {
   return server;
 }
 var deviceIdField = {
-  deviceId: import_zod19.z.string().optional().describe(
+  deviceId: import_zod22.z.string().optional().describe(
     'Target device id (from list_devices). Omit to auto-select when exactly one device is connected. Use "All" to broadcast.'
   )
 };
 
 // src/init.ts
 var import_node_child_process2 = require("child_process");
-var import_node_fs3 = __toESM(require("fs"));
+var import_node_fs4 = __toESM(require("fs"));
 var import_node_os3 = __toESM(require("os"));
-var import_node_path3 = __toESM(require("path"));
+var import_node_path4 = __toESM(require("path"));
+function defaultEnv() {
+  return { BUOY_VERIFY: "auto" };
+}
 var PUBLIC_REGISTRY = "https://registry.npmjs.org";
-var PROBE_TIMEOUT_MS2 = 3e3;
+var PROBE_TIMEOUT_MS3 = 3e3;
 function runInit(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
-  const skillSrcDir = opts.skillSrcDir ?? import_node_path3.default.resolve(__dirname, "../skill");
+  const skillSrcDir = opts.skillSrcDir ?? import_node_path4.default.resolve(__dirname, "../skill");
   const log = opts.log ?? ((m) => process.stdout.write(m + "\n"));
   const entry = resolveEntry(opts, log);
   const done = [];
-  upsertMcpConfig(import_node_path3.default.join(cwd, ".mcp.json"), "mcpServers", entry, cwd, done);
-  if (import_node_fs3.default.existsSync(import_node_path3.default.join(cwd, ".cursor"))) {
-    upsertMcpConfig(import_node_path3.default.join(cwd, ".cursor", "mcp.json"), "mcpServers", entry, cwd, done);
+  upsertMcpConfig(import_node_path4.default.join(cwd, ".mcp.json"), "mcpServers", entry, cwd, done);
+  if (import_node_fs4.default.existsSync(import_node_path4.default.join(cwd, ".cursor"))) {
+    upsertMcpConfig(import_node_path4.default.join(cwd, ".cursor", "mcp.json"), "mcpServers", entry, cwd, done);
   }
-  if (import_node_fs3.default.existsSync(import_node_path3.default.join(cwd, ".vscode"))) {
-    upsertMcpConfig(import_node_path3.default.join(cwd, ".vscode", "mcp.json"), "servers", entry, cwd, done);
+  if (import_node_fs4.default.existsSync(import_node_path4.default.join(cwd, ".vscode"))) {
+    upsertMcpConfig(import_node_path4.default.join(cwd, ".vscode", "mcp.json"), "servers", entry, cwd, done);
   }
   installSkills(skillSrcDir, cwd, done);
+  appendDebuggingGuide(import_node_path4.default.join(cwd, "CLAUDE.md"), cwd, done);
+  appendDebuggingGuide(import_node_path4.default.join(cwd, "AGENTS.md"), cwd, done);
   log("Buoy MCP installed:");
   for (const line of done) log("  \u2022 " + line);
   log("");
@@ -3745,7 +4958,7 @@ function runInit(opts = {}) {
 }
 function resolveEntry(opts, log) {
   if (opts.cliPath) {
-    return { type: "stdio", command: "node", args: [opts.cliPath] };
+    return { type: "stdio", command: "node", args: [opts.cliPath], env: defaultEnv() };
   }
   const mode = opts.mode ?? "auto";
   if (mode === "npx") {
@@ -3764,21 +4977,21 @@ function resolveEntry(opts, log) {
   return localEntry(opts, log);
 }
 function npxEntry() {
-  return { type: "stdio", command: "npx", args: ["-y", `${PACKAGE_NAME}@latest`] };
+  return { type: "stdio", command: "npx", args: ["-y", `${PACKAGE_NAME}@latest`], env: defaultEnv() };
 }
 function localEntry(opts, log) {
-  const installDir = opts.installDir ?? process.env.BUOY_MCP_HOME ?? import_node_path3.default.join(import_node_os3.default.homedir(), ".buoy-mcp");
+  const installDir = opts.installDir ?? process.env.BUOY_MCP_HOME ?? import_node_path4.default.join(import_node_os3.default.homedir(), ".buoy-mcp");
   const registry = opts.registry ?? PUBLIC_REGISTRY;
   const cliPath = installLocalCopy(installDir, registry, log);
   if (cliPath) {
-    return { type: "stdio", command: "node", args: [cliPath] };
+    return { type: "stdio", command: "node", args: [cliPath], env: defaultEnv() };
   }
   log("\u26A0 local install failed \u2014 writing the npx entry instead (see the error above).");
   return npxEntry();
 }
 function installLocalCopy(installDir, registry, log) {
   const spec = `${PACKAGE_NAME}@${VERSION === "0.0.0-dev" ? "latest" : VERSION}`;
-  import_node_fs3.default.mkdirSync(installDir, { recursive: true });
+  import_node_fs4.default.mkdirSync(installDir, { recursive: true });
   const npm = process.platform === "win32" ? "npm.cmd" : "npm";
   log(`Installing ${spec} into ${installDir} from ${registry} \u2026`);
   const res = (0, import_node_child_process2.spawnSync)(
@@ -3801,8 +5014,8 @@ function installLocalCopy(installDir, registry, log) {
     log(`\u26A0 npm install exited with code ${res.status ?? "?"}${res.error ? ` (${res.error.message})` : ""}.`);
     return null;
   }
-  const cliPath = import_node_path3.default.join(installDir, "node_modules", PACKAGE_NAME, "dist", "cli.js");
-  if (!import_node_fs3.default.existsSync(cliPath)) {
+  const cliPath = import_node_path4.default.join(installDir, "node_modules", PACKAGE_NAME, "dist", "cli.js");
+  if (!import_node_fs4.default.existsSync(cliPath)) {
     log(`\u26A0 install finished but ${cliPath} is missing.`);
     return null;
   }
@@ -3824,7 +5037,7 @@ function effectiveRegistry() {
 }
 function npmConfigGet(key) {
   const npm = process.platform === "win32" ? "npm.cmd" : "npm";
-  const res = (0, import_node_child_process2.spawnSync)(npm, ["config", "get", key], { encoding: "utf8", timeout: PROBE_TIMEOUT_MS2 });
+  const res = (0, import_node_child_process2.spawnSync)(npm, ["config", "get", key], { encoding: "utf8", timeout: PROBE_TIMEOUT_MS3 });
   if (res.status !== 0 || typeof res.stdout !== "string") return null;
   const val = res.stdout.trim();
   if (!val || val === "undefined" || val === "null") return null;
@@ -3833,8 +5046,8 @@ function npmConfigGet(key) {
 function hostReachable(registry) {
   const done = (0, import_node_child_process2.spawnSync)(
     process.execPath,
-    ["-e", REACHABILITY_PROBE, registry, String(PROBE_TIMEOUT_MS2)],
-    { encoding: "utf8", timeout: PROBE_TIMEOUT_MS2 + 2e3 }
+    ["-e", REACHABILITY_PROBE, registry, String(PROBE_TIMEOUT_MS3)],
+    { encoding: "utf8", timeout: PROBE_TIMEOUT_MS3 + 2e3 }
   );
   return done.status === 0;
 }
@@ -3854,52 +5067,129 @@ fetch(url, { method: 'HEAD', signal: c.signal })
 `;
 function upsertMcpConfig(file, key, entry, cwd, done) {
   let json3 = {};
-  if (import_node_fs3.default.existsSync(file)) {
+  if (import_node_fs4.default.existsSync(file)) {
     try {
-      json3 = JSON.parse(import_node_fs3.default.readFileSync(file, "utf8"));
+      json3 = JSON.parse(import_node_fs4.default.readFileSync(file, "utf8"));
     } catch {
-      import_node_fs3.default.copyFileSync(file, file + ".bak");
+      import_node_fs4.default.copyFileSync(file, file + ".bak");
       done.push(`existing ${rel(file, cwd)} was invalid JSON \u2014 backed up to ${rel(file, cwd)}.bak`);
       json3 = {};
     }
   } else {
-    import_node_fs3.default.mkdirSync(import_node_path3.default.dirname(file), { recursive: true });
+    import_node_fs4.default.mkdirSync(import_node_path4.default.dirname(file), { recursive: true });
   }
   const servers = json3[key] && typeof json3[key] === "object" ? json3[key] : {};
   const existed = "buoy" in servers;
   servers.buoy = entry;
   json3[key] = servers;
-  import_node_fs3.default.writeFileSync(file, JSON.stringify(json3, null, 2) + "\n");
+  import_node_fs4.default.writeFileSync(file, JSON.stringify(json3, null, 2) + "\n");
   done.push(`${existed ? "updated" : "added"} \`buoy\` in ${rel(file, cwd)}`);
 }
+var GUIDE_HEADING = "# Debugging with Buoy";
+var DEBUGGING_GUIDE = `${GUIDE_HEADING}
+
+This app's runtime is inspectable while it runs: the Buoy MCP tools read live
+state straight from the device. Route by symptom before reading source:
+
+- \`get_triage\` \u2014 START HERE. One call: device, recent console errors and
+  crashes, recent network requests, storage keys, and what's on screen. It
+  usually names the problem, and always names the tool to drill into next.
+- \`run_flow\` \u2014 reproduce a bug or verify a fix in ONE call: a scripted
+  tap/type/wait/assert sequence that returns the final screen plus the network
+  and console output it produced. Use it instead of alternating
+  \`describe_screen\` and \`tap_element\` a dozen times.
+- \`get_events\` \u2014 the universal activity timeline (network, state changes,
+  storage writes, routes, renders). Check it BEFORE driving the UI to
+  reproduce a bug \u2014 the failure is usually already recorded.
+- \`get_network_requests\` \u2014 API data wrong or calls failing \u2192 read the actual
+  request + response bodies instead of guessing from code. Boot-time requests
+  are captured too.
+- \`get_console\` \u2014 crashes and errors, including FATAL uncaught JS errors
+  (tagged \`[FATAL]\`, with the component that crashed). Readable even after the
+  app dies, so a redboxed app still tells you why.
+- \`get_storage\` \u2014 data wrong or missing after an app restart \u2192 read the
+  persisted values FIRST.
+- \`reload_app\` \u2014 recover a crashed app (the other tools stop answering until
+  you do) or pick up a change Fast Refresh missed.
+- \`get_snapshot\` \u2014 full current state of any one tool when the compact views
+  aren't enough.
+
+Runtime facts beat guesses \u2014 and after you edit, prove the fix on the device:
+reload, then re-drive EVERY screen the symptom could show up on and assert the
+corrected value. Fixes usually fail by being incomplete, not by being wrong.
+
+## Don't report a fix you haven't watched work
+
+Saying "fixed" is a claim about how the app behaves, so check it the same way
+you'd check anything else about the app \u2014 by looking at it. Re-run the exact
+interaction that was broken and report what the numbers did:
+
+- \`measure_renders\` with the same \`steps\` and \`compareToPrevious: true\` for a
+  performance change \u2014 it prints the before/after delta and flags a change that
+  made things worse.
+- \`run_flow\` re-driving the broken screen for a behaviour change.
+
+Two things this catches that reading cannot: a fix that is right but incomplete
+(the value was wrong in three places and you corrected one), and a fix that
+moved the cost instead of removing it \u2014 the usual failure mode for re-render
+work, where a page gets faster to type in and slower to tap.
+
+If the app changed since anything was last checked, Buoy will say so in a tool
+result. Whether that's worth acting on is your call \u2014 a doc edit isn't worth a
+device check, a state-management change is. Set \`BUOY_VERIFY\` in the MCP config
+to \`always\` (repeat until checked) or \`never\` (silent) to change how often it
+mentions it.
+`;
+function appendDebuggingGuide(file, cwd, done) {
+  let existing = "";
+  if (import_node_fs4.default.existsSync(file)) {
+    try {
+      existing = import_node_fs4.default.readFileSync(file, "utf8");
+    } catch {
+      done.push(`\u26A0 could not read ${rel(file, cwd)} \u2014 skipped the debugging guide`);
+      return;
+    }
+    if (existing.includes(GUIDE_HEADING)) {
+      done.push(`${rel(file, cwd)} already has the "${GUIDE_HEADING}" block`);
+      return;
+    }
+  }
+  const separator = existing === "" ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  try {
+    import_node_fs4.default.writeFileSync(file, existing + separator + DEBUGGING_GUIDE);
+    done.push(`${existing ? "appended" : "created"} "${GUIDE_HEADING}" block in ${rel(file, cwd)}`);
+  } catch {
+    done.push(`\u26A0 could not write ${rel(file, cwd)} \u2014 skipped the debugging guide`);
+  }
+}
 function installSkills(skillSrcDir, cwd, done) {
-  if (!import_node_fs3.default.existsSync(skillSrcDir)) {
+  if (!import_node_fs4.default.existsSync(skillSrcDir)) {
     done.push("\u26A0 no bundled skills found \u2014 skipped");
     return;
   }
-  const skills = import_node_fs3.default.readdirSync(skillSrcDir, { withFileTypes: true }).filter((e) => e.isDirectory() && import_node_fs3.default.existsSync(import_node_path3.default.join(skillSrcDir, e.name, "SKILL.md")));
+  const skills = import_node_fs4.default.readdirSync(skillSrcDir, { withFileTypes: true }).filter((e) => e.isDirectory() && import_node_fs4.default.existsSync(import_node_path4.default.join(skillSrcDir, e.name, "SKILL.md")));
   if (skills.length === 0) {
     done.push("\u26A0 no skills with a SKILL.md found \u2014 skipped");
     return;
   }
   for (const skill of skills) {
-    const from = import_node_path3.default.join(skillSrcDir, skill.name);
-    const to = import_node_path3.default.join(cwd, ".claude", "skills", skill.name);
+    const from = import_node_path4.default.join(skillSrcDir, skill.name);
+    const to = import_node_path4.default.join(cwd, ".claude", "skills", skill.name);
     copyDir(from, to);
-    done.push(`installed the ${skill.name} skill \u2192 ${rel(import_node_path3.default.join(to, "SKILL.md"), cwd)}`);
+    done.push(`installed the ${skill.name} skill \u2192 ${rel(import_node_path4.default.join(to, "SKILL.md"), cwd)}`);
   }
 }
 function copyDir(from, to) {
-  import_node_fs3.default.mkdirSync(to, { recursive: true });
-  for (const entry of import_node_fs3.default.readdirSync(from, { withFileTypes: true })) {
-    const s = import_node_path3.default.join(from, entry.name);
-    const d = import_node_path3.default.join(to, entry.name);
+  import_node_fs4.default.mkdirSync(to, { recursive: true });
+  for (const entry of import_node_fs4.default.readdirSync(from, { withFileTypes: true })) {
+    const s = import_node_path4.default.join(from, entry.name);
+    const d = import_node_path4.default.join(to, entry.name);
     if (entry.isDirectory()) copyDir(s, d);
-    else import_node_fs3.default.copyFileSync(s, d);
+    else import_node_fs4.default.copyFileSync(s, d);
   }
 }
 function rel(file, cwd) {
-  const r = import_node_path3.default.relative(cwd, file);
+  const r = import_node_path4.default.relative(cwd, file);
   return r && !r.startsWith("..") ? r : file;
 }
 // Annotate the CommonJS export names for ESM import in node: