@crouton-kit/capture 1.4.2 → 1.4.10

package/src/cdp/commands/tab/mock/start.ts

@@ -0,0 +1,65 @@
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { captureError } from '../../../../errors.js';
+import { CAPTURE_ROOT, unlinkPrivateFile, writePrivateFile } from '../../../../session/artifacts.js';
+import { emitResult, fact, formatArtifactList, text, type RenderableResult } from '../../../../output/render.js';
+import { type ParsedArgs } from '../../../types.js';
+import { parseMockRuleDocument } from '../../../host/collectors/intercept.js';
+import { startMock } from './lifecycle.js';
+
+const HELP = `capture tab mock start --rules <path> — intercept the tab's requests and answer them from a rule document
+
+input:
+  --rules <path>   required. Path to a JSON rule document (schema below). Requires an active session with a target; the rules live only as long as the mock, and \`capture tab mock stop\` removes them
+output: <mock …> — the installed mock, its rule count, and the artifact directory holding the copy of exactly what was installed; --json mirrors
+effects: changes what the tab's network does; spawns or joins the session's collector host, which holds the tab connection until the mock is stopped. Claims \`fetch-interception\`: refused while another mock is live, naming its holder. Composes with a live trace and with a live motion recording.
+
+rule document:
+{ "rules": [{ "url": "https://api.example.com/users*", "methods": ["GET"], "resourceTypes": ["XHR", "Fetch"], "fulfill": { "status": 200, "headers": { "content-type": "application/json" }, "body": "{\\"users\\":[]}" } }, { "url": "https://cdn.example.com/*.png", "fail": { "reason": "Failed" } }, { "url": "https://api.example.com/health", "passthrough": {} }, { "url": "https://api.example.com/*", "modify": { "headers": { "x-test": "1" } } }] }
+
+- An ordered list; first match wins; there is no priority field, because order is the priority.
+- \`url\` is a \`*\`-glob over the full URL — the same syntax CDP's own \`Fetch.enable\` patterns use. No regex in v1.
+- \`methods\` and \`resourceTypes\` are optional narrowing sets. Omitted means "any".
+- Exactly one action per rule: \`fulfill\`, \`fail\`, \`modify\`, or \`passthrough\`. \`passthrough\` exists so a specific request can shadow a later broad rule.
+- There is no default rule and no way to configure one. An unmatched request is continued unmodified.
+- \`fulfill\` bodies are inline (\`body\` string, or \`bodyBase64\`). File-referenced bodies are deferred.
+- Load is all-or-nothing: an unparseable pattern, unknown action, or oversized body refuses the whole document and nothing is installed. \`Fetch.enable\` is never sent for a document that failed validation.`;
+
+function stagedRulesPath(): string { return path.join(CAPTURE_ROOT, '.mock-inputs', `rules-${crypto.randomBytes(12).toString('hex')}.json`); }
+
+function sourceFor(pathname: string): { source: Buffer; rules: number } {
+  let source: Buffer;
+  try { source = fs.readFileSync(pathname); }
+  catch (error) { throw captureError('artifact', 'mock_rules_unreadable', `could not read mock rules at ${pathname}: ${error instanceof Error ? error.message : String(error)}`); }
+  try { return { source, rules: parseMockRuleDocument(source).length }; }
+  catch (error) { throw captureError('invocation', 'invalid_mock_rules', `received: ${pathname}\nexpected: a valid tab mock rule document\nfield: --rules\nreason: ${error instanceof Error ? error.message : String(error)}\nNext: Run \`capture tab mock start -h\` and read the rule-document schema before re-issuing.`); }
+}
+
+export function buildMockStartedResult(mock: { id: string; dir: string; rules: number; targetId: string }): RenderableResult {
+  return {
+    tag: 'mock',
+    attrs: { mock: mock.id, path: mock.dir, state: 'live', rules: mock.rules, target: mock.targetId },
+    summary: fact`Installed ${mock.rules} ordered mock rule(s) on the session tab. Requests are answered from the rule document copied to rules.json; first match wins.`,
+    artifacts: formatArtifactList([{ name: 'rules.json', note: 'the exact installed rule document' }]),
+    followUp: text`Stop and finalize this mock with \`capture tab mock stop\`.`,
+  };
+}
+
+export async function cmdTabMockStart(parsed: ParsedArgs): Promise<void> {
+  if (parsed.help) {
+    console.log(HELP);
+    return;
+  }
+  const rulesPath = parsed.rules;
+  if (!rulesPath) throw captureError('invocation', 'missing_rules', 'received: no rule document\nexpected: --rules <path>\nfield: --rules\nNext: Run `capture tab mock start -h` and read the schema before re-issuing.');
+  const loaded = sourceFor(rulesPath);
+  const staged = stagedRulesPath();
+  writePrivateFile(staged, loaded.source);
+  try {
+    const mock = await startMock(staged, loaded.rules);
+    emitResult(buildMockStartedResult(mock), { json: parsed.json });
+  } finally {
+    try { unlinkPrivateFile(staged); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  }
+}

package/src/cdp/commands/tab/mock/stop.ts

@@ -0,0 +1,39 @@
+import { emitResult, fact, formatArtifactList, type RenderableResult } from '../../../../output/render.js';
+import { type ParsedArgs } from '../../../types.js';
+import { stopMock, type StoppedMock } from './lifecycle.js';
+
+const HELP = `capture tab mock stop — remove the mock rules and finalize the record of what was mocked
+
+input:
+  (none)   the session's one live mock is selected without an id
+output: <mock …> — how many requests paused, how many matched each rule, how many were released unmatched at teardown, and the mock's completion state; --json mirrors
+effects: returns the tab to real network behavior; releases the collector host's \`fetch-interception\` claim and exits the host when nothing else is collecting`;
+
+export function buildMockStoppedResult(mock: StoppedMock): RenderableResult {
+  const sections = mock.ruleMatches.map((matched, index) => fact`Rule ${index} matched ${matched} request(s).`);
+  const incomplete = mock.completion === 'complete' ? [] : [fact`Mock completion is ${mock.completion}; counts reflect the finalized collector record.`];
+  return {
+    tag: 'mock',
+    attrs: {
+      mock: mock.id,
+      path: mock.dir,
+      state: 'stopped',
+      completion: mock.completion,
+      rules: mock.rules,
+      paused: mock.paused,
+      matched: mock.matched,
+      'released-unmatched': mock.releasedUnmatched,
+    },
+    summary: fact`Requests were answered from the rule document copied to rules.json; counts are per rule in document order, first match wins. ${mock.paused} request(s) paused, ${mock.matched} matched a rule, and ${mock.releasedUnmatched} paused request(s) were continued unmodified during teardown.`,
+    artifacts: formatArtifactList([{ name: 'rules.json', note: 'the exact installed rule document' }, { name: 'interceptions.jsonl', note: 'one record per paused request' }, { name: 'meta.json', note: 'completion and collector counts' }]),
+    sections: [...sections, ...incomplete],
+  };
+}
+
+export async function cmdTabMockStop(parsed: ParsedArgs): Promise<void> {
+  if (parsed.help) {
+    console.log(HELP);
+    return;
+  }
+  emitResult(buildMockStoppedResult(await stopMock()), { json: parsed.json });
+}

package/src/cdp/commands/tab/network.ts

@@ -15,6 +15,8 @@ import { captureError } from '../../../errors.js';
 import { getActiveSession, setActiveNetworkOffline } from '../../../session-context.js';
 import { admitSessionOperation } from '../../../session/coordinator.js';
 import { sendBridgeRequest } from '../../bridge/client.js';
+import { sendHostRequest } from '../../host/client.js';
+import { scanCollectorHost } from '../../host/handle.js';
 import { type ParsedArgs } from '../../types.js';
 import {
   emitResult,
@@ -133,16 +135,13 @@ export async function cmdTabNetwork(parsed: ParsedArgs, _args: string[]): Promis
         `Network.enable failed over the session's held bridge: ${enable.error || 'unknown bridge error'}`,
       );
     }
