@crouton-kit/capture 1.3.17 → 1.3.19

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

@@ -6,7 +6,8 @@ import { type ParsedArgs } from '../../types.js';
 import { withConnection } from '../../connection.js';
 import { isRecorderHeldClient } from '../../recorder-client.js';
 import { parseViewport, type Viewport } from '../../viewport.js';
-import { captureSnapshotSubstrate } from '../../measure/snapshot.js';
+import { captureSnapshotSubstrate, COLLECTOR_NAMES, SnapshotCaptureTimeout } from '../../measure/snapshot.js';
+import type { CollectorOutcome } from '../../measure/types.js';
 import { sanitizeString } from '../../measure/redaction.js';
 import { DEFAULT_SETTLE_TIMEOUT_MS } from '../../measure/settle.js';
 import { createOneshotSession } from '../../../session/commands.js';
@@ -31,6 +32,7 @@ input:
   --freeze-animations         pause CSS/WAAPI animation before capture
   --settle-timeout <ms>       override the default 5000ms settle wait
   --capture-unsettled         write the full substrate despite non-settlement, marking unstable regions
+  --skip-collector <name>     leave one collector out entirely (repeatable): ax, styles, queries, animation, layers, media, geometry, hittest, text, forms, focus, scroll, states, pixels. A collector that fails is recorded and skipped; every other collector's substrate is still written
   --pixels                    also write per-element raster crops
   --state <state[:selector]>  force a pseudo-state or real control state (repeatable)
   --viewport <WxH>            temporarily capture at a CSS-pixel viewport (repeatable); exact <positive-safe-int>x<positive-safe-int> grammar with lowercase x and no whitespace
@@ -188,6 +190,17 @@ export async function withAppliedViewport<T>(client: ViewportClient, viewport: V
   }
 }
 
+/** One line naming every collector whose substrate is absent or degraded, and what to do about it. */
+function collectorNote(incomplete: readonly CollectorOutcome[]) {
+  const described = incomplete
+    .map((c) => `${sanitizeString(c.name)} (${c.status}${c.requestTimeouts ? `, ${c.requestTimeouts} timed-out request(s)` : ''})`)
+    .join(', ');
+  const failed = incomplete.some((c) => c.status === 'error' || c.status === 'degraded');
+  return fact`collectors incomplete: ${described}. Every other collector's substrate is valid and queryable.${
+    failed ? ` Re-run with \`--skip-collector <name>\` to omit one deliberately rather than have it fail.` : ''
+  }`;
+}
+
 function settledNote(settled: boolean, captured: boolean, settleMs: number, settleTimeoutMs: number, unstableCount: number) {
   if (settled) {
     return fact`Settled after ${settleMs}ms (two consecutive identical captures; DOM quiet ≥300ms).`;
@@ -210,6 +223,11 @@ export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.
   if (parsed.settleTimeout !== undefined && (!Number.isFinite(parsed.settleTimeout) || parsed.settleTimeout <= 0)) {
     throw invalidInput('--settle-timeout must be a positive number of milliseconds');
   }
+  for (const name of parsed.skipCollector ?? []) {
+    if (!COLLECTOR_NAMES.includes(name)) {
+      throw invalidInput(`--skip-collector must name a collector: ${COLLECTOR_NAMES.join(', ')} (got ${sanitizeString(name)})`);
+    }
+  }
   const viewport: ViewportSpec | undefined = viewportValue === undefined
     ? undefined
     : { label: viewportValue, ...parseViewport(viewportValue) };
@@ -254,6 +272,7 @@ export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.
           pixels: parsed.pixels,
           state: parsed.state ?? [],
           viewport: viewport?.label ?? null,
+          skipCollectors: parsed.skipCollector ?? [],
         });
         artifacts = result.artifacts;
       });
@@ -262,7 +281,7 @@ export async function captureMeasureSnap(parsed: ParsedArgs, targetRef = parsed.
     if (!snapDir) throw new Error('measure snap did not allocate an artifact directory');
     return { id: snapId, dir: snapDir, artifacts, ...(base ? { base } : {}) };
   } catch (err) {
-    if (allocatedRoot) removeArtifactTree(allocatedRoot);
+    if (allocatedRoot && !(err instanceof SnapshotCaptureTimeout)) removeArtifactTree(allocatedRoot);
     throw err;
   }
 }
@@ -276,7 +295,9 @@ function buildSnapshotResult(captured: MeasureSnapCapture): RenderableResult {
     settleTimeoutMs: number;
     unstableRegionCount: number;
     states: readonly string[];
+    collectors?: readonly CollectorOutcome[];
   }>({ kind: 'snap', id: captured.id, dir: captured.dir });
+  const incomplete = (meta.collectors ?? []).filter((c) => c.status !== 'ok');
   const elements = readArrayCount(path.join(captured.dir, 'geometry.json'), 'elements');
   const artifacts = artifactEntries(captured.dir, captured.artifacts);
   const capturedFullSubstrate = fs.existsSync(path.join(captured.dir, 'geometry.json'));
@@ -301,6 +322,11 @@ function buildSnapshotResult(captured: MeasureSnapCapture): RenderableResult {
     summary: meta.settled || capturedFullSubstrate
       ? text`Snapshot substrate captured.`
       : text`The evidence snapshot is not queryable because the settledness requirement was not met.`,
+    // A collector that did not complete cleanly must be visible in the block,
+    // not only in meta.json — its artifact is absent (timeout/error/skipped)
+    // or partly built from timed-out reads (degraded), and a caller who reads
+    // the remaining substrate as a whole page would be reading a hole.
+    ...(incomplete.length ? { sections: [collectorNote(incomplete)] } : {}),
     artifacts: formatArtifactList(artifacts),
     followUp: meta.settled || capturedFullSubstrate
       ? fact`Query snapshot ${captured.id} with \`capture measure check ${captured.id}\`, \`capture measure census --snap ${captured.id} --axis color\`, or \`capture measure map focus ${captured.id}\`.`
