@crouton-kit/capture 1.4.2 → 1.4.11

package/src/cdp/bridge/spawn.ts

@@ -8,42 +8,36 @@ import { spawn } from 'child_process';
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { CAPTURE_ROOT, ensurePrivateDir } from '../../session/artifacts.js';
+import { CAPTURE_ROOT } from '../../session/artifacts.js';
 
 export function bridgeSocketPath(sessionDir: string): string {
   return path.join(sessionDir, 'bridge.sock');
 }
 
 /**
- * Fixed, short, private (`0700`) directory every recorder socket lives in — flat, and
- * deliberately NOT nested under a recording's (long) artifact dir. macOS caps `AF_UNIX`
- * pathnames at ~104 bytes; a real recording dir (`{CAPTURE_ROOT}/{session}/motion/recs/{recId}`)
- * combined with `os.tmpdir()`'s own (often long, per-user) prefix can already exceed that before
- * adding a filename, so the socket can never live inside `recDir` — see `recorderSocketPath()`.
+ * The collector host socket is stored in a short private directory because
+ * macOS caps `AF_UNIX` paths at about 104 bytes. This cannot live beneath
+ * CAPTURE_ROOT: test and caller roots can already consume that entire budget.
  */
-function recorderSocketDir(): string {
-  return ensurePrivateDir(path.join(CAPTURE_ROOT, 'sock'));
+function collectorSocketDir(): string {
+  const dir = '/tmp/capture-sockets';
+  try { fs.mkdirSync(dir, { mode: 0o700 }); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+  }
+  const stat = fs.lstatSync(dir);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`collector socket directory is not a real directory: ${dir}`);
+  if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) throw new Error(`collector socket directory is not owned by this user: ${dir}`);
+  fs.chmodSync(dir, 0o700);
+  return dir;
 }
 