-    const emulate = await sendBridgeRequest(socket, {
-      method: 'Network.emulateNetworkConditions',
-      params: {
-        offline,
-        latency: offline ? -1 : 0,
-        downloadThroughput: offline ? 0 : -1,
-        uploadThroughput: offline ? 0 : -1,
-      },
-      targetId,
-    });
+    const params = {
+      offline,
+      latency: offline ? -1 : 0,
+      downloadThroughput: offline ? 0 : -1,
+      uploadThroughput: offline ? 0 : -1,
+    };
+    const emulate = await sendBridgeRequest(socket, { method: 'Network.emulateNetworkConditions', params, targetId });
     if (!emulate.ok) {
       throw captureError(
         'world',
@@ -150,9 +149,19 @@ export async function cmdTabNetwork(parsed: ParsedArgs, _args: string[]): Promis
         `Network.emulateNetworkConditions failed over the session's held bridge: ${emulate.error || 'unknown bridge error'}`,
       );
     }
-    // Local-main session network retention: record the emulation on the
-    // active session so later independent command connections re-apply it
-    // (applyActiveSessionNetworkConditions in cdp/connection.ts).
+    const host = scanCollectorHost(session.dir);
+    if (host.classification === 'live' && host.handle) {
+      if (host.handle.targetId !== targetId) throw captureError('precondition', 'collector_host_target_mismatch', 'collector host is bound to a different session target; stop the session before changing tabs.');
+      const hostEnable = await sendHostRequest(host.handle.socketPath, { type: 'cdp', nonce: host.handle.nonce, method: 'Network.enable' });
+      if (!hostEnable.ok) throw captureError('world', 'collector_host_error', `Network.enable failed over the collector host: ${hostEnable.error || 'unknown bridge error'}`);
+      const hostEmulate = await sendHostRequest(host.handle.socketPath, { type: 'cdp', nonce: host.handle.nonce, method: 'Network.emulateNetworkConditions', params });
+      if (!hostEmulate.ok) throw captureError('world', 'collector_host_error', `Network.emulateNetworkConditions failed over the collector host: ${hostEmulate.error || 'unknown bridge error'}`);
+    } else if (host.classification !== 'absent') {
+      throw captureError('precondition', 'collector_host_unavailable', `session collector host is ${host.classification}.`);
+    }
+    // Local-main session network retention: record the emulation on the active
+    // session only after every live connection carrying the session condition
+    // has accepted it.
     await setActiveNetworkOffline(offline);
   } finally {
     await operation.release();

package/src/cdp/commands/tab/reset.ts

@@ -5,10 +5,10 @@
  *
  * Under an active session this is a session-lifecycle transition: it admits
  * as a session operation, runs under the session's `.lifecycle.lock`, and
- * REFUSES while a recording is live (a recorder is bound to the old target;
- * reset never rebinds a live recorder). Reset only clears a dangling recorder
- * pointer; dead recorders are left for the next stop/start to finalize (their
- * frames are preserved). The session's `{targetId, port}` pair is published
+ * REFUSES while a recording is live (the collector host is bound to the old
+ * target; reset never rebinds it). Reset only clears the session's dangling
+ * recording pointer; a dead collector host is left for the next stop/start to
+ * finalize its artifacts. The session's `{targetId, port}` pair is published
  * atomically under the lock.
  *
  * Emits a `<tab-reset>` block; page-derived strings flow through `data()`
@@ -23,11 +23,10 @@ import {
   admitSessionOperation,
   withSessionLifecycle,
   withSessionScopeLifecycle,
-  scanRecorderHandles,
-  clearDanglingRecorderPointer,
   type LifecycleSeams,
 } from '../../../session/coordinator.js';
 import { captureError, invalidInput } from '../../../errors.js';
+import { scanCollectorHost } from '../../host/handle.js';
 import { type CDPTarget, type ParsedArgs } from '../../types.js';
 import {
   data,
@@ -44,7 +43,7 @@ input:
   --port <port>   CDP endpoint (default: the active session's port, else the auto-discovered preferred endpoint)
 
 output: <tab-reset port=… target=…> — the fresh tab's target id and url, plus whether the active session's target was repointed at it.
-effects: opens a new background browser tab (the old tab is left behind, not closed) and waits up to 10s for its load event. Under an active session it refuses while a recording is live (stop it first: \`capture motion rec --stop\`), clears a dangling recorder pointer (dead recorders are left for the next stop/start to finalize; their frames are preserved), and updates the session's {target, port} pair together.`;
+effects: opens a new background browser tab (the old tab is left behind, not closed) and waits up to 10s for its load event. Under an active session it refuses while a recording is live (stop it first: \`capture motion rec --stop\`), clears the session's dangling recording pointer (a dead collector host remains for the next stop/start to finalize its artifacts), and updates the session's {target, port} pair together.`;
 
 /** Pure `<tab-reset>` result builder — exported for tests. */
 export function buildTabResetResult(
@@ -144,11 +143,11 @@ export async function cmdTabReset(parsed: ParsedArgs, _args: string[]): Promise<
       const result = await withSessionLifecycle(session.dir, async () => {
         const fresh = getActiveSession();
         if (!fresh || fresh.dir !== session.dir) throw captureError('precondition', 'session_unavailable', 'The active capture session is no longer available.');
-        const scan = scanRecorderHandles(session.dir, deps.lifecycle);
-        if (scan.some(h => h.classification === 'unknown')) throw captureError('world', 'recorder_liveness_unknown', 'Cannot determine recorder liveness; refusing to reset.');
-        if (scan.some(h => h.classification === 'malformed')) throw captureError('precondition', 'recorder_unavailable', 'A malformed recorder handle exists on this session; resolve it before resetting.');
-        if (scan.some(h => h.classification === 'live')) throw captureError('precondition', 'recorder_active', 'A recording is active on this session; stop it first: `capture motion rec --stop`. Reset never rebinds a live recorder.');
-        await clearDanglingRecorderPointer(session.dir, scan);
+        const host = scanCollectorHost(session.dir);
+        if (host.classification === 'unknown') throw captureError('world', 'recorder_liveness_unknown', 'Cannot determine collector-host liveness; refusing to reset.');
+        if (host.classification === 'malformed') throw captureError('precondition', 'recorder_unavailable', 'A malformed collector-host handle exists on this session; resolve it before resetting.');
+        if (host.classification === 'live' && host.handle?.collectors.some(collector => collector.kind === 'motion')) throw captureError('precondition', 'recorder_active', 'A recording is active on this session; stop it first: `capture motion rec --stop`. Reset never rebinds a live recorder.');
+        if (fresh.activeRecId) await updateSessionState(session.dir, { activeRecId: null });
         const port = fresh.port ?? parsed.port ?? (await deps.detectCdpPort());
         const tab = await openTabOrThrow(port, url);
         await boundedLoadWait(tab);

package/src/cdp/connection.ts

@@ -12,8 +12,8 @@ import {
 } from '../har-manager.js';
 import { getActiveSession, updateActiveSession, type ActiveSessionState } from '../session-context.js';
 import { withSessionScopeLifecycle } from '../session/coordinator.js';
-import { RecorderHeldClient, isRecorderHeldClient } from './recorder-client.js';
-import { recDirFor, readRecorderJson } from './motion/recorder.js';
+import { MotionHeldClient, isMotionHeldClient } from './host/held-client.js';
+import { scanCollectorHost } from './host/handle.js';
 import { captureError } from '../errors.js';
 
 function getPortFromWebSocketDebuggerUrl(url?: string): number | null {
@@ -41,12 +41,12 @@ export interface ConnectionSeams {
   resolveTab: (parsed: ParsedArgs) => Promise<{ port: number; tab: CDPTarget } | null>;
   createClient: (wsUrl: string) => CDPClient;
   appendHar: typeof appendToHar;
-  /** Recorder-routed actions only: the recorder bridge's `har-flush` health
-   * barrier (`RecorderHeldClient.flushHar()`) — resolves once every HAR
+  /** Motion-routed actions only: the collector host's `har-flush` health
+   * barrier (`MotionHeldClient.flushHar()`) — resolves once every HAR
    * entry/body/append the recorder's streaming collector had completed at
    * call time is durably in the owning session's live HAR; throws on a
    * latched fatal store failure. Never invoked for a non-recorder action. */
-  flushRecorderHar: (client: RecorderHeldClient) => Promise<void>;
+  flushRecorderHar: (client: MotionHeldClient) => Promise<void>;
   /** Monotonic clock (ms) — measured settle facts derive from it, never from wall time. */
   now: () => number;
   sleep: (ms: number) => Promise<void>;
@@ -150,51 +150,31 @@ function connectToActiveRecorder(
   parsed: ParsedArgs,
 ): { client: CDPClient; tab: CDPTarget } {
   const recId = session.activeRecId!;
-  const recDir = recDirFor(session.dir, recId);
-  const rj = readRecorderJson(recDir);
-
-  if (!rj) {
-    throw captureError(
-      'precondition',
-      'recorder_unavailable',
-      `The active session claims recording "${recId}" but its live-recorder handle (recorder.json) is missing — it was already finalized or reaped. Recover with: capture motion rec --stop.`,
-    );
-  }
-  if (
-    typeof rj.socketPath !== 'string' || rj.socketPath.length === 0
-    || typeof rj.targetId !== 'string' || rj.targetId.length === 0
-    || typeof rj.nonce !== 'string' || !/^[0-9a-f]{64}$/.test(rj.nonce)
-  ) {
-    throw captureError(
-      'precondition',
-      'recorder_unavailable',
-      `The active session's recorder handle for "${recId}" is malformed (missing or invalid socketPath/targetId/nonce). Recover with: capture motion rec --stop.`,
-    );
-  }
-  if (rj.state !== 'recording') {
+  const scanned = scanCollectorHost(session.dir);
+  const collector = scanned.handle?.collectors.find(value => value.id === recId && value.kind === 'motion');
+  if (scanned.classification !== 'live' || !scanned.handle || !collector) {
     throw captureError(
       'precondition',
       'recorder_unavailable',
-      `The active session's recorder "${recId}" is not currently recording (state: ${rj.state}) — it is finalized or mid-teardown. Recover with: capture motion rec --stop.`,
+      `The active session claims recording "${recId}" but its live collector-host handle is unavailable. Recover with: capture motion rec --stop.`,
     );
   }
 
   const actionLabel = deriveActionLabel(parsed);
-  const client = new RecorderHeldClient({ socketPath: rj.socketPath, nonce: rj.nonce, actionLabel });
+  const client = new MotionHeldClient({ socketPath: scanned.handle.socketPath, nonce: scanned.handle.nonce, actionLabel });
   const tab: CDPTarget = {
-    id: rj.targetId,
+    id: scanned.handle.targetId,
     title: '',
-    url: rj.url ?? '',
+    url: session.url ?? '',
     type: 'page',
     webSocketDebuggerUrl: undefined,
   };
 
-  console.error(`Routing via active recorder ${recId} (recorder-held tab connection, action "${actionLabel}")`);
+  console.error(`Routing via active motion collector ${recId} (collector-host tab connection, action "${actionLabel}")`);
 
-  // Documented cast — RecorderHeldClient only ever needs to satisfy the
+  // Documented cast — MotionHeldClient only ever needs to satisfy the
   // structural send/on/onDisconnect/close surface every command leaf calls;
-  // see recorder-client.ts's own header for why this mirrors
-  // recorder-bridge.ts's `asCDPClient()`.
+  // see held-client.ts and host/collectors/motion.ts's `asCDPClient()`.
   return { client: client as unknown as CDPClient, tab };
 }
 
@@ -204,8 +184,8 @@ export async function connectForCommand(
   const activeSession = seams.getActiveSession();
   if (activeSession && shouldRouteToRecorder(activeSession, parsed)) {
     const routed = connectToActiveRecorder(activeSession, parsed);
-    // The recorder bridge owns its own persistent target connection, so
-    // the persisted offline/online state must be reissued here too — the
+    // The collector host owns its own persistent target connection, so the
+    // persisted offline/online state must be reissued here too — the
     // ephemeral connection that ran `network offline` has since closed.
     await applyActiveSessionNetworkConditions(routed.client, activeSession, routed.tab.id);
     return routed;
@@ -285,7 +265,7 @@ interface Collectors {
 }
 
 async function startCollectors(parsed: ParsedArgs, client: CDPClient): Promise<Collectors> {
-  const routed = isRecorderHeldClient(client);
+  const routed = isMotionHeldClient(client);
 
   let consoleRecorder: ConsoleRecorder | undefined;
   if (!routed) {
@@ -433,7 +413,7 @@ export async function withPageAction<T>(
     // this request.
     if (collectors.routed) {
       try {
-        await seams.flushRecorderHar(client as unknown as RecorderHeldClient);
+        await seams.flushRecorderHar(client as unknown as MotionHeldClient);
       } catch (err) {
         throw captureError(
           'artifact',

package/src/cdp/detect.ts

@@ -226,22 +226,30 @@ export async function detectCdpPortsAsync(): Promise<CdpEndpoint[]> {
 // browser out of everything discovered on localhost. Shared so `capture
 // detect`'s printed default always matches what auto-discovery actually
 // picks for session start / navigate / etc.
-export function pickPreferredEndpoint(
+export interface PreferredEndpointSelection {
+  endpoint: CdpEndpoint;
+  reason: string;
+}
+
+export function pickPreferredEndpointWithReason(
   endpoints: CdpEndpoint[],
   defaultBrowser: string | null,
-): CdpEndpoint {
+): PreferredEndpointSelection {
   // Endpoints that already host a real page/tab are real browsers. CDP-
   // speaking non-browser processes (Node/workerd inspectors, etc.) never do,
   // so prefer real browsers whenever at least one is present — this is what
   // keeps an unrelated CDP listener from being picked over the intended one.
   const withPages = endpoints.filter((e) => e.hasPageTarget);
   const candidates = withPages.length > 0 ? withPages : endpoints;
+  const candidateScope = withPages.length > 0
+    ? 'among endpoints with a live page target'
+    : 'because no discovered endpoint has a live page target';
 
   if (defaultBrowser) {
     const match = candidates.find(
       (p) => p.bundleId === defaultBrowser && !p.isElectron,
     );
-    if (match) return match;
+    if (match) return { endpoint: match, reason: `matched the configured default browser ${candidateScope}` };
   }
 
   // Prefer a recognized browser over other Chromium hosts (Spotify, app
@@ -249,12 +257,20 @@ export function pickPreferredEndpoint(
   const knownBrowser = candidates.find(
     (endpoint) => endpoint.bundleId !== 'unknown' && !endpoint.isElectron,
   );
-  if (knownBrowser) return knownBrowser;
+  if (knownBrowser) return { endpoint: knownBrowser, reason: `is a recognized non-Electron browser ${candidateScope}` };
   const nonElectron = candidates.find((endpoint) => !endpoint.isElectron);
-  return nonElectron ?? candidates[0];
+  if (nonElectron) return { endpoint: nonElectron, reason: `is the first non-Electron endpoint ${candidateScope}` };
+  return { endpoint: candidates[0], reason: `is the first discovered endpoint ${candidateScope}` };
 }
 
-export async function detectCdpPort(): Promise<number> {
+export function pickPreferredEndpoint(
+  endpoints: CdpEndpoint[],
+  defaultBrowser: string | null,
+): CdpEndpoint {
+  return pickPreferredEndpointWithReason(endpoints, defaultBrowser).endpoint;
+}
+
+export async function detectCdpEndpoint(): Promise<CdpEndpoint & { selectionReason: string }> {
   const endpoints = await detectCdpPortsAsync();
   if (endpoints.length === 0) {
     throw new Error(
@@ -264,6 +280,10 @@ export async function detectCdpPort(): Promise<number> {
         '  Electron apps expose CDP automatically',
     );
   }
+  const { endpoint, reason } = pickPreferredEndpointWithReason(endpoints, getDefaultBrowserId());
+  return { ...endpoint, selectionReason: reason };
+}
 
-  return pickPreferredEndpoint(endpoints, getDefaultBrowserId()).port;
+export async function detectCdpPort(): Promise<number> {
+  return (await detectCdpEndpoint()).port;
 }

package/src/cdp/dispatch.ts

@@ -2,7 +2,7 @@
  * Shared dispatch for every routed command. Two jobs live here:
  *
  *  1. Route each root (`session`, `page`, `tab`, `measure`, `motion`,
- *     `cdp`, `lib`, hidden `__bridge-serve`) to its branch main.
+ *     `perf`, `heap`, `lighthouse`, `cdp`, `lib`, hidden `__bridge-serve`) to its branch main.
  *  2. Invoke the `--gate` guard ONCE for the whole surface: every command
  *     that is not `measure check|diff` rejects the flag structurally here,
  *     before any branch main runs.
@@ -20,6 +20,10 @@ import { cmdCdp } from './commands/cdp.js';
 import { cmdBridgeServe } from './commands/bridge-serve.js';
 import { measureMain } from './commands/measure/index.js';
 import { motionMain } from './commands/motion/index.js';
+import { perfMain } from './commands/perf/index.js';
+import { heapMain } from './commands/heap/index.js';
+import { cmdLighthouse } from './commands/lighthouse.js';
+import { cmdSessionCollectors } from './commands/session/collectors.js';
 
 /** The dotted leaf name the gate rejection reports, derived from the parsed
  * command plus its first positional (the branch-leaf token). */
@@ -50,10 +54,20 @@ async function withActiveSessionAdmission(parsed: ParsedArgs, run: () => Promise
   const active = getActiveSession();
   if (!active) return run();
   const operation = await admitSessionOperation(active.dir);
+  let completed = false;
   try {
-    return await run();
+    await run();
+    completed = true;
   } finally {
-    await operation.release();
+    try {
+      await operation.release();
+    } catch (error) {
+      if (!completed) throw error;
+      // The command's browser effect and rendered measurement already
+      // completed. A failed auxiliary lock-owner lookup cannot recast that
+      // completed observation as a failed navigation/page command.
+      process.stderr.write(`capture: session-operation release unavailable after completed command: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
   }
 }
 
@@ -70,13 +84,20 @@ export async function cdpMain(): Promise<void> {
   const resolved = resolveCliContext(parsed);
 
   switch (resolved.command) {
-    case 'session': return sessionMain(resolved, args);
+    case 'session':
+      if (resolved.positional[0] === 'collectors') {
+        return cmdSessionCollectors({ ...resolved, positional: resolved.positional.slice(1) });
+      }
+      return sessionMain(resolved, args);
     case 'page': return withActiveSessionAdmission(resolved, () => pageMain(resolved, args));
     case 'tab': return tabMain(resolved, args);
     case 'lib': return cmdLib(resolved, args);
     case 'cdp': return cmdCdp(resolved, args);
     case 'measure': return withActiveSessionAdmission(resolved, () => measureMain(resolved, args));
     case 'motion': return withActiveSessionAdmission(resolved, () => motionMain(resolved, args));
+    case 'perf': return withActiveSessionAdmission(resolved, () => perfMain(resolved, args));
+    case 'heap': return withActiveSessionAdmission(resolved, () => heapMain(resolved, args));
+    case 'lighthouse': return withActiveSessionAdmission(resolved, () => Promise.resolve(cmdLighthouse(resolved, args)));
     case '__bridge-serve': return cmdBridgeServe(resolved, args);
     default:
       // capture.ts routes only the known roots into cdpMain(); an unknown

package/src/cdp/domains.ts

@@ -29,11 +29,11 @@ export async function enableDomainsForSnap(client: CDPClient): Promise<void> {
 }
 
 /**
- * Enables the CDP domains the motion recorder bridge needs: frame/navigation metadata and
+ * Enables the CDP domains the motion collector needs: frame/navigation metadata and
  * `Page.startScreencast` (Page), element geometry for rect/selector resolution (DOM), script
  * execution for the injected Mutation/Resize/Performance observers (Runtime), request/response
  * timing for `motion response` (Network), and playback-rate control for the animation inventory
- * (Animation). `Tracing.start` is configured with its own category set by the recorder bridge
+ * (Animation). `Tracing.start` is configured with its own category set by the motion collector
  * (U13) and is not a plain `.enable` call, so it is not included here.
  */
 export async function enableDomainsForMotionRec(client: CDPClient): Promise<void> {

package/src/cdp/har-recorder.ts

@@ -514,7 +514,6 @@ export class HARRecorder {
     const terminal = current.terminal!;
     if (responseTimestamp !== null && responseTimestamp < current.requestMonotonic) return 'response_before_request';
     if (terminal.timestamp < current.requestMonotonic) return 'terminal_before_request';
-    if (responseTimestamp !== null && terminal.timestamp < responseTimestamp) return 'terminal_before_response';
     return null;
   }