@hienlh/ppm 0.18.14 → 0.18.15

package/src/services/edge-forwarder.ts

@@ -1,191 +1,191 @@
-/**
- * Edge forwarder — owns the public port and pipes raw TCP to the server's
- * current loopback port.
- *
- * ─── CRITICAL INVARIANT: THIS PROCESS MUST NEVER SPAWN A CHILD ───
- *
- * On Windows a child spawned with fd stdio inherits every inheritable handle,
- * including a listening socket. When such a descendant is orphaned it keeps the
- * socket open, so the port stays in LISTEN under a dead PID and can never be
- * rebound — a "zombie port". The server hits this constantly because it spawns
- * chat/tool/MCP subprocesses; those inherit its listener and wedge its port.
- *
- * The edge exists precisely because it spawns nothing, so its socket cannot be
- * inherited and its port cannot zombie. cloudflared can therefore stay pinned
- * to it forever and the public URL stops rotating. Adding any child-process
- * call to this file reintroduces the exact bug the edge was built to remove.
- *
- * Raw TCP, never HTTP: WebSocket upgrades and SSE streams pass through
- * untouched, and forwarded requests keep the headers cloudflared set.
- */
-import net from "node:net";
-import { resolveTargetPort, _resetTargetCache } from "./edge-target-resolver.ts";
-
-/** Delay between attempts while waiting for the server to come back. */
-const CONNECT_RETRY_MS = 250;
-/**
- * How long a client connection waits for a reachable server before giving up.
- * During an upgrade the server is briefly absent; refusing instantly would
- * surface as a broken page rather than a slow one.
- */
-const CONNECT_WINDOW_MS = 5000;
-
-const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
-
-/** Resolve once the socket is connected; reject on the first connect error. */
-function connectUpstream(port: number): Promise<net.Socket> {
-  return new Promise((resolvePromise, reject) => {
-    const upstream = net.connect({
-      port,
-      host: "127.0.0.1", // never taken from status.json — loopback only
-      allowHalfOpen: true,
-    });
-    const onError = (err: Error) => {
-      upstream.destroy();
-      reject(err);
-    };
-    upstream.once("error", onError);
-    upstream.once("connect", () => {
-      upstream.removeListener("error", onError);
-      resolvePromise(upstream);
-    });
-  });
-}
-
-/**
- * Largest amount of client data held while waiting for the server. Bounds the
- * memory a slow upload can pin during an upgrade window.
- */
-const MAX_PENDING_BYTES = 8 * 1024 * 1024;
-
-/**
- * Pipe one client connection to the server.
- *
- * Resolving the upstream is async, so the first bytes usually arrive before
- * there is anywhere to send them. They must be captured by a `data` listener
- * attached synchronously on this very tick and replayed once the upstream
- * exists.
- *
- * `socket.pause()` is NOT a substitute — verified against Bun 1.3.13: bytes
- * that arrive while paused are lost, and a later `pipe()`/`resume()` does not
- * bring them back. A socket with no `data` listener drops them outright too.
- * Both variants silently swallowed the first request in testing.
- */
-async function handleConnection(
-  client: net.Socket,
-  connectWindowMs: number,
-): Promise<void> {
-  const pending: Buffer[] = [];
-  let pendingBytes = 0;
-  let clientEnded = false;
-  const onEarlyData = (chunk: Buffer) => {
-    pendingBytes += chunk.length;
-    if (pendingBytes > MAX_PENDING_BYTES) {
-      client.destroy();
-      return;
-    }
-    pending.push(chunk);
-  };
-  client.on("data", onEarlyData);
-  client.once("end", () => { clientEnded = true; });
-
-  let upstream: net.Socket | null = null;
-  let clientGone = false;
-
-  // A socket error with no listener is an unhandled 'error' event, which would
-  // take the whole edge process — and the public port — down with it.
-  const teardown = () => {
-    upstream?.destroy();
-    client.destroy();
-  };
-  client.on("error", teardown);
-  client.once("close", () => { clientGone = true; });
-
-  const deadline = Date.now() + connectWindowMs;
-  while (!clientGone && Date.now() < deadline) {
-    const port = resolveTargetPort();
-    if (port !== null) {
-      try {
-        upstream = await connectUpstream(port);
-        break;
-      } catch {
-        // Server not up yet (or moved mid-restart) — re-resolve and retry.
-        _resetTargetCache();
-      }
-    }
-    await sleep(CONNECT_RETRY_MS);
-  }
-
-  if (clientGone) return;
-  if (!upstream) {
-    client.destroy();
-    return;
-  }
-
-  upstream.on("error", teardown);
-
-  // Replay what arrived during the connect, then hand both directions to the
-  // stream machinery. Removing the listener and piping happen in the same tick,
-  // so no chunk can slip through the gap.
-  client.off("data", onEarlyData);
-  for (const chunk of pending) upstream.write(chunk);
-  pending.length = 0;
-
-  client.pipe(upstream);
-  upstream.pipe(client);
-
-  // The client may have half-closed while we were still connecting.
-  if (clientEnded) upstream.end();
-}
-
-export interface EdgeForwarderOptions {
-  publicPort: number;
-  host?: string;
-  /** How long a client waits for a reachable server. Defaults to 5s. */
-  connectWindowMs?: number;
-}
-
-/**
- * Bind the public port and start forwarding. Resolves once listening so the
- * caller can fail fast when the port is unavailable.
- */
-export function startEdgeForwarder(
-  opts: EdgeForwarderOptions,
-): Promise<net.Server> {
-  const host = opts.host ?? "0.0.0.0";
-  const connectWindowMs = opts.connectWindowMs ?? CONNECT_WINDOW_MS;
-  return new Promise((resolvePromise, reject) => {
-    // allowHalfOpen keeps the other direction alive when one side sends FIN —
-    // long-lived chat WS and SSE streams depend on it.
-    const server = net.createServer({ allowHalfOpen: true }, (client) => {
-      void handleConnection(client, connectWindowMs);
-    });
-    server.once("error", reject);
-    server.listen(opts.publicPort, host, () => {
-      server.removeListener("error", reject);
-      resolvePromise(server);
-    });
-  });
-}
-
-// ─── Process entry ─────────────────────────────────────────────────────
-// Mirrors the `__serve__` guard in src/server/index.ts: the supervisor
-// re-invokes the binary as `<bin> __edge__ <publicPort> <host>`.
-if (process.argv.includes("__edge__")) {
-  const idx = process.argv.indexOf("__edge__");
-  const publicPort = parseInt(process.argv[idx + 1] ?? "", 10);
-  const host = process.argv[idx + 2] ?? "0.0.0.0";
-
-  if (!Number.isInteger(publicPort) || publicPort <= 0 || publicPort > 65535) {
-    process.stderr.write(`[edge] Invalid public port: ${process.argv[idx + 1]}\n`);
-    process.exit(2);
-  }
-
-  try {
-    await startEdgeForwarder({ publicPort, host });
-    process.stderr.write(`[edge] Listening on ${host}:${publicPort}\n`);
-  } catch (err) {
-    process.stderr.write(`[edge] Failed to bind ${host}:${publicPort}: ${err}\n`);
-    process.exit(1);
-  }
-}
+/**
+ * Edge forwarder — owns the public port and pipes raw TCP to the server's
+ * current loopback port.
+ *
+ * ─── CRITICAL INVARIANT: THIS PROCESS MUST NEVER SPAWN A CHILD ───
+ *
+ * On Windows a child spawned with fd stdio inherits every inheritable handle,
+ * including a listening socket. When such a descendant is orphaned it keeps the
+ * socket open, so the port stays in LISTEN under a dead PID and can never be
+ * rebound — a "zombie port". The server hits this constantly because it spawns
+ * chat/tool/MCP subprocesses; those inherit its listener and wedge its port.
+ *
+ * The edge exists precisely because it spawns nothing, so its socket cannot be
+ * inherited and its port cannot zombie. cloudflared can therefore stay pinned
+ * to it forever and the public URL stops rotating. Adding any child-process
+ * call to this file reintroduces the exact bug the edge was built to remove.
+ *
+ * Raw TCP, never HTTP: WebSocket upgrades and SSE streams pass through
+ * untouched, and forwarded requests keep the headers cloudflared set.
+ */
+import net from "node:net";
+import { resolveTargetPort, _resetTargetCache } from "./edge-target-resolver.ts";
+
+/** Delay between attempts while waiting for the server to come back. */
+const CONNECT_RETRY_MS = 250;
+/**
+ * How long a client connection waits for a reachable server before giving up.
+ * During an upgrade the server is briefly absent; refusing instantly would
+ * surface as a broken page rather than a slow one.
+ */
+const CONNECT_WINDOW_MS = 5000;
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/** Resolve once the socket is connected; reject on the first connect error. */
+function connectUpstream(port: number): Promise<net.Socket> {
+  return new Promise((resolvePromise, reject) => {
+    const upstream = net.connect({
+      port,
+      host: "127.0.0.1", // never taken from status.json — loopback only
+      allowHalfOpen: true,
+    });
+    const onError = (err: Error) => {
+      upstream.destroy();
+      reject(err);
+    };
+    upstream.once("error", onError);
+    upstream.once("connect", () => {
+      upstream.removeListener("error", onError);
+      resolvePromise(upstream);
+    });
+  });
+}
+
+/**
+ * Largest amount of client data held while waiting for the server. Bounds the
+ * memory a slow upload can pin during an upgrade window.
+ */
+const MAX_PENDING_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Pipe one client connection to the server.
+ *
+ * Resolving the upstream is async, so the first bytes usually arrive before
+ * there is anywhere to send them. They must be captured by a `data` listener
+ * attached synchronously on this very tick and replayed once the upstream
+ * exists.
+ *
+ * `socket.pause()` is NOT a substitute — verified against Bun 1.3.13: bytes
+ * that arrive while paused are lost, and a later `pipe()`/`resume()` does not
+ * bring them back. A socket with no `data` listener drops them outright too.
+ * Both variants silently swallowed the first request in testing.
+ */
+async function handleConnection(
+  client: net.Socket,
+  connectWindowMs: number,
+): Promise<void> {
+  const pending: Buffer[] = [];
+  let pendingBytes = 0;
+  let clientEnded = false;
+  const onEarlyData = (chunk: Buffer) => {
+    pendingBytes += chunk.length;
+    if (pendingBytes > MAX_PENDING_BYTES) {
+      client.destroy();
+      return;
+    }
+    pending.push(chunk);
+  };
+  client.on("data", onEarlyData);
+  client.once("end", () => { clientEnded = true; });
+
+  let upstream: net.Socket | null = null;
+  let clientGone = false;
+
+  // A socket error with no listener is an unhandled 'error' event, which would
+  // take the whole edge process — and the public port — down with it.
+  const teardown = () => {
+    upstream?.destroy();
+    client.destroy();
+  };
+  client.on("error", teardown);
+  client.once("close", () => { clientGone = true; });
+
+  const deadline = Date.now() + connectWindowMs;
+  while (!clientGone && Date.now() < deadline) {
+    const port = resolveTargetPort();
+    if (port !== null) {
+      try {
+        upstream = await connectUpstream(port);
+        break;
+      } catch {
+        // Server not up yet (or moved mid-restart) — re-resolve and retry.
+        _resetTargetCache();
+      }
+    }
+    await sleep(CONNECT_RETRY_MS);
+  }
+
+  if (clientGone) return;
+  if (!upstream) {
+    client.destroy();
+    return;
+  }
+
+  upstream.on("error", teardown);
+
+  // Replay what arrived during the connect, then hand both directions to the
+  // stream machinery. Removing the listener and piping happen in the same tick,
+  // so no chunk can slip through the gap.
+  client.off("data", onEarlyData);
+  for (const chunk of pending) upstream.write(chunk);
+  pending.length = 0;
+
+  client.pipe(upstream);
+  upstream.pipe(client);
+
+  // The client may have half-closed while we were still connecting.
+  if (clientEnded) upstream.end();
+}
+
+export interface EdgeForwarderOptions {
+  publicPort: number;
+  host?: string;
+  /** How long a client waits for a reachable server. Defaults to 5s. */
+  connectWindowMs?: number;
+}
+
+/**
+ * Bind the public port and start forwarding. Resolves once listening so the
+ * caller can fail fast when the port is unavailable.
+ */
+export function startEdgeForwarder(
+  opts: EdgeForwarderOptions,
+): Promise<net.Server> {
+  const host = opts.host ?? "0.0.0.0";
+  const connectWindowMs = opts.connectWindowMs ?? CONNECT_WINDOW_MS;
+  return new Promise((resolvePromise, reject) => {
+    // allowHalfOpen keeps the other direction alive when one side sends FIN —
+    // long-lived chat WS and SSE streams depend on it.
+    const server = net.createServer({ allowHalfOpen: true }, (client) => {
+      void handleConnection(client, connectWindowMs);
+    });
+    server.once("error", reject);
+    server.listen(opts.publicPort, host, () => {
+      server.removeListener("error", reject);
+      resolvePromise(server);
+    });
+  });
+}
+
+// ─── Process entry ─────────────────────────────────────────────────────
+// Mirrors the `__serve__` guard in src/server/index.ts: the supervisor
+// re-invokes the binary as `<bin> __edge__ <publicPort> <host>`.
+if (process.argv.includes("__edge__")) {
+  const idx = process.argv.indexOf("__edge__");
+  const publicPort = parseInt(process.argv[idx + 1] ?? "", 10);
+  const host = process.argv[idx + 2] ?? "0.0.0.0";
+
+  if (!Number.isInteger(publicPort) || publicPort <= 0 || publicPort > 65535) {
+    process.stderr.write(`[edge] Invalid public port: ${process.argv[idx + 1]}\n`);
+    process.exit(2);
+  }
+
+  try {
+    await startEdgeForwarder({ publicPort, host });
+    process.stderr.write(`[edge] Listening on ${host}:${publicPort}\n`);
+  } catch (err) {
+    process.stderr.write(`[edge] Failed to bind ${host}:${publicPort}: ${err}\n`);
+    process.exit(1);
+  }
+}

