@crouton-kit/capture 1.3.8 → 1.3.9

package/src/cdp/bridge/protocol.ts

@@ -17,7 +17,7 @@ export interface BridgeRequest {
    * domains (`Browser.*`, `Target.*`).
    */
   targetId?: string;
-  /** CDP event name to wait for (consumes the next occurrence, FIFO, buffered if it already fired). */
+  /** CDP event name to observe after this request is armed. Observation is future-only and scoped to this request's actual flattened target session (`undefined` without `targetId`); one event broadcasts to all already-armed same-key requests. */
   waitEvent?: string;
   timeoutMs?: number;
 }
@@ -47,10 +47,26 @@ export type BridgeResponse = BridgeResponseOk | BridgeResponseErr;
 // the plain bridge.
 // ---------------------------------------------------------------------------
 
-/** One synchronized (performance.now, wall-clock) pair, captured when the recorder arms. */
+/**
+ * The three-way clock baseline the design's "Recorder timing model" requires to convert
+ * screencast-frame and Tracing timestamps into the authoritative `performance.now()` domain.
+ * `performanceNowMs`/`wallClockMs` are read synchronously when the recorder arms (`rec-start`);
+ * `firstScreencastTimestampSec`/`firstTraceEventTsUs` cannot be — no frame or trace batch has
+ * necessarily arrived yet at that instant — so they are filled in opportunistically as the
+ * recorder's own screencast/tracing handlers observe the first occurrence of each, and stay
+ * `null` (with `baselinesPending: true`) until then. `rec-stop`'s response carries the same
+ * object read again at stop time — the flush path a caller uses to get the completed baselines
+ * for `markers.json` even when `rec-start`'s own response returned it still pending.
+ */
 export interface RecorderClockBaselines {
   performanceNowMs: number;
   wallClockMs: number;
+  /** First `Page.screencastFrame`'s `metadata.timestamp` (wall-clock seconds), or `null` if none had arrived yet at the moment this snapshot was taken. */
+  firstScreencastTimestampSec: number | null;
+  /** First `Tracing.dataCollected` batch's earliest event `ts` (trace-clock microseconds), or `null` if none had arrived yet at the moment this snapshot was taken. */
+  firstTraceEventTsUs: number | null;
+  /** `true` while either timestamp above is still `null`. */
+  baselinesPending: boolean;
 }
 
 /**
@@ -58,10 +74,21 @@ export interface RecorderClockBaselines {
  * domains, starts `Page.startScreencast` + `Tracing`, injects the
  * Mutation/Resize/Performance observers, and captures the clock baseline.
  * A recorder process only accepts one `rec-start` while `state==="idle"`.
+ *
+ * `nonce` (here and on every other recorder request shape) is the
+ * per-recording control-socket admission token: the recorder bridge process
+ * generates it at boot (64 lowercase hex chars, 256 bits) and hands it back
+ * to its starter over a private boot file; every request line must carry it
+ * verbatim, and the server constant-time-compares it BEFORE any handler
+ * runs. There is no unauthenticated request shape and no compatibility
+ * lane — a missing or mismatched nonce is answered `ok:false error:
+ * 'unauthorized'` with no side effects.
  */
 export interface RecStartRequest {
   reqId: number;
   type: 'rec-start';
+  /** Per-recording control-socket admission token — see the doc comment above. */
+  nonce: string;
 }
 
 export interface RecStartResponseOk {
@@ -81,6 +108,8 @@ export interface RecStartResponseOk {
 export interface RecStopRequest {
   reqId: number;
   type: 'rec-stop';
+  /** Per-recording control-socket admission token — see `RecStartRequest`. */
+  nonce: string;
 }
 
 export interface RecStopResponseOk {
@@ -90,6 +119,8 @@ export interface RecStopResponseOk {
   frameCount: number;
   eventCount: number;
   durationMs: number;
+  /** The clock baselines re-read at stop time — the flush path for a `rec-start` response whose baselines were still pending. */
+  markers: RecorderClockBaselines;
 }
 
 /**
@@ -102,11 +133,15 @@ export interface RecStopResponseOk {
  * timeline — this is the "marked CDP request message" the protocol
  * supports. Omit `mark` for a plain passthrough call (still observed
  * natively by the recorder's own event subscriptions, just not logged as a
- * distinct input landmark).
+ * distinct input landmark). Omit `method` for a wait-event-only request;
+ * the bridge arms a future-only wait on the recorder tab websocket's
+ * unscoped event envelope and returns the matched event in one response.
  */
-export interface RecCdpRequest {
+export interface RecCdpDispatchRequest {
   reqId: number;
   type: 'cdp';
+  /** Per-recording control-socket admission token — see `RecStartRequest`. */
+  nonce: string;
   method: string;
   params?: Record<string, unknown>;
   mark?: string;
@@ -114,15 +149,66 @@ export interface RecCdpRequest {
   timeoutMs?: number;
 }
 
+export interface RecCdpWaitEventRequest {
+  reqId: number;
+  type: 'cdp';
+  /** Per-recording control-socket admission token — see `RecStartRequest`. */
+  nonce: string;
+  method?: undefined;
+  waitEvent: string;
+  timeoutMs?: number;
+}
+
+export type RecCdpRequest = RecCdpDispatchRequest | RecCdpWaitEventRequest;
+
 export interface RecCdpResponseOk {
   reqId: number;
   ok: true;
   type: 'cdp';
   result?: unknown;
   event?: unknown;
+  /**
+   * Present iff this request armed a `waitEvent` AND carried a `method`. It
+   * reports the load-wait outcome SEPARATELY from the method result: a method
+   * dispatch that succeeds is always `ok:true` with its `result` preserved,
+   * regardless of whether the paired wait observed its event
+   * (`'observed'`, with `event` set) or the wait's own bounded timer elapsed
+   * first (`'bounded-timeout'`, no `event`). A wait-event-ONLY request (no
+   * `method`) whose wait times out is still `ok:false` — that path has no
+   * method result to preserve, so its timeout is a genuine failure.
+   */
+  waitOutcome?: 'observed' | 'bounded-timeout';
+}
+
+/**
+ * The action-return HAR flush/health barrier. A recorder-routed page action
+ * (`click`, `type`, `scroll`, `exec`, `navigate`) sends this after its settle
+ * window and before claiming success, so every HAR entry/body/append the
+ * recorder's streaming collector had already completed by then is durably in
+ * the owning session's live HAR first. Deliberately NON-attributing: the
+ * response reports store health only — `ok:true` means "all work completed at
+ * request time has appended and no fatal store error is latched"; it never
+ * says which entries belong to which action and carries no counts (the
+ * collector cannot truthfully attribute concurrent traffic to one action).
+ * Once the terminal `rec-stop` latch is claimed, HAR finalization belongs to
+ * that one owner and a later `har-flush` is answered with a deterministic
+ * `ok:false` rejection instead of sharing or re-driving the drain.
+ */
+export interface RecHarFlushRequest {
+  reqId: number;
+  type: 'har-flush';
+  /** Per-recording control-socket admission token — see `RecStartRequest`. */
+  nonce: string;
+}
+
+/** Health-only: success carries no result fields beyond the envelope — see `RecHarFlushRequest`. */
+export interface RecHarFlushResponseOk {
+  reqId: number;
+  ok: true;
+  type: 'har-flush';
 }
 
-export type RecorderRequest = RecStartRequest | RecStopRequest | RecCdpRequest;
+export type RecorderRequest = RecStartRequest | RecStopRequest | RecCdpRequest | RecHarFlushRequest;
 
 export interface RecorderResponseErr {
   reqId: number;
@@ -134,4 +220,5 @@ export interface RecorderResponseErr {
 export type RecStartResponse = RecStartResponseOk | RecorderResponseErr;
 export type RecStopResponse = RecStopResponseOk | RecorderResponseErr;
 export type RecCdpResponse = RecCdpResponseOk | RecorderResponseErr;
-export type RecorderResponse = RecStartResponse | RecStopResponse | RecCdpResponse;
+export type RecHarFlushResponse = RecHarFlushResponseOk | RecorderResponseErr;
+export type RecorderResponse = RecStartResponse | RecStopResponse | RecCdpResponse | RecHarFlushResponse;

package/src/cdp/bridge/server.ts

@@ -19,20 +19,30 @@ import { type CDPClient } from '../client.js';
 import { type BridgeRequest, type BridgeResponse } from './protocol.js';
 
 interface EventWaiter {
-  resolve: (v: unknown) => void;
+  resolve: (value: unknown) => void;
 }
 
+export interface EventWait {
+  /** Returns the event or throws its timeout. The broker observes timeouts internally until this is called, so a slow triggering method cannot create an unhandled rejection. */
+  result(): Promise<unknown>;
+  /** Removes and settles this waiter without affecting any other waiter. */
+  cancel(): void;
+}
+
+type EventWaitOutcome =
+  | { kind: 'event'; value: unknown }
+  | { kind: 'timeout'; error: Error }
+  | { kind: 'cancelled' };
+
 /**
- * Buffers CDP events by name and resolves `wait()` callers FIFO, either
- * immediately (from the buffer) or when the next matching event arrives.
- * Shared by the plain browser-level bridge and the recorder bridge
- * (`../recorder-bridge.ts`) — both hold one long-lived `CDPClient` and need
- * the same "consume the next occurrence of this event" primitive for
- * `waitEvent`-bearing requests.
+ * Observes future CDP events on one long-lived client. Waiters are scoped by
+ * the event envelope's actual flattened session id (including `undefined`
+ * for an unscoped event). An event is dropped when no exact-key waiter is
+ * armed, and otherwise broadcasts to every waiter already armed for that
+ * key. The broker never retains event history.
  */
 export class EventBroker {
-  private queues = new Map<string, unknown[]>();
-  private waiters = new Map<string, EventWaiter[]>();
+  private waiters = new Map<string, Map<string | undefined, Set<EventWaiter>>>();
   private listening = new Set<string>();
 
   constructor(private client: Pick<CDPClient, 'on'>) {}
@@ -40,45 +50,109 @@ export class EventBroker {
   private ensureListening(eventName: string): void {
     if (this.listening.has(eventName)) return;
     this.listening.add(eventName);
-    this.client.on(eventName, (params) => {
-      const waiters = this.waiters.get(eventName);
-      if (waiters && waiters.length > 0) {
-        waiters.shift()!.resolve(params);
-        return;
-      }
-      const q = this.queues.get(eventName) ?? [];
-      q.push(params);
-      // Cap the buffer so an event nobody ever asks for can't leak memory.
-      if (q.length > 50) q.shift();
-      this.queues.set(eventName, q);
+    this.client.on(eventName, (params, actualSessionId) => {
+      const bySession = this.waiters.get(eventName);
+      const matching = bySession?.get(actualSessionId);
+      if (!matching || matching.size === 0) return;
+
+      // Remove the exact bucket before resolving its snapshot. A waiter armed
+      // by a resolution continuation is therefore future-only and cannot
+      // observe the event currently being broadcast.
+      bySession!.delete(actualSessionId);
+      if (bySession!.size === 0) this.waiters.delete(eventName);
+      for (const waiter of matching) waiter.resolve(params);
     });
   }
 
-  wait(eventName: string, timeoutMs: number): Promise<unknown> {
+  wait(eventName: string, sessionId: string | undefined, timeoutMs: number): EventWait {
     this.ensureListening(eventName);
-    const q = this.queues.get(eventName);
-    if (q && q.length > 0) {
-      return Promise.resolve(q.shift());
+    let bySession = this.waiters.get(eventName);
+    if (!bySession) {
+      bySession = new Map();
+      this.waiters.set(eventName, bySession);
     }
-    return new Promise((resolve, reject) => {
-      const list = this.waiters.get(eventName) ?? [];
-      const entry: EventWaiter = {
-        resolve: (v) => {
-          clearTimeout(timer);
-          resolve(v);
-        },
-      };
-      const timer = setTimeout(() => {
-        const current = this.waiters.get(eventName);
-        if (current) {
-          const idx = current.indexOf(entry);
-          if (idx >= 0) current.splice(idx, 1);
-        }
-        reject(new Error(`Timed out after ${timeoutMs}ms waiting for event "${eventName}"`));
-      }, timeoutMs);
-      list.push(entry);
-      this.waiters.set(eventName, list);
+    let matching = bySession.get(sessionId);
+    if (!matching) {
+      matching = new Set();
+      bySession.set(sessionId, matching);
+    }
+
+    let settleOutcome!: (outcome: EventWaitOutcome) => void;
+    const outcome = new Promise<EventWaitOutcome>((resolve) => {
+      settleOutcome = resolve;
     });
+    let settled = false;
+    const removeOnlyThisWaiter = (): void => {
+      const currentBySession = this.waiters.get(eventName);
+      const current = currentBySession?.get(sessionId);
+      if (!current) return;
+      current.delete(waiter);
+      if (current.size === 0) currentBySession!.delete(sessionId);
+      if (currentBySession!.size === 0) this.waiters.delete(eventName);
+    };
+    const waiter: EventWaiter = {
+      resolve: (value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        settleOutcome({ kind: 'event', value });
+      },
+    };
+    matching.add(waiter);
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      removeOnlyThisWaiter();
+      settleOutcome({
+        kind: 'timeout',
+        error: new Error(
+          `Timed out after ${timeoutMs}ms waiting for event "${eventName}"` +
+            (sessionId === undefined ? ' without a session' : ` in session "${sessionId}"`),
+        ),
+      });
+    }, timeoutMs);
+
+    return {
+      result: async () => {
+        const settledOutcome = await outcome;
+        if (settledOutcome.kind === 'timeout') throw settledOutcome.error;
+        return settledOutcome.kind === 'event' ? settledOutcome.value : undefined;
+      },
+      cancel: () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        removeOnlyThisWaiter();
+        settleOutcome({ kind: 'cancelled' });
+      },
+    };
+  }
+}
+
+export async function handleBridgeRequest(
+  req: BridgeRequest,
+  client: Pick<CDPClient, 'send'>,
+  events: EventBroker,
+  attach: (targetId: string) => Promise<string>,
+): Promise<BridgeResponse> {
+  let eventWait: EventWait | undefined;
+  try {
+    const sessionId = req.targetId ? await attach(req.targetId) : undefined;
+    eventWait = req.waitEvent
+      ? events.wait(req.waitEvent, sessionId, req.timeoutMs ?? 10000)
+      : undefined;
+    const result = req.method
+      ? await client.send(req.method, req.params ?? {}, 60000, sessionId)
+      : undefined;
+    const event = eventWait ? await eventWait.result() : undefined;
+    return { reqId: req.reqId, ok: true, result, event };
+  } catch (err) {
+    eventWait?.cancel();
+    return {
+      reqId: req.reqId,
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
   }
 }
 
@@ -99,7 +173,7 @@ export async function runBridgeServer(socketPath: string, port?: number): Promis
     // requiring the full 32-char target id here.
     const tab = await findTabById(resolvedPort, targetId);
     if (!tab) {
-      throw new Error(`No target found for "${targetId}" on port ${resolvedPort}. Run "capture list" to see available tabs.`);
+      throw new Error(`No target found for "${targetId}" on port ${resolvedPort}. Run "capture tab list" to see available tabs.`);
     }
     const result = (await client.send('Target.attachToTarget', { targetId: tab.id, flatten: true })) as {
       sessionId: string;
@@ -115,16 +189,7 @@ export async function runBridgeServer(socketPath: string, port?: number): Promis
     } catch {
       return;
     }
-    let resp: BridgeResponse;
-    try {
-      const sessionId = req.targetId ? await attach(req.targetId) : undefined;
-      const eventPromise = req.waitEvent ? events.wait(req.waitEvent, req.timeoutMs ?? 10000) : undefined;
-      const result = req.method ? await client.send(req.method, req.params ?? {}, 60000, sessionId) : undefined;
-      const event = eventPromise ? await eventPromise : undefined;
-      resp = { reqId: req.reqId, ok: true, result, event };
-    } catch (err) {
-      resp = { reqId: req.reqId, ok: false, error: err instanceof Error ? err.message : String(err) };
-    }
+    const resp = await handleBridgeRequest(req, client, events, attach);
     socket.write(JSON.stringify(resp) + '\n');
   }
 

package/src/cdp/bridge/spawn.ts

@@ -5,16 +5,45 @@
  */
 
 import { spawn } from 'child_process';
+import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
+import { CAPTURE_ROOT, ensurePrivateDir } from '../../session/artifacts.js';
 
 export function bridgeSocketPath(sessionDir: string): string {
   return path.join(sessionDir, 'bridge.sock');
 }
 
-/** The recorder bridge's own socket, scoped to its recording dir so it can't collide with a session's plain `--hold` bridge. */
+/**
+ * Fixed, short, private (`0700`) directory every recorder socket lives in — flat, and
+ * deliberately NOT nested under a recording's (long) artifact dir. macOS caps `AF_UNIX`
+ * pathnames at ~104 bytes; a real recording dir (`{CAPTURE_ROOT}/{session}/motion/recs/{recId}`)
+ * combined with `os.tmpdir()`'s own (often long, per-user) prefix can already exceed that before
+ * adding a filename, so the socket can never live inside `recDir` — see `recorderSocketPath()`.
+ */
+function recorderSocketDir(): string {
+  return ensurePrivateDir(path.join(CAPTURE_ROOT, 'sock'));
+}
+
+/**
+ * A short, fixed-length filename deterministically derived from `recDir` (not from `recDir`'s
+ * own length/depth), so the resulting socket path stays bounded regardless of how deep the
+ * recording's session/motion/recs nesting is.
+ */
+function shortSocketName(recDir: string): string {
+  return crypto.createHash('sha1').update(path.resolve(recDir)).digest('hex').slice(0, 16);
+}
+
+/**
+ * The recorder bridge's own socket path. Lives in the short, flat `recorderSocketDir()` — NOT
+ * inside `recDir` (the long, deep artifact directory `frames`/`events.jsonl`/etc. write into) —
+ * so binding it never risks exceeding the platform's `AF_UNIX` pathname limit. `recDir` is still
+ * required by every recorder-mode caller (spawn args, artifact writers); this function only
+ * derives the socket's own location from it, deterministically, without embedding `recDir` in
+ * the path itself.
+ */
 export function recorderSocketPath(recDir: string): string {
-  return path.join(recDir, 'recorder.sock');
+  return path.join(recorderSocketDir(), `${shortSocketName(recDir)}.sock`);
 }
 
 export async function startBridge(
@@ -41,9 +70,13 @@ export async function startBridge(
   const start = Date.now();
   while (!fs.existsSync(socketPath)) {
     if (Date.now() - start > timeoutMs) {
+      // Own the child we spawned: a bridge that never signalled readiness is
+      // ours to reap before we reject, so no orphaned process outlives the
+      // failed start. Mirrors startRecorderBridge()'s ownership discipline.
+      stopBridge(pid, socketPath);
       throw new Error(
         `CDP bridge (pid ${pid}) did not come up within ${timeoutMs}ms. ` +
-          `Check that a browser is reachable on port ${port} (capture detect).`,
+          `Check that a browser is reachable on port ${port} (capture tab list --port ${port}).`,
       );
     }
     await new Promise((r) => setTimeout(r, 50));
@@ -78,15 +111,27 @@ export function stopBridge(pid: number | null | undefined, socketPath: string |
  * (U14's lifecycle routing) tears it down with the same `stopBridge()`
  * used for the plain held bridge.
  *
- * Recorder mode is selected via a positional (`recorder <recDir>`) rather
- * than a new flag — `capture`'s CLI arg parser (`src/cdp/args.ts`) is not
- * owned by this unit, but `positional` is already generic passthrough.
+ * Recorder mode is selected via a positional (`recorder <recDir> <harId>`)
+ * rather than a new flag — `capture`'s CLI arg parser (`src/cdp/args.ts`) is
+ * not owned by this unit, but `positional` is already generic passthrough.
+ *
+ * `harId` is the owning session's live HAR recording id (`.session.json`'s
+ * `harId`) — the recorder bridge installs a streaming `HARRecorder` on its
+ * held tab connection and appends network evidence to that store, so the id
+ * must travel to the spawned process. Required: a session-backed recorder
+ * always has one (the caller throws before spawning if it doesn't).
+ *
+ * The socket-file readiness poll below doubles as the nonce-boot-file
+ * guarantee: the recorder writes `{recDir}/recorder-nonce.json` BEFORE it
+ * binds the socket (see `../recorder-bridge.ts`), so once this resolves the
+ * caller can read the nonce without racing the child.
  */
 export async function startRecorderBridge(
   socketPath: string,
   port: number,
   targetId: string,
   recDir: string,
+  harId: string,
   timeoutMs = 5000,
 ): Promise<{ socketPath: string; pid: number }> {
   const scriptPath = process.argv[1];
@@ -103,6 +148,7 @@ export async function startRecorderBridge(
       targetId,
       'recorder',
       recDir,
+      harId,
     ],
     { detached: true, stdio: 'ignore' },
   );
@@ -115,6 +161,7 @@ export async function startRecorderBridge(
   const start = Date.now();
   while (!fs.existsSync(socketPath)) {
     if (Date.now() - start > timeoutMs) {
+      stopBridge(pid, socketPath);
       throw new Error(
         `Recorder bridge (pid ${pid}) did not come up within ${timeoutMs}ms. ` +
           `Check that target "${targetId}" is reachable on port ${port}.`,

package/src/cdp/client.ts

@@ -8,7 +8,7 @@ export class CDPClient {
     { resolve: (v: unknown) => void; reject: (e: Error) => void }
   >();
   private pendingTimeouts = new Map<number, NodeJS.Timeout>();
-  private eventHandlers = new Map<string, Array<(params: unknown) => void>>();
+  private eventHandlers = new Map<string, Array<(params: unknown, sessionId?: string) => void>>();
   private ready: Promise<void>;
 
   constructor(wsUrl: string, connectTimeout = 5000) {
@@ -47,7 +47,7 @@ export class CDPClient {
         }
       } else if (msg.method) {
         const handlers = this.eventHandlers.get(msg.method);
-        handlers?.forEach((h) => h(msg.params));
+        handlers?.forEach((handler) => handler(msg.params, msg.sessionId));
       }
     });
   }
@@ -80,13 +80,23 @@ export class CDPClient {
     });
   }
 
-  on(event: string, handler: (params: unknown) => void): void {
+  /** Registers an event callback. The second argument is the actual optional `sessionId` from a flattened CDP event envelope; it is never inferred from the method or params. */
+  on(event: string, handler: (params: unknown, sessionId?: string) => void): void {
     if (!this.eventHandlers.has(event)) {
       this.eventHandlers.set(event, []);
     }
     this.eventHandlers.get(event)!.push(handler);
   }
 
+  /** Unregisters a handler previously added with {@link on}. Required so one-shot event consumers (e.g. the `LayerTree.layerTreeDidChange` collector) can remove their listener on settle/timeout instead of leaking a retained closure for the connection's lifetime. */
+  off(event: string, handler: (params: unknown, sessionId?: string) => void): void {
+    const handlers = this.eventHandlers.get(event);
+    if (!handlers) return;
+    const index = handlers.indexOf(handler);
+    if (index !== -1) handlers.splice(index, 1);
+    if (handlers.length === 0) this.eventHandlers.delete(event);
+  }
+
   /** Fires when the underlying websocket goes away (browser closed, crashed, CDP endpoint dropped). */
   onDisconnect(handler: () => void): void {
     this.ws.on('close', handler);

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

@@ -1,5 +1,6 @@
 import { runBridgeServer } from '../bridge/server.js';
 import { runRecorderBridge } from '../recorder-bridge.js';
+import { invalidInput } from '../../errors.js';
 import { type ParsedArgs } from '../types.js';
 
 /**
@@ -8,31 +9,36 @@ import { type ParsedArgs } from '../types.js';
  * --start` in recorder mode (`startRecorderBridge()`). Not documented in
  * `capture --help` — nothing calls this directly.
  *
- * Recorder mode is selected by a `recorder <recDir>` positional rather
- * than a new flag, since `src/cdp/args.ts`'s fixed flag set isn't owned by
- * this unit but `parsed.positional` is already generic passthrough:
- *   capture __bridge-serve --socket <path> --port <cdpPort> --target <tabId> recorder <recDir>
+ * Recorder mode is selected by a `recorder <recDir> <harId>` positional
+ * rather than a new flag, since `src/cdp/args.ts`'s fixed flag set isn't
+ * owned by this unit but `parsed.positional` is already generic passthrough:
+ *   capture __bridge-serve --socket <path> --port <cdpPort> --target <tabId> recorder <recDir> <harId>
+ *
+ * Usage errors throw the repo's structured `CaptureError` — the root
+ * boundary in `src/capture.ts` renders it via `failureResult()` and exits
+ * nonzero, same as every other command leaf.
  */
 export async function cmdBridgeServe(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (!parsed.socket) {
-    console.error(
-      'Usage: capture __bridge-serve --socket <path> [--port <cdpPort>] [--target <tabId> recorder <recDir>]',
+    throw invalidInput(
+      'Usage: capture __bridge-serve --socket <path> [--port <cdpPort>] [--target <tabId> recorder <recDir> <harId>]',
+      'bridge_serve_usage',
     );
-    process.exit(1);
   }
 
   if (parsed.positional[0] === 'recorder') {
     const recDir = parsed.positional[1];
-    if (!parsed.target || !recDir) {
-      console.error(
-        'Usage: capture __bridge-serve --socket <path> --port <cdpPort> --target <tabId> recorder <recDir>',
+    const harId = parsed.positional[2];
+    if (!parsed.target || !recDir || !harId) {
+      throw invalidInput(
+        'Usage: capture __bridge-serve --socket <path> --port <cdpPort> --target <tabId> recorder <recDir> <harId>',
+        'bridge_serve_usage',
       );
-      process.exit(1);
     }
-    await runRecorderBridge({ socketPath: parsed.socket, port: parsed.port, targetId: parsed.target, recDir });
+    await runRecorderBridge({ socketPath: parsed.socket, port: parsed.port, targetId: parsed.target, recDir, harId });
     // Deliberately does not exit: the open Unix socket server and the live
-    // tab websocket keep this detached process alive until the caller sends
-    // it SIGTERM (same teardown as the plain held bridge).
+    // tab websocket keep this detached process alive until an authenticated
+    // `rec-stop` completes (self-exit) or the caller escalates with SIGTERM.
     return;
   }