@crouton-kit/capture 1.3.18 → 1.3.20

package/src/cdp/targets.ts

@@ -1,5 +1,6 @@
 import { CDPClient } from './client.js';
 import { detectCdpPortsAsync } from './detect.js';
+import { touchOwnedBrowser } from './browser-process.js';
 import { type CDPTarget } from './types.js';
 
 /**
@@ -30,6 +31,10 @@ export async function getBrowserClient(
   }
   const client = new CDPClient(version.webSocketDebuggerUrl);
   await client.waitReady();
+  // Every browser-level connection funnels through here, which makes this the
+  // one place that can tell capture's idle sweep the browser is still in use.
+  // A port capture did not launch has no registry record and this is a no-op.
+  touchOwnedBrowser(port);
   return { client, browserWsUrl: version.webSocketDebuggerUrl };
 }
 

package/src/cdp/types.ts

@@ -25,6 +25,8 @@ export interface ParsedArgs {
    * can auto-append recorded traffic to the session HAR. */
   har?: string;
   new?: boolean;
+  /** `tab launch --headed` — a visible window instead of headless. */
+  headed?: boolean;
   target?: string;
   /** Where `target` was assigned from: an actual `--target` flag, active-session
    * autofill, or the ambient `CDP_TARGET` env var. Recorded at the assignment
@@ -36,6 +38,8 @@ export interface ParsedArgs {
   into?: string;
   noScreenshot?: boolean;
   viewport?: string;
+  /** `page shot|measure snap --color-scheme dark|light` — transient media override. */
+  colorScheme?: string;
   fullPage?: boolean;
   help?: boolean;
   /** `--all` — boolean scope-widener (per-leaf semantics). */
