@crouton-kit/capture 1.4.2 → 1.4.11

package/src/session/commands.ts

@@ -8,6 +8,7 @@ import {
   validateHarFile,
   type HarFile,
   type HAREntry,
+  type HttpHAREntry,
   type Header,
   type IncompleteLifecycle,
 } from '../har-manager.js';
@@ -27,7 +28,7 @@ import {
   startSessionLogTailer,
   stopSessionLogTailers,
 } from './log-tailer.js';
-import { teardownAnyLiveRecorderAtSessionStop, isTerminalRecStopFailure } from '../cdp/motion/recorder.js';
+import { stopAndReapCollectorHostAtSessionStop } from '../cdp/host/lifecycle.js';
 import {
   emitResult,
   fact,
@@ -45,13 +46,15 @@ import {
   rejectLogLabel,
   writeJsonPrivate,
   readPrivateFile,
+  registerArtifactRoot,
+  registeredArtifactRoots,
   removeArtifactTree,
   type SnapMeta,
   type RecMeta,
 } from './artifacts.js';
 import { beginSessionStop, admitSessionOperation, withSessionLifecycle, withSessionScopeLifecycle } from './coordinator.js';
 import { parseStatusFilter, type StatusPredicate } from './har-filter.js';
-import { redactUrlCredentials } from './har-redact.js';
+import { redactHeaderCredential, redactUrlCredentials } from './har-redact.js';
 
 type Session = ActiveSessionState;
 
@@ -64,11 +67,14 @@ interface BundleManifest {
   shots: Array<{ name: string; path: string }>;
   har: { id: string; path: string; entryCount: number } | null;
   logs: Array<{ name: string; path: string; lines: number }>;
+  reports: Array<{ id: string; path: string; url: string; finalUrl: string; preset: 'mobile' | 'desktop'; categories: string[]; lighthouse: string | null; axe: string | null }>;
   other: Array<{ name: string; path: string }>;
   /** `measure snap` artifacts collected from `measure/snaps/{id}/meta.json`. */
   snaps: Array<{ id: string; path: string; url: string | null; viewport: string | null; settled: boolean; capturedAt: string }>;
   /** `motion rec` artifacts collected from `motion/recs/{id}/meta.json`. */
   recs: Array<{ id: string; path: string; action: string | null; frames: number; durationMs: number; state: string; viewportRestored: boolean | null }>;
+  /** Finalized network mocks collected from `network/mocks/{id}/meta.json`. */
+  mocks?: Array<{ id: string; path: string; completion: string; rules: number; paused: number; matched: number; releasedUnmatched: number }>;
   /** Retry outcomes for viewport obligations retained by failed recorder starts. */
   pendingViewportRestorations: Array<{ recId: string; viewportRestored: boolean | null }>;
 }
@@ -99,9 +105,19 @@ function isBundleManifest(value: unknown): value is BundleManifest {
     && Array.isArray(record.shots) && record.shots.every(isNamedPathEntry)
     && validHar
     && Array.isArray(record.logs) && record.logs.every(item => isNamedPathEntry(item) && typeof (item as unknown as Record<string, unknown>).lines === 'number')
+    && Array.isArray(record.reports) && record.reports.every(item => !!item && typeof item === 'object'
+      && typeof (item as Record<string, unknown>).id === 'string'
+      && typeof (item as Record<string, unknown>).path === 'string'
+      && typeof (item as Record<string, unknown>).url === 'string'
+      && typeof (item as Record<string, unknown>).finalUrl === 'string'
+      && ((item as Record<string, unknown>).preset === 'mobile' || (item as Record<string, unknown>).preset === 'desktop')
+      && Array.isArray((item as Record<string, unknown>).categories) && ((item as Record<string, unknown>).categories as unknown[]).every(category => typeof category === 'string')
+      && ((item as Record<string, unknown>).lighthouse === null || typeof (item as Record<string, unknown>).lighthouse === 'string')
+      && ((item as Record<string, unknown>).axe === null || typeof (item as Record<string, unknown>).axe === 'string'))
     && Array.isArray(record.other) && record.other.every(isNamedPathEntry)
     && Array.isArray(record.snaps) && record.snaps.every(item => !!item && typeof item === 'object' && typeof (item as Record<string, unknown>).id === 'string' && typeof (item as Record<string, unknown>).path === 'string')
     && Array.isArray(record.recs) && record.recs.every(item => !!item && typeof item === 'object' && typeof (item as Record<string, unknown>).id === 'string' && typeof (item as Record<string, unknown>).path === 'string')
+    && (record.mocks === undefined || Array.isArray(record.mocks) && record.mocks.every(item => !!item && typeof item === 'object' && typeof (item as Record<string, unknown>).id === 'string' && typeof (item as Record<string, unknown>).path === 'string' && typeof (item as Record<string, unknown>).completion === 'string'))
     && Array.isArray(record.pendingViewportRestorations);
 }
 
@@ -125,7 +141,7 @@ function readBundleManifest(bundlePath: string): BundleManifest {
 }
 
 /** The bundle-manifest section keys `session view --filter` can address. */
-type SectionKey = 'shots' | 'har' | 'logs' | 'snaps' | 'recs' | 'other';
+type SectionKey = 'shots' | 'har' | 'logs' | 'reports' | 'snaps' | 'recs' | 'mocks' | 'other';
 
 // The `--filter <name>` query names map onto manifest section keys. Most are
 // identical; `measure`/`motion` are the query-facing names for the `snaps`/
@@ -135,8 +151,10 @@ const VIEW_FILTERS: Record<string, SectionKey> = {
   shots: 'shots',
   har: 'har',
   logs: 'logs',
+  lighthouse: 'reports',
   measure: 'snaps',
   motion: 'recs',
+  mocks: 'mocks',
   other: 'other',
 };
 
@@ -145,13 +163,15 @@ const SECTION_LABELS: Record<SectionKey, string> = {
   shots: 'shots',
   har: 'har',
   logs: 'logs',
+  reports: 'lighthouse',
   snaps: 'measure',
   recs: 'motion',
+  mocks: 'mocks',
   other: 'other',
 };
 
-function sessionDir(id: string): string {
-  return path.join(CAPTURE_ROOT, id);
+function sessionDir(id: string, artifactRoot = CAPTURE_ROOT): string {
+  return path.join(artifactRoot, id);
 }
 
 function isSessionStopped(session: Session): boolean {
@@ -178,9 +198,9 @@ export interface OneshotSession {
  * bundled/torn down by `session stop`; it accumulates under `/tmp` the same as
  * any other session dir until the OS reaps `/tmp`.
  */
-export function createOneshotSession(kind: 'measure' | 'motion' | 'page'): OneshotSession {
+export function createOneshotSession(kind: 'measure' | 'motion' | 'page', artifactDir?: string): OneshotSession {
   const id = `oneshot-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-  const dir = sessionDir(id);
+  const dir = sessionDir(id, artifactDir === undefined ? CAPTURE_ROOT : registerArtifactRoot(artifactDir));
   const artifactsDir = kind === 'measure'
     ? path.join(dir, 'measure', 'snaps')
     : kind === 'motion'
@@ -235,8 +255,36 @@ function collectRecs(dir: string): BundleManifest['recs'] {
     .map((name) => readRecMeta(path.join(recsRoot, name), name));
 }
 
-function sessionMetaPath(id: string): string {
-  return path.join(sessionDir(id), '.session.json');
+function collectMocks(dir: string): NonNullable<BundleManifest['mocks']> {
+  const mocksRoot = path.join(dir, 'network', 'mocks');
+  if (!fs.existsSync(mocksRoot)) return [];
+  return fs.readdirSync(mocksRoot).flatMap((name) => {
+    const mockDir = path.join(mocksRoot, name);
+    const metaPath = path.join(mockDir, 'meta.json');
+    if (!fs.existsSync(metaPath)) return [];
+    const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8')) as Record<string, unknown>;
+    return [{ id: typeof meta.id === 'string' ? meta.id : name, path: mockDir, completion: typeof meta.completion === 'string' ? meta.completion : 'partial', rules: typeof meta.rules === 'number' ? meta.rules : 0, paused: typeof meta.paused === 'number' ? meta.paused : 0, matched: typeof meta.matched === 'number' ? meta.matched : 0, releasedUnmatched: typeof meta.releasedUnmatched === 'number' ? meta.releasedUnmatched : 0 }];
+  });
+}
+
+function readLighthouseReportMeta(reportDir: string, fallbackId: string): BundleManifest['reports'][number] {
+  const meta = JSON.parse(fs.readFileSync(path.join(reportDir, 'meta.json'), 'utf-8')) as Partial<BundleManifest['reports'][number]>;
+  if (typeof meta.url !== 'string' || typeof meta.finalUrl !== 'string' || (meta.preset !== 'mobile' && meta.preset !== 'desktop') || !Array.isArray(meta.categories) || !meta.categories.every(category => typeof category === 'string') || (meta.lighthouse !== null && typeof meta.lighthouse !== 'string') || (meta.axe !== null && typeof meta.axe !== 'string')) {
+    throw captureError('artifact', 'invalid_lighthouse_report_metadata', `Lighthouse report metadata at ${reportDir} is invalid.`);
+  }
+  return { id: typeof meta.id === 'string' ? meta.id : fallbackId, path: reportDir, url: meta.url, finalUrl: meta.finalUrl, preset: meta.preset, categories: meta.categories, lighthouse: meta.lighthouse, axe: meta.axe };
+}
+
+function collectLighthouseReports(dir: string): BundleManifest['reports'] {
+  const reportsRoot = path.join(dir, 'lighthouse', 'reports');
+  if (!fs.existsSync(reportsRoot)) return [];
+  return fs.readdirSync(reportsRoot)
+    .filter((name) => fs.existsSync(path.join(reportsRoot, name, 'meta.json')))
+    .map((name) => readLighthouseReportMeta(path.join(reportsRoot, name), name));
+}
+
+function sessionMetaPath(id: string, artifactRoot = CAPTURE_ROOT): string {
+  return path.join(sessionDir(id, artifactRoot), '.session.json');
 }
 
 /** Outcome of reading one persisted record without failing the caller: either
@@ -253,8 +301,8 @@ type SessionRead =
  * A missing file is not a read outcome here; only `readSession` (targeted
  * commands) turns that into `unknown_session`.
  */
-function tryReadSession(id: string): SessionRead {
-  const metaPath = sessionMetaPath(id);
+function tryReadSession(id: string, artifactRoot = CAPTURE_ROOT): SessionRead {
+  const metaPath = sessionMetaPath(id, artifactRoot);
   const bad = (reason: string): SessionRead => ({ ok: false, id, metaPath, reason });
   let parsed: unknown;
   try {
@@ -277,16 +325,21 @@ function tryReadSession(id: string): SessionRead {
  * unbranded via `fact` interpolation of undefined fields).
  */
 function readSession(id: string): Session {
-  const metaPath = sessionMetaPath(id);
-  let read: SessionRead;
-  try {
-    read = tryReadSession(id);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') throw captureError('precondition', 'unknown_session', `No capture session found: ${id}`);
-    throw error;
+  const active = getActiveSession();
+  if (active?.sessionId === id) return active;
+  for (const artifactRoot of registeredArtifactRoots()) {
+    const metaPath = sessionMetaPath(id, artifactRoot);
+    let read: SessionRead;
+    try {
+      read = tryReadSession(id, artifactRoot);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+      throw error;
+    }
+    if (!read.ok) throw captureError('artifact', 'invalid_session_record', `session metadata at ${metaPath} ${read.reason}.`);
+    return read.session;
   }
-  if (!read.ok) throw captureError('artifact', 'invalid_session_record', `session metadata at ${metaPath} ${read.reason}.`);
-  return read.session;
+  throw captureError('precondition', 'unknown_session', `No capture session found: ${id}`);
 }
 
 function generateId(): string {
@@ -330,12 +383,11 @@ export async function waitForPageLoad(
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="session">
-the artifact container — a session records HAR and bundles every artifact; it may open or adopt a tab; once it has one, every command auto-targets it
-use when starting scoped work against a page: start with --url or --target, then every other capture command needs no --target/--port threading
-  start · stop · list · view · har · log — \`capture session -h\`
+the artifact container — a session records HAR and bundles every artifact; it may open or adopt a tab, and once it has one, every command auto-targets it
+use when collecting or reading the traffic, logs, and artifacts of scoped work against one page
 </command>`;
 
-const START_USAGE = `capture session start [--url <url> | --target <tab-id>] [--hold] [--port <n>] — open or adopt a tab, record HAR, and set the active capture context.
+const START_USAGE = `capture session start [--url <url> | --target <tab-id>] [--hold] [--port <n>] [--artifact-dir <path>] — open or adopt a tab, record HAR, and set the active capture context.
 
 input:
   --url <url>       Absolute URL to open in a fresh tab through CDP's
@@ -352,6 +404,7 @@ input:
                     lifetime, so browser-level state (permission grants,
                     ServiceWorker enablement) survives across separate commands.
   --port <n>         CDP port to attach to; default is auto-detected across localhost.
+  --artifact-dir <path>  Absolute root for this session bundle and every later session-owned artifact.
 
 Output:
   One <session id=… path=… [url=…] [target=… port=…]> block: the session id,
@@ -359,7 +412,7 @@ Output:
   applicable. --json mirrors the same fields.
 
 effects:
-  Creates a private session dir with shots/, starts a HAR recording, opens a
+  Creates a private session dir under --artifact-dir when supplied (otherwise the configured capture root), with shots/, starts a HAR recording, opens a
   fresh tab only when --url is supplied or adopts the resolved --target tab,
   optionally holds a CDP bridge, and registers the session as the active capture
   context so subsequent commands auto-target its tab.`;
@@ -371,7 +424,7 @@ input:
 
 Output:
   One <session-stopped id=… path=…> block: the bundle manifest path plus
-  counts (shots, HAR entries, logs, measure snaps, motion recs, other). --json
+  counts (shots, HAR entries, logs, lighthouse reports, measure snaps, motion recs, mocks, other). --json
   mirrors the same fields.
 
 effects:
@@ -398,13 +451,10 @@ const VIEW_USAGE = `capture session view <session-id> [--filter <section>] — r
 
 input:
   <session-id>        A stopped session (from \`capture session list\`).
-  --filter <section>  Show only one section: shots, har, logs, measure,
-                      motion, or other. measure -> manifest snaps, motion ->
-                      manifest recs.
+  --filter <section>  Show only one section: shots, har, logs, lighthouse, measure, motion, mocks, or other. lighthouse -> manifest reports, measure -> manifest snaps, motion -> manifest recs.
 
 Output:
-  One <session id=… path=… [filter=…]> block: the manifest sections (shots,
-  har, logs, measure snaps, motion recs, other), or a single section under
+  One <session id=… path=… [filter=…]> block: the manifest sections (shots, har, logs, lighthouse reports, measure snaps, motion recs, mocks, other), or a single section under
   --filter. --json mirrors the same fields.
 
 effects:
@@ -414,6 +464,8 @@ effects:
  * thousands of records; an unbounded list buries the row the agent came for.
  * `--limit` overrides it in either direction. */
 const DEFAULT_HAR_ROWS = 100;
+/** `--full` includes capped body detail, so its unfiltered selection has a lower bound. */
+const DEFAULT_FULL_HAR_ROWS = 10;
 
 const HAR_USAGE = `capture session har [<session-id>] — read a session's recorded HTTP traffic as a selection list.
 
@@ -423,33 +475,42 @@ input:
                             stopped one reads the bundled har.json.
   --filter-url <pattern>    substring or regex match on the request URL (matched
                             against the URL as captured, before redaction)
+  --body <url> --out <path> write one exact, complete captured response body to
+                            the caller-owned file. <url> matches exactly one
+                            completed transaction by its captured URL; the result
+                            reports its transaction id, byte count, and encoding.
   --filter-status <spec>    exact status (100-599), one-digit class prefix
                             (1-5, e.g. 4 = every 4xx), or ordered range
                             (e.g. 400-499); any other token is invalid_filter.
                             A record with no observed response never matches.
   --filter-method <method>  HTTP method (GET, POST, …)
-  --limit <n>               list at most n matching rows; default ${DEFAULT_HAR_ROWS}
-  --full                    inline per-record detail (headers, post data,
-                            response body — escaped and capped); bodies are
-                            never inlined without it
+  --limit <n>               list at most n matching rows; default ${DEFAULT_HAR_ROWS} (${DEFAULT_FULL_HAR_ROWS} with --full)
+  --full                    inline full detail (headers, post data, response body — escaped and capped); filters resolve first, then structured responses sort before unstructured records so the bounded selection reaches API-shaped bodies before page assets; identical headers shared by every rendered record are listed once, while differing headers stay with their record; bodies are never inlined without it
 
 output:
   One <session-har id=… path=… source=live|bundle entries=… incomplete=…
   total=… total-incomplete=… [truncated=true]> block listing BOTH populations
-  in one chronological selection: completed entries (method, status, URL, body
-  size, start time) and the incomplete lifecycle records the recorder retained
-  for requests that never completed — rendered as "incomplete: <kind>" (an
-  out-of-order clock also names its violation, e.g.
-  invalid_clock_order/terminal_before_response). The path attribute is the HAR
+  in chronological order by default (or structured responses first under \`--full\`): completed entries (method, status, URL, body
+  size, start time, HAR duration, response-end time) and the incomplete
+  lifecycle records the recorder retained for requests whose response never
+  completed — rendered as "incomplete: <kind>" plus their honest unavailable
+  timing state (an out-of-order request clock also names its violation, e.g.
+  invalid_clock_order/terminal_before_request). The path attribute is the HAR
   file's absolute path — the full-fidelity pointer, which holds every record
-  including the ones this list bounds away. --json mirrors the same fields.
+  including the ones this list bounds away. \`--body\` writes one complete body to
+  \`--out\` instead of listing rows; it refuses an ambiguous, absent, or truncated
+  body rather than writing a partial result. --json mirrors the same fields.
   Credential-like query parameter values (key, token, secret, signature, auth,
-  password, oauth code, …) render as REDACTED; the HAR file keeps the real
-  value. WebSockets opened while a command was recording appear as entries with
+  password, oauth code, …) render as REDACTED; credential-valued headers render
+  as redacted · <N> chars. The HAR file keeps the real values. WebSockets opened
+  while a command was recording appear as entries with
   _resourceType "websocket" and their frames in _webSocketMessages (capped at
   200 frames/socket, 4KB/frame); sockets opened before recording started are
   not visible.
 
+boundary:
+  Reports recorded transactions and does not change responses. For a counterfactual response, use \`capture tab mock start\`.
+
 effects:
   None — reads recorded HAR data only.`;
 
@@ -474,20 +535,16 @@ effects:
   the identity-bearing tailer record is registered in the session metadata.`;
 
 function printSessionHelp(): void {
-  console.log(`capture session — the artifact container: records HAR and bundles artifacts; it may open or adopt a tab.
-
-An active session with a tab auto-targets it and auto-appends recorded traffic — no
---target/--har threading. \`stop\` finalizes the session and writes its bundle
-manifest; \`view\` reads that manifest back.
-
-  <subcommand name="start" args="[--url <url> | --target <tab-id>] [--hold] [--port <n>]" whenToUse="open or adopt a tab, start HAR, and set the active capture context"/>
-  <subcommand name="stop" args="<session-id>" whenToUse="finalize the session and write its bundle manifest"/>
-  <subcommand name="list" args="" whenToUse="show active and stopped sessions"/>
-  <subcommand name="view" args="<session-id> [--filter shots|har|logs|measure|motion|other]" whenToUse="read back a stopped session's bundle manifest"/>
-  <subcommand name="har" args="[<session-id>] [--filter-url <pattern>] [--filter-status <code>] [--filter-method <method>] [--limit <n>] [--full]" whenToUse="inspect recorded traffic — completed entries and retained incomplete lifecycle records, from the live accumulating HAR of a running session or a stopped session's bundled har.json"/>
-  <subcommand name="log" args="<path> [--name <label>] [--session <id>]" whenToUse="tail an external log file into the session's logs/ dir"/>
-
-  capture session <leaf> -h    Per-leaf usage`);
+  console.log(`<command name="session" description="the artifact container: records HTTP traffic and bundles artifacts for one page">
+<model>An active session with a tab auto-targets it and appends recorded traffic; its finalized bundle remains available for readback.</model>
+<subcommand name="start" description="open or adopt a tab and start a session" whenToUse="Use when beginning scoped work against one page and collecting its artifacts."/>
+<subcommand name="stop" description="finalize a session bundle" whenToUse="Use when scoped capture is complete and its artifacts must become a bundle."/>
+<subcommand name="list" description="active and stopped sessions" whenToUse="Use to find a session to inspect or stop."/>
+<subcommand name="view" description="one stopped session's bundle" whenToUse="Use to inspect the artifacts collected by a finalized session."/>
+<subcommand name="har" description="recorded HTTP traffic" whenToUse="Use to inspect requests from a running session or a finalized bundle."/>
+<subcommand name="log" description="tail an external log into a session" whenToUse="Use to add external process output to a session's bundled artifacts."/>
+<subcommand name="collectors" description="what is collecting right now" whenToUse="Use to see live traces, recordings, heap snapshots, and mocks before starting one that would conflict."/>
+</command>`);
 }
 
 // ============================================================================
@@ -503,7 +560,7 @@ manifest; \`view\` reads that manifest back.
 export interface SessionStartWorld {
   createHar(dir: string): Promise<string>;
   deleteHar(harId: string): Promise<void>;
-  detectCdpPort(): Promise<number>;
+  detectCdpPort(): Promise<number | { port: number; app: string; selectionReason: string }>;
   openTab(port: number, url: string): Promise<CDPTarget>;
   findTabById(port: number, targetId: string): Promise<CDPTarget | null>;
   closeTarget(port: number, targetId: string): Promise<void>;
@@ -520,8 +577,8 @@ const productionStartWorld: SessionStartWorld = {
   },
   deleteHar: deleteHarRecording,
   async detectCdpPort() {
-    const { detectCdpPort } = await import('../cdp.js');
-    return detectCdpPort();
+    const { detectCdpEndpoint } = await import('../cdp/detect.js');
+    return detectCdpEndpoint();
   },
   async openTab(port, url) {
     const { openTab } = await import('../cdp.js');
@@ -604,7 +661,7 @@ async function start(parsed: ParsedArgs): Promise<void> {
     return;
   }
 
-  if (rejectSurplusPositionals(parsed, 'start', 0, 'capture session start [--url <url> | --target <tab-id>] [--hold] [--port <n>]')) return;
+  if (rejectSurplusPositionals(parsed, 'start', 0, 'capture session start [--url <url> | --target <tab-id>] [--hold] [--port <n>] [--artifact-dir <path>]')) return;
 
   return withSessionScopeLifecycle(async () => {
     const active = getActiveSession();
@@ -623,7 +680,7 @@ async function start(parsed: ParsedArgs): Promise<void> {
     const requestedTarget = parsed.target ?? null;
     const hold = parsed.hold === true;
     const id = generateId();
-    const dir = sessionDir(id);
+    const dir = sessionDir(id, parsed.artifactDir === undefined ? CAPTURE_ROOT : registerArtifactRoot(parsed.artifactDir));
 
     // Every effect below is owned the instant it succeeds and released in exact
     // reverse order if any later step throws. Nothing is committed outside this
@@ -635,6 +692,8 @@ async function start(parsed: ParsedArgs): Promise<void> {
     let bridgeSocket: string | null = null;
     let bridgePid: number | null = null;
     let cdpPort: number | null = null;
+    let selectedBrowser: string | null = null;
+    let endpointSelectionReason: string | null = null;
 
     try {
       ensurePrivateDir(path.join(dir, 'shots'));
@@ -644,8 +703,13 @@ async function start(parsed: ParsedArgs): Promise<void> {
       const acquiredHarId = harId;
       acquired.push({ label: 'HAR recording', release: () => startWorld.deleteHar(acquiredHarId) });
 
-      if (url || requestedTarget || hold) {
-        cdpPort = parsed.port ?? await startWorld.detectCdpPort();
+      if (parsed.port !== undefined) {
+        cdpPort = parsed.port;
+      } else if (url || requestedTarget || hold) {
+        const detected = await startWorld.detectCdpPort();
+        cdpPort = typeof detected === 'number' ? detected : detected.port;
+        selectedBrowser = typeof detected === 'number' ? null : detected.app;
+        endpointSelectionReason = typeof detected === 'number' ? null : detected.selectionReason;
       }
 
       if (requestedTarget) {
@@ -715,6 +779,13 @@ async function start(parsed: ParsedArgs): Promise<void> {
 
     const rows: FactLine[] = [fact`bundle dir: ${dir}`];
     if (target) rows.push(url ? fact`tab ${target.id} opened at ${url}` : fact`tab ${target.id} adopted at ${target.url}`);
+    if (cdpPort !== null) rows.push(
+      parsed.portSource === 'env'
+        ? fact`CDP endpoint on port ${cdpPort} selected from ambient CDP_PORT; --port overrides endpoint selection and --target overrides tab selection.`
+        : parsed.port !== undefined
+          ? fact`CDP endpoint on port ${cdpPort} selected by explicit --port; --port overrides endpoint selection and --target overrides tab selection.`
+          : fact`${selectedBrowser ?? 'CDP endpoint'} on port ${cdpPort} auto-selected because it ${endpointSelectionReason ?? 'was selected by automatic endpoint detection'}; capture-launched browser recency does not affect selection. --port overrides endpoint selection and --target overrides tab selection.`,
+    );
     if (pageLoadTimedOut) rows.push(fact`page load timed out after 10000ms; the session stays attached to target ${target?.id ?? ''}`);
     if (harId) rows.push(fact`HAR recording ${harId} — traffic auto-appends while the session is active`);
     if (hold) rows.push(fact`held CDP bridge: pid ${bridgePid ?? 0}`);
@@ -1022,8 +1093,44 @@ function harUrl(url: string): FactLine {
   return data(redactUrlCredentials(url), 300);
 }
 
-/** One selection-list row: method, status, URL, body size, start time. Body
- * content is NEVER inlined here (I-7) — `--full` is the only opt-in. */
+function responseEndDateTime(
+  requestWallTime: number,
+  requestMonotonic: number,
+  terminalMonotonic: number,
+): string | null {
+  const end = new Date((requestWallTime + terminalMonotonic - requestMonotonic) * 1000);
+  return Number.isNaN(end.getTime()) ? null : end.toISOString();
+}
+
+function completedTiming(e: HAREntry): FactLine {
+  const { clocks, terminal } = e._capture;
+  if (terminal.kind === 'failed') {
+    return fact`duration ${e.time} ms — response incomplete: failed`;
+  }
+  if (terminal.kind === 'redirect' && e.response.status === 0) {
+    return fact`duration ${e.time} ms — response incomplete: redirect without HTTP response`;
+  }
+  const ended = responseEndDateTime(clocks.requestWallTime, clocks.requestMonotonic, clocks.terminalMonotonic);
+  return ended === null
+    ? fact`duration ${e.time} ms — response end unavailable`
+    : fact`duration ${e.time} ms — response ended ${ended}`;
+}
+
+function incompleteTiming(record: IncompleteLifecycle): FactLine {
+  if (record.kind === 'stopped_during_body') {
+    const { requestWallTime, requestMonotonic, terminalMonotonic } = record._capture;
+    const duration = (terminalMonotonic - requestMonotonic) * 1000;
+    const ended = responseEndDateTime(requestWallTime, requestMonotonic, terminalMonotonic);
+    return ended === null
+      ? fact`duration ${duration} ms — response end unavailable`
+      : fact`duration ${duration} ms — response ended ${ended}`;
+  }
+  if (record.kind === 'invalid_clock_order') {
+    return fact`timing unavailable: ${incompleteLabel(record)}`;
+  }
+  return text`response incomplete: terminal event never observed`;
+}
+
 function harEntryRow(e: HAREntry): FactLine {
   const bodyText = e.response.content?.text;
   const sizePart = typeof bodyText === 'string'
@@ -1034,13 +1141,11 @@ function harEntryRow(e: HAREntry): FactLine {
     harUrl(e.request.url),
     text` — `,
     sizePart,
-    fact` — started ${e.startedDateTime}`,
+    fact` — started ${e.startedDateTime} — `,
+    completedTiming(e),
   );
 }
 
-/** One selection-list row for an incomplete lifecycle record: it names the
- * kind (and clock violation) in place of the body size a completed entry
- * reports, so a row is never mistaken for finished traffic. */
 function harIncompleteRow(record: IncompleteLifecycle): FactLine {
   const response = incompleteResponse(record);
   return line(
@@ -1048,22 +1153,76 @@ function harIncompleteRow(record: IncompleteLifecycle): FactLine {
     harUrl(record.request.url),
     text` — `,
     fact`incomplete: ${incompleteLabel(record)}`,
-    fact` — started ${record.startedDateTime}`,
+    fact` — started ${record.startedDateTime} — `,
+    incompleteTiming(record),
   );
 }
 
-/** `--full` inline detail for one entry: headers, post data, and response
- * body — every value escaped and capped through data()/fact. */
-function harEntryDetail(e: HAREntry, index: number): FactLine {
+function harHeader(prefix: 'req' | 'res', header: Header): FactLine {
+  return fact`   ${prefix} ${header.name}: ${redactHeaderCredential(header.name, header.value)}`;
+}
+
+interface SharedHarHeaders {
+  request?: readonly Header[];
+  response?: readonly Header[];
+}
+
+function headersEqual(left: readonly Header[], right: readonly Header[]): boolean {
+  return left.length === right.length && left.every((header, index) => header.name === right[index]?.name && header.value === right[index]?.value);
+}
+
+function requestHeaders(item: HarSelection): readonly Header[] {
+  return item.kind === 'complete' ? item.entry.request.headers ?? [] : item.record.request.headers ?? [];
+}
+
+function responseHeaders(item: HarSelection): readonly Header[] | undefined {
+  if (item.kind === 'complete') return item.entry.response.headers ?? [];
+  return incompleteResponse(item.record)?.headers;
+}
+
+function isStructuredResponse(item: HarSelection): boolean {
+  if (item.kind !== 'complete') return false;
+  const contentType = responseHeaders(item)?.find((header) => header.name.toLowerCase() === 'content-type')?.value.toLowerCase().split(';', 1)[0]?.trim();
+  return contentType === 'application/json' || contentType === 'text/json' || contentType === 'application/x-ndjson' || contentType === 'application/xml' || contentType === 'text/xml' || contentType?.endsWith('+json') === true || contentType?.endsWith('+xml') === true;
+}
+
+/** `--full` resolves filters before this ordering, then selects its bounded record set. */
+function prioritizeFullHarSelection(items: readonly HarSelection[]): HarSelection[] {
+  return [...items].sort((left, right) => Number(isStructuredResponse(right)) - Number(isStructuredResponse(left)));
+}
+
+/** Hoist only complete identical header lists shared by every displayed row; every differing value remains next to its record. */
+function sharedHarHeaders(shown: readonly HarSelection[]): SharedHarHeaders {
+  if (shown.length < 2) return {};
+  const request = requestHeaders(shown[0]!);
+  const response = responseHeaders(shown[0]!);
+  return {
+    ...(request.length > 0 && shown.every((item) => headersEqual(request, requestHeaders(item))) ? { request } : {}),
+    ...(response && response.length > 0 && shown.every((item) => {
+      const candidate = responseHeaders(item);
+      return candidate !== undefined && headersEqual(response, candidate);
+    }) ? { response } : {}),
+  };
+}
+
+function sharedHeaderDetail(prefix: 'req' | 'res', headers: readonly Header[], shown: number): FactLine {
+  return lineList([
+    fact`shared ${prefix === 'req' ? 'request' : 'response'} headers (all ${shown} rendered records):`,
+    ...headers.map((header) => harHeader(prefix, header)),
+  ]);
+}
+
+/** `--full` inline detail for one entry: record-specific headers, post data, and response body — every value escaped and capped through data()/fact. */
+function harEntryDetail(e: HAREntry, index: number, shared: SharedHarHeaders): FactLine {
   const rows: FactLine[] = [line(fact`${index + 1}. `, harEntryRow(e))];
-  for (const h of e.request.headers ?? []) {
-    rows.push(fact`   req ${h.name}: ${h.value}`);
+  if (!shared.request) {
+    for (const h of e.request.headers ?? []) rows.push(harHeader('req', h));
   }
   if (e.request.postData?.text !== undefined) {
     rows.push(fact`   post data: ${capped(e.request.postData.text, 2000)}`);
   }
-  for (const h of e.response.headers ?? []) {
-    rows.push(fact`   res ${h.name}: ${h.value}`);
+  if (!shared.response) {
+    for (const h of e.response.headers ?? []) rows.push(harHeader('res', h));
   }
   const bodyText = e.response.content?.text;
   rows.push(
@@ -1074,21 +1233,19 @@ function harEntryDetail(e: HAREntry, index: number): FactLine {
   return lineList(rows);
 }
 
-/** `--full` inline detail for one incomplete lifecycle record: the same
- * headers/post data a completed entry shows, plus the provenance that explains
- * why the lifecycle never completed. */
-function harIncompleteDetail(record: IncompleteLifecycle, index: number): FactLine {
+/** `--full` inline detail for one incomplete lifecycle record: record-specific headers/post data plus the lifecycle provenance. */
+function harIncompleteDetail(record: IncompleteLifecycle, index: number, shared: SharedHarHeaders): FactLine {
   const rows: FactLine[] = [line(fact`${index + 1}. `, harIncompleteRow(record))];
   rows.push(fact`   request ${record.requestId} (generation ${record.generation})`);
-  for (const h of record.request.headers ?? []) {
-    rows.push(fact`   req ${h.name}: ${h.value}`);
+  if (!shared.request) {
+    for (const h of record.request.headers ?? []) rows.push(harHeader('req', h));
   }
   if (record.request.postData?.text !== undefined) {
     rows.push(fact`   post data: ${capped(record.request.postData.text, 2000)}`);
   }
   const response = incompleteResponse(record);
-  for (const h of response?.headers ?? []) {
-    rows.push(fact`   res ${h.name}: ${h.value}`);
+  if (!shared.response) {
+    for (const h of response?.headers ?? []) rows.push(harHeader('res', h));
   }
   if (record.kind === 'invalid_clock_order') {
     rows.push(fact`   terminal: ${record.terminal.kind}`);
@@ -1101,6 +1258,67 @@ function harIncompleteDetail(record: IncompleteLifecycle, index: number): FactLi
   return lineList(rows);
 }
 
+function completeBodyBytes(entry: HttpHAREntry): Buffer | { code: string; message: string } {
+  const provenance = entry._capture.body;
+  if (provenance.state !== 'captured') {
+    return { code: 'body_unavailable', message: `The selected transaction has no captured response body (${provenance.state === 'fetch_failed' ? provenance.error : provenance.reason}).` };
+  }
+  if (provenance.truncated) {
+    return { code: 'body_truncated', message: `The selected transaction retained ${provenance.capturedByteLength} of ${provenance.decodedByteLength} response bytes, so capture cannot export it as a complete body.` };
+  }
+  const content = entry.response.content.text;
+  if (content === undefined) {
+    return { code: 'body_unavailable', message: 'The selected transaction claims a captured response body but its HAR content is absent.' };
+  }
+  return provenance.sourceEncoding === 'base64' ? Buffer.from(content, 'base64') : Buffer.from(content, 'utf8');
+}
+
+function exportHarBody(id: string, located: HarSource, parsed: ParsedArgs): boolean {
+  if (parsed.body === undefined) return false;
+  if (!parsed.out) {
+    emitResult({ tag: 'error', attrs: { command: 'session har', code: 'body_out_required' }, summary: fact`--body requires --out <path>; response bytes are written only to a caller-named file.` }, { json: parsed.json });
+    process.exitCode = 1;
+    return true;
+  }
+  if (parsed.filterUrl !== undefined || parsed.filterStatus !== undefined || parsed.filterMethod !== undefined || parsed.limit !== undefined || parsed.full) {
+    emitResult({ tag: 'error', attrs: { command: 'session har', code: 'body_selection_conflict' }, summary: fact`--body selects one exact captured URL and cannot be combined with --filter-url, --filter-status, --filter-method, --limit, or --full.` }, { json: parsed.json });
+    process.exitCode = 1;
+    return true;
+  }
+  const matches = located.har.log.entries.filter((entry): entry is HttpHAREntry => entry.request.url === parsed.body && '_capture' in entry);
+  if (matches.length !== 1) {
+    const code = matches.length === 0 ? 'body_not_found' : 'body_ambiguous';
+    const message = matches.length === 0
+      ? line(text`No completed captured transaction has the exact URL `, harUrl(parsed.body), text`.`)
+      : line(fact`${matches.length} completed captured transactions have the exact URL `, harUrl(parsed.body), text`; --body requires one recorded transaction.`);
+    emitResult({ tag: 'error', attrs: { command: 'session har', code }, summary: message }, { json: parsed.json });
+    process.exitCode = 1;
+    return true;
+  }
+  const entry = matches[0]!;
+  const bytes = completeBodyBytes(entry);
+  if (!(bytes instanceof Buffer)) {
+    emitResult({ tag: 'error', attrs: { command: 'session har', code: bytes.code }, summary: fact`${bytes.message}` }, { json: parsed.json });
+    process.exitCode = 1;
+    return true;
+  }
+  try {
+    fs.writeFileSync(parsed.out, bytes);
+  } catch (cause) {
+    emitResult({ tag: 'error', attrs: { command: 'session har', code: 'body_write_failed' }, summary: fact`The selected response body was not written to ${parsed.out}: ${cause instanceof Error ? cause.message : String(cause)}` }, { json: parsed.json });
+    process.exitCode = 1;
+    return true;
+  }
+  const provenance = entry._capture.body;
+  emitResult({
+    tag: 'session-har',
+    attrs: { id, path: located.path, source: located.source, 'body-path': parsed.out, bytes: bytes.length, encoding: provenance.sourceEncoding, transaction: entry._capture.requestId, generation: entry._capture.generation, status: entry.response.status },
+    summary: line(fact`Wrote the complete recorded response body for ${entry.request.method} `, harUrl(entry.request.url), fact` to ${parsed.out}.`),
+    sections: [fact`Transaction ${entry._capture.requestId} (generation ${entry._capture.generation}) started ${entry.startedDateTime}; capture recorded ${provenance.capturedByteLength} of ${provenance.decodedByteLength} decoded bytes with ${provenance.sourceEncoding} encoding (truncated=${String(provenance.truncated)}).`],
+  }, { json: parsed.json });
+  return true;
+}
+
 async function har(parsed: ParsedArgs): Promise<void> {
   if (parsed.help) {
     console.log(HAR_USAGE);
@@ -1169,6 +1387,13 @@ async function har(parsed: ParsedArgs): Promise<void> {
     return;
   }
 
+  if (exportHarBody(id, located, parsed)) return;
+  if (parsed.out) {
+    emitResult({ tag: 'error', attrs: { command: 'session har', code: 'out_requires_body' }, summary: fact`--out is only available with --body <url>; it names the caller-owned response-body file.` }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+
   let selection = buildHarSelection(located.har);
   const total = located.har.log.entries.length;
   const totalIncomplete = located.har.incompleteLifecycles.length;
@@ -1200,7 +1425,8 @@ async function har(parsed: ParsedArgs): Promise<void> {
 
   const requestedLimit = typeof parsed.limit === 'number' && parsed.limit > 0 ? parsed.limit : null;
   if (requestedLimit !== null) filters.push(`limit=${requestedLimit}`);
-  const bound = requestedLimit ?? DEFAULT_HAR_ROWS;
+  if (parsed.full) selection = prioritizeFullHarSelection(selection);
+  const bound = requestedLimit ?? (parsed.full ? DEFAULT_FULL_HAR_ROWS : DEFAULT_HAR_ROWS);
   const matched = selection.length;
   const shown = selection.slice(0, bound);
   const truncated = matched > shown.length;
@@ -1215,7 +1441,14 @@ async function har(parsed: ParsedArgs): Promise<void> {
   const summary = fact`${shownEntries} of ${total} complete entries and ${shownIncomplete} of ${totalIncomplete} incomplete lifecycle records listed${filterNote}.${truncationNote}`;
 
   const sections = parsed.full
-    ? shown.map((item, i) => (item.kind === 'complete' ? harEntryDetail(item.entry, i) : harIncompleteDetail(item.record, i)))
+    ? (() => {
+      const shared = sharedHarHeaders(shown);
+      return [
+        ...(shared.request ? [sharedHeaderDetail('req', shared.request, shown.length)] : []),
+        ...(shared.response ? [sharedHeaderDetail('res', shared.response, shown.length)] : []),
+        ...shown.map((item, i) => (item.kind === 'complete' ? harEntryDetail(item.entry, i, shared) : harIncompleteDetail(item.record, i, shared))),
+      ];
+    })()
     : [lineList(shown.map((item, i) => line(
       fact`${i + 1}. `,
       item.kind === 'complete' ? harEntryRow(item.entry) : harIncompleteRow(item.record),
@@ -1234,7 +1467,10 @@ async function har(parsed: ParsedArgs): Promise<void> {
       truncated: truncated ? true : undefined,
     },
     summary,
-    sections,
+    sections: [
+      ...sections,
+      fact`Recorded transactions only; this read does not change responses. \`capture tab mock start\` serves a counterfactual response.`,
+    ],
   }, { json: parsed.json });
 }
 
@@ -1243,8 +1479,10 @@ function bundleRows(manifest: BundleManifest): FactLine[] {
     fact`shots: ${manifest.shots.length}`,
     manifest.har ? fact`har: ${manifest.har.entryCount} entries — ${manifest.har.path}` : fact`har: 0 entries`,
     fact`logs: ${manifest.logs.length}`,
+    fact`lighthouse reports: ${manifest.reports.length}`,
     fact`measure snaps: ${manifest.snaps.length}`,
     fact`motion recs: ${manifest.recs.length}`,
+    fact`mocks: ${manifest.mocks?.length ?? 0}`,
     fact`other: ${manifest.other.length}`,
   ];
 }
@@ -1332,19 +1570,9 @@ async function stop(parsed: ParsedArgs): Promise<void> {
       await stopSessionLogTailers(session.logPids ?? []);
       if (session.bridgePid || session.bridgeSocket) stopBridge(session.bridgePid, session.bridgeSocket);
 
-      let recorderTeardown: Awaited<ReturnType<typeof teardownAnyLiveRecorderAtSessionStop>> | null = null;
-      try {
-        recorderTeardown = await teardownAnyLiveRecorderAtSessionStop(session.dir);
-      } catch (error) {
-        // A terminal `rec-stop` failure (the bridge authenticated the request
-        // and explicitly refused — e.g. a fatal HAR drain) must NOT be
-        // swallowed into a warning: it escapes to the outer `stop_failed`
-        // lane below, so no bundle is committed and no live HAR/recorder
-        // handle is deleted while admitted append work may still be lost.
-        // Non-fatal teardown noise (dead handle, liveness-unknown, malformed
-        // handle) keeps the existing warn-and-continue policy.
-        if (isTerminalRecStopFailure(error)) throw error;
-        console.error(`Warning: could not finalize active recording: ${error instanceof Error ? error.message : error}`);
+      const hostTeardown = await stopAndReapCollectorHostAtSessionStop(session.dir);
+      if (hostTeardown.status === 'terminal') {
+        throw new Error(`collector host teardown failed: ${hostTeardown.error}`);
       }
 
       const shotsDir = path.join(session.dir, 'shots');
@@ -1370,7 +1598,9 @@ async function stop(parsed: ParsedArgs): Promise<void> {
         : [];
       const snaps = collectSnaps(session.dir);
       const recs = collectRecs(session.dir);
-      const knownDirs = new Set(['shots', 'logs', 'measure', 'motion', '.har', '.stop.lock', '.operations.lock']);
+      const mocks = collectMocks(session.dir);
+      const reports = collectLighthouseReports(session.dir);
+      const knownDirs = new Set(['shots', 'logs', 'lighthouse', 'measure', 'motion', 'network', '.har', '.stop.lock', '.operations.lock']);
       const knownFiles = new Set(['.session.json', '.operations.json', 'har.json', 'bundle.json', 'bridge.sock']);
       const other = fs.readdirSync(session.dir)
         .filter(name => !knownDirs.has(name) && !knownFiles.has(name))
@@ -1385,10 +1615,12 @@ async function stop(parsed: ParsedArgs): Promise<void> {
         shots,
         har,
         logs,
+        reports,
         other,
         snaps,
         recs,
-        pendingViewportRestorations: recorderTeardown?.pendingViewportRestorations ?? [],
+        mocks,
+        pendingViewportRestorations: [],
       };
 
       // The immutable bundle is the commit point. Live HAR deletion, stopped
@@ -1400,8 +1632,6 @@ async function stop(parsed: ParsedArgs): Promise<void> {
       committed = true;
 
       const rows = bundleRows(manifest);
-      if (recorderTeardown && 'recId' in recorderTeardown) rows.push(fact`recorder ${recorderTeardown.recId} finalized — state ${recorderTeardown.state}, viewport restored ${String(recorderTeardown.viewportRestored)}`);
-      if (recorderTeardown?.pendingViewportRestorations.length) rows.push(fact`pending viewport restorations: ${recorderTeardown.pendingViewportRestorations.length}`);
       emitResult({
         tag: 'session-stopped',
         attrs: { id, path: bundlePath },
@@ -1431,14 +1661,14 @@ function list(parsed: ParsedArgs): void {
 
   if (rejectSurplusPositionals(parsed, 'list', 0, 'capture session list')) return;
 
-  const reads = fs.existsSync(CAPTURE_ROOT)
-    ? fs.readdirSync(CAPTURE_ROOT)
-        .filter((d) => fs.existsSync(sessionMetaPath(d)))
+  const reads = registeredArtifactRoots().flatMap((artifactRoot) => fs.existsSync(artifactRoot)
+    ? fs.readdirSync(artifactRoot)
+        .filter((d) => fs.existsSync(sessionMetaPath(d, artifactRoot)))
         .flatMap((d) => {
           // A record deleted between readdir and read is simply gone, not unreadable.
-          try { return [tryReadSession(d)]; } catch { return []; }
+          try { return [tryReadSession(d, artifactRoot)]; } catch { return []; }
         })
-    : [];
+    : []);
 
   const sessions = reads.flatMap((read) => {
     if (!read.ok) return [];
@@ -1488,12 +1718,17 @@ function sectionRows(manifest: BundleManifest, key: SectionKey): FactLine[] {
         : [];
     case 'logs':
       return manifest.logs.map((l) => fact`${l.name} — ${l.lines} lines — ${l.path}`);
+    case 'reports':
+      return manifest.reports.map((r) => fact`${r.id} — url ${r.url} — final URL ${r.finalUrl} — ${r.preset} — categories ${r.categories.join(',')} — ${r.path}`);
     case 'snaps':
       return manifest.snaps.map((s) =>
         fact`${s.id} — url ${s.url ?? '(none)'} — viewport ${s.viewport ?? '(none)'} — settled ${String(s.settled)} — ${s.path}`);
     case 'recs':
       return manifest.recs.map((r) =>
         fact`${r.id} — ${r.action ?? '(none)'} — ${r.frames} frames, ${r.durationMs}ms, ${r.state} — ${r.path}`);
+    case 'mocks':
+      return (manifest.mocks ?? []).map((m) =>
+        fact`${m.id} — ${m.completion} — ${m.matched}/${m.paused} matched/paused, ${m.releasedUnmatched} released unmatched — ${m.path}`);
     case 'other':
       return manifest.other.map((o) => fact`${o.name} — ${o.path}`);
   }
@@ -1557,7 +1792,7 @@ function view(parsed: ParsedArgs): void {
       emitResult({
         tag: 'error',
         attrs: { command: 'session view', code: 'invalid_filter' },
-        summary: fact`received: --filter ${parsed.filter}; expected one of: shots, har, logs, measure, motion, other.`,
+        summary: fact`received: --filter ${parsed.filter}; expected one of: shots, har, logs, lighthouse, measure, motion, mocks, other.`,
         followUp: text`Re-run \`capture session view <id> --filter <section>\` with a valid section.`,
       }, { json: parsed.json });
       process.exitCode = 1;
@@ -1574,7 +1809,7 @@ function view(parsed: ParsedArgs): void {
     return;
   }
 
-  const keys: SectionKey[] = ['shots', 'har', 'logs', 'snaps', 'recs', 'other'];
+  const keys: SectionKey[] = ['shots', 'har', 'logs', 'reports', 'snaps', 'recs', 'mocks', 'other'];
   const sections = keys.map((key) => {
     const rows = sectionRows(manifest, key);
     return lineList([