@crouton-kit/capture 1.4.2 → 1.4.10

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

@@ -0,0 +1,42 @@
+import { type ParsedArgs } from '../../types.js';
+import { 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 objects <snapshot> --constructor <name> [--limit <N>] [--sort retained|self] — the individual objects of one constructor
+
+input:
+  <snapshot>            heap snapshot id in the active session or an absolute snapshot path (required)
+  --constructor <name>  required. Exact constructor name as reported by \`capture heap census\` — the id source for \`capture heap retainers\`
+  --limit <N>           return the top N objects in prose and JSON; default 25
+  --sort <key>          retained (default) or self
+output: <heap-objects …> — one row per object with its Chrome snapshot object id, node type, self bytes, and retained bytes, carrying the same retained-size qualification as \`census\`; --json mirrors
+effects: read-only — reads the finalized snapshot artifact, never drives the browser`;
+
+export function cmdHeapObjects(parsed: ParsedArgs): void {
+  if (parsed.help) {
+    console.log(HELP);
+    return;
+  }
+  const ref = resolveHeapRef(parsed.positional[0]);
+  const heap = loadHeap(ref);
+  const constructor = parsed.constructor!;
+  const sort = parsed.sort ?? 'retained';
+  const dominators = heap.computeDominators();
+  const objects = [] as Array<{ objectId: number; type: string; name: string; selfBytes: number; retainedBytes: number }>;
+  for (let index = 0; index < heap.nodeCount; index += 1) {
+    const node = heap.nodeAt(index);
+    if (node.name === constructor) objects.push({ objectId: node.id, type: node.type, name: node.name, selfBytes: node.selfSize, retainedBytes: dominators.retainedSizes[index] });
+  }
+  objects.sort((a, b) => (sort === 'self' ? b.selfBytes - a.selfBytes || b.retainedBytes - a.retainedBytes : b.retainedBytes - a.retainedBytes || b.selfBytes - a.selfBytes) || a.objectId - b.objectId);
+  const displayed = selectRecords(objects, parsed, 25);
+  emitResult({
+    tag: 'heap-objects',
+    attrs: { heap: ref.id, path: ref.dir, ...completionAttrs(ref.meta), constructor, objects: objects.length, displayed: displayed.length, sort, 'size-qualification': dominators.sizeQualification },
+    summary: text`Individual snapshot nodes of the selected constructor. Chrome snapshot object ids are not DOM backend node ids and are not stable across snapshots.`,
+    artifacts: formatArtifactList([{ name: 'snapshot.heapsnapshot' }]),
+    sections: [fact`${dominators.sizeQualification}`, lineList(displayed.map((object, index) => fact`${index + 1}. object-id=${object.objectId} type=${object.type} self-bytes=${object.selfBytes} retained-bytes=${object.retainedBytes}`))],
+    jsonSections: displayed.map(object => ({ ...object, sizeQualification: dominators.sizeQualification })),
+    followUp: fact`Use \`capture heap retainers ${resultReference(ref)} --node <object-id>\` with one Chrome snapshot object id from this result.`,
+  }, { json: parsed.json });
+}

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

@@ -0,0 +1,52 @@
+import { type ParsedArgs } from '../../types.js';
+import { emitResult, fact, formatArtifactList, line, lineList, text } from '../../../output/render.js';
+import { completionAttrs, loadHeap, resolveHeapRef, resultReference } from './common.js';
+
+const HELP = `capture heap retainers <snapshot> --node <object-id> [--paths <N>] — what is keeping one object alive
+
+input:
+  <snapshot>          heap snapshot id in the active session or an absolute snapshot path (required)
+  --node <object-id>  required. Chrome snapshot object id from \`capture heap objects\`
+  --paths <N>         return up to N paths; default 1
+output: <retainers …> — each path from the nearest application-owned retainer to the selected object as an alternating node/edge chain, with each edge's kind and property name, and each node's self bytes under the same size qualification as \`census\`; V8 root plumbing is excluded from path selection; --json mirrors
+effects: read-only — reads the finalized snapshot artifact, never drives the browser`;
+
+export function cmdHeapRetainers(parsed: ParsedArgs): void {
+  if (parsed.help) {
+    console.log(HELP);
+    return;
+  }
+  const ref = resolveHeapRef(parsed.positional[0]);
+  const heap = loadHeap(ref);
+  const objectId = Number(parsed.node);
+  let targetIndex = -1;
+  for (let index = 0; index < heap.nodeCount; index += 1) if (heap.nodeAt(index).id === objectId) { targetIndex = index; break; }
+  if (targetIndex < 0) throw new Error(`Heap snapshot ${ref.id} has no node with Chrome snapshot object id ${objectId}.`);
+  const paths = heap.applicationRetainingPaths(targetIndex, { maxPaths: parsed.paths ?? 1 });
+  const dominators = heap.computeDominators();
+  const prosePaths = paths.paths.map((path, index) => {
+    const chain = [] as ReturnType<typeof fact>[];
+    for (let node = 0; node < path.nodes.length; node += 1) {
+      const item = path.nodes[node];
+      chain.push(fact`object-id=${item.id} ${item.type} ${item.name} self-bytes=${item.selfSize}`);
+      if (node < path.edges.length) {
+        const edge = path.edges[node];
+        chain.push(fact` --${edge.type}:${String(edge.name)}--> `);
+      }
+    }
+    return line(fact`${index + 1}. `, ...chain);
+  });
+  emitResult({
+    tag: 'retainers',
+    attrs: { heap: ref.id, path: ref.dir, ...completionAttrs(ref.meta), node: objectId, paths: paths.paths.length, truncated: paths.truncated, selection: paths.selection, 'size-qualification': dominators.sizeQualification },
+    summary: text`Paths start at the nearest closure, object, or array that retains the selected object, rather than at V8's synthetic roots and handle tables. Other retaining references may exist and are not enumerated unless --paths asks for them.`,
+    artifacts: formatArtifactList([{ name: 'snapshot.heapsnapshot' }]),
+    sections: [fact`${dominators.sizeQualification}`, ...(prosePaths.length ? [lineList(prosePaths)] : [text`No application-owned retainer was found for this node.`])],
+    jsonSections: paths.paths.map(path => ({
+      path: path.nodes.map(node => ({ objectId: node.id, type: node.type, name: node.name, selfBytes: node.selfSize })),
+      edges: path.edges.map(edge => ({ type: edge.type, name: String(edge.name) })),
+      sizeQualification: dominators.sizeQualification,
+    })),
+    followUp: fact`Use \`capture heap objects ${resultReference(ref)} --constructor <name>\` to select another Chrome snapshot object id.`,
+  }, { json: parsed.json });
+}

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

@@ -0,0 +1,94 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { type ParsedArgs } from '../../types.js';
+import { captureError } from '../../../errors.js';
+import { detectCdpPort } from '../../detect.js';
+import { findTabById, openTab } from '../../targets.js';
+import { collectorHostSocketPath, startCollectorHost } from '../../bridge/spawn.js';
+import { sendHostRequest } from '../../host/client.js';
+import { scanCollectorHost, type CollectorHostHandle } from '../../host/handle.js';
+import { stopAndReapCollectorHostAtSessionStop } from '../../host/lifecycle.js';
+import { CAPTURE_ROOT, ensurePrivateDir, registerArtifactRoot } from '../../../session/artifacts.js';
+import { getActiveSession } from '../../../session-context.js';
+import { withSessionLifecycle } from '../../../session/coordinator.js';
+import { emitResult, fact, formatArtifactList, text } from '../../../output/render.js';
+import { completionAttrs, loadHeap, resolveHeapRef, resultReference } from './common.js';
+
+const HELP = `capture heap snapshot [url] — take a V8 heap snapshot of the tab's JavaScript heap
+
+input:
+  [url]   navigate to this URL and snapshot it in a one-shot session; without a URL the active session tab is snapshotted in place
+  --artifact-dir <path>  root for a sessionless heap snapshot bundle
+output: <heap-snapshot …> — the finalized snapshot artifact, its node and edge counts, on-disk bytes, and completion state; --json mirrors
+effects: drives the browser and writes a large artifact under the active session or, when sessionless, a bundle under --artifact-dir; spawns or joins the session's collector host for the duration of one snapshot and releases it immediately. Claims \`heap-snapshot\`; refused while another heap snapshot is streaming, and the refusal names the claim and its holder. Composes with a live trace and with a live mock.`;
+
+async function liveHost(sessionDir: string, port: number, targetId: string): Promise<CollectorHostHandle> {
+  let scanned = scanCollectorHost(sessionDir);
+  if (scanned.classification === 'dead') {
+    const reaped = await stopAndReapCollectorHostAtSessionStop(sessionDir);
+    if (reaped.status === 'terminal') throw new Error(reaped.error);
+    scanned = scanCollectorHost(sessionDir);
+  }
+  if (scanned.classification === 'unknown' || scanned.classification === 'malformed') throw new Error(`Collector host is ${scanned.classification}.`);
+  if (scanned.classification === 'absent') {
+    await startCollectorHost(collectorHostSocketPath(sessionDir), port, targetId, sessionDir);
+    scanned = scanCollectorHost(sessionDir);
+  }
+  if (scanned.classification !== 'live' || !scanned.handle) throw new Error('Collector host did not publish a live handle.');
+  if (scanned.handle.targetId !== targetId) throw new Error('Collector host is bound to a different tab. Stop the session before changing tabs.');
+  return scanned.handle;
+}
+
+async function collect(sessionDir: string, port: number, targetId: string): Promise<string> {
+  const host = await liveHost(sessionDir, port, targetId);
+  const started = await sendHostRequest(host.socketPath, { type: 'collector-start', nonce: host.nonce, kind: 'heap', config: {} }, 120_000);
+  if (!started.ok || !started.collector || typeof started.collector !== 'object') throw new Error(started.error ?? 'collector host refused to start heap snapshot');
+  const collector = started.collector as { id?: unknown; dir?: unknown };
+  if (typeof collector.id !== 'string' || typeof collector.dir !== 'string') throw new Error('collector host returned a malformed heap collector');
+  const stopped = await sendHostRequest(host.socketPath, { type: 'collector-stop', nonce: host.nonce, id: collector.id }, 120_000);
+  if (!stopped.ok) throw new Error(stopped.error ?? 'collector host refused to finalize heap snapshot');
+  return collector.dir;
+}
+
+function oneshotHeapDir(artifactDir?: string): string {
+  const dir = path.join(artifactDir === undefined ? CAPTURE_ROOT : registerArtifactRoot(artifactDir), `oneshot-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`, 'heap', 'snapshots');
+  ensurePrivateDir(dir);
+  return path.dirname(path.dirname(dir));
+}
+
+export async function cmdHeapSnapshot(parsed: ParsedArgs): Promise<void> {
+  if (parsed.help) {
+    console.log(HELP);
+    return;
+  }
+  const url = parsed.positional[0];
+  const active = getActiveSession();
+  const selectedPort = parsed.port ?? active?.port;
+  if (!url && (!active?.targetId || selectedPort === null || selectedPort === undefined)) {
+    throw captureError('precondition', 'heap_snapshot_unavailable', 'heap snapshot without a URL requires an active capture session with a target tab and CDP port.');
+  }
+  const port = selectedPort ?? await detectCdpPort();
+  let snapshotDir: string;
+  let targetId: string;
+  if (url) {
+    const tab = await openTab(port, url);
+    targetId = tab.id;
+    const sessionDir = oneshotHeapDir(parsed.artifactDir);
+    snapshotDir = await collect(sessionDir, port, targetId);
+  } else {
+    targetId = active!.targetId!;
+    snapshotDir = await withSessionLifecycle(active!.dir, () => collect(active!.dir, port, targetId));
+  }
+  const target = await findTabById(port, targetId);
+  if (!target) throw new Error(`Heap snapshot target ${targetId} disappeared before its URL could be recorded.`);
+  const ref = resolveHeapRef(snapshotDir);
+  const heap = loadHeap(ref);
+  const bytes = fs.statSync(path.join(ref.dir, 'snapshot.heapsnapshot')).size;
+  emitResult({
+    tag: 'heap-snapshot',
+    attrs: { heap: ref.id, path: ref.dir, url: target.url, ...completionAttrs(ref.meta), nodes: heap.nodeCount, edges: heap.edgeCount, bytes },
+    summary: text`Chrome's own .heapsnapshot, taken after Chrome's forced pre-snapshot garbage collection. This is the V8 JavaScript heap of one renderer, not the browser process's memory.`,
+    artifacts: formatArtifactList([{ name: 'snapshot.heapsnapshot', note: `${bytes} bytes` }]),
+    followUp: fact`Query heap snapshot ${resultReference(ref)} with \`capture heap census ${resultReference(ref)}\`, \`capture heap objects ${resultReference(ref)} --constructor <name>\`, or \`capture heap retainers ${resultReference(ref)} --node <object-id>\`.`,
+  }, { json: parsed.json });
+}

package/src/cdp/commands/lib.ts

@@ -37,25 +37,17 @@ import {
 
 /** Root-help representation of this leaf, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="lib">
-vault-lib introspection (dev checkout only) — discover the forked vault libs and their function schemas, then run them in the tab
-use when scripting against a bundled service lib: find the function, read its schema, invoke it via page exec
-  list · search · show · read — \`capture lib -h\`
+vault-lib introspection (dev checkout only) — discover the forked vault libs and their function schemas
+use when scripting against a bundled service library and need to find a function or read its schema
 </command>`;
 
-const LIB_USAGE = `capture lib — vault-lib introspection (dev checkout only): discover the
-forked vault libs and their function schemas, then run them in the tab via
-\`capture page exec\`.
-
-Pure local reads — no CDP connection. Requires a capture checkout with
-vault/ source + esbuild; the published package answers every leaf with a
-structured dev_only error.
-
-<subcommand name="list" args="" whenToUse="list every lib — name, function count, one-line summary"/>
-<subcommand name="search" args="<query> [--limit <n>]" whenToUse="rank functions across all libs against a query (default limit 20, max 500; multi-word queries require every token to match)"/>
-<subcommand name="show" args="<name>" whenToUse="one lib's function summaries — names + one-line descriptions, no schemas"/>
-<subcommand name="read" args="<name> [fn…]" whenToUse="full input/output JSON Schemas for named functions — the full-fidelity step before exec"/>
-
-capture lib <leaf> -h    Per-leaf usage`;
+const LIB_USAGE = `<command name="lib" description="vault library introspection for a development checkout">
+<model>Pure local reads — no CDP connection. Requires a Capture checkout with vault/ source and esbuild; the published package answers every leaf with a structured dev_only error.</model>
+<subcommand name="list" description="available libraries" whenToUse="Use to discover libraries and their summaries."/>
+<subcommand name="search" description="functions matching a query" whenToUse="Use to find a function when its library or exact name is unknown."/>
+<subcommand name="show" description="one library's function summaries" whenToUse="Use to inspect a known library's functions before selecting one."/>
+<subcommand name="read" description="function input and output schemas" whenToUse="Use to read the full schema for functions selected from a library."/>
+</command>`;
 
 const LEAF_USAGE: Record<string, string> = {
   list: `capture lib list — list every vault lib: name, function count, one-line summary.

package/src/cdp/commands/lighthouse.ts

@@ -0,0 +1,414 @@
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createRequire } from 'node:module';
+import { detectCdpPort } from '../detect.js';
+import { captureError } from '../../errors.js';
+import { type ParsedArgs } from '../types.js';
+import { selectRecords } from '../../output/selection.js';
+import { CAPTURE_ROOT, ensurePrivateDir, processPidBirthProvider, registerArtifactRoot, writeJsonPrivate, writePrivateFile } from '../../session/artifacts.js';
+import { getActiveSession } from '../../session-context.js';
+import { withSessionLifecycle } from '../../session/coordinator.js';
+import { collectorHostSocketPath, startCollectorHost } from '../bridge/spawn.js';
+import { sendHostRequest } from '../host/client.js';
+import { scanCollectorHost } from '../host/handle.js';
+import { stopAndReapCollectorHostAtSessionStop } from '../host/lifecycle.js';
+import { capped, emitResult, fact, formatArtifactList, line, lineList, text, type FactLine, type JsonValue, type RenderableResult } from '../../output/render.js';
+
+export const COMMAND_BLOCK = `<command name="lighthouse">
+a third-party scored diagnostic report — capture runs Lighthouse against a URL and stores its report unmodified
+use for one Lighthouse report's audited accessibility, SEO, performance, or best-practices conditions, categories, scores, and audits
+</command>`;
+
+const HELP = `capture lighthouse <url> [--categories <list>] [--preset mobile|desktop] [--limit <N>] [--out <path>] — run Lighthouse's third-party scored diagnostic sweep against a URL and store its report
+
+input:
+  <url>                 required. The URL Lighthouse navigates to. Lighthouse drives the browser destructively — it clears state and reloads — so it will not run against a tab another collector is recording
+  --categories <list>   comma-separated Lighthouse categories; default performance. Any category Lighthouse ships (performance, accessibility, best-practices, seo)
+  --preset <preset>     mobile (default, Lighthouse's mobile emulation and simulated throttling) or desktop
+  --limit <N>           return at most N failing nodes per audit in prose and JSON; default 25
+  --out <path>          also write Lighthouse's HTML report to this caller-owned path
+  --artifact-dir <path> root for this sessionless Lighthouse report bundle
+output: <lighthouse …> — Lighthouse's own category scores, its audit pass/fail counts, one row per failing audit, and for each failing node that audit's DOM path with its selector, snippet, and Lighthouse's own explanation; plus the absolute path to the unmodified JSON report; capture adds no assessment of its own; --json mirrors
+effects: drives the browser destructively — a sessionless report bundle lands under --artifact-dir; Lighthouse clears storage and cache and performs its own navigations on the target tab, and runs its own trace. Refused while anything holds the browser-global \`tracing\` claim, and refused while any collector is live on the target tab; both refusals name the holder.`;
+
+type NodeItem = {
+  readonly path: string;
+  readonly selector: string;
+  readonly snippet: string;
+  readonly explanation: string;
+  readonly nodeLabel?: string;
+};
+
+type FailingAudit = {
+  readonly id: string;
+  readonly title: string;
+  readonly score: number;
+  readonly items: readonly NodeItem[];
+};
+
+type Category = {
+  readonly id: string;
+  readonly score: number | null;
+  readonly auditsPassed: number;
+  readonly auditsFailed: number;
+  readonly failingAudits: readonly FailingAudit[];
+};
+
+type LighthouseReport = {
+  readonly requestedUrl?: string;
+  readonly finalUrl?: string;
+  readonly lighthouseVersion?: string;
+  readonly environment?: { readonly credits?: Record<string, string | undefined> };
+  readonly categories?: Record<string, {
+    readonly id?: string;
+    readonly score?: number | null;
+    readonly auditRefs?: readonly { readonly id?: string }[];
+  }>;
+  readonly audits?: Record<string, {
+    readonly id?: string;
+    readonly title?: string;
+    readonly score?: number | null;
+    readonly details?: { readonly items?: readonly unknown[] };
+  }>;
+};
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function string(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function nodeItem(value: unknown): NodeItem | undefined {
+  const item = record(value);
+  const node = item && record(item.node);
+  if (!node) return undefined;
+  const nodePath = string(node.path);
+  const rawSelector = node.selector;
+  const selector = typeof rawSelector === 'string'
+    ? rawSelector
+    : Array.isArray(rawSelector) && rawSelector.every(part => typeof part === 'string')
+      ? rawSelector.join(', ')
+      : undefined;
+  if (!nodePath || !selector) return undefined;
+  return {
+    path: nodePath,
+    selector,
+    snippet: string(node.snippet) ?? '',
+    explanation: string(node.explanation) ?? '',
+    nodeLabel: string(node.nodeLabel),
+  };
+}
+
+function categoriesFrom(report: LighthouseReport): readonly Category[] {
+  const audits = report.audits ?? {};
+  return Object.entries(report.categories ?? {}).map(([categoryId, category]) => {
+    const refs = category.auditRefs ?? [];
+    const categoryAudits = refs.map(ref => audits[ref.id ?? '']).filter((audit): audit is NonNullable<typeof audit> => audit !== undefined);
+    const failingAudits = categoryAudits
+      .filter((audit): audit is typeof audit & { score: number } => typeof audit.score === 'number' && audit.score < 1)
+      .map(audit => ({
+        id: audit.id ?? '',
+        title: audit.title ?? '',
+        score: audit.score,
+        items: (audit.details?.items ?? []).map(nodeItem).filter((item): item is NodeItem => item !== undefined),
+      }));
+    return {
+      id: category.id ?? categoryId,
+      score: category.score ?? null,
+      auditsPassed: categoryAudits.filter(audit => audit.score === 1).length,
+      auditsFailed: failingAudits.length,
+      failingAudits,
+    };
+  });
+}
+
+type TracingReservation = { socketPath: string; nonce: string; token: string; targetId: string };
+
+type LighthousePage = NonNullable<Parameters<typeof import('lighthouse').default>[3]>;
+
+type PuppeteerSession = { send(method: string, params?: Record<string, unknown>): Promise<unknown>; detach(): Promise<void> };
+type PuppeteerPage = { target(): { createCDPSession(): Promise<PuppeteerSession> } };
+type PuppeteerBrowser = { pages(): Promise<PuppeteerPage[]>; disconnect(): Promise<void> };
+type PuppeteerModule = { connect(options: { browserURL: string; defaultViewport: null }): Promise<PuppeteerBrowser> };
+
+function claimFailure(message: string): never {
+  throw captureError('precondition', 'claim_held', `${message} Run \`capture session collectors\` to see live collectors, stop the holder, then re-issue.`);
+}
+
+async function reserveTracing(port: number): Promise<TracingReservation | undefined> {
+  const active = getActiveSession();
+  if (!active?.targetId || active.port !== port) return undefined;
+  return withSessionLifecycle(active.dir, async () => {
+    const session = getActiveSession();
+    if (!session || session.dir !== active.dir || !session.targetId || session.port !== port) return undefined;
+    let scanned = scanCollectorHost(session.dir);
+    if (scanned.classification === 'unknown' || scanned.classification === 'malformed') {
+      throw captureError('precondition', 'collector_host_unavailable', `This session's collector host is ${scanned.classification}; Lighthouse cannot reserve the browser-global tracing claim.`);
+    }
+    if (scanned.classification === 'dead') {
+      const reaped = await stopAndReapCollectorHostAtSessionStop(session.dir);
+      if (reaped.status === 'terminal') throw captureError('precondition', 'collector_host_unavailable', `This session's collector host could not be reaped: ${reaped.error}`);
+      scanned = scanCollectorHost(session.dir);
+    }
+    if (scanned.classification === 'absent') {
+      await startCollectorHost(collectorHostSocketPath(session.dir), port, session.targetId, session.dir);
+      scanned = scanCollectorHost(session.dir);
+    }
+    if (scanned.classification !== 'live' || !scanned.handle) {
+      throw captureError('precondition', 'collector_host_unavailable', 'Collector host did not publish a live handle for Lighthouse.');
+    }
+    if (scanned.handle.targetId !== session.targetId) {
+      throw captureError('precondition', 'collector_host_target_mismatch', 'A collector host is bound to a different session target. Stop the session before running Lighthouse.');
+    }
+    const birth = processPidBirthProvider.read(process.pid);
+    if (birth.status !== 'found') {
+      throw captureError('precondition', 'collector_host_unavailable', 'Lighthouse could not establish its process identity to reserve the tracing claim.');
+    }
+    const response = await sendHostRequest(scanned.handle.socketPath, {
+      type: 'claim-reserve', nonce: scanned.handle.nonce, claims: ['tracing'], exclusive: true, holderLabel: 'lighthouse', pid: process.pid, birth: birth.identity,
+    });
+    if (!response.ok) {
+      const message = response.error ?? 'collector host refused the tracing reservation.';
+      if (message.startsWith('Claim ') || message.startsWith('Target ')) claimFailure(`Lighthouse could not reserve the target tab and browser-global tracing claim: ${message}`);
+      throw captureError('precondition', 'collector_host_reservation_failed', `Lighthouse could not reserve the target tab and browser-global tracing claim: ${message}`);
+    }
+    const reservation = response.reservation as { token?: unknown } | undefined;
+    if (!reservation || typeof reservation.token !== 'string') {
+      throw captureError('internal', 'collector_host_reservation_malformed', 'Collector host returned a malformed tracing reservation.');
+    }
+    return { socketPath: scanned.handle.socketPath, nonce: scanned.handle.nonce, token: reservation.token, targetId: session.targetId };
+  });
+}
+
+async function releaseTracing(reservation: TracingReservation): Promise<void> {
+  const response = await sendHostRequest(reservation.socketPath, { type: 'claim-release', nonce: reservation.nonce, token: reservation.token });
+  if (!response.ok) throw captureError('cleanup', 'tracing_claim_release_failed', `Lighthouse finished but its tracing reservation could not be released: ${response.error ?? 'collector host refused the release.'}`);
+}
+
+async function pageForSessionTarget(port: number, targetId: string): Promise<{ browser: PuppeteerBrowser; page: LighthousePage }> {
+  const lighthouseRequire = createRequire(require.resolve('lighthouse'));
+  const puppeteer = lighthouseRequire('puppeteer-core') as PuppeteerModule;
+  const browser = await puppeteer.connect({ browserURL: `http://localhost:${port}`, defaultViewport: null });
+  try {
+    for (const page of await browser.pages()) {
+      const session = await page.target().createCDPSession();
+      try {
+        const result = await session.send('Target.getTargetInfo') as { targetInfo?: { targetId?: unknown } };
+        if (result.targetInfo?.targetId === targetId) return { browser, page: page as LighthousePage };
+      } finally {
+        await session.detach();
+      }
+    }
+  } catch (error) {
+    try {
+      await browser.disconnect();
+    } catch (disconnectError) {
+      throw new AggregateError([error, disconnectError], 'Lighthouse could not resolve the active session target or disconnect its browser client.');
+    }
+    throw error;
+  }
+  await browser.disconnect();
+  throw captureError('precondition', 'lighthouse_target_unavailable', `Lighthouse could not find the active session target ${targetId} on CDP port ${port}.`);
+}
+
+function reportDirectory(artifactDir?: string): { id: string; dir: string } {
+  const id = `report-${Date.now().toString(36)}-${crypto.randomBytes(6).toString('hex')}`;
+  const parent = getActiveSession()?.dir ?? path.join(artifactDir === undefined ? CAPTURE_ROOT : registerArtifactRoot(artifactDir), `oneshot-${Date.now().toString(36)}-${crypto.randomBytes(4).toString('hex')}`);
+  const dir = path.join(parent, 'lighthouse', 'reports', id);
+  ensurePrivateDir(dir);
+  return { id, dir };
+}
+
+function writeHtml(pathname: string, html: string): void {
+  try {
+    ensurePrivateDir(path.dirname(pathname));
+    writePrivateFile(pathname, html);
+  } catch (error) {
+    if (path.resolve(pathname).startsWith(`${CAPTURE_ROOT}${path.sep}`)) throw error;
+    fs.writeFileSync(pathname, html);
+  }
+}
+
+function reportStrings(report: string | readonly string[]): { json: string; html: string } {
+  const outputs = Array.isArray(report) ? report : [report];
+  const json = outputs.find(output => output.trimStart().startsWith('{'));
+  const html = outputs.find(output => output.trimStart().startsWith('<'));
+  if (!json || !html) throw captureError('world', 'lighthouse_report_missing', 'Lighthouse did not return both JSON and HTML reports.');
+  return { json, html };
+}
+
+const FULL_DATA_MAX = Number.MAX_SAFE_INTEGER;
+
+function full(value: string) {
+  return capped(value, FULL_DATA_MAX);
+}
+
+function categoryJson(category: Category, limit: number): JsonValue {
+  return {
+    category: category.id,
+    score: category.score,
+    auditsPassed: category.auditsPassed,
+    auditsFailed: category.auditsFailed,
+    failingAudits: category.failingAudits.map(audit => ({
+      id: audit.id,
+      title: audit.title,
+      score: audit.score,
+      items: selectRecords(audit.items, { limit }, limit).map(item => ({
+        path: full(item.path),
+        selector: full(item.selector),
+        snippet: full(item.snippet),
+        explanation: full(item.explanation),
+        ...(item.nodeLabel === undefined ? {} : { nodeLabel: full(item.nodeLabel) }),
+      })),
+    })),
+  };
+}
+
+function categoryProse(category: Category, limit: number): FactLine {
+  const rows: FactLine[] = [fact`${category.id}: score ${category.score ?? 'not-scored'}; ${category.auditsPassed} passed audit(s), ${category.auditsFailed} failed audit(s).`];
+  for (const audit of category.failingAudits) {
+    rows.push(line(text`  `, fact`${audit.id} — ${audit.title}; score ${audit.score}`));
+    const displayed = selectRecords(audit.items, { limit }, limit);
+    for (const item of displayed) {
+      rows.push(line(text`    path: `, fact`${full(item.path)}`));
+      rows.push(line(text`    selector: `, fact`${full(item.selector)}`));
+      rows.push(line(text`    snippet: `, fact`${full(item.snippet)}`));
+      rows.push(line(text`    Lighthouse explanation: `, fact`${full(item.explanation)}`));
+      if (item.nodeLabel !== undefined) rows.push(line(text`    node label: `, fact`${full(item.nodeLabel)}`));
+    }
+    if (audit.items.length === 0) rows.push(text`    No failing nodes were attached to this audit by Lighthouse.`);
+    if (audit.items.length > displayed.length) rows.push(fact`    ${displayed.length} of ${audit.items.length} failing node(s) rendered (--limit ${limit}).`);
+  }
+  return lineList(rows);
+}
+
+function resultFor(input: {
+  id: string;
+  dir: string;
+  url: string;
+  report: LighthouseReport;
+  preset: 'mobile' | 'desktop';
+  categories: readonly string[];
+  htmlStored: boolean;
+  limit: number;
+}): RenderableResult {
+  const categories = categoriesFrom(input.report);
+  const lighthouseVersion = input.report.lighthouseVersion ?? 'unknown';
+  const axe = input.report.environment?.credits?.['axe-core'];
+  const finalUrl = input.report.finalUrl ?? input.url;
+  return {
+    tag: 'lighthouse',
+    attrs: {
+      report: input.id,
+      path: input.dir,
+      'report-path': full(path.join(input.dir, 'report.json')),
+      url: input.url,
+      'final-url': finalUrl,
+      preset: input.preset,
+      categories: input.categories.join(','),
+      lighthouse: lighthouseVersion,
+      axe,
+    },
+    summary: fact`Scores and audit results are Lighthouse's own, computed by lighthouse@${lighthouseVersion} under the ${input.preset} preset. Capture stores the report unmodified and adds no assessment of its own.`,
+    artifacts: formatArtifactList(input.htmlStored ? [{ name: 'report.json' }, { name: 'report.html' }] : [{ name: 'report.json' }]),
+    jsonArtifacts: input.htmlStored ? ['report.json', 'report.html'] : ['report.json'],
+    sections: [
+      ...categories.map(category => categoryProse(category, input.limit)),
+      text`Lighthouse applies simulated throttling by default, so its timings are not the wall-clock timings of an unthrottled load and are not comparable with capture perf vitals.`,
+      text`Failing-node selectors are minimized by axe and may drop class modifiers, so a selector can match more elements than the one that failed; the DOM path identifies the failing node.`,
+    ],
+    jsonSections: categories.map(category => categoryJson(category, input.limit)),
+  };
+}
+
+export async function cmdLighthouse(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(HELP);
+    return;
+  }
+
+  let lighthouseModule: typeof import('lighthouse');
+  try {
+    lighthouseModule = await import('lighthouse');
+  } catch (error) {
+    throw captureError('precondition', 'lighthouse_unavailable', 'Lighthouse is not installed. Install capture with its production dependencies before running this command.', error);
+  }
+
+  const url = parsed.positional[0]!;
+  const preset = parsed.preset === 'desktop' ? 'desktop' : 'mobile';
+  const categories = parsed.categories?.split(',') ?? ['performance'];
+  const port = parsed.port ?? await detectCdpPort();
+  const reservation = await reserveTracing(port);
+  let run: Awaited<ReturnType<typeof lighthouseModule.default>> | undefined;
+  let browser: PuppeteerBrowser | undefined;
+  let primary: unknown;
+  try {
+    const target = reservation && await pageForSessionTarget(port, reservation.targetId);
+    browser = target?.browser;
+    run = await lighthouseModule.default(url, {
+      port,
+      output: ['json', 'html'],
+      onlyCategories: categories,
+      logLevel: 'error',
+    }, preset === 'desktop' ? lighthouseModule.desktopConfig : undefined, target?.page);
+  } catch (error) {
+    primary = captureError('world', 'lighthouse_failed', `Lighthouse could not run: ${error instanceof Error ? error.message : String(error)}`, error);
+  }
+  const cleanupFailures: unknown[] = [];
+  if (browser) {
+    try {
+      await browser.disconnect();
+    } catch (error) {
+      cleanupFailures.push(captureError('cleanup', 'lighthouse_browser_disconnect_failed', `Lighthouse finished but its browser client could not be disconnected: ${error instanceof Error ? error.message : String(error)}`, error));
+    }
+  }
+  if (reservation) {
+    try {
+      await releaseTracing(reservation);
+    } catch (error) {
+      cleanupFailures.push(error);
+    }
+  }
+  if (primary && cleanupFailures.length > 0) throw new AggregateError([primary, ...cleanupFailures], 'Lighthouse failed and cleanup could not complete.');
+  if (primary) throw primary;
+  if (cleanupFailures.length === 1) throw cleanupFailures[0];
+  if (cleanupFailures.length > 1) throw new AggregateError(cleanupFailures, 'Lighthouse completed but cleanup could not complete.');
+  if (!run) throw captureError('world', 'lighthouse_no_report', 'Lighthouse completed without a report.');
+
+  const reports = reportStrings(run.report);
+  const artifact = reportDirectory(parsed.artifactDir);
+  const reportPath = path.join(artifact.dir, 'report.json');
+  writePrivateFile(reportPath, reports.json);
+  if (parsed.out) {
+    writePrivateFile(path.join(artifact.dir, 'report.html'), reports.html);
+    try {
+      writeHtml(parsed.out, reports.html);
+    } catch (error) {
+      throw captureError('world', 'lighthouse_html_write_failed', `Lighthouse report JSON was stored at ${reportPath}, but its HTML could not be written to ${parsed.out}: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+  }
+  const report = run.lhr as unknown as LighthouseReport;
+  writeJsonPrivate(path.join(artifact.dir, 'meta.json'), {
+    id: artifact.id,
+    url,
+    finalUrl: report.finalUrl ?? url,
+    preset,
+    categories,
+    lighthouse: report.lighthouseVersion ?? null,
+    axe: report.environment?.credits?.['axe-core'] ?? null,
+  });
+
+  emitResult(resultFor({
+    id: artifact.id,
+    dir: artifact.dir,
+    url,
+    report,
+    preset,
+    categories,
+    htmlStored: parsed.out !== undefined,
+    limit: parsed.limit ?? 25,
+  }), { json: parsed.json });
+}

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

@@ -13,8 +13,9 @@ input:
   --snap <id|path>    existing snapshot id or absolute artifact path (repeatable)
   --url <url>         URL to snap first (repeatable)
   --set-file <path>   file listing one snapshot id/path or URL per line
+  --artifact-dir <path>  root for each one-shot snapshot bundle created by --url
 output: <census axis=… snapshots=… distinct=…> — distributions with provenance where recorded, and per-region nondeterminism caveats for facts touching an unsettled capture; --json mirrors
-effects: read-only over existing snapshot artifacts; each --url writes one one-shot snapshot first`;
+effects: read-only over existing snapshot artifacts; each --url writes one one-shot snapshot bundle under --artifact-dir when supplied`;
 
 function targetsFromFile(filePath: string): string[] {
   const raw = fs.readFileSync(filePath, 'utf8');