@@ -68,6 +72,8 @@ export interface ParsedArgs {
   settleTimeout?: number;
   /** `snap --capture-unsettled` — write full substrate despite non-settlement. */
   captureUnsettled?: boolean;
+  /** `snap --skip-collector <name>` — repeatable; one entry per occurrence. */
+  skipCollector?: string[];
   /** `snap|diff|mask --pixels` — include raster crop/diff facts. */
   pixels?: boolean;
   /** `snap --state <state[:selector]>` — repeatable; one entry per occurrence. */

package/src/har-manager.ts

@@ -552,8 +552,8 @@ function vEntry(v: unknown, source: string, path: string): HAREntry {
 
   // Response-state ⇄ status coupling.
   if (capResponse.state === 'received') {
-    if (status < 100 || status > 599) {
-      fail(source, `${path}.response.status`, 'a received response requires status 100..599');
+    if ((status < 100 || status > 599) && !(terminal.kind === 'redirect' && status === 0)) {
+      fail(source, `${path}.response.status`, 'a received response requires status 100..599 (or 0 for a redirect with no HTTP response)');
     }
   } else {
     // unavailable
@@ -566,8 +566,8 @@ function vEntry(v: unknown, source: string, path: string): HAREntry {
       fail(source, `${path}._capture.clocks.responseMonotonic`, 'must be null when no response was received');
     }
   }
-  if (status === 0 && capResponse.state !== 'unavailable') {
-    fail(source, `${path}.response.status`, 'status 0 is permitted only when _capture.response.state is "unavailable"');
+  if (status === 0 && capResponse.state !== 'unavailable' && terminal.kind !== 'redirect') {
+    fail(source, `${path}.response.status`, 'status 0 is permitted only for an unavailable response or a redirect with no HTTP response');
   }
 
   // Terminal ⇄ response/status/body coupling.
@@ -582,8 +582,8 @@ function vEntry(v: unknown, source: string, path: string): HAREntry {
     if (capResponse.state !== 'received') {
       fail(source, `${path}._capture.response.state`, 'a redirect requires a received response');
     }
-    if (status < 300 || status > 399) {
-      fail(source, `${path}.response.status`, 'a redirect requires status 300..399');
+    if (status !== 0 && (status < 300 || status > 399)) {
+      fail(source, `${path}.response.status`, 'a redirect requires status 0 (no HTTP response) or 300..399');
     }
     if (body.state !== 'not_applicable' || body.reason !== 'redirect') {
       fail(source, `${path}._capture.body`, 'a redirect requires body not_applicable/redirect');
@@ -666,17 +666,18 @@ function vIncompleteResponse(
   path: string,
   minResponseMonotonic: number,
   allowUnknownClock = false,
+  allowNoHttpStatus = false,
 ): IncompleteResponse {
   const o = vObject(v, source, path);
   exactKeys(o, ['status', 'headers', 'responseMonotonic'], source, path);
   const responseMonotonic = o.responseMonotonic === null
     ? allowUnknownClock ? null : fail(source, `${path}.responseMonotonic`, 'must be a finite number')
     : vFiniteMin(o.responseMonotonic, minResponseMonotonic, source, `${path}.responseMonotonic`);
-  return {
-    status: vIntInRange(o.status, 100, 599, source, `${path}.status`),
-    headers: vHeaders(o.headers, source, `${path}.headers`),
-    responseMonotonic,
-  };
+  const status = vIntInRange(o.status, 0, 599, source, `${path}.status`);
+  if ((status < 100 && status !== 0) || (status === 0 && (!allowNoHttpStatus || responseMonotonic !== null))) {
+    fail(source, `${path}.status`, 'must be 100..599 (or 0 for a redirect with no HTTP response)');
+  }
+  return { status, headers: vHeaders(o.headers, source, `${path}.headers`), responseMonotonic };
 }
 
 function vStoppedBeforeTerminal(
@@ -754,9 +755,9 @@ function vInvalidClockOrder(
   const generation = vSafeIntMin(o.generation, 1, source, `${path}.generation`);
   const startedDateTime = vString(o.startedDateTime, source, `${path}.startedDateTime`);
   const request = vRequest(o.request, source, `${path}.request`);
-  const response =
-    o.response === null ? null : vIncompleteResponse(o.response, source, `${path}.response`, 0, true);
   const terminal = vInvalidClockTerminal(o.terminal, source, `${path}.terminal`);
+  const response =
+    o.response === null ? null : vIncompleteResponse(o.response, source, `${path}.response`, 0, true, terminal.kind === 'redirect');
 
   const cap = vObject(o._capture, source, `${path}._capture`);
   exactKeys(cap, ['schemaVersion', 'requestWallTime', 'requestMonotonic'], source, `${path}._capture`);
@@ -775,8 +776,8 @@ function vInvalidClockOrder(
   // CDP redirectResponse preserves redirect facts but has no independently observed response clock.
   if (terminal.kind === 'redirect') {
     if (response === null) fail(source, `${path}.response`, 'a redirect terminal requires an observed response');
-    if (response.status < 300 || response.status > 399) {
-      fail(source, `${path}.response.status`, 'a redirect terminal requires status 300..399');
+    if (response.status !== 0 && (response.status < 300 || response.status > 399)) {
+      fail(source, `${path}.response.status`, 'a redirect terminal requires status 0 (no HTTP response) or 300..399');
     }
     if (response.responseMonotonic !== null) {
       fail(source, `${path}.response.responseMonotonic`, 'must be null for a redirect terminal');

package/src/interact.ts

@@ -89,6 +89,11 @@ export type ResolutionFailure =
       readonly input: string;
       readonly acceptedPrefixes: typeof ACCEPTED_LIVE_PREFIXES;
     }
+  | {
+      readonly ok: false;
+      readonly code: 'invalid-css-selector';
+      readonly input: string;
+    }
   | {
       readonly ok: false;
       readonly code: 'no-match' | 'ambiguous';
@@ -222,10 +227,21 @@ async function resolveLiveCss(
 ): Promise<ResolvedTarget | ResolutionFailure> {
   await client.send('DOM.enable');
   const { root } = (await client.send('DOM.getDocument', { depth: 0 })) as { root: { nodeId: number } };
-  const { nodeIds } = (await client.send('DOM.querySelectorAll', {
-    nodeId: root.nodeId,
-    selector,
-  })) as { nodeIds: number[] };
+  let nodeIds: number[];
+  try {
+    ({ nodeIds } = (await client.send('DOM.querySelectorAll', {
+      nodeId: root.nodeId,
+      selector,
+    })) as { nodeIds: number[] });
+  } catch (error) {
+    // Chrome reports a malformed CSS selector from this CDP method as the
+    // otherwise opaque "DOM Error while querying". The bare grammar is CSS;
+    // make the accessible-name retry explicit instead of leaking that error.
+    if (error instanceof Error && error.message.includes('DOM Error while querying')) {
+      return { ok: false, code: 'invalid-css-selector', input };
+    }
+    throw error;
+  }
 
   if (nodeIds.length === 1) {
     const backendNodeId = await backendNodeIdFor(client, nodeIds[0]);

package/src/output/render.ts

@@ -56,6 +56,8 @@ export const RESULT_TAGS = [
   'tab-opened',
   'tab-closed',
   'tab-reset',
+  'browser-launched',
+  'browser-quit',
   'network',
   'cdp-result',
   'libs',

package/src/registry.ts

@@ -87,7 +87,7 @@ const ref = 'css:<selector> | backend:<id> | axid:<id> | ax:<name> | text:<text>
 
 export const CAPTURE_REGISTRY: RegistryBranch = branch('', 'Capture — browser evidence and automation over CDP.', [
   branch('session', 'persistent browser-work lifecycle and artifact bundles.', [
-    leaf('session start', 'start a fresh persistent capture session.', { flags: [requiredValue('--url', 'absolute-http(s)-url'), port()], effects: effects(true, true, true), constraints: 'Required singleton --url <absolute-http(s)-url>; optional singleton --port <1..65535>. No target, prefix, positional URL, or ambient CDP selection.', orderedOutput: 'Exact session ID; open lifecycle; full target ID; endpoint; observed URL; target_live=true; scope key; active generation.', artifactOwnership: 'Exclusively allocates the session directory and atomically publishes the canonical session record before its scoped pointer.' }),
+    leaf('session start', 'open or prepare a tab for a persistent capture session.', { flags: [value('--url', 'absolute-http(s)-url'), bool('--hold'), port()], effects: effects(true, true, true), constraints: 'Optional singleton --url <absolute-http(s)-url> opens a fresh tab through Target.createTarget; endpoints such as Electron that reject Target.createTarget cannot use --url. Optional singleton --hold retains a browser connection; optional singleton --port <1..65535> selects its endpoint. To work against an existing tab, omit --url, run `capture session start --hold --port <port>`, list it with `capture tab list --port <port>`, then run `capture page navigate <url> --target <target-id> --port <port>`; that navigate command adopts the target and later page commands auto-target it. No target, prefix, positional URL, or ambient CDP selection on session start.', orderedOutput: 'Exact session ID; open lifecycle; full target ID or null; endpoint or null; observed URL or null; target_live=true when a tab was opened; scope key; active generation.', artifactOwnership: 'Exclusively allocates the session directory and atomically publishes the canonical session record before its scoped pointer.' }),
     leaf('session stop', 'stop and bundle one exact capture session.', { positionals: [positional('session-id', 'exact-session-id')], effects: effects(true, true, true), constraints: 'One exact case-sensitive session ID; no prefixes. Only matching open/stopping/completed lifecycle records are accepted before bundle effects.', orderedOutput: 'Exact ID; stop-operation ID; stopped lifecycle; final bundle access; pointer outcome deleted|absent|superseded.', artifactOwnership: 'Resumes the recorded operation and owns bundle staging/publication; never rolls lifecycle back to open.', recovery: 'session_stop_state_invalid: inspect capture session view <exact-session-id> and preserve the session directory; never delete or allocate a new stop. session_stop_staging_cleanup_failed: correct access at the reported staging path and retry the identical capture session stop <exact-session-id>. session_stop_bundle_failed: correct the reported bundle/filesystem cause and retry that identical command. Both retries resume the recorded operation.' }),
     leaf('session list', 'list same-user host capture sessions.', { effects: effects(false, true), constraints: 'No target/session filters or ambient defaults.', orderedOutput: 'Rows sorted by exact session ID: ID, lifecycle, active_in_current_scope, full target ID or null, endpoint or null, target_live.' }),
     leaf('session view', 'view one exact capture session.', { positionals: [positional('session-id', 'exact-session-id')], effects: effects(false, true), constraints: 'One exact case-sensitive session ID; no prefix.' }),

package/src/session/commands.ts

@@ -8,6 +8,8 @@ import {
   validateHarFile,
   type HarFile,
   type HAREntry,
+  type Header,
+  type IncompleteLifecycle,
 } from '../har-manager.js';
 import {
   getActiveSession,
@@ -49,6 +51,7 @@ import {
 } 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';
 
 type Session = ActiveSessionState;
 
@@ -327,32 +330,40 @@ 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 opens a tab, records HAR, and bundles every artifact; while active, every command auto-targets its tab
+the artifact container — a session records HAR and bundles every artifact; it may open a tab or adopt one later; while active, every command auto-targets its tab
 use when starting scoped work against a page: start first, then every other capture command needs no --target/--port threading
   start · stop · list · view · har · log — \`capture session -h\`
 </command>`;
 
-const START_USAGE = `capture session start [--url <url>] [--hold] — open a tab, record HAR, and set the active capture context.
+const START_USAGE = `capture session start [--url <url>] [--hold] — open or prepare a tab, record HAR, and set the active capture context.
 
 input:
-  --url <url>    Absolute URL to open in a fresh tab. Omit to start a session
-                 with no tab (HAR-only until a later command targets one).
+  --url <url>    Absolute URL to open in a fresh tab through CDP's
+                 Target.createTarget. Some endpoints, including Electron,
+                 expose existing tabs but reject Target.createTarget; on those
+                 endpoints --url cannot be used.
   --hold         Hold one CDP browser connection open for the session's
                  lifetime, so browser-level state (permission grants,
                  ServiceWorker enablement) survives across separate commands.
-                 With no --url, later --target <existing-id> commands adopt
-                 an already-open tab without creating a new one.
+                 With no --url, start a held session and adopt an existing tab
+                 with this supported workflow:
+                   capture session start --hold --port <port>
+                   capture tab list --port <port>
+                   capture page navigate <url> --target <target-id> --port <port>
+                 The navigate command adopts that target for the session; later
+                 page commands then auto-target it.
   --port <n>     CDP port to attach to; default is auto-detected across localhost.
 
 Output:
   One <session id=… path=… [url=…]> block: the session id, bundle dir, opened
-  tab, HAR recording id, and held-bridge pid when applicable. --json mirrors
-  the same fields.
+  tab when --url succeeds, HAR recording id, and held-bridge pid when
+  applicable. --json mirrors the same fields.
 
 effects:
-  Creates a private session dir with shots/, starts a HAR recording, opens the
-  tab (with --url), optionally holds a CDP bridge, and registers the session as
-  the active capture context so subsequent commands auto-target it.`;
+  Creates a private session dir with shots/, starts a HAR recording, opens a
+  fresh tab only when --url is supplied, optionally holds a CDP bridge, and
+  registers the session as the active capture context so subsequent commands
+  auto-target it.`;
 
 const STOP_USAGE = `capture session stop <session-id> — finalize a session and write its bundle manifest.
 
@@ -400,30 +411,45 @@ Output:
 effects:
   None — reads bundle.json only.`;
 
+/** Default row bound for one `session har` read. A busy page produces
+ * thousands of records; an unbounded list buries the row the agent came for.
+ * `--limit` overrides it in either direction. */
+const DEFAULT_HAR_ROWS = 100;
+
 const HAR_USAGE = `capture session har [<session-id>] — read a session's recorded HTTP traffic as a selection list.
 
 input:
   <session-id>              session to read; defaults to the active session. A
                             running session reads its live accumulating HAR; a
                             stopped one reads the bundled har.json.
-  --filter-url <pattern>    substring or regex match on the request URL
+  --filter-url <pattern>    substring or regex match on the request URL (matched
+                            against the URL as captured, before redaction)
   --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
+                            (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>               first n matching entries
-  --full                    inline per-entry detail (headers, post data,
+  --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
 
 output:
-  One <session-har id=… path=… source=live|bundle entries=… total=…> block,
-  one row per entry: method, status, URL, body size, start time. The path
-  attribute is the HAR file's absolute path — the full-fidelity pointer.
-  --json mirrors the same fields. 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.
+  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
+  file's absolute path — the full-fidelity pointer, which holds every record
+  including the ones this list bounds away. --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
+  _resourceType "websocket" and their frames in _webSocketMessages (capped at
+  200 frames/socket, 4KB/frame); sockets opened before recording started are
+  not visible.
 
 effects:
   None — reads recorded HAR data only.`;
@@ -449,17 +475,17 @@ effects:
   the identity-bearing tailer record is registered in the session metadata.`;
 
 function printSessionHelp(): void {
-  console.log(`capture session — the artifact container: opens a tab, records HAR, bundles every artifact.
+  console.log(`capture session — the artifact container: records HAR and bundles artifacts; it may open a tab or adopt one later.
 
 An active session auto-targets its tab 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>] [--hold]" whenToUse="open a tab, start HAR, and set the active capture context"/>
+  <subcommand name="start" args="[--url <url>] [--hold]" whenToUse="open or prepare 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 — the live accumulating HAR of a running session or a stopped session's bundled har.json"/>
+  <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`);
@@ -618,7 +644,18 @@ async function start(parsed: ParsedArgs): Promise<void> {
       }
 
       if (url) {
-        target = await startWorld.openTab(cdpPort!, url);
+        try {
+          target = await startWorld.openTab(cdpPort!, url);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          if (message.toLowerCase().includes('not supported')) {
+            throw worldFailure(
+              `Target.createTarget is unsupported on port ${cdpPort}. Use existing tab: \`capture page navigate <url> --target <target-id> --port ${cdpPort}\` after \`capture session start --hold --port ${cdpPort}\` and \`capture tab list\`.`,
+              error,
+            );
+          }
+          throw error;
+        }
         const openedPort = cdpPort!;
         const openedTargetId = target.id;
         acquired.push({ label: 'opened target', release: () => startWorld.closeTarget(openedPort, openedTargetId) });
@@ -887,6 +924,89 @@ async function locateSessionHar(session: Session): Promise<HarSource | { unavail
   }
 }
 
+/**
+ * The `session har` selection population is BOTH of the HAR file's records:
+ * the completed entries under `log.entries` and the incomplete lifecycle
+ * records under `incompleteLifecycles`. A request whose lifecycle the recorder
+ * could not complete (the page was still in flight at session stop, or Chrome
+ * reported clocks out of order) is retained evidence, not lost traffic —
+ * rendering only `log.entries` hid it from every read, which is exactly when an
+ * agent is looking for the request that did not finish.
+ */
+type HarSelection = {
+  /** Original captured URL — what every filter matches against. */
+  url: string;
+  method: string;
+  /** Response status when one was observed; null when the record has no response. */
+  status: number | null;
+  startedDateTime: string;
+  /** Capture order, the deterministic tie-breaker for equal start times. */
+  order: number;
+} & (
+  | { kind: 'complete'; entry: HAREntry }
+  | { kind: 'incomplete'; record: IncompleteLifecycle }
+);
+
+/** The response an incomplete record observed before it was cut short, if any. */
+function incompleteResponse(record: IncompleteLifecycle): { status: number; headers: Header[] } | null {
+  switch (record.kind) {
+    case 'stopped_before_terminal':
+      return record._capture.response;
+    case 'invalid_clock_order':
+      return record.response;
+    case 'stopped_during_body':
+      return record.response;
+  }
+}
+
+/** The incomplete record's kind, qualified by the clock violation when it has one. */
+function incompleteLabel(record: IncompleteLifecycle): string {
+  return record.kind === 'invalid_clock_order' ? `${record.kind}/${record.violation}` : record.kind;
+}
+
+/**
+ * Merges completed entries and incomplete lifecycle records into one
+ * chronologically ordered population. Ordering is deterministic for a given
+ * HAR file: start time first, then capture order (entries before incomplete
+ * records at an identical timestamp).
+ */
+function buildHarSelection(har: HarFile): HarSelection[] {
+  const items: HarSelection[] = [];
+  for (const entry of har.log.entries) {
+    items.push({
+      kind: 'complete',
+      entry,
+      url: entry.request.url,
+      method: entry.request.method,
+      status: entry.response.status,
+      startedDateTime: entry.startedDateTime,
+      order: items.length,
+    });
+  }
+  for (const record of har.incompleteLifecycles) {
+    items.push({
+      kind: 'incomplete',
+      record,
+      url: record.request.url,
+      method: record.request.method,
+      status: incompleteResponse(record)?.status ?? null,
+      startedDateTime: record.startedDateTime,
+      order: items.length,
+    });
+  }
+  return items.sort((a, b) =>
+    a.startedDateTime === b.startedDateTime
+      ? a.order - b.order
+      : (a.startedDateTime < b.startedDateTime ? -1 : 1),
+  );
+}
+
+/** Every rendered URL passes through render-time credential redaction; the HAR
+ * artifact and the `--filter-url` match target keep the original value. */
+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 harEntryRow(e: HAREntry): FactLine {
@@ -896,13 +1016,27 @@ function harEntryRow(e: HAREntry): FactLine {
     : text`body not captured`;
   return line(
     fact`${e.request.method} ${e.response.status} `,
-    data(e.request.url, 300),
+    harUrl(e.request.url),
     text` — `,
     sizePart,
     fact` — started ${e.startedDateTime}`,
   );
 }
 
+/** 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(
+    fact`${record.request.method} ${response ? response.status : 'no-response'} `,
+    harUrl(record.request.url),
+    text` — `,
+    fact`incomplete: ${incompleteLabel(record)}`,
+    fact` — started ${record.startedDateTime}`,
+  );
+}
+
 /** `--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 {
@@ -925,6 +1059,33 @@ 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 {
+  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 (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 (record.kind === 'invalid_clock_order') {
+    rows.push(fact`   terminal: ${record.terminal.kind}`);
+    if (record.terminal.kind === 'failed') {
+      rows.push(fact`   error: ${record.terminal.errorText} (canceled=${String(record.terminal.canceled)})`);
+    }
+  } else {
+    rows.push(text`   terminal: never observed`);
+  }
+  return lineList(rows);
+}
+
 async function har(parsed: ParsedArgs): Promise<void> {
   if (parsed.help) {
     console.log(HAR_USAGE);
@@ -993,41 +1154,57 @@ async function har(parsed: ParsedArgs): Promise<void> {
     return;
   }
 
-  let entries = located.har.log.entries;
-  const total = entries.length;
+  let selection = buildHarSelection(located.har);
+  const total = located.har.log.entries.length;
+  const totalIncomplete = located.har.incompleteLifecycles.length;
   const filters: string[] = [];
 
+  // Every filter matches the ORIGINAL captured URL/method/status — redaction is
+  // applied at render time only, so a `--filter-url` pattern still selects on
+  // what the browser actually requested.
   if (parsed.filterUrl) {
     const pattern = parsed.filterUrl;
     let re: RegExp | null = null;
     try { re = new RegExp(pattern, 'i'); } catch { re = null; }
-    entries = entries.filter((e) =>
-      re ? re.test(e.request.url) : e.request.url.toLowerCase().includes(pattern.toLowerCase()),
+    selection = selection.filter((item) =>
+      re ? re.test(item.url) : item.url.toLowerCase().includes(pattern.toLowerCase()),
     );
     filters.push(`url~${pattern}`);
   }
   if (statusMatch) {
     const matches = statusMatch;
-    entries = entries.filter((e) => matches(e.response.status));
+    // A record with no observed response cannot satisfy a status filter.
+    selection = selection.filter((item) => item.status !== null && matches(item.status));
     filters.push(`status=${parsed.filterStatus}`);
   }
   if (parsed.filterMethod) {
     const m = parsed.filterMethod.toUpperCase();
-    entries = entries.filter((e) => e.request.method.toUpperCase() === m);
+    selection = selection.filter((item) => item.method.toUpperCase() === m);
     filters.push(`method=${m}`);
   }
-  if (typeof parsed.limit === 'number' && parsed.limit > 0) {
-    entries = entries.slice(0, parsed.limit);
-    filters.push(`limit=${parsed.limit}`);
-  }
 
-  const summary = filters.length > 0
-    ? fact`${entries.length} of ${total} entries match (${filters.join(', ')}).`
-    : fact`${total} entries.`;
+  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;
+  const matched = selection.length;
+  const shown = selection.slice(0, bound);
+  const truncated = matched > shown.length;
+
+  const shownEntries = shown.filter((item) => item.kind === 'complete').length;
+  const shownIncomplete = shown.length - shownEntries;
+
+  const filterNote = filters.length > 0 ? ` (${filters.join(', ')})` : '';
+  const truncationNote = truncated
+    ? ` ${matched - shown.length} further matching rows are not listed — raise the bound with --limit.`
+    : '';
+  const summary = fact`${shownEntries} of ${total} complete entries and ${shownIncomplete} of ${totalIncomplete} incomplete lifecycle records listed${filterNote}.${truncationNote}`;
 
   const sections = parsed.full
-    ? entries.map((e, i) => harEntryDetail(e, i))
-    : [lineList(entries.map((e, i) => line(fact`${i + 1}. `, harEntryRow(e))))];
+    ? shown.map((item, i) => (item.kind === 'complete' ? harEntryDetail(item.entry, i) : harIncompleteDetail(item.record, i)))
+    : [lineList(shown.map((item, i) => line(
+      fact`${i + 1}. `,
+      item.kind === 'complete' ? harEntryRow(item.entry) : harIncompleteRow(item.record),
+    )))];
 
   emitResult({
     tag: 'session-har',
@@ -1035,8 +1212,11 @@ async function har(parsed: ParsedArgs): Promise<void> {
       id,
       path: located.path,
       source: located.source,
-      entries: entries.length,
+      entries: shownEntries,
+      incomplete: shownIncomplete,
       total,
+      'total-incomplete': totalIncomplete,
+      truncated: truncated ? true : undefined,
     },
     summary,
     sections,