@crouton-kit/capture 1.3.17 → 1.3.18

package/bin/capture

@@ -7093,6 +7093,9 @@ var init_artifacts = __esm({
 function activeScopeKey() {
   return process.env.CRTR_NODE_ID ?? "default";
 }
+function activeSessionScopeKey() {
+  return activeScopeKey();
+}
 function getActivePath() {
   return path2.join(CAPTURE_ROOT, `.active-${activeScopeKey()}`);
 }
@@ -8379,6 +8382,32 @@ var init_a11y = __esm({
 });
 
 // src/cdp/record.ts
+function isMissingDefaultExecutionContext(err) {
+  return err instanceof Error && err.message === "Cannot find default execution context";
+}
+async function readReadyStateWithRetry(client, timeout) {
+  const deadline = Date.now() + timeout;
+  let lastRetryableError;
+  while (true) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      if (lastRetryableError) throw lastRetryableError;
+      throw new Error("Runtime.evaluate deadline exceeded");
+    }
+    try {
+      const result = await client.send("Runtime.evaluate", {
+        expression: "document.readyState",
+        returnByValue: true
+      }, remaining);
+      return result?.result?.value;
+    } catch (err) {
+      const remainingAfterAttempt = deadline - Date.now();
+      if (!isMissingDefaultExecutionContext(err) || remainingAfterAttempt <= 0) throw err;
+      lastRetryableError = err;
+      await new Promise((resolve11) => setTimeout(resolve11, Math.min(50, remainingAfterAttempt)));
+    }
+  }
+}
 async function navigateAndWait(port, url, options = {}) {
   const timeout = options.timeout ?? 1e4;
   if (!options.forceNew) {
@@ -8412,11 +8441,7 @@ async function navigateAndWait(port, url, options = {}) {
       }, timeout);
     });
     try {
-      const result = await client.send("Runtime.evaluate", {
-        expression: "document.readyState",
-        returnByValue: true
-      });
-      const readyState = result?.result?.value;
+      const readyState = await readReadyStateWithRetry(client, timeout);
       if (readyState !== "complete") {
         await loadPromise;
         if (loadTimeoutError) throw loadTimeoutError;
@@ -9842,7 +9867,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.3.17";
+  const version = "1.3.18";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -11601,7 +11626,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.3.17";
+  const version = "1.3.18";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -13825,25 +13850,30 @@ function collectRecs(dir) {
 function sessionMetaPath2(id) {
   return path12.join(sessionDir(id), ".session.json");
 }
+function tryReadSession(id) {
+  const metaPath2 = sessionMetaPath2(id);
+  const bad = (reason) => ({ ok: false, id, metaPath: metaPath2, reason });
+  let parsed;
+  try {
+    parsed = JSON.parse(readPrivateFile(metaPath2).toString("utf-8"));
+  } catch (error) {
+    if (error.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 };
+}
 function readSession(id) {
   const metaPath2 = sessionMetaPath2(id);
-  let raw;
+  let read;
   try {
-    raw = readPrivateFile(metaPath2).toString("utf-8");
+    read = tryReadSession(id);
   } catch (error) {
     if (error.code === "ENOENT") throw captureError("precondition", "unknown_session", `No capture session found: ${id}`);
     throw error;
   }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (cause) {
-    throw captureError("artifact", "invalid_session_record", `session metadata at ${metaPath2} 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 ${metaPath2} 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 ${metaPath2} ${read.reason}.`);
+  return read.session;
 }
 function generateId() {
   return `cap-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
@@ -13907,9 +13937,9 @@ async function start(parsed) {
     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;
@@ -14433,12 +14463,21 @@ function list(parsed) {
     return;
   }
   if (rejectSurplusPositionals(parsed, "list", 0, "capture session list")) return;
-  const sessions = fs9.existsSync(CAPTURE_ROOT) ? fs9.readdirSync(CAPTURE_ROOT).filter((d) => fs9.existsSync(sessionMetaPath2(d))).map((d) => {
-    const session = readSession(d);
-    const hasBundled = fs9.existsSync(path12.join(session.dir, "bundle.json"));
-    return { id: session.sessionId, startedAt: session.startedAt ?? "", url: session.url ?? null, status: hasBundled ? "stopped" : "active" };
+  const reads = fs9.existsSync(CAPTURE_ROOT) ? fs9.readdirSync(CAPTURE_ROOT).filter((d) => fs9.existsSync(sessionMetaPath2(d))).flatMap((d) => {
+    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 = fs9.existsSync(path12.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 },
@@ -14452,10 +14491,14 @@ function list(parsed) {
       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 });
 }
 function sectionRows(manifest, key) {
@@ -14665,8 +14708,11 @@ input:
   (none)
 
 output:
-  One <sessions count=\u2026> block, one row per session: id, status
+  One <sessions count=\u2026 unreadable=\u2026> 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> \u2014 unreadable \u2014 <path> \u2014 <reason>" row and is excluded from count;
+  one bad record never hides the others.
 
 effects:
   None \u2014 reads session metadata only.`;
@@ -228435,11 +228481,11 @@ async function runBrowserScope(method, params, parsed, timeoutMs, deps7 = DEFAUL
       const attached = await client.send("Target.attachToTarget", {
         targetId: tab.id,
         flatten: true
-      });
+      }, timeoutMs);
       sessionId = attached.sessionId;
     }
     const eventPromise = parsed.waitEvent ? waitForEventOnce(client, parsed.waitEvent, timeoutMs) : void 0;
-    const result = method ? await client.send(method, params ?? {}, 6e4, sessionId) : void 0;
+    const result = method ? await client.send(method, params ?? {}, timeoutMs, sessionId) : void 0;
     const event = eventPromise ? await eventPromise : void 0;
     emitCdpResult({
       method,
@@ -228476,7 +228522,7 @@ async function runPageScope(method, params, parsed, timeoutMs, connect = connect
       }
     } else {
       const eventPromise = parsed.waitEvent ? waitForEventOnce(client, parsed.waitEvent, timeoutMs) : void 0;
-      result = method ? await client.send(method, params ?? {}) : void 0;
+      result = method ? await client.send(method, params ?? {}, timeoutMs) : void 0;
       event = eventPromise ? await eventPromise : void 0;
     }
     emitCdpResult({
@@ -228532,7 +228578,7 @@ Input:
   --browser                    route through the held connection (session start --hold) instead of a one-shot page websocket. Connection-scoped state (permission grants, domain enables) reverts the instant its connection closes \u2014 it survives across commands only inside a held session.
   --port <port>                CDP endpoint. An explicit flag selects that endpoint even when an active session holds another browser connection.
   --target <id>                with --browser: attach a flattened CDP session on the held connection to this target (for target-scoped domains), including an already-open tab adopted by \`session start --hold\` without --url; without --browser: the page target to run against. 8-char id prefix accepted.
-  --timeout <ms>               event-wait timeout (default ${DEFAULT_TIMEOUT_MS}ms).
+  --timeout <ms>               one-shot method-response and event-wait timeout (default ${DEFAULT_TIMEOUT_MS}ms). WebSocket connection setup is separately bounded to 5000ms.
 
 Output:
   <cdp-result method=\u2026 wait-event=\u2026 scope=\u2026> \u2014 the protocol result and/or awaited event as an escaped, length-capped JSON payload. --json mirrors the same block with the payload at full fidelity.
@@ -241172,7 +241218,7 @@ CDP_PORT / CDP_TARGET pin the browser + tab for orchestrators \u2014 precedence:
 explicit flag > active session > env.`;
 }
 function printVersion() {
-  const declared = "1.3.17";
+  const declared = "1.3.18";
   if (declared) {
     console.log(declared);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.3.17",
+  "version": "1.3.18",
   "description": "Browser automation and UI validation via CDP — session-based screenshots, HAR, a11y, click/type, and JS exec",
   "bin": {
     "capture": "./bin/capture"

package/src/cdp/commands/cdp.ts

@@ -58,7 +58,7 @@ Input:
   --browser                    route through the held connection (session start --hold) instead of a one-shot page websocket. Connection-scoped state (permission grants, domain enables) reverts the instant its connection closes — it survives across commands only inside a held session.
   --port <port>                CDP endpoint. An explicit flag selects that endpoint even when an active session holds another browser connection.
   --target <id>                with --browser: attach a flattened CDP session on the held connection to this target (for target-scoped domains), including an already-open tab adopted by \`session start --hold\` without --url; without --browser: the page target to run against. 8-char id prefix accepted.
-  --timeout <ms>               event-wait timeout (default ${DEFAULT_TIMEOUT_MS}ms).
+  --timeout <ms>               one-shot method-response and event-wait timeout (default ${DEFAULT_TIMEOUT_MS}ms). WebSocket connection setup is separately bounded to 5000ms.
 
 Output:
   <cdp-result method=… wait-event=… scope=…> — the protocol result and/or awaited event as an escaped, length-capped JSON payload. --json mirrors the same block with the payload at full fidelity.
@@ -73,7 +73,7 @@ Effects:
  * command wiring against a stub without a live browser.
  */
 export interface CdpScopeClient {
-  send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+  send(method: string, params?: Record<string, unknown>, timeout?: number): Promise<unknown>;
   on(event: string, handler: (params: unknown) => void): void;
   close(): void;
 }
@@ -279,11 +279,11 @@ export async function runBrowserScope(
       const attached = (await client.send('Target.attachToTarget', {
         targetId: tab.id,
         flatten: true,
-      })) as { sessionId: string };
+      }, timeoutMs)) as { sessionId: string };
       sessionId = attached.sessionId;
     }
     const eventPromise = parsed.waitEvent ? waitForEventOnce(client, parsed.waitEvent, timeoutMs) : undefined;
-    const result = method ? await client.send(method, params ?? {}, 60000, sessionId) : undefined;
+    const result = method ? await client.send(method, params ?? {}, timeoutMs, sessionId) : undefined;
     const event = eventPromise ? await eventPromise : undefined;
     emitCdpResult({
       method,
@@ -349,7 +349,7 @@ export async function runPageScope(
       }
     } else {
       const eventPromise = parsed.waitEvent ? waitForEventOnce(client, parsed.waitEvent, timeoutMs) : undefined;
-      result = method ? await client.send(method, params ?? {}) : undefined;
+      result = method ? await client.send(method, params ?? {}, timeoutMs) : undefined;
       event = eventPromise ? await eventPromise : undefined;
     }
     emitCdpResult({

package/src/cdp/record.ts

@@ -11,6 +11,42 @@ import { type CDPTarget } from './types.js';
  * load-wait helper. Navigation of an existing tab lives in
  * `./commands/page/navigate.ts` via ordinary page targeting.
  */
+function isMissingDefaultExecutionContext(err: unknown): boolean {
+  return err instanceof Error && err.message === 'Cannot find default execution context';
+}
+
+/**
+ * Arc can report the page load before it has installed the default execution
+ * context (notably for hash-routed Gmail URLs). Retry only that known transient
+ * CDP error; every other Runtime.evaluate failure remains fatal.
+ */
+export async function readReadyStateWithRetry(
+  client: Pick<CDPClient, 'send'>,
+  timeout: number,
+): Promise<unknown> {
+  const deadline = Date.now() + timeout;
+  let lastRetryableError: unknown;
+  while (true) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      if (lastRetryableError) throw lastRetryableError;
+      throw new Error('Runtime.evaluate deadline exceeded');
+    }
+    try {
+      const result = await client.send('Runtime.evaluate', {
+        expression: 'document.readyState',
+        returnByValue: true,
+      }, remaining);
+      return (result as { result?: { value?: unknown } } | undefined)?.result?.value;
+    } catch (err) {
+      const remainingAfterAttempt = deadline - Date.now();
+      if (!isMissingDefaultExecutionContext(err) || remainingAfterAttempt <= 0) throw err;
+      lastRetryableError = err;
+      await new Promise<void>((resolve) => setTimeout(resolve, Math.min(50, remainingAfterAttempt)));
+    }
+  }
+}
+
 export async function navigateAndWait(
   port: number,
   url: string,
@@ -59,11 +95,7 @@ export async function navigateAndWait(
     });
 
     try {
-      const result = await client.send('Runtime.evaluate', {
-        expression: 'document.readyState',
-        returnByValue: true,
-      });
-      const readyState = (result as { result?: { value?: unknown } } | undefined)?.result?.value;
+      const readyState = await readReadyStateWithRetry(client, timeout);
       if (readyState !== 'complete') {
         await loadPromise;
         if (loadTimeoutError) throw loadTimeoutError;

package/src/session/commands.ts

@@ -11,6 +11,7 @@ import {
 } from '../har-manager.js';
 import {
   getActiveSession,
+  activeSessionScopeKey,
   setActiveSession,
   clearActiveSessionIf,
   updateSessionState,
@@ -235,10 +236,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 +275,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 {
@@ -354,8 +375,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.`;
@@ -557,9 +581,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;
@@ -1212,17 +1236,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 +1268,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 });
 }