@buoy-gg/mcp 7.0.17 → 7.0.19

package/dist/{chunk-7NCVMOMV.mjs → chunk-TZ2C4X6V.mjs}

@@ -24,8 +24,12 @@ var SyncClient = class {
     this.devices = [];
     /** Latest snapshot payload per `${deviceId}::${toolId}`. */
     this.snapshots = /* @__PURE__ */ new Map();
-    /** Tools we've asked the broker to keep streaming, as `${deviceId}::${toolId}`. */
-    this.watching = /* @__PURE__ */ new Set();
+    /**
+     * Capture-mode watches this client holds, keyed by snapKey. Stored with
+     * their addressing because they have to be RE-SENT on every reconnect: the
+     * broker keys watch state by socket id, and a reconnect gets a new one.
+     */
+    this.watching = /* @__PURE__ */ new Map();
     /** In-flight actions awaiting a result, keyed by requestId. */
     this.pendingActions = /* @__PURE__ */ new Map();
     /** Callbacks waiting for the next snapshot of `${deviceId}::${toolId}`. */
@@ -81,6 +85,7 @@ var SyncClient = class {
         resolve();
       };
       socket.on("connect", onConnect);
+      socket.on("connect", () => this.rearmWatches());
       socket.once("connect_error", (err) => {
         if (settled) return;
         settled = true;
@@ -191,11 +196,50 @@ var SyncClient = class {
   // ----------------------------------------------------------------
   // Watch + snapshots
   // ----------------------------------------------------------------
+  /**
+   * Keep the device RECORDING this tool, without asking it to stream.
+   *
+   * A dashboard watches for as long as its panel is open; this client is
+   * request/response, so it used to watch and unwatch around every single
+   * read. That works for a tool whose state just IS (the query cache, the env
+   * table) and is useless for one that records a timeline: the unwatch drops
+   * the device's subscriber count to zero, which stops capture, so nothing is
+   * ever recorded between two reads. The list comes back empty and reads as
+   * "the app made no requests" — a wrong conclusion that is very expensive to
+   * chase, because everything about the app looks fine.
+   *
+   * Capture-mode watches are held for the life of the connection and released
+   * on disconnect (the broker also drops them for us). They cost the device's
+   * ring buffer, not the socket: no snapshot is pushed, and reads still go
+   * through `request-devtool-state`.
+   */
   ensureWatching(toolId, targetDeviceId) {
     const key = snapKey(targetDeviceId, toolId);
     if (this.watching.has(key)) return;
-    this.watching.add(key);
-    this.socket?.emit("devtool-watch", { toolId, targetDeviceId, watching: true });
+    this.watching.set(key, { toolId, targetDeviceId });
+    this.sendWatch(toolId, targetDeviceId);
+  }
+  sendWatch(toolId, targetDeviceId) {
+    this.socket?.emit("devtool-watch", {
+      toolId,
+      targetDeviceId,
+      watching: true,
+      stream: false
+    });
+  }
+  /**
+   * Re-arm every held watch after a reconnect.
+   *
+   * The broker tracks watches per SOCKET, so a reconnect (broker restart, a
+   * dropped wifi link) silently discards all of ours while `watching` still
+   * says we hold them — `ensureWatching` would then short-circuit forever and
+   * the device would never record again. Silent and permanent: the exact
+   * failure this whole capture-mode change exists to remove.
+   */
+  rearmWatches() {
+    for (const { toolId, targetDeviceId } of this.watching.values()) {
+      this.sendWatch(toolId, targetDeviceId);
+    }
   }
   /** Stop streaming a tool (releases the device-side backpressure). */
   unwatch(toolId, targetDeviceId) {
@@ -208,26 +252,25 @@ var SyncClient = class {
     return this.snapshots.get(snapKey(deviceId, toolId));
   }
   /**
-   * Get a tool's current state. Starts watching (so the device begins emitting),
-   * explicitly requests state, and resolves with the next snapshot. Falls back
-   * to the last cached snapshot if the request times out.
+   * Get a tool's current state: arm capture (once, for the connection), ask
+   * for state explicitly, and resolve with the snapshot that comes back.
+   * Falls back to the last cached snapshot if the request times out.
+   *
+   * The capture watch is deliberately NOT released afterwards — see
+   * `ensureWatching`. It costs the device nothing on the socket, and dropping
+   * it is what made every timeline tool look permanently empty from here.
    */
   async getSnapshot(toolId, deviceId, opts = {}) {
     const target = this.resolveDevice(deviceId);
     const key = snapKey(target, toolId);
-    const wasWatching = this.watching.has(key);
     this.ensureWatching(toolId, target);
-    try {
-      const next = this.waitForSnapshot(key, opts.timeoutMs ?? DEFAULT_SNAPSHOT_TIMEOUT_MS);
-      this.socket?.emit("request-devtool-state", { toolId, targetDeviceId: target });
-      const payload = await next;
-      if (payload !== void 0) return { deviceId: target, payload };
-      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?)`);
-    } finally {
-      if (!wasWatching) this.unwatch(toolId, target);
-    }
+    const next = this.waitForSnapshot(key, opts.timeoutMs ?? DEFAULT_SNAPSHOT_TIMEOUT_MS);
+    this.socket?.emit("request-devtool-state", { toolId, targetDeviceId: target });
+    const payload = await next;
+    if (payload !== void 0) return { deviceId: target, payload };
+    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?)`);
   }
   waitForSnapshot(key, timeoutMs) {
     return new Promise((resolve) => {
@@ -301,7 +344,7 @@ async function waitForBroker(url, attempts = 20) {
 var delay = (ms) => new Promise((r) => setTimeout(r, ms));
 
 // src/version.ts
-var VERSION = "7.0.17" ? "7.0.17" : "0.0.0-dev";
+var VERSION = "7.0.19" ? "7.0.19" : "0.0.0-dev";
 var PACKAGE_NAME = "@buoy-gg/mcp";
 
 // src/update/checkForUpdate.ts
@@ -2079,6 +2122,60 @@ function truncate2(v, n = 600) {
   const s = typeof v === "string" ? v : JSON.stringify(v);
   return s.length > n ? `${s.slice(0, n)}\u2026(+${s.length - n} chars)` : s;
 }
+var MAX_BODY_FETCHES = 8;
+async function resolveBodies(sync, rows, target, max = MAX_BODY_FETCHES) {
+  const needed = rows.filter(
+    (e) => e.id && (e.requestBodyOmitted === true && e.requestData === void 0 || e.responseBodyOmitted === true && e.responseData === void 0)
+  );
+  const bodies = /* @__PURE__ */ new Map();
+  if (needed.length === 0) return { bodies, skipped: 0 };
+  const take = needed.slice(0, max);
+  const settled = await Promise.allSettled(
+    take.map(
+      (e) => sync.callAction(NETWORK_TOOL_ID, "getEventBody", { id: e.id }, target)
+    )
+  );
+  settled.forEach((r, i) => {
+    const id = take[i].id;
+    const body = r.status === "fulfilled" ? r.value : null;
+    bodies.set(id, body ? { ...body } : { unresolved: true });
+  });
+  return { bodies, skipped: needed.length - take.length };
+}
+async function captureDiagnosis(sync, target) {
+  let status = null;
+  try {
+    status = await sync.callAction(
+      NETWORK_TOOL_ID,
+      "getCaptureStatus",
+      {},
+      target
+    );
+  } catch {
+    return "The network tool has captured nothing yet.";
+  }
+  if (!status || status.capturing !== false) {
+    return "The device IS capturing, so nothing has been requested since it started.";
+  }
+  return "The device is NOT capturing. Reading from here arms capture, so the very next read should see traffic \u2014 trigger it and call again. This is not an app or interception problem. (If it stays off, the device is on a Buoy older than the capture-mode watch: open the Network panel on the device or in Buoy Desktop to record.)";
+}
+function skippedNote(skipped) {
+  return skipped > 0 ? `
+
+_${skipped} more withheld ${skipped === 1 ? "body was" : "bodies were"} not fetched (cap ${MAX_BODY_FETCHES} per listing, they are large). Get one in full with its id._` : "";
+}
+function bodyLines(e, fetched) {
+  const got = e.id ? fetched.get(e.id) : void 0;
+  const label = (inline, resolved, omitted) => {
+    const value = inline ?? resolved;
+    if (value !== void 0 && value !== null) return truncate2(value);
+    if (!omitted) return "(none)";
+    return got?.unresolved ? "(withheld \u2014 the device did not answer getEventBody)" : "(none)";
+  };
+  return `
+   \u2514\u2500 request: ${label(e.requestData, got?.requestData, e.requestBodyOmitted)}
+   \u2514\u2500 response: ${label(e.responseData, got?.responseData, e.responseBodyOmitted)}`;
+}
 function formatRow(index, e, markers) {
   const where = e.path || e.url;
   const bits = [
@@ -2132,6 +2229,7 @@ function registerNetworkTools(server, sync) {
 The developer pins/saves a request from the Network tool (long-press a row, or the pin/bookmark buttons in the request detail header), or you can with network_action.`
             );
           }
+          const kept = args.includeBodies ? await resolveBodies(sync, rows2.map((r) => r.event), target) : { bodies: /* @__PURE__ */ new Map(), skipped: 0 };
           const body2 = rows2.map((r, i) => {
             const marks = [r.pinned ? "\u{1F4CC} pinned" : "", r.saved ? "\u{1F516} saved" : ""].filter(Boolean).join(" ");
             const stale = r.event.id?.startsWith("saved:") ? " \xB7 from an earlier app run" : "";
@@ -2139,12 +2237,7 @@ The developer pins/saves a request from the Network tool (long-press a row, or t
             let out = formatRow(i + 1, r.event, marks);
             out += `
    \u2514\u2500 key \`${r.key}\`${stale}${trunc}`;
-            if (args.includeBodies) {
-              out += `
-   \u2514\u2500 request: ${truncate2(r.event.requestData)}`;
-              out += `
-   \u2514\u2500 response: ${truncate2(r.event.responseData)}`;
-            }
+            if (args.includeBodies) out += bodyLines(r.event, kept.bodies);
             return out;
           }).join("\n");
           return text10(
@@ -2152,23 +2245,19 @@ The developer pins/saves a request from the Network tool (long-press a row, or t
 
 ${body2}
 
-_These are snapshots: they survive Clear, the 500-request cap and app restarts. Remove one with network_action({action:"remove", key}). Ids starting \`saved:\` are from an earlier run of the app._`
+_These are snapshots: they survive Clear, the 500-request cap and app restarts. Remove one with network_action({action:"remove", key}). Ids starting \`saved:\` are from an earlier run of the app._${skippedNote(kept.skipped)}`
           );
         }
         const rows = events.filter((e) => matchesStatus(e, args.status)).filter((e) => !pattern || (e.url ?? "").toLowerCase().includes(pattern)).slice(0, limit);
         if (rows.length === 0) {
-          const why = events.length === 0 ? "The network tool has captured nothing yet (is it enabled, and has the app made a request?)." : "No request matched the filter.";
+          const why = events.length === 0 ? await captureDiagnosis(sync, target) : "No request matched the filter.";
           return text10(`No requests on ${target}. ${why}`);
         }
+        const live = args.includeBodies ? await resolveBodies(sync, rows, target) : { bodies: /* @__PURE__ */ new Map(), skipped: 0 };
         const body = rows.map((e, i) => {
           const marks = [pinnedIds.has(e.id) ? "\u{1F4CC}" : "", savedIds.has(e.id) ? "\u{1F516}" : ""].filter(Boolean).join("");
           let out = formatRow(i + 1, e, marks);
-          if (args.includeBodies) {
-            out += `
-   \u2514\u2500 request: ${truncate2(e.requestData)}`;
-            out += `
-   \u2514\u2500 response: ${truncate2(e.responseData)}`;
-          }
+          if (args.includeBodies) out += bodyLines(e, live.bodies);
           return out;
         }).join("\n");
         const keptNote = saved.length > 0 ? ` \xB7 ${saved.length} kept (flagged:'any' to list)` : "";
@@ -2177,7 +2266,7 @@ _These are snapshots: they survive Clear, the 500-request cap and app restarts.
 
 ${body}
 
-_\u{1F4CC} pinned \xB7 \u{1F516} saved. Act on one with its id, e.g. network_action({action:"pin", id:"${rows[0].id}"})._`
+_\u{1F4CC} pinned \xB7 \u{1F516} saved. Act on one with its id, e.g. network_action({action:"pin", id:"${rows[0].id}"})._${skippedNote(live.skipped)}`
         );
       } catch (e) {
         return fail12(errMsg12(e));
@@ -2530,12 +2619,13 @@ ${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, 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), 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: z13.enum(["capture", "capture_baseline", "restore", "delete", "rename"]).describe("What to do."),
+        action: z13.enum(["capture", "capture_baseline", "preview", "restore", "delete", "rename"]).describe("What to do."),
         id: z13.string().optional().describe("Snapshot id (required for restore/delete/rename; from get_time_machine)."),
         name: z13.string().optional().describe("Snapshot name (for capture and rename)."),
         mode: z13.enum(["live", "reload"]).optional().describe("Restore mode. Default 'live'."),
+        excludeKeys: z13.array(z13.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").'),
         sourceIds: z13.array(z13.string()).optional().describe("Capture/restore only these source ids (default all)."),
         deviceId: z13.string().optional().describe("Target device id (auto-selected if one is connected).")
       }
@@ -2556,9 +2646,36 @@ ${formatOutcome(p.lastOutcome)}`);
             const result = await call("captureBaseline", {});
             return text11(`Captured baseline \`${result.snapshot.id}\` \u2014 restoring it wipes app storage and reloads.`);
           }
+          case "preview": {
+            if (!args.id) return fail13("preview requires `id` (from get_time_machine).");
+            const result = await call("preview", { id: args.id });
+            const lines = [];
+            let totalApplies = 0;
+            for (const src of result.sources) {
+              const counts = {};
+              for (const item of src.items) {
+                counts[item.verdict] = (counts[item.verdict] ?? 0) + 1;
+              }
+              const applies = (counts.added ?? 0) + (counts.removed ?? 0) + (counts.changed ?? 0) + (counts["too-large"] ?? 0);
+              totalApplies += applies;
+              const parts = Object.entries(counts).filter(([v]) => v !== "unchanged").map(([v, n]) => `${n} ${v}`);
+              lines.push(`- **${src.label}**: ${parts.length ? parts.join(", ") : "no changes"}${src.error ? ` \u2014 \u26A0 ${src.error}` : ""}`);
+              for (const item of src.items.filter((i) => i.verdict !== "unchanged").slice(0, 8)) {
+                lines.push(`    ${item.verdict === "added" ? "+" : item.verdict === "removed" ? "\u2212" : item.verdict === "wont-apply" ? "\u2298" : "\u2248"} ${item.label}${item.reason ? ` (${item.reason})` : ""}`);
+              }
+              for (const note of src.notes) lines.push(`    \xB7 ${note}`);
+            }
+            const head = totalApplies === 0 ? "**Restore would change NOTHING** (states identical or nothing applicable)." : `**Restore would apply ${totalApplies} change(s):**`;
+            return text11(`${head}
+${lines.join("\n")}`);
+          }
           case "restore": {
             if (!args.id) return fail13("restore requires `id` (from get_time_machine).");
-            const outcome = await call("restore", { id: args.id, mode: args.mode ?? "live" });
+            const outcome = await call("restore", {
+              id: args.id,
+              mode: args.mode ?? "live",
+              excludeKeys: args.excludeKeys
+            });
             return text11(formatOutcome(outcome));
           }
           case "delete": {

package/dist/cli.js

@@ -52,8 +52,12 @@ var SyncClient = class {
     this.devices = [];
     /** Latest snapshot payload per `${deviceId}::${toolId}`. */
     this.snapshots = /* @__PURE__ */ new Map();
-    /** Tools we've asked the broker to keep streaming, as `${deviceId}::${toolId}`. */
-    this.watching = /* @__PURE__ */ new Set();
+    /**
+     * Capture-mode watches this client holds, keyed by snapKey. Stored with
+     * their addressing because they have to be RE-SENT on every reconnect: the
+     * broker keys watch state by socket id, and a reconnect gets a new one.
+     */
+    this.watching = /* @__PURE__ */ new Map();
     /** In-flight actions awaiting a result, keyed by requestId. */
     this.pendingActions = /* @__PURE__ */ new Map();
     /** Callbacks waiting for the next snapshot of `${deviceId}::${toolId}`. */
@@ -109,6 +113,7 @@ var SyncClient = class {
         resolve();
       };
       socket.on("connect", onConnect);
+      socket.on("connect", () => this.rearmWatches());
       socket.once("connect_error", (err) => {
         if (settled) return;
         settled = true;
@@ -219,11 +224,50 @@ var SyncClient = class {
   // ----------------------------------------------------------------
   // Watch + snapshots
   // ----------------------------------------------------------------
+  /**
+   * Keep the device RECORDING this tool, without asking it to stream.
+   *
+   * A dashboard watches for as long as its panel is open; this client is
+   * request/response, so it used to watch and unwatch around every single
+   * read. That works for a tool whose state just IS (the query cache, the env
+   * table) and is useless for one that records a timeline: the unwatch drops
+   * the device's subscriber count to zero, which stops capture, so nothing is
+   * ever recorded between two reads. The list comes back empty and reads as
+   * "the app made no requests" — a wrong conclusion that is very expensive to
+   * chase, because everything about the app looks fine.
+   *
+   * Capture-mode watches are held for the life of the connection and released
+   * on disconnect (the broker also drops them for us). They cost the device's
+   * ring buffer, not the socket: no snapshot is pushed, and reads still go
+   * through `request-devtool-state`.
+   */
   ensureWatching(toolId, targetDeviceId) {
     const key = snapKey(targetDeviceId, toolId);
     if (this.watching.has(key)) return;
-    this.watching.add(key);
-    this.socket?.emit("devtool-watch", { toolId, targetDeviceId, watching: true });
+    this.watching.set(key, { toolId, targetDeviceId });
+    this.sendWatch(toolId, targetDeviceId);
+  }
+  sendWatch(toolId, targetDeviceId) {
+    this.socket?.emit("devtool-watch", {
+      toolId,
+      targetDeviceId,
+      watching: true,
+      stream: false
+    });
+  }
+  /**
+   * Re-arm every held watch after a reconnect.
+   *
+   * The broker tracks watches per SOCKET, so a reconnect (broker restart, a
+   * dropped wifi link) silently discards all of ours while `watching` still
+   * says we hold them — `ensureWatching` would then short-circuit forever and
+   * the device would never record again. Silent and permanent: the exact
+   * failure this whole capture-mode change exists to remove.
+   */
+  rearmWatches() {
+    for (const { toolId, targetDeviceId } of this.watching.values()) {
+      this.sendWatch(toolId, targetDeviceId);
+    }
   }
   /** Stop streaming a tool (releases the device-side backpressure). */
   unwatch(toolId, targetDeviceId) {
@@ -236,26 +280,25 @@ var SyncClient = class {
     return this.snapshots.get(snapKey(deviceId, toolId));
   }
   /**
-   * Get a tool's current state. Starts watching (so the device begins emitting),
-   * explicitly requests state, and resolves with the next snapshot. Falls back
-   * to the last cached snapshot if the request times out.
+   * Get a tool's current state: arm capture (once, for the connection), ask
+   * for state explicitly, and resolve with the snapshot that comes back.
+   * Falls back to the last cached snapshot if the request times out.
+   *
+   * The capture watch is deliberately NOT released afterwards — see
+   * `ensureWatching`. It costs the device nothing on the socket, and dropping
+   * it is what made every timeline tool look permanently empty from here.
    */
   async getSnapshot(toolId, deviceId, opts = {}) {
     const target = this.resolveDevice(deviceId);
     const key = snapKey(target, toolId);
-    const wasWatching = this.watching.has(key);
     this.ensureWatching(toolId, target);
-    try {
-      const next = this.waitForSnapshot(key, opts.timeoutMs ?? DEFAULT_SNAPSHOT_TIMEOUT_MS);
-      this.socket?.emit("request-devtool-state", { toolId, targetDeviceId: target });
-      const payload = await next;
-      if (payload !== void 0) return { deviceId: target, payload };
-      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?)`);
-    } finally {
-      if (!wasWatching) this.unwatch(toolId, target);
-    }
+    const next = this.waitForSnapshot(key, opts.timeoutMs ?? DEFAULT_SNAPSHOT_TIMEOUT_MS);
+    this.socket?.emit("request-devtool-state", { toolId, targetDeviceId: target });
+    const payload = await next;
+    if (payload !== void 0) return { deviceId: target, payload };
+    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?)`);
   }
   waitForSnapshot(key, timeoutMs) {
     return new Promise((resolve) => {
@@ -341,7 +384,7 @@ var import_node_os = __toESM(require("os"));
 var import_node_path = __toESM(require("path"));
 
 // src/version.ts
-var VERSION = "7.0.17" ? "7.0.17" : "0.0.0-dev";
+var VERSION = "7.0.19" ? "7.0.19" : "0.0.0-dev";
 var PACKAGE_NAME = "@buoy-gg/mcp";
 
 // src/update/checkForUpdate.ts
@@ -1342,6 +1385,60 @@ function truncate(v, n = 600) {
   const s = typeof v === "string" ? v : JSON.stringify(v);
   return s.length > n ? `${s.slice(0, n)}\u2026(+${s.length - n} chars)` : s;
 }
+var MAX_BODY_FETCHES = 8;
+async function resolveBodies(sync, rows, target, max = MAX_BODY_FETCHES) {
+  const needed = rows.filter(
+    (e) => e.id && (e.requestBodyOmitted === true && e.requestData === void 0 || e.responseBodyOmitted === true && e.responseData === void 0)
+  );
+  const bodies = /* @__PURE__ */ new Map();
+  if (needed.length === 0) return { bodies, skipped: 0 };
+  const take = needed.slice(0, max);
+  const settled = await Promise.allSettled(
+    take.map(
+      (e) => sync.callAction(NETWORK_TOOL_ID, "getEventBody", { id: e.id }, target)
+    )
+  );
+  settled.forEach((r, i) => {
+    const id = take[i].id;
+    const body = r.status === "fulfilled" ? r.value : null;
+    bodies.set(id, body ? { ...body } : { unresolved: true });
+  });
+  return { bodies, skipped: needed.length - take.length };
+}
+async function captureDiagnosis(sync, target) {
+  let status = null;
+  try {
+    status = await sync.callAction(
+      NETWORK_TOOL_ID,
+      "getCaptureStatus",
+      {},
+      target
+    );
+  } catch {
+    return "The network tool has captured nothing yet.";
+  }
+  if (!status || status.capturing !== false) {
+    return "The device IS capturing, so nothing has been requested since it started.";
+  }
+  return "The device is NOT capturing. Reading from here arms capture, so the very next read should see traffic \u2014 trigger it and call again. This is not an app or interception problem. (If it stays off, the device is on a Buoy older than the capture-mode watch: open the Network panel on the device or in Buoy Desktop to record.)";
+}
+function skippedNote(skipped) {
+  return skipped > 0 ? `
+
+_${skipped} more withheld ${skipped === 1 ? "body was" : "bodies were"} not fetched (cap ${MAX_BODY_FETCHES} per listing, they are large). Get one in full with its id._` : "";
+}
+function bodyLines(e, fetched) {
+  const got = e.id ? fetched.get(e.id) : void 0;
+  const label = (inline, resolved, omitted) => {
+    const value = inline ?? resolved;
+    if (value !== void 0 && value !== null) return truncate(value);
+    if (!omitted) return "(none)";
+    return got?.unresolved ? "(withheld \u2014 the device did not answer getEventBody)" : "(none)";
+  };
+  return `
+   \u2514\u2500 request: ${label(e.requestData, got?.requestData, e.requestBodyOmitted)}
+   \u2514\u2500 response: ${label(e.responseData, got?.responseData, e.responseBodyOmitted)}`;
+}
 function formatRow(index, e, markers) {
   const where = e.path || e.url;
   const bits = [
@@ -1395,6 +1492,7 @@ function registerNetworkTools(server, sync) {
 The developer pins/saves a request from the Network tool (long-press a row, or the pin/bookmark buttons in the request detail header), or you can with network_action.`
             );
           }
+          const kept = args.includeBodies ? await resolveBodies(sync, rows2.map((r) => r.event), target) : { bodies: /* @__PURE__ */ new Map(), skipped: 0 };
           const body2 = rows2.map((r, i) => {
             const marks = [r.pinned ? "\u{1F4CC} pinned" : "", r.saved ? "\u{1F516} saved" : ""].filter(Boolean).join(" ");
             const stale = r.event.id?.startsWith("saved:") ? " \xB7 from an earlier app run" : "";
@@ -1402,12 +1500,7 @@ The developer pins/saves a request from the Network tool (long-press a row, or t
             let out = formatRow(i + 1, r.event, marks);
             out += `
    \u2514\u2500 key \`${r.key}\`${stale}${trunc}`;
-            if (args.includeBodies) {
-              out += `
-   \u2514\u2500 request: ${truncate(r.event.requestData)}`;
-              out += `
-   \u2514\u2500 response: ${truncate(r.event.responseData)}`;
-            }
+            if (args.includeBodies) out += bodyLines(r.event, kept.bodies);
             return out;
           }).join("\n");
           return text3(
@@ -1415,23 +1508,19 @@ The developer pins/saves a request from the Network tool (long-press a row, or t
 
 ${body2}
 
-_These are snapshots: they survive Clear, the 500-request cap and app restarts. Remove one with network_action({action:"remove", key}). Ids starting \`saved:\` are from an earlier run of the app._`
+_These are snapshots: they survive Clear, the 500-request cap and app restarts. Remove one with network_action({action:"remove", key}). Ids starting \`saved:\` are from an earlier run of the app._${skippedNote(kept.skipped)}`
           );
         }
         const rows = events.filter((e) => matchesStatus(e, args.status)).filter((e) => !pattern || (e.url ?? "").toLowerCase().includes(pattern)).slice(0, limit);
         if (rows.length === 0) {
-          const why = events.length === 0 ? "The network tool has captured nothing yet (is it enabled, and has the app made a request?)." : "No request matched the filter.";
+          const why = events.length === 0 ? await captureDiagnosis(sync, target) : "No request matched the filter.";
           return text3(`No requests on ${target}. ${why}`);
         }
+        const live = args.includeBodies ? await resolveBodies(sync, rows, target) : { bodies: /* @__PURE__ */ new Map(), skipped: 0 };
         const body = rows.map((e, i) => {
           const marks = [pinnedIds.has(e.id) ? "\u{1F4CC}" : "", savedIds.has(e.id) ? "\u{1F516}" : ""].filter(Boolean).join("");
           let out = formatRow(i + 1, e, marks);
-          if (args.includeBodies) {
-            out += `
-   \u2514\u2500 request: ${truncate(e.requestData)}`;
-            out += `
-   \u2514\u2500 response: ${truncate(e.responseData)}`;
-          }
+          if (args.includeBodies) out += bodyLines(e, live.bodies);
           return out;
         }).join("\n");
         const keptNote = saved.length > 0 ? ` \xB7 ${saved.length} kept (flagged:'any' to list)` : "";
@@ -1440,7 +1529,7 @@ _These are snapshots: they survive Clear, the 500-request cap and app restarts.
 
 ${body}
 
-_\u{1F4CC} pinned \xB7 \u{1F516} saved. Act on one with its id, e.g. network_action({action:"pin", id:"${rows[0].id}"})._`
+_\u{1F4CC} pinned \xB7 \u{1F516} saved. Act on one with its id, e.g. network_action({action:"pin", id:"${rows[0].id}"})._${skippedNote(live.skipped)}`
         );
       } catch (e) {
         return fail4(errMsg4(e));
@@ -2388,12 +2477,13 @@ ${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, 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), 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", "restore", "delete", "rename"]).describe("What to do."),
+        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").'),
         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).")
       }
@@ -2414,9 +2504,36 @@ ${formatOutcome(p.lastOutcome)}`);
             const result = await call("captureBaseline", {});
             return text11(`Captured baseline \`${result.snapshot.id}\` \u2014 restoring it wipes app storage and reloads.`);
           }
+          case "preview": {
+            if (!args.id) return fail12("preview requires `id` (from get_time_machine).");
+            const result = await call("preview", { id: args.id });
+            const lines = [];
+            let totalApplies = 0;
+            for (const src of result.sources) {
+              const counts = {};
+              for (const item of src.items) {
+                counts[item.verdict] = (counts[item.verdict] ?? 0) + 1;
+              }
+              const applies = (counts.added ?? 0) + (counts.removed ?? 0) + (counts.changed ?? 0) + (counts["too-large"] ?? 0);
+              totalApplies += applies;
+              const parts = Object.entries(counts).filter(([v]) => v !== "unchanged").map(([v, n]) => `${n} ${v}`);
+              lines.push(`- **${src.label}**: ${parts.length ? parts.join(", ") : "no changes"}${src.error ? ` \u2014 \u26A0 ${src.error}` : ""}`);
+              for (const item of src.items.filter((i) => i.verdict !== "unchanged").slice(0, 8)) {
+                lines.push(`    ${item.verdict === "added" ? "+" : item.verdict === "removed" ? "\u2212" : item.verdict === "wont-apply" ? "\u2298" : "\u2248"} ${item.label}${item.reason ? ` (${item.reason})` : ""}`);
+              }
+              for (const note of src.notes) lines.push(`    \xB7 ${note}`);
+            }
+            const head = totalApplies === 0 ? "**Restore would change NOTHING** (states identical or nothing applicable)." : `**Restore would apply ${totalApplies} change(s):**`;
+            return text11(`${head}
+${lines.join("\n")}`);
+          }
           case "restore": {
             if (!args.id) return fail12("restore requires `id` (from get_time_machine).");
-            const outcome = await call("restore", { id: args.id, mode: args.mode ?? "live" });
+            const outcome = await call("restore", {
+              id: args.id,
+              mode: args.mode ?? "live",
+              excludeKeys: args.excludeKeys
+            });
             return text11(formatOutcome(outcome));
           }
           case "delete": {

package/dist/cli.mjs

@@ -3,7 +3,7 @@ import {
   SyncClient,
   createMcpServer,
   runInit
-} from "./chunk-7NCVMOMV.mjs";
+} from "./chunk-TZ2C4X6V.mjs";
 
 // src/cli.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/index.d.mts

@@ -47,7 +47,11 @@ declare class SyncClient {
     private devices;
     /** Latest snapshot payload per `${deviceId}::${toolId}`. */
     private snapshots;
-    /** Tools we've asked the broker to keep streaming, as `${deviceId}::${toolId}`. */
+    /**
+     * Capture-mode watches this client holds, keyed by snapKey. Stored with
+     * their addressing because they have to be RE-SENT on every reconnect: the
+     * broker keys watch state by socket id, and a reconnect gets a new one.
+     */
     private watching;
     /** In-flight actions awaiting a result, keyed by requestId. */
     private pendingActions;
@@ -87,15 +91,47 @@ declare class SyncClient {
      * is blocked.
      */
     requireProDevice(deviceId?: string): string;
+    /**
+     * Keep the device RECORDING this tool, without asking it to stream.
+     *
+     * A dashboard watches for as long as its panel is open; this client is
+     * request/response, so it used to watch and unwatch around every single
+     * read. That works for a tool whose state just IS (the query cache, the env
+     * table) and is useless for one that records a timeline: the unwatch drops
+     * the device's subscriber count to zero, which stops capture, so nothing is
+     * ever recorded between two reads. The list comes back empty and reads as
+     * "the app made no requests" — a wrong conclusion that is very expensive to
+     * chase, because everything about the app looks fine.
+     *
+     * Capture-mode watches are held for the life of the connection and released
+     * on disconnect (the broker also drops them for us). They cost the device's
+     * ring buffer, not the socket: no snapshot is pushed, and reads still go
+     * through `request-devtool-state`.
+     */
     private ensureWatching;
+    private sendWatch;
+    /**
+     * Re-arm every held watch after a reconnect.
+     *
+     * The broker tracks watches per SOCKET, so a reconnect (broker restart, a
+     * dropped wifi link) silently discards all of ours while `watching` still
+     * says we hold them — `ensureWatching` would then short-circuit forever and
+     * the device would never record again. Silent and permanent: the exact
+     * failure this whole capture-mode change exists to remove.
+     */
+    private rearmWatches;
     /** Stop streaming a tool (releases the device-side backpressure). */
     unwatch(toolId: string, targetDeviceId: string): void;
     /** Last snapshot received for a tool/device, if any. */
     cachedSnapshot(toolId: string, deviceId: string): unknown;
     /**
-     * Get a tool's current state. Starts watching (so the device begins emitting),
-     * explicitly requests state, and resolves with the next snapshot. Falls back
-     * to the last cached snapshot if the request times out.
+     * Get a tool's current state: arm capture (once, for the connection), ask
+     * for state explicitly, and resolve with the snapshot that comes back.
+     * Falls back to the last cached snapshot if the request times out.
+     *
+     * The capture watch is deliberately NOT released afterwards — see
+     * `ensureWatching`. It costs the device nothing on the socket, and dropping
+     * it is what made every timeline tool look permanently empty from here.
      */
     getSnapshot(toolId: string, deviceId?: string, opts?: {
         timeoutMs?: number;

package/dist/index.d.ts

@@ -47,7 +47,11 @@ declare class SyncClient {
     private devices;
     /** Latest snapshot payload per `${deviceId}::${toolId}`. */
     private snapshots;
-    /** Tools we've asked the broker to keep streaming, as `${deviceId}::${toolId}`. */
+    /**
+     * Capture-mode watches this client holds, keyed by snapKey. Stored with
+     * their addressing because they have to be RE-SENT on every reconnect: the
+     * broker keys watch state by socket id, and a reconnect gets a new one.
+     */
     private watching;
     /** In-flight actions awaiting a result, keyed by requestId. */
     private pendingActions;
@@ -87,15 +91,47 @@ declare class SyncClient {
      * is blocked.
      */
     requireProDevice(deviceId?: string): string;
+    /**
+     * Keep the device RECORDING this tool, without asking it to stream.
+     *
+     * A dashboard watches for as long as its panel is open; this client is
+     * request/response, so it used to watch and unwatch around every single
+     * read. That works for a tool whose state just IS (the query cache, the env
+     * table) and is useless for one that records a timeline: the unwatch drops
+     * the device's subscriber count to zero, which stops capture, so nothing is
+     * ever recorded between two reads. The list comes back empty and reads as
+     * "the app made no requests" — a wrong conclusion that is very expensive to
+     * chase, because everything about the app looks fine.
+     *
+     * Capture-mode watches are held for the life of the connection and released
+     * on disconnect (the broker also drops them for us). They cost the device's
+     * ring buffer, not the socket: no snapshot is pushed, and reads still go
+     * through `request-devtool-state`.
+     */
     private ensureWatching;
+    private sendWatch;
+    /**
+     * Re-arm every held watch after a reconnect.
+     *
+     * The broker tracks watches per SOCKET, so a reconnect (broker restart, a
+     * dropped wifi link) silently discards all of ours while `watching` still
+     * says we hold them — `ensureWatching` would then short-circuit forever and
+     * the device would never record again. Silent and permanent: the exact
+     * failure this whole capture-mode change exists to remove.
+     */
+    private rearmWatches;
     /** Stop streaming a tool (releases the device-side backpressure). */
     unwatch(toolId: string, targetDeviceId: string): void;
     /** Last snapshot received for a tool/device, if any. */
     cachedSnapshot(toolId: string, deviceId: string): unknown;
     /**
-     * Get a tool's current state. Starts watching (so the device begins emitting),
-     * explicitly requests state, and resolves with the next snapshot. Falls back
-     * to the last cached snapshot if the request times out.
+     * Get a tool's current state: arm capture (once, for the connection), ask
+     * for state explicitly, and resolve with the snapshot that comes back.
+     * Falls back to the last cached snapshot if the request times out.
+     *
+     * The capture watch is deliberately NOT released afterwards — see
+     * `ensureWatching`. It costs the device nothing on the socket, and dropping
+     * it is what made every timeline tool look permanently empty from here.
      */
     getSnapshot(toolId: string, deviceId?: string, opts?: {
         timeoutMs?: number;

package/dist/index.js

@@ -87,8 +87,12 @@ var SyncClient = class {
     this.devices = [];
     /** Latest snapshot payload per `${deviceId}::${toolId}`. */
     this.snapshots = /* @__PURE__ */ new Map();
-    /** Tools we've asked the broker to keep streaming, as `${deviceId}::${toolId}`. */
-    this.watching = /* @__PURE__ */ new Set();
+    /**
+     * Capture-mode watches this client holds, keyed by snapKey. Stored with
+     * their addressing because they have to be RE-SENT on every reconnect: the
+     * broker keys watch state by socket id, and a reconnect gets a new one.
+     */
+    this.watching = /* @__PURE__ */ new Map();
     /** In-flight actions awaiting a result, keyed by requestId. */
     this.pendingActions = /* @__PURE__ */ new Map();
     /** Callbacks waiting for the next snapshot of `${deviceId}::${toolId}`. */
@@ -144,6 +148,7 @@ var SyncClient = class {
         resolve();
       };
       socket.on("connect", onConnect);
+      socket.on("connect", () => this.rearmWatches());
       socket.once("connect_error", (err) => {
         if (settled) return;
         settled = true;
@@ -254,11 +259,50 @@ var SyncClient = class {
   // ----------------------------------------------------------------
   // Watch + snapshots
   // ----------------------------------------------------------------
+  /**
+   * Keep the device RECORDING this tool, without asking it to stream.
+   *
+   * A dashboard watches for as long as its panel is open; this client is
+   * request/response, so it used to watch and unwatch around every single
+   * read. That works for a tool whose state just IS (the query cache, the env
+   * table) and is useless for one that records a timeline: the unwatch drops
+   * the device's subscriber count to zero, which stops capture, so nothing is
+   * ever recorded between two reads. The list comes back empty and reads as
+   * "the app made no requests" — a wrong conclusion that is very expensive to
+   * chase, because everything about the app looks fine.
+   *
+   * Capture-mode watches are held for the life of the connection and released
+   * on disconnect (the broker also drops them for us). They cost the device's
+   * ring buffer, not the socket: no snapshot is pushed, and reads still go
+   * through `request-devtool-state`.
+   */
   ensureWatching(toolId, targetDeviceId) {
     const key = snapKey(targetDeviceId, toolId);
     if (this.watching.has(key)) return;
-    this.watching.add(key);
-    this.socket?.emit("devtool-watch", { toolId, targetDeviceId, watching: true });
+    this.watching.set(key, { toolId, targetDeviceId });
+    this.sendWatch(toolId, targetDeviceId);
+  }
+  sendWatch(toolId, targetDeviceId) {
+    this.socket?.emit("devtool-watch", {
+      toolId,
+      targetDeviceId,
+      watching: true,
+      stream: false
+    });
+  }
+  /**
+   * Re-arm every held watch after a reconnect.
+   *
+   * The broker tracks watches per SOCKET, so a reconnect (broker restart, a
+   * dropped wifi link) silently discards all of ours while `watching` still
+   * says we hold them — `ensureWatching` would then short-circuit forever and
+   * the device would never record again. Silent and permanent: the exact
+   * failure this whole capture-mode change exists to remove.
+   */
+  rearmWatches() {
+    for (const { toolId, targetDeviceId } of this.watching.values()) {
+      this.sendWatch(toolId, targetDeviceId);
+    }
   }
   /** Stop streaming a tool (releases the device-side backpressure). */
   unwatch(toolId, targetDeviceId) {
@@ -271,26 +315,25 @@ var SyncClient = class {
     return this.snapshots.get(snapKey(deviceId, toolId));
   }
   /**
-   * Get a tool's current state. Starts watching (so the device begins emitting),
-   * explicitly requests state, and resolves with the next snapshot. Falls back
-   * to the last cached snapshot if the request times out.
+   * Get a tool's current state: arm capture (once, for the connection), ask
+   * for state explicitly, and resolve with the snapshot that comes back.
+   * Falls back to the last cached snapshot if the request times out.
+   *
+   * The capture watch is deliberately NOT released afterwards — see
+   * `ensureWatching`. It costs the device nothing on the socket, and dropping
+   * it is what made every timeline tool look permanently empty from here.
    */
   async getSnapshot(toolId, deviceId, opts = {}) {
     const target = this.resolveDevice(deviceId);
     const key = snapKey(target, toolId);
-    const wasWatching = this.watching.has(key);
     this.ensureWatching(toolId, target);
-    try {
-      const next = this.waitForSnapshot(key, opts.timeoutMs ?? DEFAULT_SNAPSHOT_TIMEOUT_MS);
-      this.socket?.emit("request-devtool-state", { toolId, targetDeviceId: target });
-      const payload = await next;
-      if (payload !== void 0) return { deviceId: target, payload };
-      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?)`);
-    } finally {
-      if (!wasWatching) this.unwatch(toolId, target);
-    }
+    const next = this.waitForSnapshot(key, opts.timeoutMs ?? DEFAULT_SNAPSHOT_TIMEOUT_MS);
+    this.socket?.emit("request-devtool-state", { toolId, targetDeviceId: target });
+    const payload = await next;
+    if (payload !== void 0) return { deviceId: target, payload };
+    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?)`);
   }
   waitForSnapshot(key, timeoutMs) {
     return new Promise((resolve) => {
@@ -376,7 +419,7 @@ var import_node_os = __toESM(require("os"));
 var import_node_path = __toESM(require("path"));
 
 // src/version.ts
-var VERSION = "7.0.17" ? "7.0.17" : "0.0.0-dev";
+var VERSION = "7.0.19" ? "7.0.19" : "0.0.0-dev";
 var PACKAGE_NAME = "@buoy-gg/mcp";
 
 // src/update/checkForUpdate.ts
@@ -1377,6 +1420,60 @@ function truncate(v, n = 600) {
   const s = typeof v === "string" ? v : JSON.stringify(v);
   return s.length > n ? `${s.slice(0, n)}\u2026(+${s.length - n} chars)` : s;
 }
+var MAX_BODY_FETCHES = 8;
+async function resolveBodies(sync, rows, target, max = MAX_BODY_FETCHES) {
+  const needed = rows.filter(
+    (e) => e.id && (e.requestBodyOmitted === true && e.requestData === void 0 || e.responseBodyOmitted === true && e.responseData === void 0)
+  );
+  const bodies = /* @__PURE__ */ new Map();
+  if (needed.length === 0) return { bodies, skipped: 0 };
+  const take = needed.slice(0, max);
+  const settled = await Promise.allSettled(
+    take.map(
+      (e) => sync.callAction(NETWORK_TOOL_ID, "getEventBody", { id: e.id }, target)
+    )
+  );
+  settled.forEach((r, i) => {
+    const id = take[i].id;
+    const body = r.status === "fulfilled" ? r.value : null;
+    bodies.set(id, body ? { ...body } : { unresolved: true });
+  });
+  return { bodies, skipped: needed.length - take.length };
+}
+async function captureDiagnosis(sync, target) {
+  let status = null;
+  try {
+    status = await sync.callAction(
+      NETWORK_TOOL_ID,
+      "getCaptureStatus",
+      {},
+      target
+    );
+  } catch {
+    return "The network tool has captured nothing yet.";
+  }
+  if (!status || status.capturing !== false) {
+    return "The device IS capturing, so nothing has been requested since it started.";
+  }
+  return "The device is NOT capturing. Reading from here arms capture, so the very next read should see traffic \u2014 trigger it and call again. This is not an app or interception problem. (If it stays off, the device is on a Buoy older than the capture-mode watch: open the Network panel on the device or in Buoy Desktop to record.)";
+}
+function skippedNote(skipped) {
+  return skipped > 0 ? `
+
+_${skipped} more withheld ${skipped === 1 ? "body was" : "bodies were"} not fetched (cap ${MAX_BODY_FETCHES} per listing, they are large). Get one in full with its id._` : "";
+}
+function bodyLines(e, fetched) {
+  const got = e.id ? fetched.get(e.id) : void 0;
+  const label = (inline, resolved, omitted) => {
+    const value = inline ?? resolved;
+    if (value !== void 0 && value !== null) return truncate(value);
+    if (!omitted) return "(none)";
+    return got?.unresolved ? "(withheld \u2014 the device did not answer getEventBody)" : "(none)";
+  };
+  return `
+   \u2514\u2500 request: ${label(e.requestData, got?.requestData, e.requestBodyOmitted)}
+   \u2514\u2500 response: ${label(e.responseData, got?.responseData, e.responseBodyOmitted)}`;
+}
 function formatRow(index, e, markers) {
   const where = e.path || e.url;
   const bits = [
@@ -1430,6 +1527,7 @@ function registerNetworkTools(server, sync) {
 The developer pins/saves a request from the Network tool (long-press a row, or the pin/bookmark buttons in the request detail header), or you can with network_action.`
             );
           }
+          const kept = args.includeBodies ? await resolveBodies(sync, rows2.map((r) => r.event), target) : { bodies: /* @__PURE__ */ new Map(), skipped: 0 };
           const body2 = rows2.map((r, i) => {
             const marks = [r.pinned ? "\u{1F4CC} pinned" : "", r.saved ? "\u{1F516} saved" : ""].filter(Boolean).join(" ");
             const stale = r.event.id?.startsWith("saved:") ? " \xB7 from an earlier app run" : "";
@@ -1437,12 +1535,7 @@ The developer pins/saves a request from the Network tool (long-press a row, or t
             let out = formatRow(i + 1, r.event, marks);
             out += `
    \u2514\u2500 key \`${r.key}\`${stale}${trunc}`;
-            if (args.includeBodies) {
-              out += `
-   \u2514\u2500 request: ${truncate(r.event.requestData)}`;
-              out += `
-   \u2514\u2500 response: ${truncate(r.event.responseData)}`;
-            }
+            if (args.includeBodies) out += bodyLines(r.event, kept.bodies);
             return out;
           }).join("\n");
           return text3(
@@ -1450,23 +1543,19 @@ The developer pins/saves a request from the Network tool (long-press a row, or t
 
 ${body2}
 
-_These are snapshots: they survive Clear, the 500-request cap and app restarts. Remove one with network_action({action:"remove", key}). Ids starting \`saved:\` are from an earlier run of the app._`
+_These are snapshots: they survive Clear, the 500-request cap and app restarts. Remove one with network_action({action:"remove", key}). Ids starting \`saved:\` are from an earlier run of the app._${skippedNote(kept.skipped)}`
           );
         }
         const rows = events.filter((e) => matchesStatus(e, args.status)).filter((e) => !pattern || (e.url ?? "").toLowerCase().includes(pattern)).slice(0, limit);
         if (rows.length === 0) {
-          const why = events.length === 0 ? "The network tool has captured nothing yet (is it enabled, and has the app made a request?)." : "No request matched the filter.";
+          const why = events.length === 0 ? await captureDiagnosis(sync, target) : "No request matched the filter.";
           return text3(`No requests on ${target}. ${why}`);
         }
+        const live = args.includeBodies ? await resolveBodies(sync, rows, target) : { bodies: /* @__PURE__ */ new Map(), skipped: 0 };
         const body = rows.map((e, i) => {
           const marks = [pinnedIds.has(e.id) ? "\u{1F4CC}" : "", savedIds.has(e.id) ? "\u{1F516}" : ""].filter(Boolean).join("");
           let out = formatRow(i + 1, e, marks);
-          if (args.includeBodies) {
-            out += `
-   \u2514\u2500 request: ${truncate(e.requestData)}`;
-            out += `
-   \u2514\u2500 response: ${truncate(e.responseData)}`;
-          }
+          if (args.includeBodies) out += bodyLines(e, live.bodies);
           return out;
         }).join("\n");
         const keptNote = saved.length > 0 ? ` \xB7 ${saved.length} kept (flagged:'any' to list)` : "";
@@ -1475,7 +1564,7 @@ _These are snapshots: they survive Clear, the 500-request cap and app restarts.
 
 ${body}
 
-_\u{1F4CC} pinned \xB7 \u{1F516} saved. Act on one with its id, e.g. network_action({action:"pin", id:"${rows[0].id}"})._`
+_\u{1F4CC} pinned \xB7 \u{1F516} saved. Act on one with its id, e.g. network_action({action:"pin", id:"${rows[0].id}"})._${skippedNote(live.skipped)}`
         );
       } catch (e) {
         return fail4(errMsg4(e));
@@ -2423,12 +2512,13 @@ ${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, 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), 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", "restore", "delete", "rename"]).describe("What to do."),
+        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").'),
         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).")
       }
@@ -2449,9 +2539,36 @@ ${formatOutcome(p.lastOutcome)}`);
             const result = await call("captureBaseline", {});
             return text11(`Captured baseline \`${result.snapshot.id}\` \u2014 restoring it wipes app storage and reloads.`);
           }
+          case "preview": {
+            if (!args.id) return fail12("preview requires `id` (from get_time_machine).");
+            const result = await call("preview", { id: args.id });
+            const lines = [];
+            let totalApplies = 0;
+            for (const src of result.sources) {
+              const counts = {};
+              for (const item of src.items) {
+                counts[item.verdict] = (counts[item.verdict] ?? 0) + 1;
+              }
+              const applies = (counts.added ?? 0) + (counts.removed ?? 0) + (counts.changed ?? 0) + (counts["too-large"] ?? 0);
+              totalApplies += applies;
+              const parts = Object.entries(counts).filter(([v]) => v !== "unchanged").map(([v, n]) => `${n} ${v}`);
+              lines.push(`- **${src.label}**: ${parts.length ? parts.join(", ") : "no changes"}${src.error ? ` \u2014 \u26A0 ${src.error}` : ""}`);
+              for (const item of src.items.filter((i) => i.verdict !== "unchanged").slice(0, 8)) {
+                lines.push(`    ${item.verdict === "added" ? "+" : item.verdict === "removed" ? "\u2212" : item.verdict === "wont-apply" ? "\u2298" : "\u2248"} ${item.label}${item.reason ? ` (${item.reason})` : ""}`);
+              }
+              for (const note of src.notes) lines.push(`    \xB7 ${note}`);
+            }
+            const head = totalApplies === 0 ? "**Restore would change NOTHING** (states identical or nothing applicable)." : `**Restore would apply ${totalApplies} change(s):**`;
+            return text11(`${head}
+${lines.join("\n")}`);
+          }
           case "restore": {
             if (!args.id) return fail12("restore requires `id` (from get_time_machine).");
-            const outcome = await call("restore", { id: args.id, mode: args.mode ?? "live" });
+            const outcome = await call("restore", {
+              id: args.id,
+              mode: args.mode ?? "live",
+              excludeKeys: args.excludeKeys
+            });
             return text11(formatOutcome(outcome));
           }
           case "delete": {

package/dist/index.mjs

@@ -27,7 +27,7 @@ import {
   registerStorageTools,
   registerZustandTools,
   runInit
-} from "./chunk-7NCVMOMV.mjs";
+} from "./chunk-TZ2C4X6V.mjs";
 export {
   ALL_DEVICES,
   BROKER_PORT,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@buoy-gg/mcp",
   "mcpName": "io.github.buoy-gg/mcp",
-  "version": "7.0.17",
+  "version": "7.0.19",
   "description": "MCP server for Buoy devtools — lets any LLM copilot drive Buoy tools (perf-monitor benchmarks, etc.) over the devtool sync protocol",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -31,7 +31,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "socket.io-client": "^4.8.1",
     "zod": "^3.25.0",
-    "@buoy-gg/sync-broker": "^7.0.17"
+    "@buoy-gg/sync-broker": "^7.0.19"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",