@@ -312,6 +338,9 @@ interface SnapErrorDetails {
   readonly status: string;
   readonly message: string;
   readonly resolution?: ArtifactResolutionError;
+  readonly phase?: string;
+  readonly method?: string;
+  readonly partialPath?: string;
 }
 
 function safeErrorDetail(value: unknown): string {
@@ -319,6 +348,9 @@ function safeErrorDetail(value: unknown): string {
 }
 
 export function classifySnapError(err: unknown): SnapErrorDetails {
+  if (err instanceof SnapshotCaptureTimeout) {
+    return { status: 'snapshot_capture_timeout', message: safeErrorDetail(err), phase: err.phase, method: err.method, partialPath: err.partialPath };
+  }
   if (err instanceof ArtifactResolutionError) {
     return { status: 'snapshot_ref_unavailable', message: safeErrorDetail(err), resolution: err };
   }
@@ -399,6 +431,9 @@ export async function cmdMeasureSnap(parsed: ParsedArgs, _args: string[]): Promi
       attrs: {
         command: 'measure snap',
         status: classified.status,
+        ...(classified.phase ? { phase: classified.phase } : {}),
+        ...(classified.method ? { method: classified.method } : {}),
+        ...(classified.partialPath ? { 'partial-path': classified.partialPath } : {}),
         ...(classified.resolution ? {
           recovery: 'artifact-resolution-error',
           ref: sanitizeString(classified.resolution.ref),

package/src/cdp/commands/motion/mask.ts

@@ -24,9 +24,15 @@ export async function cmdMotionMask(parsed: ParsedArgs, _args: string[]): Promis
 
   try {
     const ref = resolveRecRef(parsed.positional[0]);
-    const meta = readMeta<{ state?: unknown }>(ref);
+    const meta = readMeta<{ state?: unknown; reason?: unknown }>(ref);
     const state = typeof meta.state === 'string' ? meta.state : 'unknown';
-    if (state !== 'finalized' && state !== 'orphaned-finalized') {
+    // A one-shot recording that captured zero screencast frames is a completed
+    // recording, not one awaiting `--stop` (which only finalizes an active
+    // composed lifecycle recording) — let it through and rely on
+    // createMotionMask's own accurate "needs at least two frames" rejection
+    // below, matching the same exception in response.ts's loadResponseTimeline.
+    const readablePartial = state === 'partial' && meta.reason === 'no_frames';
+    if (state !== 'finalized' && state !== 'orphaned-finalized' && !readablePartial) {
       return emitCommandError(parsed, 'recording_not_finalized', `Recording ${ref.id} has state ${state}; finalize it with \`capture motion rec --stop\` before creating a mask.`);
     }
     const mask = createMotionMask(ref);

package/src/cdp/commands/page/click.ts

@@ -94,6 +94,20 @@ export function emitResolutionError(parsed: ParsedArgs, command: string, failure
     return;
   }
 
+  if (failure.code === 'invalid-css-selector') {
+    emitResult(
+      {
+        tag: 'error',
+        attrs: { command, code: 'invalid_css_selector' },
+        summary: fact`received: bare target \`${failure.input}\` was rejected by DOM.querySelectorAll as a CSS selector.`,
+        followUp: fact`Retry \`capture ${command} ax:${failure.input}\` to target that accessible name, or use \`backend:<id>\` from \`capture page elements\`.`,
+      },
+      { json: parsed.json },
+    );
+    process.exitCode = 1;
+    return;
+  }
+
   const code = failure.code === 'no-match' ? 'no_match' : 'ambiguous_target';
   const candidateRows: FactLine[] = failure.candidates.map((c) =>
     line(data(c.role ?? 'unknown'), text` "`, data(c.name ?? ''), text`" — backend:`, data(c.backendNodeId)),

package/src/cdp/commands/page/elements.ts

@@ -42,7 +42,7 @@ Input:
   --json              mirror the result as JSON
 
 Output:
-  <elements scope="interactive|all" count=<total>> — one row per element: role "name" backend:<id>
+  <elements scope="interactive|all" count=<total>> — one row per element: role "name" target:ax:<name> backend:<id>; copy the target value into a driving verb
 
 Effects: read-only — the accessibility fetch is CDP-side, no page-observable writes; routes unmarked through an active composed recording.`;
 
@@ -106,7 +106,7 @@ export function buildElementsResult(
 
   const rows = shown.map((r) =>
     r.backendNodeId !== null
-      ? fact`${r.role} "${r.name}" backend:${r.backendNodeId}`
+      ? fact`${r.role} "${r.name}" target:ax:${r.name} backend:${r.backendNodeId}`
       : fact`${r.role} "${r.name}"`,
   );
 

package/src/cdp/commands/page/shot.ts

@@ -18,7 +18,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { type ParsedArgs } from '../../types.js';
 import { withConnection } from '../../connection.js';
-import { captureScreenshot } from '../../screenshot.js';
+import { captureScreenshotWithCssViewport, type CapturedRegion } from '../../screenshot.js';
 import { parseViewport, type Viewport } from '../../viewport.js';
 import { nextStepPath } from '../../../session-context.js';
 import { createOneshotSession } from '../../../session/commands.js';
@@ -40,7 +40,7 @@ input:
   --target <tabId> | --url <pattern> | --port <n>   tab targeting; defaults to the active session tab
   --json            mirror the result as JSON
 output:
-  <screenshot path=… width=… height=… emulation=none|viewport|full-page> — saved path, PNG pixel dimensions, byte size, and the emulation fact (whether a transient override was applied, or its absence)
+  <screenshot path=… width=… height=… css-width=… css-height=… css-x=… css-y=… css-to-image-x=… css-to-image-y=… emulation=none|viewport|full-page> — saved path, PNG pixel dimensions, the CSS-pixel region the image covers (its page-coordinate origin and size) with the CSS-to-image scale derived from it, byte size, and the emulation fact (whether a transient override was applied, or its absence)
 effects:
   no flags: none — the capture reads the viewport as-is, with zero Emulation.* calls. With --viewport/--full-page: applies a transient Emulation.setDeviceMetricsOverride (~150ms re-layout wait) and clears it after the capture — two page-observable resizes (resize events fire; media queries flip and flip back)`;
 
@@ -116,14 +116,29 @@ function writeScreenshot(outPath: string, png: Buffer): void {
 
 export type EmulationMode = 'none' | 'viewport' | 'full-page';
 
+/** Renders a CSS-pixel measurement without inventing precision: an integer stays an integer, a fractional zoomed viewport keeps six decimals. */
+function round6(value: number): number {
+  return Math.round(value * 1e6) / 1e6;
+}
+
 export function buildScreenshotResult(f: {
   path: string;
   bytes: number;
   dimensions: { width: number; height: number } | null;
+  cssViewport?: CapturedRegion;
   emulation: EmulationMode;
   viewport?: { width: number; height: number };
 }): RenderableResult {
+  // The denominator is the CSS region the image was actually cut from, so the
+  // ratio stays true under page zoom, device pixel ratio, and the local
+  // downscale — the layout viewport is a different space and is never used here.
+  const scale = f.dimensions && f.cssViewport
+    ? { x: f.dimensions.width / f.cssViewport.width, y: f.dimensions.height / f.cssViewport.height }
+    : undefined;
   const sections: FactLine[] = [
+    scale && f.cssViewport
+      ? fact`CSS-to-image scale: ${scale.x.toFixed(6)} image px/CSS px horizontally and ${scale.y.toFixed(6)} image px/CSS px vertically (captured CSS region ${round6(f.cssViewport.width)}×${round6(f.cssViewport.height)} at page origin ${round6(f.cssViewport.x)},${round6(f.cssViewport.y)}).`
+      : text`CSS-to-image scale unavailable: the browser did not return the CSS region this capture covers.`,
     f.emulation === 'none'
       ? text`emulation: none — the browser's actual current viewport was captured; no Emulation call was made.`
       : f.emulation === 'viewport'
@@ -138,6 +153,12 @@ export function buildScreenshotResult(f: {
       path: f.path,
       width: f.dimensions?.width,
       height: f.dimensions?.height,
+      'css-width': f.cssViewport === undefined ? undefined : round6(f.cssViewport.width),
+      'css-height': f.cssViewport === undefined ? undefined : round6(f.cssViewport.height),
+      'css-x': f.cssViewport === undefined ? undefined : round6(f.cssViewport.x),
+      'css-y': f.cssViewport === undefined ? undefined : round6(f.cssViewport.y),
+      'css-to-image-x': scale?.x.toFixed(6),
+      'css-to-image-y': scale?.y.toFixed(6),
       emulation: f.emulation,
     },
     summary: f.dimensions
@@ -196,10 +217,10 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
   const result = await deps.withConnection(
     { ...parsed, command: 'shot' },
     async (client) => {
-      const png = await captureScreenshot(client, viewport, { fullPage: parsed.fullPage });
+      const screenshot = await captureScreenshotWithCssViewport(client, viewport, { fullPage: parsed.fullPage });
       const outPath = await resolveOutPath(parsed);
-      writeScreenshot(outPath, png);
-      return { path: outPath, bytes: png.length, dimensions: pngDimensions(png) };
+      writeScreenshot(outPath, screenshot.png);
+      return { path: outPath, bytes: screenshot.png.length, dimensions: pngDimensions(screenshot.png), cssViewport: screenshot.cssViewport };
     },
     { settle: 0 },
   );

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

@@ -10,6 +10,8 @@
  */
 import { invalidInput } from '../../../errors.js';
 import { type ParsedArgs } from '../../types.js';
+import { cmdTabLaunch } from './launch.js';
+import { cmdTabQuit } from './quit.js';
 import { cmdTabList } from './list.js';
 import { cmdTabOpen } from './open.js';
 import { cmdTabClose } from './close.js';
@@ -18,19 +20,24 @@ import { cmdTabNetwork } from './network.js';
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="tab">
-tab and connection plumbing — endpoint/tab discovery, lifecycle, connection-level network emulation
-use when finding a CDP endpoint or tab, opening/closing/replacing a tab, or toggling connectivity; \`tab list\` is the probe for a running browser
-  list · open · close · reset · network — \`capture tab -h\`
+browser and tab plumbing — starting/stopping a browser capture owns, endpoint/tab discovery, tab lifecycle, connection-level network emulation
+use when nothing is running yet (\`tab launch\` starts a browser capture owns and reaps), when finding a CDP endpoint or tab, opening/closing/replacing a tab, or toggling connectivity; \`tab list\` is the probe for a running browser
+  launch · quit · list · open · close · reset · network — \`capture tab -h\`
 </command>`;
 
-export const TAB_USAGE = `capture tab — tab and connection plumbing: discovery, lifecycle, network emulation.
+export const TAB_USAGE = `capture tab — browser and tab plumbing: browser lifecycle, discovery, tab lifecycle, network emulation.
 
 \`tab list\` with no --port performs full endpoint discovery and is the probe
-for whether a CDP-enabled browser is running at all. \`tab reset\` replaces a
-stuck tab with a fresh one; under an active session it refuses while a
-recording is active (stop it first), reaps dead recorder handles, and updates
-the session's {target, port} pair together.
+for whether a CDP-enabled browser is running at all; when nothing is running,
+\`tab launch\` starts one capture owns — never hand-roll a detached browser,
+since nothing reaps that. Capture signals only browsers it launched itself
+(verified by process-birth identity): an endpoint you reach with --port stays
+untouched. \`tab reset\` replaces a stuck tab with a fresh one; under an active
+session it refuses while a recording is active (stop it first), reaps dead
+recorder handles, and updates the session's {target, port} pair together.
 
+<subcommand name="launch" args="[--url <url>] [--port <port>] [--headed]" whenToUse="start a browser capture owns (and reaps) when none is running"/>
+<subcommand name="quit" args="[<port>] [--all]" whenToUse="stop a browser capture launched; never touches a browser capture did not start"/>
 <subcommand name="list" args="[--port <port>]" whenToUse="discover CDP endpoints and the tabs open on them"/>
 <subcommand name="open" args="<url> [--new] [--port <port>]" whenToUse="open a URL and get its tab id"/>
 <subcommand name="close" args="<target> [--port <port>]" whenToUse="close one explicitly identified background tab"/>
@@ -44,6 +51,10 @@ export async function tabMain(parsed: ParsedArgs, args: string[]): Promise<void>
   const rest: ParsedArgs = { ...parsed, positional: parsed.positional.slice(1) };
 
   switch (leaf) {
+    case 'launch':
+      return cmdTabLaunch(rest, args);
+    case 'quit':
+      return cmdTabQuit(rest, args);
     case 'list':
       return cmdTabList(rest, args);
     case 'open':

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

@@ -0,0 +1,73 @@
+/**
+ * `capture tab launch [--url <url>] [--port <port>] [--headed]` — start a
+ * browser capture owns, and report the endpoint every other capture command can
+ * now be pointed at.
+ *
+ * This is the answer to "a CDP-enabled browser must be running": without it the
+ * only way to satisfy that precondition was a hand-rolled detached Chrome with
+ * an invented port and an invented scratch profile, which nothing ever reaped.
+ * Ownership, registry, and reaping all live in `../../browser-process.ts`; this
+ * leaf is the surface over them.
+ */
+import { launchOwnedBrowser, sweepOwnedBrowsers, IDLE_REAP_MS } from '../../browser-process.js';
+import { type ParsedArgs } from '../../types.js';
+import { data, emitResult, fact, line, lineList, text, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `capture tab launch — start a browser capture owns and report its CDP endpoint.
+
+input:
+  --url <url>     first page to open (default: about:blank)
+  --port <port>   pin the debugging port (default: a free port chosen by the kernel)
+  --headed        run with a visible window instead of headless
+
+output: <browser-launched port=… pid=…> — the port to pass as --port (or CDP_PORT), the pid capture owns, and the executable that answered with its provenance (CAPTURE_BROWSER, puppeteer-cache, or system).
+effects: spawns a detached browser with a private profile under CAPTURE_ROOT, and registers it as capture-owned. Capture stops it on \`capture tab quit\`, or on the first later capture invocation once it has been unused for ${IDLE_REAP_MS / 60000} minutes; a browser capture did not start is never signalled. Also sweeps previously-launched browsers that have exited, stopped answering CDP, or gone idle.`;
+
+/** Pure `<browser-launched>` result builder — exported for tests. */
+export function buildBrowserLaunchedResult(
+  browser: { port: number; pid: number; executablePath: string; source: string; headless: boolean },
+  swept: number,
+): RenderableResult {
+  const sections = [
+    lineList([
+      line(text`executable `, data(browser.executablePath, 300), text` (`, data(browser.source), text`)`),
+      line(text`mode `, data(browser.headless ? 'headless' : 'headed')),
+    ]),
+  ];
+  if (swept > 0) sections.push(fact`swept ${swept} previously-launched browser(s) that had exited, stopped answering CDP, or gone idle.`);
+  return {
+    tag: 'browser-launched',
+    attrs: { port: browser.port, pid: browser.pid, headless: browser.headless },
+    summary: line(
+      text`capture-owned browser on port `,
+      data(browser.port),
+      fact` (pid ${browser.pid}) is answering CDP.`,
+    ),
+    sections,
+    followUp: line(text`capture tab quit `, data(browser.port)),
+  };
+}
+
+export async function cmdTabLaunch(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  const swept = await sweepOwnedBrowsers();
+  const browser = await launchOwnedBrowser({
+    url: parsed.url,
+    port: parsed.port,
+    headless: !parsed.headed,
+  });
+
+  emitResult(
+    buildBrowserLaunchedResult(
+      // A launched browser always reports a port — `launchOwnedBrowser` only
+      // returns once its endpoint answered on one.
+      { ...browser, port: browser.port! },
+      swept.length,
+    ),
+    { json: parsed.json },
+  );
+}

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

@@ -13,6 +13,7 @@ import {
   pickPreferredEndpoint,
 } from '../../detect.js';
 import { listTargets } from '../../targets.js';
+import { ownedBrowsersByPort, sweepOwnedBrowsers } from '../../browser-process.js';
 import { type ParsedArgs } from '../../types.js';
 import {
   data,
@@ -30,8 +31,8 @@ const USAGE = `capture tab list — discover CDP endpoints and list the page tab
 input:
   --port <port>   probe one endpoint only, instead of discovering every localhost CDP endpoint
 
-output: <tabs endpoints=… tabs=…> — one section per reachable endpoint (port, app, page-tab count, preferred marker) listing each page tab's target id (first 8 chars, enough for --target), title, and url; an endpoint that failed the tab fetch is an endpoints-unreachable fact, never a silent omission.
-effects: read-only — probes local CDP endpoints over HTTP/WebSocket; no page-observable writes.`;
+output: <tabs endpoints=… tabs=…> — one section per reachable endpoint (port, app, page-tab count, preferred marker, and a capture-owned pid marker on any browser \`tab launch\` started) listing each page tab's target id (first 8 chars, enough for --target), title, and url; an endpoint that failed the tab fetch is an endpoints-unreachable fact, never a silent omission.
+effects: probes local CDP endpoints over HTTP/WebSocket; no page-observable writes. Also sweeps capture-launched browsers, stopping any that have exited, stopped answering CDP, or gone idle — browsers capture did not start are never signalled.`;
 
 export interface TabRow {
   id: string;
@@ -45,6 +46,9 @@ export interface EndpointTabs {
   app?: string;
   /** Marked on the endpoint auto-discovery would pick for port-less commands. */
   preferred: boolean;
+  /** The pid of the capture-launched browser serving this endpoint, when this
+   * is one capture owns — absent for every foreign/user-owned endpoint. */
+  ownedPid?: number;
   pages: TabRow[];
 }
 
@@ -76,6 +80,7 @@ export function buildTabsResult(
       ...(ep.app !== undefined ? [line(text` — `, data(ep.app, 80))] : []),
       fact` — ${ep.pages.length} page tab(s)`,
       ...(ep.preferred ? [text` [preferred]`] : []),
+      ...(ep.ownedPid !== undefined ? [line(fact` [capture-owned pid=${ep.ownedPid}]`)] : []),
     );
     const rows = ep.pages.map((t) =>
       line(text`  `, data(t.id.slice(0, 8)), text`  "`, data(t.title, 120), text`"  `, data(t.url, 300)),
@@ -121,6 +126,11 @@ export async function cmdTabList(parsed: ParsedArgs, _args: string[]): Promise<v
     return;
   }
 
+  // The probe agents run constantly is also where abandoned owned browsers
+  // die: sweeping here is what keeps a launch from outliving the agent that
+  // made it, without any daemon in the picture.
+  await sweepOwnedBrowsers();
+  const owned = ownedBrowsersByPort();
   const reachable: EndpointTabs[] = [];
   const unreachable: UnreachableEndpoint[] = [];
 
@@ -130,6 +140,7 @@ export async function cmdTabList(parsed: ParsedArgs, _args: string[]): Promise<v
       reachable.push({
         port: parsed.port,
         preferred: false,
+        ...(owned.has(parsed.port) ? { ownedPid: owned.get(parsed.port)!.pid } : {}),
         pages: targets
           .filter((t) => t.type === 'page')
           .map((t) => ({ id: t.id, title: t.title, url: t.url })),
@@ -149,6 +160,7 @@ export async function cmdTabList(parsed: ParsedArgs, _args: string[]): Promise<v
             port: ep.port,
             app: ep.app,
             preferred: ep.port === preferredPort,
+            ...(owned.has(ep.port) ? { ownedPid: owned.get(ep.port)!.pid } : {}),
             pages: targets
               .filter((t) => t.type === 'page')
               .map((t) => ({ id: t.id, title: t.title, url: t.url })),

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

@@ -0,0 +1,78 @@
+/**
+ * `capture tab quit [<port>] [--all]` — stop browsers capture started.
+ *
+ * Named `quit` rather than `close` deliberately: `capture tab close` closes one
+ * TAB inside a browser, this ends the browser process itself. It reaches only
+ * browsers in capture's own registry, verified by PID birth — a port capture
+ * never launched (the user's own browser, or one an agent started by hand)
+ * matches nothing here and is never signalled.
+ */
+import { quitOwnedBrowsers, sweepOwnedBrowsers, type ReapedBrowser } from '../../browser-process.js';
+import { invalidInput } from '../../../errors.js';
+import { type ParsedArgs } from '../../types.js';
+import { data, emitResult, fact, line, lineList, text, type RenderableResult } from '../../../output/render.js';
+
+const USAGE = `capture tab quit — stop a browser capture started.
+
+input:
+  <port>          the port of a capture-launched browser (as reported by tab launch / tab list)
+  --all           stop every browser capture launched
+
+output: <browser-quit stopped=…> — one line per stopped browser (port, pid) and the reason it ended.
+effects: SIGTERM (then SIGKILL if needed) to capture-launched browsers only, verified by process-birth identity, and removes their private profiles. A browser capture did not start is never signalled — a port with no capture record stops nothing.`;
+
+/** Pure `<browser-quit>` result builder — exported for tests. */
+export function buildBrowserQuitResult(stopped: readonly ReapedBrowser[], selector: string): RenderableResult {
+  return {
+    tag: 'browser-quit',
+    attrs: { stopped: stopped.length },
+    summary:
+      stopped.length === 0
+        ? line(text`no capture-launched browser matched `, data(selector), text`; nothing was signalled.`)
+        : fact`stopped ${stopped.length} capture-launched browser(s).`,
+    sections:
+      stopped.length === 0
+        ? []
+        : [
+            lineList(
+              stopped.map((browser) =>
+                line(
+                  text`port `,
+                  data(browser.port ?? 'unstarted'),
+                  fact`  pid ${browser.pid}  `,
+                  data(browser.reason),
+                ),
+              ),
+            ),
+          ],
+  };
+}
+
+export async function cmdTabQuit(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  const token = parsed.positional[0];
+  if (!parsed.all && token === undefined) {
+    throw invalidInput('received: no target; expected: capture tab quit <port> or capture tab quit --all.', 'missing_argument');
+  }
+  if (parsed.all && token !== undefined) {
+    throw invalidInput('received: both a port and --all; expected: one or the other.');
+  }
+  if (token !== undefined && !/^\d+$/.test(token)) {
+    throw invalidInput(`Invalid port: ${token}.`);
+  }
+  const port = token === undefined ? undefined : Number(token);
+
+  // The sweep runs first so a browser that already exited is reported as
+  // reaped rather than as "no match" for the port the caller remembered.
+  const swept = await sweepOwnedBrowsers();
+  const stopped = await quitOwnedBrowsers({ port, all: parsed.all });
+  const matchedSweep = swept.filter((browser) => parsed.all || browser.port === port);
+
+  emitResult(buildBrowserQuitResult([...stopped, ...matchedSweep], parsed.all ? '--all' : String(port)), {
+    json: parsed.json,
+  });
+}

package/src/cdp/har-recorder.ts

@@ -164,8 +164,6 @@ export class HARRecorder {
   private readonly recordedKeys = new Set<string>();
   /** Snapshot mode only — streaming mode retains no materialized values. */
   private readonly materializedByKey = new Map<string, Materialized>();
-  /** Last terminal remains comparable until this CDP id opens its next generation. */
-  private readonly closedTerminals = new Map<string, Terminal>();
   /** Sockets opened while this recorder is attached — CDP does not replay creation events for pre-existing sockets. */
   private readonly webSockets = new Map<string, WebSocketConnection>();
   private readonly bodyTasks = new Set<Promise<void>>();
@@ -245,11 +243,13 @@ export class HARRecorder {
     const hasRedirect = 'redirectResponse' in params && params.redirectResponse !== undefined;
     if (previous && !hasRedirect) fail('duplicate active requestId without redirectResponse');
     if (hasRedirect && previous) {
-      const redirect = this.parseResponse(params.redirectResponse, 'redirectResponse');
-      if (redirect.status < 300 || redirect.status > 399) fail('redirectResponse.status');
+      // CDP uses status 0 when a redirect response is observable but never
+      // reached HTTP (for example, an extension redirect during navigation).
+      // Preserve that factual response rather than aborting the whole session.
+      const redirect = this.parseResponse(params.redirectResponse, 'redirectResponse', true);
+      if (redirect.status !== 0 && (redirect.status < 300 || redirect.status > 399)) fail('redirectResponse.status');
       this.assignTerminal(previous, { kind: 'redirect', timestamp: monotonic }, redirect);
     }
-    this.closedTerminals.delete(requestId);
     const generation = this.nextGenerationByRequestId.get(requestId) ?? 1;
     this.nextGenerationByRequestId.set(requestId, generation + 1);
     this.activeByRequestId.set(requestId, {
@@ -338,11 +338,11 @@ export class HARRecorder {
     });
   }
 
-  private parseResponse(value: unknown, name: string): RedirectResponse {
+  private parseResponse(value: unknown, name: string, allowNoHttpStatus = false): RedirectResponse {
     if (!isPlainObject(value)) fail(name);
     nonempty(value.url, `${name}.url`);
     const status = finite(value.status, `${name}.status`);
-    if (!Number.isInteger(status) || status < 100 || status > 599) fail(`${name}.status`);
+    if (!Number.isInteger(status) || status < 0 || status > 599 || (status < 100 && !(allowNoHttpStatus && status === 0))) fail(`${name}.status`);
     return { status, headers: headers(value.headers, `${name}.headers`) };
   }
 
@@ -366,11 +366,13 @@ export class HARRecorder {
     const requestId = this.eventRequestId(params);
     if (!requestId) return;
     const current = this.activeByRequestId.get(requestId);
-    const closed = this.closedTerminals.has(requestId);
-    if (!current && !closed) return;
+    // Chromium can follow a loadingFailed with loadingFinished for the same
+    // request (for example, a blocked iframe during navigation). Once the
+    // first terminal materializes its generation, a later terminal cannot be
+    // assigned safely, so the first factual terminal remains authoritative.
+    if (!current) return;
     const event = params as Record<string, unknown>;
     const terminal: Terminal = { kind: 'finished', timestamp: finite(event.timestamp, 'timestamp'), encodedDataLength: finite(event.encodedDataLength, 'encodedDataLength') };
-    if (!current) return this.compareClosedTerminal(requestId, terminal);
     if (!current.response) fail('loadingFinished without responseReceived');
     this.assignTerminal(current, terminal);
   }
@@ -379,8 +381,7 @@ export class HARRecorder {
     const requestId = this.eventRequestId(params);
     if (!requestId) return;
     const current = this.activeByRequestId.get(requestId);
-    const closed = this.closedTerminals.has(requestId);
-    if (!current && !closed) return;
+    if (!current) return;
     const event = params as Record<string, unknown>;
     const terminal: Terminal = {
       kind: 'failed',
@@ -390,22 +391,15 @@ export class HARRecorder {
       blockedReason: event.blockedReason === undefined ? null : typeof event.blockedReason === 'string' ? event.blockedReason : fail('blockedReason'),
       resourceType: event.type === undefined ? null : typeof event.type === 'string' ? event.type : fail('type'),
     };
-    if (!current) return this.compareClosedTerminal(requestId, terminal);
     this.assignTerminal(current, terminal);
   }
 
-  private compareClosedTerminal(requestId: string, terminal: Terminal): void {
-    const previous = this.closedTerminals.get(requestId);
-    if (previous && !same(previous, terminal)) fail('conflicting terminal event');
-  }
-
   private assignTerminal(current: Generation, terminal: Terminal, redirectResponse?: RedirectResponse): void {
     if (current.terminal) {
-      if (!same(current.terminal, terminal)) fail('conflicting terminal event');
+      if (!same(current.terminal, terminal)) fail(`conflicting terminal event for requestId ${current.requestId} generation ${current.generation}`);
       return;
     }
     current.terminal = terminal;
-    this.closedTerminals.set(current.requestId, terminal);
     if (redirectResponse) {
       current.redirectResponse = redirectResponse;
       this.materialize(current, { state: 'not_applicable', reason: 'redirect' });

package/src/cdp/measure/collectors/ax.ts

@@ -7,10 +7,9 @@
  * shared with `styles.json`/`media.json` per the U04 contract — no
  * coordination with those files is needed.
  *
- * "geometry ids ... when possible": U07's `geometry.json` is a
- * concurrently-written sibling collector (`Promise.all` in `snapshot.ts`,
- * no cross-collector read ordering) that this file must not depend on or
- * read at capture time. Read here as "attach a `rect` fact directly per AX
+ * "geometry ids ... when possible": `geometry.json` is a separate
+ * collector artifact that this file does not depend on or read at capture
+ * time. Read here as "attach a `rect` fact directly per AX
  * node via a best-effort `DOM.getBoxModel` lookup" rather than a join
  * against `geometry.json` — a deliberate, bounded reading documented in
  * the U08 build-plan report, not a defect.