-/**
- * A short, fixed-length filename deterministically derived from `recDir` (not from `recDir`'s
- * own length/depth), so the resulting socket path stays bounded regardless of how deep the
- * recording's session/motion/recs nesting is.
- */
-function shortSocketName(recDir: string): string {
-  return crypto.createHash('sha1').update(path.resolve(recDir)).digest('hex').slice(0, 16);
+function shortSocketName(scopeDir: string): string {
+  return crypto.createHash('sha1').update(path.resolve(scopeDir)).digest('hex').slice(0, 16);
 }
 
-/**
- * The recorder bridge's own socket path. Lives in the short, flat `recorderSocketDir()` — NOT
- * inside `recDir` (the long, deep artifact directory `frames`/`events.jsonl`/etc. write into) —
- * so binding it never risks exceeding the platform's `AF_UNIX` pathname limit. `recDir` is still
- * required by every recorder-mode caller (spawn args, artifact writers); this function only
- * derives the socket's own location from it, deterministically, without embedding `recDir` in
- * the path itself.
- */
-export function recorderSocketPath(recDir: string): string {
-  return path.join(recorderSocketDir(), `${shortSocketName(recDir)}.sock`);
+/** The one collector host socket is keyed by its session, not an individual artifact. */
+export function collectorHostSocketPath(sessionDir: string): string {
+  return path.join(collectorSocketDir(), `host-${shortSocketName(sessionDir)}.sock`);
 }
 
 export async function startBridge(
@@ -85,6 +79,27 @@ export async function startBridge(
   return { socketPath, pid };
 }
 
+export async function startCollectorHost(
+  socketPath: string,
+  port: number,
+  targetId: string,
+  sessionDir: string,
+  timeoutMs = 5000,
+): Promise<{ socketPath: string; pid: number }> {
+  const child = spawn(process.execPath, [process.argv[1], '__bridge-serve', '--socket', socketPath, '--port', String(port), '--target', targetId, 'host', sessionDir], { detached: true, stdio: 'ignore' });
+  child.unref();
+  if (!child.pid) throw new Error('Failed to spawn collector host process.');
+  const started = Date.now();
+  while (!fs.existsSync(socketPath)) {
+    if (Date.now() - started > timeoutMs) {
+      stopBridge(child.pid, socketPath);
+      throw new Error(`Collector host (pid ${child.pid}) did not come up within ${timeoutMs}ms.`);
+    }
+    await new Promise(resolve => setTimeout(resolve, 50));
+  }
+  return { socketPath, pid: child.pid };
+}
+
 export function stopBridge(pid: number | null | undefined, socketPath: string | null | undefined): void {
   if (pid) {
     try {
@@ -95,80 +110,9 @@ export function stopBridge(pid: number | null | undefined, socketPath: string |
   }
   if (socketPath) {
     try {
-      fs.unlinkSync(socketPath);
+      if (fs.lstatSync(socketPath).isSocket()) fs.unlinkSync(socketPath);
     } catch {
       // Already gone.
     }
   }
 }
-
-/**
- * Spawns the same detached `__bridge-serve` entrypoint in recorder mode:
- * it connects to one tab (`targetId`) instead of the browser level, and
- * drives `capture motion rec`'s screencast/tracing/observers instead of
- * proxying arbitrary `--browser` CDP calls. Mirrors `startBridge()`'s
- * spawn + "wait for the socket file to appear" pattern; the caller
- * (U14's lifecycle routing) tears it down with the same `stopBridge()`
- * used for the plain held bridge.
- *
- * Recorder mode is selected via a positional (`recorder <recDir> <harId>`)
- * rather than a new flag — `capture`'s CLI arg parser (`src/cdp/args.ts`) is
- * not owned by this unit, but `positional` is already generic passthrough.
- *
- * `harId` is the owning session's live HAR recording id (`.session.json`'s
- * `harId`) — the recorder bridge installs a streaming `HARRecorder` on its
- * held tab connection and appends network evidence to that store, so the id
- * must travel to the spawned process. Required: a session-backed recorder
- * always has one (the caller throws before spawning if it doesn't).
- *
- * The socket-file readiness poll below doubles as the nonce-boot-file
- * guarantee: the recorder writes `{recDir}/recorder-nonce.json` BEFORE it
- * binds the socket (see `../recorder-bridge.ts`), so once this resolves the
- * caller can read the nonce without racing the child.
- */
-export async function startRecorderBridge(
-  socketPath: string,
-  port: number,
-  targetId: string,
-  recDir: string,
-  harId: string,
-  timeoutMs = 5000,
-): Promise<{ socketPath: string; pid: number }> {
-  const scriptPath = process.argv[1];
-  const child = spawn(
-    process.execPath,
-    [
-      scriptPath,
-      '__bridge-serve',
-      '--socket',
-      socketPath,
-      '--port',
-      String(port),
-      '--target',
-      targetId,
-      'recorder',
-      recDir,
-      harId,
-    ],
-    { detached: true, stdio: 'ignore' },
-  );
-  child.unref();
-  const pid = child.pid;
-  if (!pid) {
-    throw new Error('Failed to spawn recorder bridge process.');
-  }
-
-  const start = Date.now();
-  while (!fs.existsSync(socketPath)) {
-    if (Date.now() - start > timeoutMs) {
-      stopBridge(pid, socketPath);
-      throw new Error(
-        `Recorder bridge (pid ${pid}) did not come up within ${timeoutMs}ms. ` +
-          `Check that target "${targetId}" is reachable on port ${port}.`,
-      );
-    }
-    await new Promise((r) => setTimeout(r, 50));
-  }
-
-  return { socketPath, pid };
-}

package/src/cdp/commands/bridge-serve.ts

@@ -1,18 +1,15 @@
 import { runBridgeServer } from '../bridge/server.js';
-import { runRecorderBridge } from '../recorder-bridge.js';
+import { runCollectorHost } from '../host/server.js';
 import { invalidInput } from '../../errors.js';
 import { type ParsedArgs } from '../types.js';
 
 /**
  * Hidden entrypoint spawned detached by `capture session start --hold`
  * (see `bridge/spawn.ts`'s `startBridge()`) or by `capture motion rec
- * --start` in recorder mode (`startRecorderBridge()`). Not documented in
- * `capture --help` — nothing calls this directly.
- *
- * Recorder mode is selected by a `recorder <recDir> <harId>` positional
- * rather than a new flag, since `src/cdp/args.ts`'s fixed flag set isn't
- * owned by this unit but `parsed.positional` is already generic passthrough:
- *   capture __bridge-serve --socket <path> --port <cdpPort> --target <tabId> recorder <recDir> <harId>
+ * --start` in collector-host mode. Not documented in `capture --help` —
+ * nothing calls this directly. Collector-host mode is selected by the
+ * `host <sessionDir>` positional:
+ *   capture __bridge-serve --socket <path> --port <cdpPort> --target <tabId> host <sessionDir>
  *
  * Usage errors throw the repo's structured `CaptureError` — the root
  * boundary in `src/capture.ts` renders it via `failureResult()` and exits
@@ -21,24 +18,17 @@ import { type ParsedArgs } from '../types.js';
 export async function cmdBridgeServe(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (!parsed.socket) {
     throw invalidInput(
-      'Usage: capture __bridge-serve --socket <path> [--port <cdpPort>] [--target <tabId> recorder <recDir> <harId>]',
+      'Usage: capture __bridge-serve --socket <path> [--port <cdpPort>] [--target <tabId>] [host <sessionDir>]',
       'bridge_serve_usage',
     );
   }
 
-  if (parsed.positional[0] === 'recorder') {
-    const recDir = parsed.positional[1];
-    const harId = parsed.positional[2];
-    if (!parsed.target || !recDir || !harId) {
-      throw invalidInput(
-        'Usage: capture __bridge-serve --socket <path> --port <cdpPort> --target <tabId> recorder <recDir> <harId>',
-        'bridge_serve_usage',
-      );
+  if (parsed.positional[0] === 'host') {
+    const sessionDir = parsed.positional[1];
+    if (!parsed.target || !sessionDir || parsed.port === undefined) {
+      throw invalidInput('Usage: capture __bridge-serve --socket <path> --port <cdpPort> --target <tabId> host <sessionDir>', 'bridge_serve_usage');
     }
-    await runRecorderBridge({ socketPath: parsed.socket, port: parsed.port, targetId: parsed.target, recDir, harId });
-    // Deliberately does not exit: the open Unix socket server and the live
-    // tab websocket keep this detached process alive until an authenticated
-    // `rec-stop` completes (self-exit) or the caller escalates with SIGTERM.
+    await runCollectorHost({ socketPath: parsed.socket, port: parsed.port, targetId: parsed.target, sessionDir });
     return;
   }
 

package/src/cdp/commands/cdp.ts

@@ -24,7 +24,7 @@ import { connectForCommand } from '../connection.js';
 import { getBrowserClient, findTabById } from '../targets.js';
 import { detectCdpPort } from '../detect.js';
 import { sendBridgeRequest } from '../bridge/client.js';
-import { isRecorderHeldClient } from '../recorder-client.js';
+import { isMotionHeldClient } from '../host/held-client.js';
 import { type ParsedArgs } from '../types.js';
 import {
   capped,
@@ -45,8 +45,7 @@ const GENEROUS_RESULT_CAP = 4000;
 /** Root-help representation of this leaf, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="cdp">
 raw CDP escape hatch — send any protocol method capture doesn't wrap, or wait for a protocol event
-use when no other capture command covers the protocol surface you need (Browser.*, ServiceWorker.*, Target.*, ...)
-  cdp [<Domain.method>] [--params <json>] [--browser] [--wait-event <name>] — \`capture cdp -h\`
+use when sending a CDP method or waiting for an event Capture does not otherwise expose
 </command>`;
 
 const HELP = `capture cdp — send a raw CDP protocol method and/or wait for a protocol event: the escape hatch for domains no other capture command wraps (Browser.*, ServiceWorker.*, Target.*, ...).
@@ -60,6 +59,9 @@ Input:
   --target <id>                with --browser: attach a flattened CDP session on the held connection to this target (for target-scoped domains), including an already-open tab adopted by \`session start --hold\` without --url; without --browser: the page target to run against. 8-char id prefix accepted.
   --timeout <ms>               one-shot method-response and event-wait timeout (default ${DEFAULT_TIMEOUT_MS}ms). WebSocket connection setup is separately bounded to 5000ms.
 
+Connection lifetime:
+  Unless --browser routes through a held session, each invocation opens an isolated CDP connection and closes it when the command exits. Domain enables and remote object handles (objectIds) are connection-scoped, so a later one-shot invocation cannot use either. A multi-step protocol sequence needs connection state that survives between its calls.
+
 Output:
   <cdp-result method=… wait-event=… scope=…> — the protocol result and/or awaited event as an escaped, length-capped JSON payload. --json mirrors the same block with the payload at full fidelity.
 
@@ -68,7 +70,7 @@ Effects:
 
 /**
  * The minimal client surface both scopes drive. Satisfied structurally by
- * `CDPClient`, `RecorderHeldClient`, and test stubs \u2014 the injectable
+ * `CDPClient`, `MotionHeldClient`, and test stubs \u2014 the injectable
  * `connect` parameter on `runPageScope` exists so tests can exercise the
  * command wiring against a stub without a live browser.
  */
@@ -145,8 +147,15 @@ const TAB_SCOPE_RECOVERY =
   'Many CDP domains (Storage.*, Page.*, DOM.*, Emulation.*, ...) are tab-scoped, not connection-scoped — re-run with --target <tabId> (`capture tab list` shows available tabs).';
 
 /** Appends the tab-scope recovery hint when the failed call was target-less. */
-function cdpFailed(message: string, flagTarget: string | undefined, cause?: unknown): CaptureError {
-  return captureError('world', 'cdp_failed', flagTarget ? message : `${message} ${TAB_SCOPE_RECOVERY}`, cause);
+function timeoutGuidance(message: string, timeoutMs: number): string {
+  return /\b(?:timed out|timeout)\b/i.test(message)
+    ? `${message} The request limit was ${timeoutMs}ms; re-run with \`--timeout <ms>\` to extend it.`
+    : message;
+}
+
+function cdpFailed(message: string, flagTarget: string | undefined, timeoutMs: number, cause?: unknown): CaptureError {
+  const detailed = timeoutGuidance(message, timeoutMs);
+  return captureError('world', 'cdp_failed', flagTarget ? detailed : `${detailed} ${TAB_SCOPE_RECOVERY}`, cause);
 }
 
 export async function cmdCdp(parsed: ParsedArgs, _args: string[]): Promise<void> {
@@ -193,7 +202,7 @@ export async function cmdCdp(parsed: ParsedArgs, _args: string[]): Promise<void>
     throw captureError(
       'world',
       'cdp_failed',
-      `\`${invocationLabel(method, parsed.waitEvent)}\` failed on the page connection: ${err instanceof Error ? err.message : String(err)}`,
+      timeoutGuidance(`\`${invocationLabel(method, parsed.waitEvent)}\` failed on the page connection: ${err instanceof Error ? err.message : String(err)}`, timeoutMs),
       err,
     );
   }
@@ -224,17 +233,29 @@ export async function runBrowserScope(
   const bridgeSocket = session?.bridgeSocket;
   const heldBridgeActive = Boolean(bridgeSocket && fs.existsSync(bridgeSocket));
   if (parsed.portSource !== 'flag' && bridgeSocket && heldBridgeActive) {
-    const resp = await deps.sendBridgeRequest(bridgeSocket, {
-      method,
-      params,
-      targetId: flagTarget,
-      waitEvent: parsed.waitEvent,
-      timeoutMs,
-    });
+    let resp;
+    try {
+      resp = await deps.sendBridgeRequest(bridgeSocket, {
+        method,
+        params,
+        targetId: flagTarget,
+        waitEvent: parsed.waitEvent,
+        timeoutMs,
+      });
+    } catch (err) {
+      if (err instanceof CaptureError) throw err;
+      throw cdpFailed(
+        `\`${invocationLabel(method, parsed.waitEvent)}\` failed over the held connection: ${err instanceof Error ? err.message : String(err)}`,
+        flagTarget,
+        timeoutMs,
+        err,
+      );
+    }
     if (!resp.ok) {
       throw cdpFailed(
         `\`${invocationLabel(method, parsed.waitEvent)}\` failed over the held connection: ${resp.error ?? 'unknown bridge error'}`,
         flagTarget,
+        timeoutMs,
       );
     }
     emitCdpResult({
@@ -299,6 +320,7 @@ export async function runBrowserScope(
     throw cdpFailed(
       `\`${invocationLabel(method, parsed.waitEvent)}\` failed on the one-shot browser connection: ${err instanceof Error ? err.message : String(err)}`,
       flagTarget,
+      timeoutMs,
       err,
     );
   } finally {
@@ -309,7 +331,7 @@ export async function runBrowserScope(
 /**
  * Exported for testing (`test/recorder-navigate-waitevent.test.ts`,
  * `test/cdp-command.test.ts`): the recorder-held branch below
- * (`isRecorderHeldClient(client)`) is the actual command wiring
+ * (`isMotionHeldClient(client)`) is the actual command wiring
  * `capture cdp --wait-event` runs under an active recording, and the
  * injectable `connect` lets `test/cdp-command.test.ts` drive the non-held
  * branch against a stub client.
@@ -325,17 +347,17 @@ export async function runPageScope(
   try {
     let result: unknown;
     let event: unknown;
-    if (isRecorderHeldClient(client)) {
-      // The recorder-held adapter's `.on()` is a documented no-op (nothing
+    if (isMotionHeldClient(client)) {
+      // The motion-held adapter's `.on()` is a documented no-op (nothing
       // pushes unsolicited events back over its one-request-one-response
       // socket) — `waitForEventOnce` below would hang until its own timeout.
       // `.waitEvent()`/`.dispatch()` are the real event-wait surface for this
-      // adapter, routing the wait through the recorder bridge's own event
-      // broker. When both a method and a wait-event are requested,
-      // `.dispatch()` carries them in ONE request so the bridge arms the wait
-      // before dispatching the call — sending them as two separate requests
+      // adapter, routing the wait through the collector host's event broker.
+      // When both a method and a wait-event are requested, `.dispatch()`
+      // carries them in ONE request so the host arms the wait before
+      // dispatching the call — sending them as two separate requests
       // (`.send()` then `.waitEvent()`) risks the action firing the event
-      // before the wait-only request even reaches the bridge. This command has
+      // before the wait-only request even reaches the host. This command has
       // no fragment-nav-style multi-call logic and already throws on an
       // event-wait timeout, so one combined request preserves the complete
       // result contract (contrast `page/navigate.ts`'s multi-call

package/src/cdp/commands/heap/census.ts

@@ -0,0 +1,61 @@
+import { type ParsedArgs } from '../../types.js';
+import { capped, emitResult, fact, formatArtifactList, lineList, text } from '../../../output/render.js';
+import { completionAttrs, loadHeap, resolveHeapRef, resultReference } from './common.js';
+import { selectRecords } from '../../../output/selection.js';
+
+const HELP = `capture heap census <snapshot> [--axis constructor|string] [--limit <N>] — what the heap is made of
+
+input:
+  <snapshot>       heap snapshot id in the active session or an absolute snapshot path (required)
+  --axis <axis>    constructor (default) groups every node by constructor name with node count and retained bytes; string groups equal-content strings with their instance count and estimated duplicate bytes
+  --limit <N>      return the top N groups by retained bytes; default 25, including under --json
+output: <heap-census …> — one row per group with its counts and sizes, plus the size qualification for the chosen axis; --json mirrors
+effects: read-only — reads the finalized snapshot artifact, never drives the browser`;
+
+export function cmdHeapCensus(parsed: ParsedArgs): void {
+  if (parsed.help) {
+    console.log(HELP);
+    return;
+  }
+  const ref = resolveHeapRef(parsed.positional[0]);
+  const heap = loadHeap(ref);
+  const limit = parsed.limit ?? 25;
+  const axis = parsed.axis ?? 'constructor';
+  if (axis === 'string') {
+    const duplicate = heap.duplicateStrings();
+    const groups = [...duplicate.duplicates].sort((a, b) => b.wastedBytes - a.wastedBytes || b.totalSelfBytes - a.totalSelfBytes || a.value.localeCompare(b.value));
+    const displayed = selectRecords(groups, parsed, limit);
+    emitResult({
+      tag: 'heap-census',
+      attrs: { heap: ref.id, path: ref.dir, ...completionAttrs(ref.meta), axis, groups: groups.length, displayed: displayed.length, nodes: heap.nodeCount, 'size-qualification': duplicate.sizeQualification },
+      summary: text`Equal-content string instances grouped from the Chrome heap snapshot.`,
+      artifacts: formatArtifactList([{ name: 'snapshot.heapsnapshot' }]),
+      sections: [fact`${duplicate.sizeQualification}`, lineList(displayed.map((group, index) => fact`${index + 1}. ${capped(group.value, 120)} · instances=${group.count} self-bytes=${group.totalSelfBytes} wasted-bytes=${group.wastedBytes}`))],
+      jsonSections: displayed.map(group => ({ string: capped(group.value, Number.MAX_SAFE_INTEGER), instanceCount: group.count, selfBytes: group.totalSelfBytes, wastedBytes: group.wastedBytes, sizeQualification: duplicate.sizeQualification })),
+      followUp: fact`Use \`capture heap objects ${resultReference(ref)} --constructor <name>\` to inspect one constructor, or \`capture heap diff --before ${resultReference(ref)} --after <snapshot>\` to compare snapshots.`,
+    }, { json: parsed.json });
+    return;
+  }
+
+  const dominators = heap.computeDominators();
+  const grouped = new Map<string, { constructor: string; nodeCount: number; retainedBytes: number; selfBytes: number }>();
+  for (let index = 0; index < heap.nodeCount; index += 1) {
+    const node = heap.nodeAt(index);
+    const group = grouped.get(node.name) ?? { constructor: node.name, nodeCount: 0, retainedBytes: 0, selfBytes: 0 };
+    group.nodeCount += 1;
+    group.retainedBytes += dominators.retainedSizes[index];
+    group.selfBytes += node.selfSize;
+    grouped.set(node.name, group);
+  }
+  const groups = [...grouped.values()].sort((a, b) => b.retainedBytes - a.retainedBytes || b.selfBytes - a.selfBytes || a.constructor.localeCompare(b.constructor));
+  const displayed = selectRecords(groups, parsed, limit);
+  emitResult({
+    tag: 'heap-census',
+    attrs: { heap: ref.id, path: ref.dir, ...completionAttrs(ref.meta), axis, groups: groups.length, displayed: displayed.length, nodes: heap.nodeCount, 'size-qualification': dominators.sizeQualification },
+    summary: text`Constructor totals from the V8 heap snapshot.`,
+    artifacts: formatArtifactList([{ name: 'snapshot.heapsnapshot' }]),
+    sections: [fact`${dominators.sizeQualification}`, lineList(displayed.map((group, index) => fact`${index + 1}. ${capped(group.constructor, 120)} · nodes=${group.nodeCount} retained-bytes=${group.retainedBytes} self-bytes=${group.selfBytes}`))],
+    jsonSections: displayed.map(group => ({ constructor: capped(group.constructor, Number.MAX_SAFE_INTEGER), nodeCount: group.nodeCount, retainedBytes: group.retainedBytes, selfBytes: group.selfBytes, sizeQualification: dominators.sizeQualification })),
+    followUp: fact`Use \`capture heap objects ${resultReference(ref)} --constructor <name>\` for Chrome snapshot object ids and \`capture heap retainers ${resultReference(ref)} --node <object-id>\` for a retaining path.`,
+  }, { json: parsed.json });
+}

package/src/cdp/commands/heap/common.ts

@@ -0,0 +1,77 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { captureError } from '../../../errors.js';
+import { HeapSnapshot } from '../../heap-snapshot.js';
+import { assertUnderCaptureRoot, readPrivateFile } from '../../../session/artifacts.js';
+import { getActiveSession } from '../../../session-context.js';
+import type { ResolvedCompletion } from '../../host/collector.js';
+
+export interface HeapMeta {
+  id: string;
+  completion: ResolvedCompletion;
+  reason?: string;
+  url?: string;
+  files: readonly { name: string; bytes: number }[];
+}
+
+export interface HeapRef {
+  readonly kind: 'heap';
+  readonly id: string;
+  readonly dir: string;
+  readonly meta: HeapMeta;
+}
+
+function readHeapMeta(dir: string, ref: string): HeapMeta {
+  const metaPath = path.join(dir, 'meta.json');
+  let raw: Record<string, unknown>;
+  try {
+    raw = JSON.parse(readPrivateFile(metaPath).toString('utf8')) as Record<string, unknown>;
+  } catch (error) {
+    throw captureError('artifact', 'heap_ref_unavailable', `Could not read finalized heap snapshot ${JSON.stringify(ref)} at ${dir}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (raw.kind !== 'heap' || typeof raw.id !== 'string' || !['complete', 'partial', 'orphaned'].includes(String(raw.completion))) {
+    throw captureError('artifact', 'heap_ref_unavailable', `Artifact ${JSON.stringify(ref)} is not a finalized heap snapshot.`);
+  }
+  const files = Array.isArray(raw.files) && raw.files.every(file => file && typeof file === 'object' && typeof (file as { name?: unknown }).name === 'string' && typeof (file as { bytes?: unknown }).bytes === 'number')
+    ? raw.files as Array<{ name: string; bytes: number }>
+    : [];
+  const snapshot = files.find(file => file.name === 'snapshot.heapsnapshot');
+  let completion = raw.completion as ResolvedCompletion;
+  if (!snapshot || !fs.existsSync(path.join(dir, 'snapshot.heapsnapshot')) || fs.statSync(path.join(dir, 'snapshot.heapsnapshot')).size !== snapshot.bytes) completion = 'truncated';
+  return { id: raw.id, completion, ...(typeof raw.reason === 'string' ? { reason: raw.reason } : {}), ...(typeof raw.url === 'string' ? { url: raw.url } : {}), files };
+}
+
+export function resolveHeapRef(ref: string): HeapRef {
+  let dir: string;
+  if (path.isAbsolute(ref)) {
+    const resolved = assertUnderCaptureRoot(ref);
+    dir = path.basename(resolved) === 'snapshot.heapsnapshot' ? path.dirname(resolved) : resolved;
+  } else {
+    if (ref.includes('/') || ref.includes(path.sep)) throw captureError('invocation', 'heap_ref_invalid', 'Heap snapshot references must be a bare id or an absolute artifact path.');
+    const active = getActiveSession();
+    if (!active) throw captureError('precondition', 'heap_ref_unavailable', `A bare heap snapshot id (${ref}) requires an active capture session; pass the absolute path printed by capture heap snapshot.`);
+    dir = assertUnderCaptureRoot(path.join(active.dir, 'heap', 'snapshots', ref));
+  }
+  return { kind: 'heap', id: path.basename(dir), dir, meta: readHeapMeta(dir, ref) };
+}
+
+export function loadHeap(ref: HeapRef): HeapSnapshot {
+  const snapshotPath = path.join(ref.dir, 'snapshot.heapsnapshot');
+  if (ref.meta.completion === 'truncated' || !fs.existsSync(snapshotPath)) {
+    throw captureError('artifact', 'heap_snapshot_truncated', `Heap snapshot ${ref.id} is ${ref.meta.completion}; snapshot.heapsnapshot does not match its finalized inventory.`);
+  }
+  try {
+    return HeapSnapshot.parse(readPrivateFile(snapshotPath).toString('utf8'));
+  } catch (error) {
+    throw captureError('artifact', 'heap_snapshot_invalid', `Heap snapshot ${ref.id} could not be parsed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export function completionAttrs(meta: HeapMeta): { completion: ResolvedCompletion; 'completion-reason'?: string } {
+  return { completion: meta.completion, ...(meta.completion !== 'complete' && meta.reason ? { 'completion-reason': meta.reason } : {}) };
+}
+
+export function resultReference(ref: HeapRef): string {
+  const active = getActiveSession();
+  return active && path.join(active.dir, 'heap', 'snapshots', ref.id) === ref.dir ? ref.id : ref.dir;
+}

package/src/cdp/commands/heap/diff.ts

@@ -0,0 +1,92 @@
+import { type ParsedArgs } from '../../types.js';
+import { HeapSnapshot } from '../../heap-snapshot.js';
+import { capped, emitResult, fact, formatArtifactList, lineList, text } from '../../../output/render.js';
+import { completionAttrs, loadHeap, resolveHeapRef, resultReference } from './common.js';
+import { selectRecords } from '../../../output/selection.js';
+
+const HELP = `capture heap diff --before <snapshot> --after <snapshot> [--limit <N>] — what changed between two heap snapshots
+
+input:
+  --before <snapshot>   required. Heap snapshot id in the active session or an absolute snapshot path
+  --after <snapshot>    required. Heap snapshot id in the active session or an absolute snapshot path
+  --limit <N>           return the top N constructors by added retained bytes and top N after-snapshot nodes Chrome marks detached in prose and JSON; default 25
+output: <heap-diff …> — before/after snapshot node and serialized-byte totals, then per constructor nodes added, removed, and grown with retained-byte and detached-node totals; after-snapshot nodes Chrome marks detached are listed with their object ids; --json mirrors
+effects: read-only — reads both finalized snapshot artifacts, never drives the browser`;
+
+export function cmdHeapDiff(parsed: ParsedArgs): void {
+  if (parsed.help) {
+    console.log(HELP);
+    return;
+  }
+  const before = resolveHeapRef(parsed.before!);
+  const after = resolveHeapRef(parsed.after!);
+  const beforeHeap = loadHeap(before);
+  const afterHeap = loadHeap(after);
+  const comparison = HeapSnapshot.compare(beforeHeap, afterHeap);
+  const snapshotBytes = (ref: typeof before) => ref.meta.files.find((file) => file.name === 'snapshot.heapsnapshot')?.bytes;
+  const totals = {
+    before: { nodes: beforeHeap.nodeCount, bytes: snapshotBytes(before) },
+    after: { nodes: afterHeap.nodeCount, bytes: snapshotBytes(after) },
+  };
+  const constructors = [...comparison.constructors].sort((a, b) => b.added.retainedSize - a.added.retainedSize || b.grown.retainedSize - a.grown.retainedSize || b.removed.retainedSize - a.removed.retainedSize || a.constructorName.localeCompare(b.constructorName));
+  const limit = parsed.limit ?? 25;
+  const displayed = selectRecords(constructors, parsed, limit);
+  const detached = selectRecords(comparison.afterDetachedNodes, parsed, limit);
+  const detachedSection = detached.length
+    ? lineList(detached.map((node, index) => fact`${index + 1}. object-id=${node.objectId} constructor=${capped(node.constructorName, 120)} type=${node.type} detachedness=${node.detachedness}`))
+    : text`No after-snapshot nodes are marked detached by Chrome.`;
+  const jsonSections = [
+    { before: totals.before, after: totals.after },
+    ...displayed.map(constructor => ({
+      constructor: capped(constructor.constructorName, Number.MAX_SAFE_INTEGER),
+      added: { nodeCount: constructor.added.nodeCount, detachedNodeCount: constructor.added.detachedNodeCount, retainedSize: constructor.added.retainedSize },
+      removed: { nodeCount: constructor.removed.nodeCount, detachedNodeCount: constructor.removed.detachedNodeCount, retainedSize: constructor.removed.retainedSize },
+      grown: { nodeCount: constructor.grown.nodeCount, detachedNodeCount: constructor.grown.detachedNodeCount, retainedSize: constructor.grown.retainedSize },
+      retainedSizeQualification: comparison.retainedSizeQualification,
+      matching: comparison.matching,
+    })),
+    ...(comparison.afterDetachedNodes.length ? [{
+      afterDetachedNodes: detached.map(node => ({
+        objectId: node.objectId,
+        constructor: capped(node.constructorName, Number.MAX_SAFE_INTEGER),
+        type: node.type,
+        detachedness: node.detachedness,
+      })),
+      total: comparison.afterDetachedNodes.length,
+      displayed: detached.length,
+      detachednessQualification: 'Chrome detachedness metadata value 2 marks these after-snapshot nodes detached.',
+    }] : []),
+  ];
+  emitResult({
+    tag: 'heap-diff',
+    attrs: {
+      before: before.id,
+      'before-path': before.dir,
+      ...Object.fromEntries(Object.entries(completionAttrs(before.meta)).map(([key, value]) => [`before-${key}`, value])),
+      after: after.id,
+      'after-path': after.dir,
+      ...Object.fromEntries(Object.entries(completionAttrs(after.meta)).map(([key, value]) => [`after-${key}`, value])),
+      matching: comparison.matching,
+      constructors: constructors.length,
+      displayed: displayed.length,
+      'after-detached-nodes': comparison.afterDetachedNodes.length,
+      'detached-displayed': detached.length,
+      'retained-size-qualification': comparison.retainedSizeQualification,
+      'before-nodes': totals.before.nodes,
+      'before-bytes': totals.before.bytes,
+      'after-nodes': totals.after.nodes,
+      'after-bytes': totals.after.bytes,
+    },
+    summary: text`Nodes are matched by Chrome snapshot object id. “grown” reports the increase in retained size for id-matched nodes, not their current size.`,
+    artifacts: formatArtifactList([{ name: `${resultReference(before)}/snapshot.heapsnapshot`, note: 'before' }, { name: `${resultReference(after)}/snapshot.heapsnapshot`, note: 'after' }]),
+    sections: [
+      fact`Snapshot totals: before nodes=${totals.before.nodes} serialized-bytes=${totals.before.bytes ?? 'unavailable'}; after nodes=${totals.after.nodes} serialized-bytes=${totals.after.bytes ?? 'unavailable'}.`,
+      fact`${comparison.retainedSizeQualification}`,
+      lineList(displayed.map((constructor, index) => fact`${index + 1}. ${capped(constructor.constructorName, 120)} · added nodes=${constructor.added.nodeCount} detached-nodes=${constructor.added.detachedNodeCount} retained-bytes=${constructor.added.retainedSize}; removed nodes=${constructor.removed.nodeCount} detached-nodes=${constructor.removed.detachedNodeCount} retained-bytes=${constructor.removed.retainedSize}; grown nodes=${constructor.grown.nodeCount} detached-nodes=${constructor.grown.detachedNodeCount} retained-bytes=${constructor.grown.retainedSize}`)),
+      fact`After-snapshot nodes marked detached by Chrome (object-id is the heap retainers --node input):`,
+      detachedSection,
+    ],
+    jsonSections,
+    followUp: fact`The detached object ids above are inputs to \`capture heap retainers ${resultReference(after)} --node <object-id>\`.`,
+  }, { json: parsed.json });
+}

package/src/cdp/commands/heap/index.ts

@@ -0,0 +1,38 @@
+import { invalidInput } from '../../../errors.js';
+import { type ParsedArgs } from '../../types.js';
+import { cmdHeapSnapshot } from './snapshot.js';
+import { cmdHeapCensus } from './census.js';
+import { cmdHeapObjects } from './objects.js';
+import { cmdHeapRetainers } from './retainers.js';
+import { cmdHeapDiff } from './diff.js';
+
+export const COMMAND_BLOCK = `<command name="heap">
+the tab's JavaScript heap — \`snapshot\` records the heap as a V8 snapshot, every other leaf is a read-only graph query over it
+use for JavaScript-heap retention: constructor totals, retained sizes, retaining paths, duplicate strings, and before/after comparison
+</command>`;
+
+const HELP = `<command name="heap" description="the V8 heap-snapshot substrate">
+<model>\`snapshot\` drives the browser; every other leaf is a read of the finalized snapshot artifact and never touches Chrome. Retained sizes are dominator-subtree sums of Chrome's own self_size. Findings exit 0; input/precondition errors exit 1. No leaf accepts --gate.</model>
+<subcommand name="snapshot" description="take a V8 heap snapshot" whenToUse="Use to write the substrate every other heap leaf reads."/>
+<subcommand name="census" description="what the heap is made of" whenToUse="Use for per-constructor node counts and retained bytes, or for duplicated strings."/>
+<subcommand name="objects" description="the individual objects of one constructor" whenToUse="Use to get the snapshot object ids and sizes you need before asking what retains one."/>
+<subcommand name="retainers" description="what is keeping one object alive" whenToUse="Use with an object id from \`objects\` to get the nearest application-owned retainers."/>
+<subcommand name="diff" description="what changed between two snapshots" whenToUse="Use to see which constructors added, removed, or grew across an interaction."/>
+</command>`;
+
+export async function heapMain(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  const leaf = parsed.positional[0];
+  const rest: ParsedArgs = { ...parsed, positional: parsed.positional.slice(1) };
+  switch (leaf) {
+    case 'snapshot': return cmdHeapSnapshot(rest);
+    case 'census': return cmdHeapCensus(rest);
+    case 'objects': return cmdHeapObjects(rest);
+    case 'retainers': return cmdHeapRetainers(rest);
+    case 'diff': return cmdHeapDiff(rest);
+    case undefined:
+      console.log(HELP);
+      return;
+    default:
+      throw invalidInput(`Unknown heap leaf: ${leaf}.`, 'unknown_command');
+  }
+}