@corenel/sidecar 0.3.2 → 0.4.0

package/dist/cli.js

@@ -21692,6 +21692,7 @@ var SidecarServer = class {
       case "session-destroy":
       case "session-commit":
       case "session-snapshots":
+      case "session-snapshot-usage":
       case "session-watch":
       case "session-unwatch":
         if (!this.authed) {
@@ -21877,6 +21878,11 @@ var SidecarServer = class {
           this.ch.send({ t: "session-snapshots-result", id, snapshots });
           return;
         }
+        case "session-snapshot-usage": {
+          const usage = sessions.snapshotUsage ? await sessions.snapshotUsage() : { usedBytes: 0, budgetBytes: 0, count: 0 };
+          this.ch.send({ t: "session-snapshot-usage-result", id, usage });
+          return;
+        }
         case "session-watch": {
           if (this.sessionWatch.has(m2.sessionId)) {
             this.ch.send({ t: "session-ok", id });
@@ -22331,10 +22337,18 @@ var SidecarServer = class {
   ask = (questions) => this.hostCall("ask", "ask", [questions]).then((v2) => v2, () => null);
 };
 
-// src/wsChannel.ts
+// ../harness/sidecar/wsChannel.ts
 function wsChannel(ws) {
   let handler = null;
   let closeHandler = null;
+  const pending = [];
+  const flushPending = () => {
+    if (ws.readyState !== ws.OPEN) return;
+    while (pending.length > 0) {
+      ws.send(JSON.stringify(pending.shift()));
+    }
+  };
+  ws.on("open", flushPending);
   ws.on("message", (data) => {
     if (!handler) return;
     try {
@@ -22348,7 +22362,11 @@ function wsChannel(ws) {
   });
   return {
     send(msg) {
-      if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(msg));
+      if (ws.readyState === ws.OPEN) {
+        ws.send(JSON.stringify(msg));
+      } else if (ws.readyState === ws.CONNECTING) {
+        pending.push(msg);
+      }
     },
     onMessage(h2) {
       handler = h2;
@@ -24052,7 +24070,34 @@ import { isAbsolute as isAbsolute3, relative as relative3, resolve as resolve3 }
 // ../tools-node/fileService.ts
 import { promises as fs4 } from "node:fs";
 import { join as join3, resolve as resolve2, relative as relative2, dirname as dirname2, sep as sep2, basename, isAbsolute as isAbsolute2 } from "node:path";
-var SKIP = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", ".next", ".cache", ".turbo"]);
+var SKIP = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  ".cache",
+  ".turbo",
+  "dist-corenel",
+  "test-results",
+  "playwright-report"
+]);
+var SKIP_PATHS = /* @__PURE__ */ new Set([".claude/skills"]);
+var COVERAGE_REPORT_MARKERS = /* @__PURE__ */ new Set([
+  "coverage-final.json",
+  "lcov.info",
+  "clover.xml",
+  "coverage-summary.json",
+  "prettify.js"
+]);
+async function looksLikeGeneratedCoverage(absDir) {
+  try {
+    const names = await fs4.readdir(absDir);
+    return names.some((n2) => COVERAGE_REPORT_MARKERS.has(n2));
+  } catch {
+    return false;
+  }
+}
 function escapesRoot(rel, platformSep = sep2) {
   if (rel === "") return false;
   if (rel === ".." || rel.startsWith(".." + platformSep)) return true;
@@ -24127,6 +24172,8 @@ var NodeFileService = class {
         if (SKIP.has(e2.name)) continue;
         const absChild = join3(absDir, e2.name);
         const path = normalizeFilePath(relative2(this.root, absChild));
+        if (e2.isDirectory() && SKIP_PATHS.has(path)) continue;
+        if (e2.isDirectory() && e2.name === "coverage" && await looksLikeGeneratedCoverage(absChild)) continue;
         if (e2.isDirectory()) {
           out.push({ name: e2.name, path, kind: "directory", children: await walk(absChild) });
         } else {
@@ -24458,6 +24505,34 @@ ${e2 instanceof Error ? e2.message : String(e2)}` });
   });
 }
 
+// src/session/snapshotBudget.ts
+var DEFAULT_SNAPSHOT_BUDGET_BYTES = 32 * 1024 ** 3;
+function parseByteSize(spelling) {
+  const s2 = spelling.trim();
+  const m2 = /^(\d+(?:\.\d+)?)\s*([KMGT]?)i?B?$/i.exec(s2);
+  if (!m2) throw new Error(`not a size: "${spelling}" (expected e.g. "8G", "512M", or a bare byte count)`);
+  const n2 = Number(m2[1]);
+  const unit = (m2[2] ?? "").toUpperCase();
+  const mult = unit === "K" ? 1024 : unit === "M" ? 1024 ** 2 : unit === "G" ? 1024 ** 3 : unit === "T" ? 1024 ** 4 : 1;
+  return Math.round(n2 * mult);
+}
+function formatByteSize(bytes) {
+  const units = [[1024 ** 4, "T"], [1024 ** 3, "G"], [1024 ** 2, "M"], [1024, "K"]];
+  for (const [mult, suffix] of units) {
+    if (bytes >= mult) return `${(bytes / mult).toFixed(1)}${suffix}`;
+  }
+  return `${bytes}B`;
+}
+function checkSnapshotBudget(check) {
+  const { usedBytes, estimateBytes, budgetBytes } = check;
+  const projected = usedBytes + estimateBytes;
+  if (projected <= budgetBytes) return { ok: true };
+  return {
+    ok: false,
+    message: `refusing to capture: session snapshots already use ${formatByteSize(usedBytes)} of a ${formatByteSize(budgetBytes)} budget, and this capture could add up to ${formatByteSize(estimateBytes)} more. Free space by removing snapshots you no longer need (\`msb snapshot list\`, \`msb snapshot remove <name>\`), or raise the ceiling with --snapshot-budget <size>.`
+  };
+}
+
 // src/session/microvmBackend.ts
 var GUEST_WORKDIR = "/workspace";
 var seq2 = 0;
@@ -24578,6 +24653,14 @@ function makeMicrovmBackend(deps) {
     }
     return r2.stdout;
   };
+  const listSnapshotsRaw = async () => {
+    const r2 = await deps.run(snapshotListArgs());
+    if (r2.code !== 0) {
+      const detail = (r2.stderr || r2.stdout).trim().split("\n").slice(-2).join("; ");
+      throw new Error(`list snapshots failed (msb exit ${r2.code}): ${detail || "no output"}`);
+    }
+    return parseSnapshotList(r2.stdout);
+  };
   let lastReconcile = 0;
   let reconciling = false;
   const RECONCILE_MS = 1e4;
@@ -24905,7 +24988,13 @@ function makeMicrovmBackend(deps) {
           workdir,
           createdAt: Number.isFinite(stamped) && stamped > 0 ? stamped : row.createdAt ?? now2(),
           ...owner ? { owner } : {},
-          ...repoUrl && repoCommit ? { source: { url: repoUrl, commit: repoCommit, ...repoRef ? { ref: repoRef } : {} } } : {}
+          ...repoUrl && repoCommit ? { source: { url: repoUrl, commit: repoCommit, ...repoRef ? { ref: repoRef } : {} } } : {},
+          /* THE ONLY PLACE THIS IS EVER SET TRUE. `create()` never touches it,
+           * so a card can tell "this daemon booted it" from "this daemon
+           * found it already running" — procs.ts's own words: a running
+           * process nobody can see is worse than one that died, and adoption
+           * used to be invisible past this log line. */
+          adopted: true
         });
         adopted.push(id);
       }
@@ -24944,6 +25033,12 @@ function makeMicrovmBackend(deps) {
           `session ${id} must be paused before it can be captured (it is "${s2.status}"): pause first and check the drain result, or the snapshot may be torn`
         );
       }
+      const existing = await listSnapshotsRaw();
+      const usedBytes = existing.reduce((sum, snap) => sum + (snap.sizeBytes ?? 0), 0);
+      const budgetBytes = deps.snapshotBudgetBytes ?? DEFAULT_SNAPSHOT_BUDGET_BYTES;
+      const estimateBytes = parseByteSize(limits.rootDisk);
+      const budget = checkSnapshotBudget({ usedBytes, estimateBytes, budgetBytes });
+      if (!budget.ok) throw new Error(budget.message);
       const snapName = name ?? `${sandboxName(id)}-${now2()}-${++snapSeq}`;
       await msb([
         "snapshot",
@@ -24975,12 +25070,19 @@ function makeMicrovmBackend(deps) {
      * memory would show nothing after a restart while the artifacts sat on
      * disk. */
     async snapshots() {
-      const r2 = await deps.run(snapshotListArgs());
-      if (r2.code !== 0) {
-        const detail = (r2.stderr || r2.stdout).trim().split("\n").slice(-2).join("; ");
-        throw new Error(`list snapshots failed (msb exit ${r2.code}): ${detail || "no output"}`);
-      }
-      return parseSnapshotList(r2.stdout);
+      return listSnapshotsRaw();
+    },
+    /** Current usage against the refuse-at-budget ceiling, BEFORE a capture
+     * ever hits it — a budget you only learn about at the moment it stops you
+     * is a bad budget. Same arithmetic `commit()` checks against, so a caller
+     * watching this can see a refusal coming. */
+    async snapshotUsage() {
+      const existing = await listSnapshotsRaw();
+      return {
+        usedBytes: existing.reduce((sum, snap) => sum + (snap.sizeBytes ?? 0), 0),
+        budgetBytes: deps.snapshotBudgetBytes ?? DEFAULT_SNAPSHOT_BUDGET_BYTES,
+        count: existing.length
+      };
     }
   };
 }
@@ -25091,7 +25193,10 @@ function toInfo(h2, backend) {
     // Read from the HANDLE, so it survives every later list() — and, on the
     // microVM backend, a daemon restart, since the sandbox carries it in its
     // own labels.
-    ...h2.source ? { source: h2.source } : {}
+    ...h2.source ? { source: h2.source } : {},
+    // Same reasoning as `source`: a client cannot derive "this daemon found
+    // it running rather than booted it" from anything else it is given.
+    ...h2.adopted ? { adopted: true } : {}
   };
 }
 function makeSessionsPort(deps) {
@@ -25167,6 +25272,9 @@ function makeSessionsPort(deps) {
         ...s2.sizeBytes !== void 0 ? { sizeBytes: s2.sizeBytes } : {}
       }))
     } : {},
+    ...backend.snapshotUsage ? {
+      snapshotUsage: () => backend.snapshotUsage()
+    } : {},
     ...backend.metrics ? {
       watchMetrics: (id, onSample) => {
         const st2 = backend.metrics(id, onSample);
@@ -28012,6 +28120,7 @@ async function wireSessions(opts) {
     image: opts.image,
     // Safe to apply everywhere: it only rewrites drive-letter paths.
     hostPath: wslHostPath,
+    ...opts.snapshotBudgetBytes !== void 0 ? { snapshotBudgetBytes: opts.snapshotBudgetBytes } : {},
     ...opts.log ? { log: opts.log } : {}
   });
   const manager = new SessionManager({
@@ -28891,24 +29000,75 @@ function ensureWritable(path) {
     throw new Error(`${PROMPD_INSTALL_DIR}/ install dirs are read-only (managed by package install). Refusing to modify "${path}". Install or remove packages instead of editing them directly.`);
   }
 }
-function flatten(nodes, out = []) {
-  for (const n2 of nodes) {
-    out.push(`${n2.kind === "directory" ? "[dir] " : ""}${n2.path}${n2.kind === "file" && n2.size != null ? ` (${n2.size}b)` : ""}`);
-    if (n2.children?.length) flatten(n2.children, out);
+function describe(n2) {
+  return `${n2.kind === "directory" ? "[dir] " : ""}${n2.path}${n2.kind === "file" && n2.size != null ? ` (${n2.size}b)` : ""}`;
+}
+function bfsNodes(roots, maxDepth = Infinity) {
+  const out = [];
+  let level = roots;
+  let depth = 1;
+  while (level.length) {
+    const next = [];
+    for (const n2 of level) {
+      out.push(n2);
+      if (n2.kind === "directory" && n2.children?.length && depth < maxDepth) next.push(...n2.children);
+    }
+    level = next;
+    depth++;
+  }
+  return out;
+}
+var LIST_FILES_MAX_ENTRIES = 300;
+function selectByBreadthFirstCap(roots, maxDepth) {
+  const bfs = bfsNodes(roots, maxDepth);
+  return { keep: new Set(bfs.slice(0, LIST_FILES_MAX_ENTRIES)), total: bfs.length };
+}
+function describeInTreeOrder(roots, keep, maxDepth = Infinity, depth = 1, out = []) {
+  for (const n2 of roots) {
+    if (!keep.has(n2)) continue;
+    out.push(describe(n2));
+    if (n2.kind === "directory" && n2.children?.length && depth < maxDepth) {
+      describeInTreeOrder(n2.children, keep, maxDepth, depth + 1, out);
+    }
   }
   return out;
 }
+function truncationMarker(total, maxDepth) {
+  const omitted = total - LIST_FILES_MAX_ENTRIES;
+  const omittedEntries = `${omitted} more entr${omitted === 1 ? "y" : "ies"} omitted`;
+  if (maxDepth != null && Number.isFinite(maxDepth)) {
+    return `\u2026 truncated: ${omittedEntries}. ${total} entries were collected within depth ${maxDepth}; deeper levels were not counted, so this is not the size of the whole tree. Pass \`dir\` to narrow by subdirectory, or a larger \`depth\` to go deeper.`;
+  }
+  return `\u2026 truncated: ${omittedEntries} (${total} total). Pass \`dir\` to list a specific subdirectory (narrower breadth), or \`depth\` to limit how many levels deep the listing goes (narrower depth), instead of the whole tree.`;
+}
+function normalizeDepth(args) {
+  const v2 = args["depth"];
+  if (v2 == null) return void 0;
+  const n2 = typeof v2 === "number" ? v2 : typeof v2 === "string" ? Number(v2) : NaN;
+  if (!Number.isFinite(n2)) return void 0;
+  const floored = Math.floor(n2);
+  return floored < 1 ? 1 : floored;
+}
 var listFilesTool = {
   name: "list_files",
-  description: "List files and directories in the workspace (the open folder or the virtual workspace). Optionally pass `dir` to list a subdirectory. Returns paths relative to the workspace root.",
+  description: "List files and directories in the workspace (the open folder or the virtual workspace). Start shallow and drill in: pass `depth` to limit how many levels deep the listing goes (vertical narrowing \u2014 `depth: 1` returns just the immediate children of the target, a quick orientation call) and/or `dir` to list a specific subdirectory instead of the whole tree (horizontal narrowing). Omit `depth` for a full recursive listing. Returns paths relative to the workspace root.",
   parameters: {
     type: "object",
-    properties: { dir: { type: "string", description: "Subdirectory to list (optional; omit for the root)." } }
+    properties: {
+      dir: { type: "string", description: "Subdirectory to list (optional; omit for the root)." },
+      depth: {
+        type: "number",
+        description: "How many levels deep to list (optional; omit for the full recursive tree). 1 = immediate children of `dir` (or the root) only, 2 = two levels, and so on. Values below 1 (0, negative) are treated as 1, not rejected."
+      }
+    }
   },
   async run(args, ctx) {
     const files = requireFiles(ctx);
     const nodes = await files.list(str(args, "dir") || void 0);
-    const lines = flatten(nodes);
+    const maxDepth = normalizeDepth(args);
+    const { keep, total } = selectByBreadthFirstCap(nodes, maxDepth);
+    const lines = describeInTreeOrder(nodes, keep, maxDepth);
+    if (total > LIST_FILES_MAX_ENTRIES) lines.push(truncationMarker(total, maxDepth));
     return lines.length ? lines.join("\n") : "(empty)";
   }
 };
@@ -29647,7 +29807,7 @@ function allTools() {
   return [...defaultTools, ...extensionTools()];
 }
 
-// ../crew/callAgent.ts
+// ../harness/tools/callAgent.ts
 function str5(v2) {
   return typeof v2 === "string" ? v2.trim() : "";
 }
@@ -36875,6 +37035,7 @@ var BUILTIN_NAMESPACES = {
   ask_user: "agent",
   spawn_agent: "agent",
   spawn_agents: "agent",
+  call_agent: "agent",
   todo_write: "agent",
   // Named here as a backstop; the sidecar's own decls also carry `namespace`,
   // and an explicit field always wins (resolveNamespace). Both say the same
@@ -36893,7 +37054,17 @@ var BUILTIN_NAMESPACES = {
   view_strategy: "agent",
   run_strategy: "agent",
   list_strategies: "agent",
-  list_saved_strategies: "agent"
+  list_saved_strategies: "agent",
+  // Long-lived process control (proc_start/proc_stop/proc_list, see tools/procs.ts).
+  // `shell` is its own subject, deliberately distinct from the one-shot exec's
+  // `sidecar:shell_exec`: a process that stays running is a different risk from
+  // one that returns, and one address lets an operator ban (or allow) both
+  // start and stop together. proc_list is a read - it namespaces as `sidecar`
+  // (like the other machine-state reads) so it is NOT swept up by a `shell:*`
+  // deny; listing what is running carries none of spawn/kill's risk.
+  proc_start: "shell",
+  proc_stop: "shell",
+  proc_list: "sidecar"
 };
 function resolveNamespace(tool) {
   if (tool.namespace) return tool.namespace;
@@ -36921,6 +37092,7 @@ function toolAddress(tool) {
       }
     }
   }
+  if (ns === "shell" && (leaf === "proc_start" || leaf === "proc_stop")) leaf = "spawn";
   return `${ns}:${leaf}`;
 }
 
@@ -36932,8 +37104,12 @@ function effectiveThreshold(mode, fill = 0) {
   const factor = fill < 0.5 ? 1 : fill < 0.7 ? 0.7 : fill < 0.85 ? 0.5 : 0.35;
   return Math.max(FLOOR[mode], Math.round(BASE[mode] * factor));
 }
+var OFFLOAD_MARKER_PREFIX = "[offloaded tool result \xB7 ";
+function isOffloadPointer(content) {
+  return content.startsWith(OFFLOAD_MARKER_PREFIX);
+}
 function formatOffloadRef(ref) {
-  const head = `[offloaded tool result \xB7 ${ref.toolName} \xB7 ${ref.bytes.toLocaleString()} bytes \xB7 recall the full content with recall_result({ id: "${ref.id}" })]`;
+  const head = `${OFFLOAD_MARKER_PREFIX}${ref.toolName} \xB7 ${ref.bytes.toLocaleString()} bytes \xB7 recall the full content with recall_result({ id: "${ref.id}" })]`;
   return ref.preview ? `${head}
 --- preview ---
 ${ref.preview}${ref.bytes > ref.preview.length ? "\n\u2026(truncated)" : ""}` : head;
@@ -36956,7 +37132,9 @@ async function runAgent(args) {
   const permission = args.permission;
   const compression = args.compression;
   const ctxWindow = compression?.contextWindow;
+  const compressionStrategy = compression?.strategy ?? "eager";
   let fill = 0;
+  const deferredOffloads = [];
   const maxTurns = policy.maxTurns ?? args.maxTurns ?? 8;
   const signal = args.signal ?? new AbortController().signal;
   const emit = (e2) => args.onEvent?.(e2);
@@ -36973,6 +37151,9 @@ async function runAgent(args) {
     function: { name: t2.name, description: t2.description, parameters: t2.parameters }
   }));
   const toolByName = new Map(tools.map((t2) => [t2.name, t2]));
+  if (compressionStrategy === "deferred" && compression && compression.mode !== "off" && toolCtx.recall) {
+    await compactIncomingOffloads(messages, toolByName, compression, toolCtx.recall, emit);
+  }
   const usage = { promptTokens: 0, completionTokens: 0 };
   let text = "";
   let stopReason = "stop";
@@ -37046,6 +37227,13 @@ async function runAgent(args) {
       stopReason = "error";
       break;
     }
+    if (compressionStrategy === "deferred" && deferredOffloads.length) {
+      for (const o2 of deferredOffloads) {
+        const orig = messages[o2.index];
+        if (orig.role === "tool") messages[o2.index] = { ...orig, content: formatOffloadRef(o2.ref) };
+      }
+      deferredOffloads.length = 0;
+    }
     usage.promptTokens += streamed.usage.promptTokens;
     usage.completionTokens += streamed.usage.completionTokens;
     if (ctxWindow && ctxWindow > 0 && streamed.usage.promptTokens) {
@@ -37121,14 +37309,21 @@ async function runAgent(args) {
         const decision = await permission.check({ name: tool.name, address, mutates: tool.mutates, permission: tool.permission }, parsed);
         emit({ type: "permission", tool: tool.name, decision });
         if (decision === "deny") {
-          messages.push({ role: "tool", tool_call_id: call.id, content: "Permission denied by the user \u2014 the action was not performed." });
+          const denialMsg = args.describePermissionDenial?.(tool.name) ?? "Permission denied by the user \u2014 the action was not performed.";
+          messages.push({ role: "tool", tool_call_id: call.id, content: denialMsg });
           emit({ type: "tool-result", id: call.id, name: tool.name, result: "permission denied", isError: true });
           continue;
         }
       }
       const startedAt = Date.now();
+      let callSettled = false;
+      const stream = (text2) => {
+        if (callSettled) return;
+        emit({ type: "tool-delta", id: call.id, name: call.name, delta: text2 });
+      };
       try {
-        const result = await tool.run(parsed, { ...toolCtx, callId: call.id });
+        const result = await tool.run(parsed, { ...toolCtx, callId: call.id, stream });
+        callSettled = true;
         const durationMs = Date.now() - startedAt;
         gstate.toolCalls++;
         gstate.calledTools.add(tool.name);
@@ -37142,8 +37337,12 @@ async function runAgent(args) {
           if (result.length > effectiveThreshold(compression.mode, fill)) {
             try {
               const ref = await toolCtx.recall.record(tool.name, result);
-              out = formatOffloadRef(ref);
               emit({ type: "offload", id: ref.id, name: tool.name, bytes: ref.bytes });
+              if (compressionStrategy === "deferred") {
+                deferredOffloads.push({ index: messages.length, ref });
+              } else {
+                out = formatOffloadRef(ref);
+              }
             } catch {
               out = result;
             }
@@ -37152,6 +37351,7 @@ async function runAgent(args) {
         messages.push({ role: "tool", tool_call_id: call.id, content: out });
         emit({ type: "tool-result", id: call.id, name: call.name, result: out, durationMs });
       } catch (e2) {
+        callSettled = true;
         const errMsg = String(e2?.message || e2);
         const kind2 = classifyToolError(errMsg);
         const attempt = toolFails.fail(tool.name, kind2);
@@ -37175,6 +37375,30 @@ async function runAgent(args) {
   emit({ type: "done", reason: stopReason });
   return { messages, text, usage, stopReason };
 }
+async function compactIncomingOffloads(messages, toolByName, compression, recall, emit) {
+  const nameForCallId = /* @__PURE__ */ new Map();
+  for (const m2 of messages) {
+    if (m2.role === "assistant" && m2.tool_calls) {
+      for (const c2 of m2.tool_calls) nameForCallId.set(c2.id, c2.function.name);
+    }
+  }
+  for (let i2 = 0; i2 < messages.length; i2++) {
+    const m2 = messages[i2];
+    if (m2.role !== "tool" || typeof m2.content !== "string") continue;
+    if (isOffloadPointer(m2.content)) continue;
+    const toolName = nameForCallId.get(m2.tool_call_id);
+    if (!toolName) continue;
+    const tool = toolByName.get(toolName);
+    if (!tool || tool.noOffload) continue;
+    if (m2.content.length <= effectiveThreshold(compression.mode, 0)) continue;
+    try {
+      const ref = await recall.record(toolName, m2.content);
+      messages[i2] = { ...m2, content: formatOffloadRef(ref) };
+      emit({ type: "offload", id: ref.id, name: toolName, bytes: ref.bytes });
+    } catch {
+    }
+  }
+}
 function reconcileDanglingToolCalls(messages) {
   let idx = -1;
   for (let i2 = messages.length - 1; i2 >= 0; i2--) {
@@ -39377,6 +39601,114 @@ async function runHostsCli(argv) {
 
 // src/sessionsCli.ts
 import { resolve as resolve6 } from "node:path";
+
+// ../harness/sessions/fileRecallStore.ts
+var UNATTACHED_SESSION = "_unattached";
+
+// ../harness/sessions/blobGc.ts
+var DEFAULT_UNATTACHED_GRACE_MS = 30 * 60 * 1e3;
+var MARKER_ID_RE = /recall_result\(\{\s*id:\s*\\?"([^"\\]+)\\?"\s*\}\)/g;
+async function globalReferencedIds(files, root, sessionDirs) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const dir of sessionDirs) {
+    if (!dir.hasSessionLog) continue;
+    const text = await files.read(`${root}/${dir.id}/SESSION.jsonl`).catch(() => null);
+    if (text == null) continue;
+    for (const m2 of text.matchAll(MARKER_ID_RE)) {
+      const id = m2[1];
+      if (id) ids.add(id);
+    }
+  }
+  return ids;
+}
+async function listSessionDirs(files, root) {
+  const nodes = await files.list(root).catch(() => []);
+  const flat = flattenFiles(nodes).filter((f2) => f2.path.startsWith(`${root}/`));
+  const dirs = /* @__PURE__ */ new Map();
+  for (const f2 of flat) {
+    const rest = f2.path.slice(root.length + 1);
+    const slash = rest.indexOf("/");
+    if (slash < 0) continue;
+    const id = rest.slice(0, slash);
+    const isSessionLog = rest === `${id}/SESSION.jsonl`;
+    if (!dirs.has(id)) dirs.set(id, false);
+    if (isSessionLog) dirs.set(id, true);
+  }
+  return [...dirs.entries()].map(([id, hasSessionLog]) => ({ id, hasSessionLog }));
+}
+async function listBlobs(files, root, sessionId) {
+  const dir = `${root}/${sessionId}/blobs`;
+  const nodes = await files.list(dir).catch(() => []);
+  const blobFiles = flattenFiles(nodes).filter((f2) => f2.path.startsWith(`${dir}/`) && f2.path.endsWith(".json"));
+  const out = [];
+  for (const f2 of blobFiles) {
+    const text = await files.read(f2.path).catch(() => null);
+    if (text == null) continue;
+    try {
+      const record = JSON.parse(text);
+      if (record && typeof record.id === "string") out.push({ path: f2.path, record });
+    } catch {
+    }
+  }
+  return out;
+}
+async function planBlobGc(files, opts = {}) {
+  const root = opts.root ?? sessionsRoot();
+  const now2 = (opts.now ?? Date.now)();
+  const graceMs = opts.graceMs ?? DEFAULT_UNATTACHED_GRACE_MS;
+  const sessionDirs = await listSessionDirs(files, root);
+  const referenced = await globalReferencedIds(files, root, sessionDirs);
+  const reapable = [];
+  const liveUnreferenced = [];
+  for (const dir of sessionDirs) {
+    const blobs = await listBlobs(files, root, dir.id);
+    for (const { path, record } of blobs) {
+      const isReferenced = referenced.has(record.id);
+      const base = {
+        sessionId: dir.id,
+        id: record.id,
+        path,
+        bytes: record.bytes,
+        toolName: record.toolName,
+        createdAt: record.createdAt
+      };
+      if (isReferenced) continue;
+      if (dir.id === UNATTACHED_SESSION) {
+        const age = now2 - record.createdAt;
+        if (age < graceMs) continue;
+        reapable.push({
+          ...base,
+          disposition: "reap",
+          reason: `unattached, unreferenced, and ${Math.round(age / 6e4)}m old (grace is ${Math.round(graceMs / 6e4)}m)`
+        });
+        continue;
+      }
+      if (!dir.hasSessionLog) {
+        reapable.push({ ...base, disposition: "reap", reason: "owning session directory has no SESSION.jsonl" });
+        continue;
+      }
+      liveUnreferenced.push({ ...base, disposition: "report-only", reason: "unreferenced, but the owning session is live \u2014 not deleted by this tool" });
+    }
+  }
+  return {
+    reapable,
+    liveUnreferenced,
+    reapableBytes: reapable.reduce((sum, e2) => sum + e2.bytes, 0),
+    liveUnreferencedBytes: liveUnreferenced.reduce((sum, e2) => sum + e2.bytes, 0)
+  };
+}
+async function runBlobGc(files, opts = {}) {
+  const plan = await planBlobGc(files, opts);
+  if (!opts.delete) return { plan, removed: [] };
+  const removed = [];
+  for (const entry of plan.reapable) {
+    await files.remove(entry.path).catch(() => void 0);
+    removed.push(entry);
+  }
+  return { plan, removed };
+}
+
+// src/sessionsCli.ts
 async function sandboxLifecycle(run, verb, name) {
   const call = async (args) => {
     const r2 = await run(args).catch((e2) => ({ code: 1, stdout: "", stderr: String(e2) }));
@@ -39448,6 +39780,31 @@ function formatSession(r2) {
     ...r2.repo ? [`repo     ${r2.repo}`] : []
   ].join("\n");
 }
+function formatBlobGcReport(result, deleted) {
+  const line = (e2) => `  ${e2.path}  ${formatByteSize(e2.bytes)}  (${e2.reason})`;
+  const lines = [];
+  const { plan } = result;
+  if (!plan.reapable.length && !plan.liveUnreferenced.length) {
+    lines.push("no unattached blobs found.");
+    return lines.join("\n");
+  }
+  if (plan.reapable.length) {
+    lines.push(deleted ? `removed ${result.removed.length} blob(s), ${formatByteSize(plan.reapableBytes)} freed:` : `would remove ${plan.reapable.length} blob(s), ${formatByteSize(plan.reapableBytes)} total:`);
+    lines.push(...plan.reapable.map(line));
+  } else {
+    lines.push("nothing is reap-eligible.");
+  }
+  if (plan.liveUnreferenced.length) {
+    lines.push("");
+    lines.push(`${plan.liveUnreferenced.length} unreferenced blob(s) in live sessions, ${formatByteSize(plan.liveUnreferencedBytes)} total (not removed by this tool):`);
+    lines.push(...plan.liveUnreferenced.map(line));
+  }
+  if (!deleted && plan.reapable.length) {
+    lines.push("");
+    lines.push("pass --delete to remove the first list. Nothing above was touched.");
+  }
+  return lines.join("\n");
+}
 var DEFAULT_GUEST_IMAGE = "corenel-guest:dev";
 function backendFor(deps, roots, run) {
   return makeMicrovmBackend({
@@ -39619,13 +39976,28 @@ async function runSessionsCli(argv, deps) {
       return 0;
     } catch (e2) {
       err(`corenel sessions ${verb}: ${e2 instanceof Error ? e2.message : String(e2)}
+`);
+      return 1;
+    }
+  }
+  if (verb === "gc") {
+    const root = rootFrom(argv, process.cwd());
+    const doDelete = argv.includes("--delete");
+    try {
+      const files = new NodeFileService(root);
+      const result = await runBlobGc(files, { delete: doDelete });
+      out(`${formatBlobGcReport(result, doDelete)}
+`);
+      return 0;
+    } catch (e2) {
+      err(`corenel sessions gc: ${e2 instanceof Error ? e2.message : String(e2)}
 `);
       return 1;
     }
   }
   err(`corenel sessions: unknown subcommand "${verb}"
   usage: corenel sessions [list | show <id> | create [--root <dir>] | run <id> "<prompt>"
-                          | pause <id> | resume <id> | destroy <id>]
+                          | pause <id> | resume <id> | destroy <id> | gc [--delete]]
 `);
   return 1;
 }
@@ -39664,6 +40036,7 @@ var FLAGS = [
   { flag: "--isolation", arg: "<none|microvm>", help: "How a session confines a run: none (this process) or microvm (a sandbox per session, needs msb). Default none." },
   { flag: "--msb", arg: "<path>", help: "Path to the msb binary, for --isolation microvm." },
   { flag: "--guest-image", arg: "<ref>", help: "Image a session boots (default corenel-guest:dev). Pin by digest for anything snapshotted." },
+  { flag: "--snapshot-budget", arg: "<size>", help: "Ceiling on TOTAL bytes used by session snapshots (default 32G). A capture that would exceed it is refused, never pruned; size accepts K/M/G/T suffixes." },
   { flag: "--clone-under", arg: "<dir>", help: "Let a session clone a repository into <dir>. Repeatable. Off by default; the clone runs on THIS host with your own git credentials, which never enter the session." },
   { flag: "--keep-transcripts", help: "PERMIT session runs to keep their words, not just metadata. Off by default; each run still has to ask, and none can ask past this." },
   { flag: "--acp", arg: "<target>", help: "Proxy an external ACP agent (claude-code). Needs --root." },
@@ -39792,6 +40165,7 @@ function parseArgs(argv) {
     isolation: "none",
     msbBin: process.env.MSB_BIN ?? "msb",
     guestImage: "corenel-guest:dev",
+    snapshotBudgetBytes: DEFAULT_SNAPSHOT_BUDGET_BYTES,
     selfSigned: false,
     open: false,
     appUrl: "https://corenel.ai",
@@ -39828,7 +40202,15 @@ function parseArgs(argv) {
       out.isolation = v2;
     } else if (a2 === "--msb") out.msbBin = argv[++i2];
     else if (a2 === "--guest-image") out.guestImage = argv[++i2];
-    else if (a2 === "--allow-lan") out.allowLan = true;
+    else if (a2 === "--snapshot-budget") {
+      const v2 = argv[++i2];
+      if (v2 === void 0) throw new Error('--snapshot-budget needs a size, e.g. "32G"');
+      try {
+        out.snapshotBudgetBytes = parseByteSize(v2);
+      } catch (e2) {
+        throw new Error(`--snapshot-budget: ${e2 instanceof Error ? e2.message : String(e2)}`);
+      }
+    } else if (a2 === "--allow-lan") out.allowLan = true;
     else if (a2 === "--tls-cert") out.tlsCert = resolve7(argv[++i2]);
     else if (a2 === "--tls-key") out.tlsKey = resolve7(argv[++i2]);
     else if (a2 === "--self-signed") out.selfSigned = true;
@@ -41562,6 +41944,7 @@ async function main() {
     runner,
     image: args.guestImage,
     msbBin: args.msbBin,
+    snapshotBudgetBytes: args.snapshotBudgetBytes,
     log: slog,
     // Metadata for every session run, filed under the CALLER'S own root. The
     // runner service owns owner resolution (a wire-supplied clientId is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corenel/sidecar",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "license": "Elastic-2.0",
   "description": "Prompd sidecar — a local capability server. Run it next to Prompd (prompd.app) so the browser app can reach your machine: local LLMs (Ollama/LM Studio/vLLM) without CORS, your filesystem, and (opt-in) shell.",
@@ -36,15 +36,18 @@
     "esbuild": "^0.21.5",
     "tsx": "^4.19.2",
     "typescript": "^5.9.3",
-    "@corenel/protocol": "0.3.2",
-    "@corenel/harness": "0.3.2",
-    "@corenel/tools-node": "0.2.0",
-    "@corenel/crew": "0.0.0"
+    "@corenel/protocol": "0.4.0",
+    "@corenel/tools-node": "0.2.1",
+    "@corenel/crew": "0.0.0",
+    "@corenel/harness": "0.4.0"
   },
   "scripts": {
+    "prebuild": "pnpm --filter @corenel/protocol build && pnpm --filter @corenel/harness build",
     "build": "node build.mjs",
+    "prestart": "pnpm --filter @corenel/protocol build && pnpm --filter @corenel/harness build",
     "start": "tsx src/cli.ts",
     "typecheck": "tsc --noEmit",
+    "preverify": "pnpm --filter @corenel/protocol build && pnpm --filter @corenel/harness build",
     "verify": "tsx src/verify.ts"
   }
 }