@crouton-kit/capture 1.3.17 → 1.3.19

package/src/session/commands.ts

@@ -8,9 +8,12 @@ import {
   validateHarFile,
   type HarFile,
   type HAREntry,
+  type Header,
+  type IncompleteLifecycle,
 } from '../har-manager.js';
 import {
   getActiveSession,
+  activeSessionScopeKey,
   setActiveSession,
   clearActiveSessionIf,
   updateSessionState,
@@ -48,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;
 
@@ -235,10 +239,38 @@ function sessionMetaPath(id: string): string {
   return path.join(sessionDir(id), '.session.json');
 }
 
+/** Outcome of reading one persisted record without failing the caller: either
+ * the validated session or the short reason its `.session.json` is unreadable. */
+type SessionRead =
+  | { ok: true; session: Session }
+  | { ok: false; id: string; metaPath: string; reason: string };
+
+/**
+ * Reads one record without throwing. A listing is what an agent reaches for
+ * precisely when it is working out what state it is in, so one corrupt or
+ * legacy-schema record on a shared capture root must not make every other
+ * session invisible — `list` renders the reason as its own unreadable row.
+ * A missing file is not a read outcome here; only `readSession` (targeted
+ * commands) turns that into `unknown_session`.
+ */
+function tryReadSession(id: string): SessionRead {
+  const metaPath = sessionMetaPath(id);
+  const bad = (reason: string): SessionRead => ({ ok: false, id, metaPath, reason });
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readPrivateFile(metaPath).toString('utf-8'));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') throw error;
+    return bad('not valid JSON; the record is corrupt');
+  }
+  if (!isActiveStateCandidate(parsed)) return bad('does not match the session record schema; written by an incompatible version or corrupted');
+  return { ok: true, session: parsed };
+}
+
 /**
- * Reads and VALIDATES one persisted `.session.json`. A missing file throws a
- * typed `unknown_session` precondition error (leaf catch-alls emit it as
- * `unknown_session`); unparsable bytes or a record failing the shared
+ * Reads and VALIDATES one persisted `.session.json` for a command that named
+ * this session. A missing file throws a typed `unknown_session` precondition
+ * error; unparsable bytes or a record failing the shared
  * `isActiveStateCandidate` schema throw a typed `invalid_session_record`
  * artifact error instead of letting a structurally-trusted cast reach the
  * renderer (where a legacy-schema record used to crash `session list`
@@ -246,23 +278,15 @@ function sessionMetaPath(id: string): string {
  */
 function readSession(id: string): Session {
   const metaPath = sessionMetaPath(id);
-  let raw: string;
+  let read: SessionRead;
   try {
-    raw = readPrivateFile(metaPath).toString('utf-8');
+    read = tryReadSession(id);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') throw captureError('precondition', 'unknown_session', `No capture session found: ${id}`);
     throw error;
   }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (cause) {
-    throw captureError('artifact', 'invalid_session_record', `session metadata at ${metaPath} is not valid JSON; the record is corrupt and cannot be read as a capture session.`, cause);
-  }
-  if (!isActiveStateCandidate(parsed)) {
-    throw captureError('artifact', 'invalid_session_record', `session metadata at ${metaPath} does not match the capture session record schema; it was written by an incompatible version or corrupted.`);
-  }
-  return parsed;
+  if (!read.ok) throw captureError('artifact', 'invalid_session_record', `session metadata at ${metaPath} ${read.reason}.`);
+  return read.session;
 }
 
 function generateId(): string {
@@ -306,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.
 
@@ -354,8 +386,11 @@ input:
   (none)
 
 output:
-  One <sessions count=…> block, one row per session: id, status
+  One <sessions count=… unreadable=…> block, one row per session: id, status
   (active|stopped), start time, and URL when set. --json mirrors the same rows.
+  A record that is corrupt or written by an incompatible version lists as its
+  own "<id> — unreadable — <path> — <reason>" row and is excluded from count;
+  one bad record never hides the others.
 
 effects:
   None — reads session metadata only.`;
@@ -376,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.`;
@@ -425,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`);
@@ -557,9 +607,9 @@ async function start(parsed: ParsedArgs): Promise<void> {
     if (active && !isSessionStopped(active)) {
       emitResult({
         tag: 'error',
-        attrs: { command: 'session start', code: 'start_failed' },
-        summary: fact`A session is already active for this scope (${active.sessionId}); stop it first with \`session stop ${active.sessionId}\`.`,
-        followUp: text`Only one live session is allowed per capture scope at a time.`,
+        attrs: { command: 'session start', code: 'session_already_active' },
+        summary: fact`Session ${active.sessionId} is already live in this capture scope (${activeSessionScopeKey()}); one live session per scope.`,
+        followUp: fact`Scopes are per-agent (CRTR_NODE_ID), so this session is yours — a concurrent agent's session never blocks yours. Keep using it (every command auto-targets its tab), or run \`capture session stop ${active.sessionId}\` to start fresh. To drive a different tab without ending it, pass \`--target <target-id>\` from \`capture tab list\`.`,
       }, { json: parsed.json });
       process.exitCode = 1;
       return;
@@ -594,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) });
@@ -863,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 {
@@ -872,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 {
@@ -901,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);
@@ -969,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',
@@ -1011,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,
@@ -1212,17 +1416,24 @@ function list(parsed: ParsedArgs): void {
 
   if (rejectSurplusPositionals(parsed, 'list', 0, 'capture session list')) return;
 
-  const sessions = fs.existsSync(CAPTURE_ROOT)
+  const reads = fs.existsSync(CAPTURE_ROOT)
     ? fs.readdirSync(CAPTURE_ROOT)
         .filter((d) => fs.existsSync(sessionMetaPath(d)))
-        .map((d) => {
-          const session = readSession(d);
-          const hasBundled = fs.existsSync(path.join(session.dir, 'bundle.json'));
-          return { id: session.sessionId, startedAt: session.startedAt ?? '', url: session.url ?? null, status: hasBundled ? 'stopped' : 'active' };
+        .flatMap((d) => {
+          // A record deleted between readdir and read is simply gone, not unreadable.
+          try { return [tryReadSession(d)]; } catch { return []; }
         })
     : [];
 
-  if (sessions.length === 0) {
+  const sessions = reads.flatMap((read) => {
+    if (!read.ok) return [];
+    const session = read.session;
+    const hasBundled = fs.existsSync(path.join(session.dir, 'bundle.json'));
+    return [{ id: session.sessionId, startedAt: session.startedAt ?? '', url: session.url ?? null, status: hasBundled ? 'stopped' : 'active' }];
+  });
+  const unreadable = reads.flatMap((read) => (read.ok ? [] : [read]));
+
+  if (reads.length === 0) {
     emitResult({
       tag: 'sessions',
       attrs: { count: 0 },
@@ -1237,11 +1448,17 @@ function list(parsed: ParsedArgs): void {
       s.url ? fact` — ${s.url}` : text``,
     ),
   );
+  const unreadableRows = unreadable.map((u) =>
+    line(fact`${u.id} — unreadable — ${u.metaPath} — ${u.reason}`),
+  );
 
   emitResult({
     tag: 'sessions',
-    attrs: { count: sessions.length },
-    sections: [lineList(rows)],
+    attrs: { count: sessions.length, unreadable: unreadable.length },
+    sections: [lineList([...rows, ...unreadableRows])],
+    ...(unreadable.length > 0
+      ? { followUp: text`Unreadable records are corrupt or written by an incompatible version; they are inert. Delete the named .session.json (or its session dir) to drop the row.` }
+      : {}),
   }, { json: parsed.json });
 }