package/src/services/fs-credential-path-guard.ts

@@ -2,6 +2,7 @@ import { resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { getPpmDir } from "./ppm-dir.ts";
 import { getUploadsDir } from "./chat-upload-storage.service.ts";
+import { getBackupsDir } from "./db-backup/db-backup-paths.ts";
 import { realPathOrSelf } from "./fs-ops/fs-real-path.ts";
 
 /**
@@ -11,6 +12,9 @@ import { realPathOrSelf } from "./fs-ops/fs-real-path.ts";
  * cert). Split out of `fs-path-guard.service.ts` so this one seam — "is this
  * a credential path" — stays a single file instead of growing alongside the
  * platform-allowlist and protected-root logic that lives there.
+ *
+ * Three roots, not two: the PPM config DB, `~/.cloudflared`, and the database
+ * snapshot directory, which holds full copies of the first one.
  */
 
 /** Case-insensitive prefix test on Windows/macOS-style paths. */
@@ -50,9 +54,23 @@ export function isCloudflaredDirPath(resolved: string): boolean {
   return isInside(resolved, resolve(homedir(), ".cloudflared"));
 }
 
+/**
+ * True when the path is the database-snapshot directory or anything inside it.
+ *
+ * A snapshot is a byte-for-byte copy of the config database, so it carries the
+ * same provider keys, encrypted accounts, and auth token. In production that
+ * directory deliberately sits OUTSIDE `~/.ppm` (so it survives a wipe of the
+ * PPM directory), which means `isPpmDirPath` does not cover it — without this
+ * branch, moving snapshots out of the PPM directory would have quietly opened
+ * a credential-read hole through the generic file routes.
+ */
+export function isDbBackupsDirPath(resolved: string): boolean {
+  return isInside(resolved, getBackupsDir());
+}
+
 /** True when the path holds credential material a generic file route must never serve or relocate. */
 export function isCredentialPath(resolved: string): boolean {
-  return isPpmDirPath(resolved) || isCloudflaredDirPath(resolved);
+  return isPpmDirPath(resolved) || isCloudflaredDirPath(resolved) || isDbBackupsDirPath(resolved);
 }
 
 /**

package/src/services/named-tunnel/cloudflared-login.service.ts

@@ -98,7 +98,7 @@ export async function startLogin(opts: { relogin?: boolean } = {}): Promise<Logi
       // itself failed to run, so cert.pem is left untouched and the user
       // gets a clear, retryable error instead of an unwanted fresh login.
       if (liveCheck === "unreachable") {
-        setTerminal("error", "không kết nối được Cloudflare để kiểm tra đăng nhập — thử lại");
+        setTerminal("error", "could not reach Cloudflare to check the sign-in — try again");
         return getLoginSnapshot();
       }
 
@@ -117,7 +117,7 @@ export async function startLogin(opts: { relogin?: boolean } = {}): Promise<Logi
       renameCertAside();
     }
   } else {
-    // Explicit ?relogin=1 — the user deliberately pressed "Đăng nhập lại",
+    // Explicit ?relogin=1 — the user deliberately pressed "Sign in again",
     // so this renames unconditionally regardless of network reachability.
     renameCertAside();
   }

package/src/services/nested-subagent-spy.ts

@@ -0,0 +1,206 @@
+/**
+ * NestedSubagentSpy — surface nested-agent activity on a live Agent card.
+ *
+ * The SDK streams a subagent's events with `parent_tool_use_id` only for
+ * agents the session itself spawned. When that agent spawns another one
+ * (a reviewer running a skill that forks its own worker, a planner calling
+ * researchers), the CLI emits nothing for the nested agent — the parent card
+ * looks frozen on its last step for as long as the grandchild works, which
+ * can be many minutes.
+ *
+ * The nested agent does keep writing its transcript under
+ *   <sessionDir>/subagents/agent-<id>.jsonl
+ * with a meta whose `parentAgentId` chains back to the card's agent. While a
+ * card is open we tail those transcripts and emit their events stamped with
+ * the card's toolUseId, so they render flat inside the card exactly like the
+ * live depth-1 children do. Same shape as bashOutputSpy: start on tool_use,
+ * poll, stop on tool_result.
+ *
+ * One poller per session, not per card: the dir scan that finds nested agents
+ * is shared across every open card, so N cards cost one scan per tick.
+ *
+ * Spies live only in memory. A backgrounded agent that outlives the server
+ * process (or the session's consumer) loses live nested visibility until the
+ * next reload, where the transcript merger restores the same events from disk.
+ */
+
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { ChatEvent } from "../types/chat.ts";
+import { createAgentTranscriptLineParser } from "./subagent-transcript-merger.ts";
+import { groupSubagentsByCard } from "./team-member-activity/subagent-transcript-index.ts";
+
+const POLL_INTERVAL_MS = 1000;
+/** Repeated per-file read failures (locked/replaced file) log once per this window. */
+const WARN_THROTTLE_MS = 30_000;
+
+interface TranscriptTail {
+  bytesRead: number;
+  /** Unterminated trailing bytes — kept raw so a split multi-byte char survives. */
+  pending: Buffer;
+  parser: ReturnType<typeof createAgentTranscriptLineParser>;
+}
+
+interface CardSpy {
+  /** Tails keyed by nested agentId. */
+  tails: Map<string, TranscriptTail>;
+  onEvents: (events: ChatEvent[]) => void;
+}
+
+interface SessionSpy {
+  sessionId: string;
+  subagentsDir: string;
+  cards: Map<string, CardSpy>;
+  intervalId: ReturnType<typeof setInterval>;
+  lastWarnAt: number;
+}
+
+/** Keyed by sessionId — one poller shared by every open card of that session. */
+const sessions = new Map<string, SessionSpy>();
+
+/** Read bytes appended since the last tick; null when nothing new. Throws on I/O error. */
+function readAppended(filePath: string, tail: TranscriptTail): Buffer | null {
+  const size = statSync(filePath).size;
+  if (size <= tail.bytesRead) return null;
+  const fd = openSync(filePath, "r");
+  try {
+    const buf = Buffer.alloc(size - tail.bytesRead);
+    const n = readSync(fd, buf, 0, buf.length, tail.bytesRead);
+    tail.bytesRead += n;
+    return buf.subarray(0, n);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Split pending + chunk into complete lines; the unterminated remainder stays
+ * raw in `tail.pending` because a write can land mid-record, even mid-char.
+ */
+function drainLines(tail: TranscriptTail, chunk: Buffer): string[] {
+  const all = tail.pending.length ? Buffer.concat([tail.pending, chunk]) : chunk;
+  const lastNl = all.lastIndexOf(0x0a);
+  if (lastNl === -1) {
+    tail.pending = all;
+    return [];
+  }
+  tail.pending = all.subarray(lastNl + 1);
+  return all.subarray(0, lastNl).toString("utf8").split("\n");
+}
+
+function warnThrottled(spy: SessionSpy, message: string): void {
+  const now = Date.now();
+  if (now - spy.lastWarnAt < WARN_THROTTLE_MS) return;
+  spy.lastWarnAt = now;
+  console.warn(`[nested-spy] session=${spy.sessionId} ${message}`);
+}
+
+/** One poll for a session: scan the dir once, then drain each open card's nested tails. */
+function tick(spy: SessionSpy): void {
+  let groups: ReturnType<typeof groupSubagentsByCard>;
+  try {
+    groups = groupSubagentsByCard(spy.subagentsDir);
+  } catch (e) {
+    warnThrottled(spy, `scan failed: ${(e as Error).message}`);
+    return;
+  }
+  for (const [cardToolUseId, card] of spy.cards) {
+    const group = groups.get(cardToolUseId);
+    if (!group) continue;
+    const events: ChatEvent[] = [];
+    for (const agent of group) {
+      // Depth-1 (the card's own agent) is already streamed live by the SDK.
+      if (!agent.parentAgentId) continue;
+      let tail = card.tails.get(agent.agentId);
+      if (!tail) {
+        tail = { bytesRead: 0, pending: Buffer.alloc(0), parser: createAgentTranscriptLineParser() };
+        card.tails.set(agent.agentId, tail);
+      }
+      let chunk: Buffer | null;
+      try {
+        chunk = readAppended(agent.transcriptPath, tail);
+      } catch (e) {
+        // A locked or replaced file must not stall the other agents in the group.
+        warnThrottled(spy, `read failed for ${agent.agentId}: ${(e as Error).message}`);
+        continue;
+      }
+      if (!chunk) continue;
+      for (const line of drainLines(tail, chunk)) {
+        for (const timed of tail.parser.feed(line)) {
+          events.push(withParent(timed.ev, cardToolUseId));
+        }
+      }
+    }
+    if (events.length > 0) card.onEvents(events);
+  }
+}
+
+/** Stamp a child with the card it belongs to, keeping the event union intact. */
+function withParent(ev: ChatEvent, parentToolUseId: string): ChatEvent {
+  switch (ev.type) {
+    case "text":
+    case "thinking":
+    case "tool_use":
+    case "tool_result":
+      return { ...ev, parentToolUseId };
+    default:
+      return ev;
+  }
+}
+
+/**
+ * Start tailing nested transcripts for an open Agent/Task card.
+ * `sessionDir` is …/projects/<slug>/<sessionId>; its subagents/ child may not
+ * exist yet — the CLI creates it with the first subagent write, and the scan
+ * simply finds nothing until then.
+ */
+function startSpy(
+  sessionId: string,
+  cardToolUseId: string,
+  sessionDir: string,
+  onEvents: (events: ChatEvent[]) => void,
+): void {
+  let spy = sessions.get(sessionId);
+  if (!spy) {
+    const created: SessionSpy = {
+      sessionId,
+      subagentsDir: join(sessionDir, "subagents"),
+      cards: new Map(),
+      lastWarnAt: 0,
+      intervalId: setInterval(() => tick(created), POLL_INTERVAL_MS),
+    };
+    sessions.set(sessionId, created);
+    spy = created;
+  }
+  if (spy.cards.has(cardToolUseId)) return;
+  spy.cards.set(cardToolUseId, { tails: new Map(), onEvents });
+  console.log(`[nested-spy] session=${sessionId} started card=${cardToolUseId} (${spy.cards.size} open)`);
+}
+
+/** Stop a card's spy, draining whatever landed since the last poll first. */
+function stopSpy(cardToolUseId: string): void {
+  for (const spy of sessions.values()) {
+    if (!spy.cards.has(cardToolUseId)) continue;
+    // Final drain covers every open card; the spare work is one scan.
+    tick(spy);
+    spy.cards.delete(cardToolUseId);
+    console.log(`[nested-spy] session=${spy.sessionId} stopped card=${cardToolUseId} (${spy.cards.size} open)`);
+    if (spy.cards.size === 0) {
+      clearInterval(spy.intervalId);
+      sessions.delete(spy.sessionId);
+    }
+    return;
+  }
+}
+
+/** Stop every spy for a session (turn ended, session migrated, socket closed). */
+function stopAllForSession(sessionId: string): void {
+  const spy = sessions.get(sessionId);
+  if (!spy) return;
+  tick(spy);
+  clearInterval(spy.intervalId);
+  sessions.delete(sessionId);
+  console.log(`[nested-spy] session=${sessionId} stopped all (${spy.cards.size} cards)`);
+}
+
+export const nestedSubagentSpy = { startSpy, stopSpy, stopAllForSession };