@crouton-kit/capture 1.4.26 → 1.4.28

package/bin/capture

@@ -5654,8 +5654,12 @@ function forgetRecordFile(file) {
   }
 }
 function stillOurs(record5) {
+  return processOwnership(record5) === "ours";
+}
+function processOwnership(record5) {
   const observed = processPidBirthProvider.read(record5.pid);
-  return observed.status === "found" && sameBirth(observed.identity, record5.birth);
+  if (observed.status === "unknown") return "unknown";
+  return observed.status === "found" && sameBirth(observed.identity, record5.birth) ? "ours" : "gone";
 }
 function removeProfile(profileDir) {
   fs2.rmSync(assertUnderCaptureRoot(profileDir), { recursive: true, force: true });
@@ -5677,26 +5681,33 @@ async function reap(record5) {
   forgetRecordFile(recordPath(record5.token));
   removeProfile(record5.profileDir);
 }
-async function endpointAnswers(port) {
+async function probeEndpoint(port) {
   try {
     const response = await fetch(`http://${CDP_LOOPBACK_HOST}:${port}/json/version`, {
       signal: AbortSignal.timeout(ENDPOINT_PROBE_MS)
     });
-    return response.ok;
-  } catch {
-    return false;
+    return response.ok ? "up" : "down";
+  } catch (error4) {
+    const code = error4.cause?.code;
+    return code === "ECONNREFUSED" ? "down" : "unknown";
   }
 }
+async function endpointAnswers(port) {
+  return await probeEndpoint(port) === "up";
+}
 async function sweepOwnedBrowsers() {
   const reaped = [];
   for (const record5 of readOwnedBrowsers()) {
-    if (!stillOurs(record5)) {
+    const ownership2 = processOwnership(record5);
+    if (ownership2 === "unknown") continue;
+    if (ownership2 === "gone") {
       forgetRecordFile(recordPath(record5.token));
       removeProfile(record5.profileDir);
       reaped.push({ port: record5.port, pid: record5.pid, reason: "exited" });
       continue;
     }
-    if (record5.port === null || !await endpointAnswers(record5.port)) {
+    if (record5.port === null && Date.now() - Date.parse(record5.startedAt) <= READY_TIMEOUT_MS + ENDPOINT_PROBE_MS) continue;
+    if (record5.port === null || await probeEndpoint(record5.port) === "down") {
       await reap(record5);
       reaped.push({ port: record5.port, pid: record5.pid, reason: "unreachable" });
       continue;
@@ -5930,7 +5941,7 @@ __export(targets_exports, {
   scoreTabUrlMatch: () => scoreTabUrlMatch
 });
 async function getBrowserClient(port) {
-  const versionResp = await fetch(`http://${CDP_LOOPBACK_HOST}:${port}/json/version`);
+  const versionResp = await fetch(`http://${CDP_LOOPBACK_HOST}:${port}/json/version`, { signal: AbortSignal.timeout(BROWSER_PROBE_TIMEOUT_MS) });
   if (!versionResp.ok) {
     throw new Error(
       `Failed to connect to CDP on port ${port}: ${versionResp.status}`
@@ -5952,8 +5963,8 @@ async function getBrowserClient(port) {
 async function listTargets(port) {
   const { client } = await getBrowserClient(port);
   try {
-    await client.send("Target.setDiscoverTargets", { discover: true });
-    const result = await client.send("Target.getTargets");
+    await client.send("Target.setDiscoverTargets", { discover: true }, BROWSER_PROBE_TIMEOUT_MS);
+    const result = await client.send("Target.getTargets", {}, BROWSER_PROBE_TIMEOUT_MS);
     return result.targetInfos.map((t) => ({
       id: t.targetId,
       title: t.title,
@@ -5991,25 +6002,40 @@ async function findTabById(port, targetId) {
   }
   return null;
 }
+function unlistedTargetError(query, failures) {
+  const detail = failures.map(({ port, error: error4 }) => `port ${port}: ${error4 instanceof Error ? error4.message : String(error4)}`).join("; ");
+  return captureError(
+    "precondition",
+    "target_unavailable",
+    `No tab found for "${query}", and ${failures.length} endpoint(s) could not list their tabs (${detail}). Run "capture tab list" to see which endpoints answer.`,
+    failures[0]?.error
+  );
+}
 async function findTabByIdInPorts(targetId, ports, finder = findTabById) {
+  const failures = [];
   for (const port of ports) {
     try {
       const tab = await finder(port, targetId);
       if (tab) return { port, tab };
-    } catch {
+    } catch (error4) {
+      failures.push({ port, error: error4 });
     }
   }
+  if (failures.length > 0) throw unlistedTargetError(targetId, failures);
   return null;
 }
 async function findUnambiguousPageTabInPorts(ports, lister = listTargets) {
   const candidates = [];
+  const failures = [];
   for (const port of ports) {
     try {
       for (const tab of await lister(port)) if (tab.type === "page") candidates.push({ port, tab });
-    } catch {
+    } catch (error4) {
+      failures.push({ port, error: error4 });
     }
   }
   if (candidates.length > 1) throw new AmbiguousPageTargetError(candidates);
+  if (candidates.length === 0 && failures.length > 0) throw unlistedTargetError("(any page tab)", failures);
   return candidates[0] ?? null;
 }
 function normalizeUrlForMatch(value) {
@@ -6076,6 +6102,7 @@ async function findResponsivePageTabByUrl(port, url) {
 async function findTabByUrlAcrossEndpoints(url, preferredPort) {
   const ports = resolveSearchPorts(await detectCdpPortsAsync(), preferredPort);
   let best = null;
+  const failures = [];
   for (const port of ports) {
     try {
       const targets = await listTargets(port);
@@ -6086,10 +6113,13 @@ async function findTabByUrlAcrossEndpoints(url, preferredPort) {
           best = { port, tab, score };
         }
       }
-    } catch {
+    } catch (error4) {
+      failures.push({ port, error: error4 });
     }
   }
-  return best ? { port: best.port, tab: best.tab } : null;
+  if (best) return { port: best.port, tab: best.tab };
+  if (failures.length > 0) throw unlistedTargetError(url, failures);
+  return null;
 }
 function requireTargetId(targetId, url) {
   if (!targetId) {
@@ -6129,13 +6159,15 @@ async function openTab(port, url) {
     client.close();
   }
 }
-var AmbiguousPageTargetError;
+var BROWSER_PROBE_TIMEOUT_MS, AmbiguousPageTargetError;
 var init_targets = __esm({
   "src/cdp/targets.ts"() {
     init_client();
     init_loopback();
     init_detect();
     init_browser_process();
+    init_errors();
+    BROWSER_PROBE_TIMEOUT_MS = 1e4;
     AmbiguousPageTargetError = class extends Error {
       constructor(candidates) {
         super(`More than one page tab is available:
@@ -8671,7 +8703,7 @@ async function captureScreenshotWithCssViewport(client, viewport2, options) {
 }
 async function viewportScopedCapture(client, viewport2, options, includeCssViewport = false) {
   const MAX_DIM = 1600;
-  const SCREENSHOT_REQUEST_TIMEOUT_MS = 3e4;
+  const SCREENSHOT_REQUEST_TIMEOUT_MS = options?.requestTimeoutMs ?? 3e4;
   let ownsDeviceMetricsOverride = false;
   let primaryFailed = false;
   let primaryError;
@@ -9031,7 +9063,10 @@ async function navigateAndWait(port, url, options = {}) {
   }
   const targets = await listTargets(port);
   const refreshed = targets.find((t) => t.id === tab.id);
-  return refreshed ?? tab;
+  if (!refreshed) {
+    throw new Error(`the browser accepted the new tab ${tab.id} but no longer lists it \u2014 it dropped the tab. Open it again.`);
+  }
+  return refreshed;
 }
 var init_record = __esm({
   "src/cdp/record.ts"() {
@@ -10945,7 +10980,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.4.26";
+  const version = "1.4.28";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -13047,7 +13082,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.4.26";
+  const version = "1.4.28";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -16777,6 +16812,24 @@ async function applyActiveSessionNetworkConditions(client, session, targetId) {
     uploadThroughput: offline ? 0 : -1
   });
 }
+function setupDeadlineMs(parsed) {
+  return parsed.timeoutMs ?? DEFAULT_SETUP_DEADLINE_MS;
+}
+async function withinDeadline(ms, phase, work) {
+  let timer;
+  const expired = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(captureError(
+      "world",
+      "command_deadline_exceeded",
+      `${phase} did not finish within ${ms}ms \u2014 the tab is not answering CDP (its main thread may be blocked, or the tab throttled). Raise --timeout to wait longer.`
+    )), ms);
+  });
+  try {
+    return await Promise.race([work, expired]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
 function deriveActionLabel(parsed) {
   if (parsed.command === "type") {
     return `type:${parsed.into ?? "focused element"}`;
@@ -16864,7 +16917,7 @@ async function connectForCommand(parsed) {
   const client = seams.createClient(tab.webSocketDebuggerUrl);
   try {
     await client.waitReady();
-    await applyActiveSessionNetworkConditions(client, seams.getActiveSession(), tab.id);
+    await withinDeadline(setupDeadlineMs(parsed), "Restoring the session network state", applyActiveSessionNetworkConditions(client, seams.getActiveSession(), tab.id));
     return { client, tab };
   } catch (err) {
     client.close();
@@ -16916,8 +16969,8 @@ function finishConsole(collectors) {
 }
 async function withConnection(parsed, fn, opts = {}) {
   const { client, tab } = await connectForCommand(parsed);
-  const collectors = await startCollectors(parsed, client);
   try {
+    const collectors = await withinDeadline(setupDeadlineMs(parsed), "Starting page collectors", startCollectors(parsed, client));
     const result = await fn(client, tab);
     if (collectors.harRecorder && parsed.har) {
       const settle = opts.settle !== void 0 ? opts.settle : 3e3;
@@ -16934,8 +16987,8 @@ async function withConnection(parsed, fn, opts = {}) {
 }
 async function withPageAction(parsed, opts, fn) {
   const { client, tab } = await connectForCommand(parsed);
-  const collectors = await startCollectors(parsed, client);
   try {
+    const collectors = await withinDeadline(setupDeadlineMs(parsed), "Starting page collectors", startCollectors(parsed, client));
     const result = await fn(client, tab);
     const requestedMs = opts.settleMs;
     const t0 = seams.now();
@@ -16963,7 +17016,7 @@ async function withPageAction(parsed, opts, fn) {
     client.close();
   }
 }
-var fs14, import_node_perf_hooks2, seams;
+var fs14, import_node_perf_hooks2, seams, DEFAULT_SETUP_DEADLINE_MS;
 var init_connection = __esm({
   "src/cdp/connection.ts"() {
     fs14 = __toESM(require("fs"));
@@ -16990,6 +17043,7 @@ var init_connection = __esm({
       now: () => import_node_perf_hooks2.performance.now(),
       sleep: (ms) => new Promise((r) => setTimeout(r, ms))
     };
+    DEFAULT_SETUP_DEADLINE_MS = 3e4;
   }
 });
 
@@ -229200,7 +229254,7 @@ async function focusScopedEvaluate(client, expression, evaluationTimeoutMs) {
   let primaryError;
   try {
     ownsFocusOverride = true;
-    await client.send("Emulation.setFocusEmulationEnabled", { enabled: true });
+    await client.send("Emulation.setFocusEmulationEnabled", { enabled: true }, evaluationTimeoutMs);
     try {
       return await client.send("Runtime.evaluate", {
         expression,
@@ -229224,7 +229278,7 @@ async function focusScopedEvaluate(client, expression, evaluationTimeoutMs) {
   } finally {
     if (ownsFocusOverride) {
       try {
-        await client.send("Emulation.setFocusEmulationEnabled", { enabled: false });
+        await client.send("Emulation.setFocusEmulationEnabled", { enabled: false }, evaluationTimeoutMs);
       } catch (error4) {
         const cleanupError = captureError(
           "cleanup",
@@ -229706,6 +229760,7 @@ async function cmdPageShot(parsed, _args) {
         fullPage: parsed.fullPage,
         crop: requestedCrop,
         zoom,
+        requestTimeoutMs: parsed.timeoutMs,
         ...colorScheme ? { beforeCapture: () => finishColorTransitions(client) } : {}
       });
       const outPath = await resolveOutPath(parsed);
@@ -229746,6 +229801,7 @@ input:
   --out <path>      caller-owned destination PNG; default: the active session's shots/ sequence, or a fresh one-shot bundle when no session is active
   --artifact-dir <path>  root for that sessionless one-shot bundle (ignored with --out or an active session)
   --target <tabId> | --url <pattern> | --port <n>   tab targeting; defaults to the active session tab
+  --timeout <ms>    deadline for connecting to the tab and for each screenshot request (default: 30000 for connecting and each screenshot request); a tab that does not answer in time fails with command_deadline_exceeded or a CDP request timeout instead of waiting
   --json            mirror the result as JSON
 output:
   <screenshot path=\u2026 width=\u2026 height=\u2026 css-width=\u2026 css-height=\u2026 css-x=\u2026 css-y=\u2026 css-to-image-x=\u2026 css-to-image-y=\u2026 effective-downscale-x=\u2026 effective-downscale-y=\u2026 scroll-x=\u2026 scroll-y=\u2026 emulation=none|viewport|full-page color-scheme=dark|light> \u2014 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, visual-viewport scroll offset at capture, any effective downscale below 1 image px/CSS px, byte size, crop provenance, and any requested transient emulation
@@ -230361,7 +230417,7 @@ function buildBrowserLaunchedResult(browser, swept) {
       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.`);
+  if (swept > 0) sections.push(fact`swept ${swept} previously-launched browser(s) that had exited, refused CDP connections, or gone idle.`);
   return {
     tag: "browser-launched",
     attrs: { port: browser.port, pid: browser.pid, headless: browser.headless },
@@ -230409,7 +230465,7 @@ input:
   --headed        run with a visible window instead of headless
 
 output: <browser-launched port=\u2026 pid=\u2026> \u2014 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 / 6e4} minutes; a browser capture did not start is never signalled. Also sweeps previously-launched browsers that have exited, stopped answering CDP, or gone idle.`;
+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 / 6e4} minutes; a browser capture did not start is never signalled. Also sweeps previously-launched browsers that have exited, refused CDP connections, or gone idle.`;
   }
 });
 
@@ -230587,7 +230643,7 @@ input:
   --port <port>   probe one endpoint only, instead of discovering every localhost CDP endpoint; an active session's endpoint does not narrow it (CDP_PORT still pins one endpoint)
 
 output: <tabs endpoints=\u2026 tabs=\u2026> \u2014 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 \u2014 browsers capture did not start are never signalled.`;
+effects: probes local CDP endpoints over HTTP/WebSocket; no page-observable writes. Also sweeps capture-launched browsers, stopping any that have exited, refused CDP connections, or gone idle \u2014 browsers capture did not start are never signalled.`;
     ARC_ENDPOINT_NOTE = text`  note: Arc exposes only tabs opened over CDP as page targets; the tabs in its windows are not listed. Open one with "capture tab open <url> --port <port>", then "capture session start --port <port> --target <id>".`;
   }
 });
@@ -267596,7 +267652,7 @@ I/O contract: flags and positionals on input; one rendered prose block on stdout
 A CDP-enabled browser must be running; \`capture tab list\` is the probe, and \`capture tab launch\` starts one capture owns and reaps when nothing is (never hand-roll a detached browser \u2014 nothing reaps that). Capture never signals a browser it did not start, so attaching to your own with --port is unchanged. CDP_PORT / CDP_TARGET pin the browser + tab for target-selecting commands \u2014 precedence: explicit flag > active session > env. \`session start\` adopts only an explicit --target. When CRTR_NODE_ID is set (a crtr agent node), a browser command with no --port, no --target and no active session of that node is refused instead of falling back to CDP_PORT, CDP_TARGET or localhost discovery, because the browser found could belong to another node: run \`capture session start --url <url>\`, or pass --port or --target. \`capture tab list\` and commands that only read a recorded artifact are not refused.`;
 }
 function printVersion() {
-  const declared = "1.4.26";
+  const declared = "1.4.28";
   if (declared) {
     console.log(declared);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.4.26",
+  "version": "1.4.28",
   "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/browser-process.ts

@@ -191,8 +191,16 @@ function forgetRecordFile(file: string): void {
  * ONLY gate that authorizes a signal; an `unknown` read (a provider that could
  * not answer) is deliberately NOT a kill authorization. */
 function stillOurs(record: OwnedBrowser): boolean {
+  return processOwnership(record) === 'ours';
+}
+
+/** `gone` — the process exited, or its pid was recycled by a stranger; `unknown` —
+ * the provider could not answer (e.g. its `sysctl` read timed out on a loaded
+ * host), which says nothing about whether the browser is alive. */
+function processOwnership(record: OwnedBrowser): 'ours' | 'gone' | 'unknown' {
   const observed = processPidBirthProvider.read(record.pid);
-  return observed.status === 'found' && sameBirth(observed.identity, record.birth);
+  if (observed.status === 'unknown') return 'unknown';
+  return observed.status === 'found' && sameBirth(observed.identity, record.birth) ? 'ours' : 'gone';
 }
 
 /**
@@ -229,17 +237,26 @@ async function reap(record: OwnedBrowser): Promise<void> {
   removeProfile(record.profileDir);
 }
 
-async function endpointAnswers(port: number): Promise<boolean> {
+/** `up` — answered; `down` — the connection was refused or the answer was an
+ * error, so nothing is serving CDP there; `unknown` — no answer within the probe
+ * window or the request failed some other way. A browser starved of CPU on a
+ * loaded host answers slowly, so `unknown` is never evidence it is unusable. */
+async function probeEndpoint(port: number): Promise<'up' | 'down' | 'unknown'> {
   try {
     const response = await fetch(`http://${CDP_LOOPBACK_HOST}:${port}/json/version`, {
       signal: AbortSignal.timeout(ENDPOINT_PROBE_MS),
     });
-    return response.ok;
-  } catch {
-    return false;
+    return response.ok ? 'up' : 'down';
+  } catch (error) {
+    const code = (error as { cause?: { code?: unknown } }).cause?.code;
+    return code === 'ECONNREFUSED' ? 'down' : 'unknown';
   }
 }
 
+async function endpointAnswers(port: number): Promise<boolean> {
+  return (await probeEndpoint(port)) === 'up';
+}
+
 /**
  * Reconciles the registry with reality and reaps what no longer earns its
  * memory. Run at the top of every `tab` leaf that touches owned browsers — this
@@ -249,7 +266,12 @@ async function endpointAnswers(port: number): Promise<boolean> {
 export async function sweepOwnedBrowsers(): Promise<ReapedBrowser[]> {
   const reaped: ReapedBrowser[] = [];
   for (const record of readOwnedBrowsers()) {
-    if (!stillOurs(record)) {
+    const ownership = processOwnership(record);
+    // An unreadable process identity proves nothing: removing the profile of a
+    // browser that is in fact running would pull its user-data-dir out from
+    // under it. Leave the record for a sweep that can read it.
+    if (ownership === 'unknown') continue;
+    if (ownership === 'gone') {
       // Crashed, or SIGKILLed by someone else. Nothing to signal — just drop
       // the claim and the profile it left behind.
       forgetRecordFile(recordPath(record.token));
@@ -257,7 +279,11 @@ export async function sweepOwnedBrowsers(): Promise<ReapedBrowser[]> {
       reaped.push({ port: record.port, pid: record.pid, reason: 'exited' });
       continue;
     }
-    if (record.port === null || !(await endpointAnswers(record.port))) {
+    // A record with no port is a launch in flight in another capture process
+    // (the registry is shared by every agent on the host), not a dead browser —
+    // until the launch's own readiness deadline has passed.
+    if (record.port === null && Date.now() - Date.parse(record.startedAt) <= READY_TIMEOUT_MS + ENDPOINT_PROBE_MS) continue;
+    if (record.port === null || (await probeEndpoint(record.port)) === 'down') {
       await reap(record);
       reaped.push({ port: record.port, pid: record.pid, reason: 'unreachable' });
       continue;

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

@@ -177,7 +177,7 @@ async function focusScopedEvaluate(client: ExecClient, expression: string, evalu
     // Emulate focus so network requests the code triggers aren't deferred
     // by the browser, without foregrounding the tab.
     ownsFocusOverride = true;
-    await client.send('Emulation.setFocusEmulationEnabled', { enabled: true });
+    await client.send('Emulation.setFocusEmulationEnabled', { enabled: true }, evaluationTimeoutMs);
     try {
       return (await client.send('Runtime.evaluate', {
         expression,
@@ -201,7 +201,7 @@ async function focusScopedEvaluate(client: ExecClient, expression: string, evalu
   } finally {
     if (ownsFocusOverride) {
       try {
-        await client.send('Emulation.setFocusEmulationEnabled', { enabled: false });
+        await client.send('Emulation.setFocusEmulationEnabled', { enabled: false }, evaluationTimeoutMs);
       } catch (error) {
         const cleanupError = captureError(
           'cleanup',

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

@@ -47,6 +47,7 @@ input:
   --out <path>      caller-owned destination PNG; default: the active session's shots/ sequence, or a fresh one-shot bundle when no session is active
   --artifact-dir <path>  root for that sessionless one-shot bundle (ignored with --out or an active session)
   --target <tabId> | --url <pattern> | --port <n>   tab targeting; defaults to the active session tab
+  --timeout <ms>    deadline for connecting to the tab and for each screenshot request (default: 30000 for connecting and each screenshot request); a tab that does not answer in time fails with command_deadline_exceeded or a CDP request timeout instead of waiting
   --json            mirror the result as JSON
 output:
   <screenshot path=… width=… height=… css-width=… css-height=… css-x=… css-y=… css-to-image-x=… css-to-image-y=… effective-downscale-x=… effective-downscale-y=… scroll-x=… scroll-y=… emulation=none|viewport|full-page color-scheme=dark|light> — 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, visual-viewport scroll offset at capture, any effective downscale below 1 image px/CSS px, byte size, crop provenance, and any requested transient emulation
@@ -410,7 +411,7 @@ export async function cmdPageShot(parsed: ParsedArgs, _args: string[]): Promise<
         cropProvenance = { source: 'coordinates', requested: requestedCrop, zoom };
       }
       const screenshot = await captureScreenshotWithCssViewport(client, viewport, {
-        fullPage: parsed.fullPage, crop: requestedCrop, zoom,
+        fullPage: parsed.fullPage, crop: requestedCrop, zoom, requestTimeoutMs: parsed.timeoutMs,
         ...(colorScheme ? { beforeCapture: () => finishColorTransitions(client) } : {}),
       });
       const outPath = await resolveOutPath(parsed);

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

@@ -21,7 +21,7 @@ input:
   --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.`;
+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, refused CDP connections, or gone idle.`;
 
 /** Pure `<browser-launched>` result builder — exported for tests. */
 export function buildBrowserLaunchedResult(
@@ -34,7 +34,7 @@ export function buildBrowserLaunchedResult(
       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.`);
+  if (swept > 0) sections.push(fact`swept ${swept} previously-launched browser(s) that had exited, refused CDP connections, or gone idle.`);
   return {
     tag: 'browser-launched',
     attrs: { port: browser.port, pid: browser.pid, headless: browser.headless },

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

@@ -33,7 +33,7 @@ input:
   --port <port>   probe one endpoint only, instead of discovering every localhost CDP endpoint; an active session's endpoint does not narrow it (CDP_PORT still pins one endpoint)
 
 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.`;
+effects: probes local CDP endpoints over HTTP/WebSocket; no page-observable writes. Also sweeps capture-launched browsers, stopping any that have exited, refused CDP connections, or gone idle — browsers capture did not start are never signalled.`;
 
 export interface TabRow {
   id: string;

package/src/cdp/connection.ts

@@ -97,6 +97,42 @@ export async function applyActiveSessionNetworkConditions(
   });
 }
 
+
+// ---------------------------------------------------------------------------
+// Command deadline — a page that stops answering CDP (blocked main thread,
+// throttled background tab) never replies to anything, so every wait on it
+// must be bounded by capture itself.
+// ---------------------------------------------------------------------------
+
+/** Bound on connecting to a tab and starting its collectors when the caller declares no `--timeout`. */
+export const DEFAULT_SETUP_DEADLINE_MS = 30_000;
+
+/** The deadline for connecting a page command to its tab: the declared `--timeout`, else the default. */
+function setupDeadlineMs(parsed: ParsedArgs): number {
+  return parsed.timeoutMs ?? DEFAULT_SETUP_DEADLINE_MS;
+}
+
+/**
+ * Races `work` against `ms`. On expiry it rejects with `command_deadline_exceeded`
+ * naming the phase; the caller's `finally` closes the client, which rejects the
+ * abandoned work's pending requests.
+ */
+async function withinDeadline<T>(ms: number, phase: string, work: Promise<T>): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  const expired = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(captureError(
+      'world',
+      'command_deadline_exceeded',
+      `${phase} did not finish within ${ms}ms — the tab is not answering CDP (its main thread may be blocked, or the tab throttled). Raise --timeout to wait longer.`,
+    )), ms);
+  });
+  try {
+    return await Promise.race([work, expired]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 /**
  * Builds a short, human-readable label for this command invocation, used to
  * tag every marked (`Input.dispatch*`) CDP call the recorder-held adapter
@@ -251,7 +287,7 @@ export async function connectForCommand(
     await client.waitReady();
     // Reissue the session's persisted offline/online state on this fresh
     // connection — network emulation belongs to a connection, not the tab.
-    await applyActiveSessionNetworkConditions(client, seams.getActiveSession(), tab.id);
+    await withinDeadline(setupDeadlineMs(parsed), 'Restoring the session network state', applyActiveSessionNetworkConditions(client, seams.getActiveSession(), tab.id));
     return { client, tab };
   } catch (err) {
     client.close();
@@ -339,9 +375,9 @@ export async function withConnection<T>(
   opts: { settle?: number } = {},
 ): Promise<T> {
   const { client, tab } = await connectForCommand(parsed);
-  const collectors = await startCollectors(parsed, client);
 
   try {
+    const collectors = await withinDeadline(setupDeadlineMs(parsed), 'Starting page collectors', startCollectors(parsed, client));
     const result = await fn(client, tab);
 
     if (collectors.harRecorder && parsed.har) {
@@ -400,9 +436,9 @@ export async function withPageAction<T>(
   fn: (client: CDPClient, tab: CDPTarget) => Promise<T>,
 ): Promise<{ result: T; settle: SettleFacts }> {
   const { client, tab } = await connectForCommand(parsed);
-  const collectors = await startCollectors(parsed, client);
 
   try {
+    const collectors = await withinDeadline(setupDeadlineMs(parsed), 'Starting page collectors', startCollectors(parsed, client));
     // Action callback first — a rejection here claims no settle.
     const result = await fn(client, tab);
 

package/src/cdp/record.ts

@@ -111,5 +111,11 @@ export async function navigateAndWait(
   // Refresh target info — find by ID to avoid returning a different tab with same URL
   const targets = await listTargets(port);
   const refreshed = targets.find((t) => t.id === tab.id);
-  return refreshed ?? tab;
+  // Some browsers (Arc) acknowledge Target.createTarget and then drop the page.
+  // Reporting an id the browser no longer lists hands the caller a target every
+  // later command rejects, so the open itself fails instead.
+  if (!refreshed) {
+    throw new Error(`the browser accepted the new tab ${tab.id} but no longer lists it — it dropped the tab. Open it again.`);
+  }
+  return refreshed;
 }

package/src/cdp/screenshot.ts

@@ -31,7 +31,7 @@ export interface ScreenshotCrop {
   readonly height: number;
 }
 
-type ScreenshotOptions = { fullPage?: boolean; crop?: ScreenshotCrop; zoom?: number; beforeCapture?: () => Promise<void> };
+type ScreenshotOptions = { fullPage?: boolean; crop?: ScreenshotCrop; zoom?: number; beforeCapture?: () => Promise<void>; requestTimeoutMs?: number };
 
 /** A region is reportable only if every number is finite and its size is positive; anything else would produce a fabricated scale. */
 function validRegion(region: CapturedRegion): CapturedRegion | undefined {
@@ -151,7 +151,7 @@ async function viewportScopedCapture(
   includeCssViewport = false,
 ): Promise<{ png: Buffer; cssViewport?: CapturedRegion; scrollOffset?: ScrollOffset }> {
   const MAX_DIM = 1600; // headroom below Anthropic's 2000px many-image limit
-  const SCREENSHOT_REQUEST_TIMEOUT_MS = 30_000;
+  const SCREENSHOT_REQUEST_TIMEOUT_MS = options?.requestTimeoutMs ?? 30_000;
   let ownsDeviceMetricsOverride = false;
   let primaryFailed = false;
   let primaryError: unknown;

package/src/cdp/targets.ts

@@ -3,6 +3,10 @@ import { CDP_LOOPBACK_HOST } from './loopback.js';
 import { detectCdpPortsAsync } from './detect.js';
 import { touchOwnedBrowser } from './browser-process.js';
 import { type CDPTarget } from './types.js';
+import { captureError } from '../errors.js';
+
+/** A browser that accepts the connection but never answers `/json/version` or `Target.getTargets` must fail the command, not stall it. */
+const BROWSER_PROBE_TIMEOUT_MS = 10_000;
 
 /**
  * Connects to the BROWSER-level CDP websocket (not a page/tab target).
@@ -14,7 +18,7 @@ import { type CDPTarget } from './types.js';
 export async function getBrowserClient(
   port: number,
 ): Promise<{ client: CDPClient; browserWsUrl: string }> {
-  const versionResp = await fetch(`http://${CDP_LOOPBACK_HOST}:${port}/json/version`);
+  const versionResp = await fetch(`http://${CDP_LOOPBACK_HOST}:${port}/json/version`, { signal: AbortSignal.timeout(BROWSER_PROBE_TIMEOUT_MS) });
   if (!versionResp.ok) {
     throw new Error(
       `Failed to connect to CDP on port ${port}: ${versionResp.status}`,
@@ -46,8 +50,8 @@ export async function listTargets(port: number): Promise<CDPTarget[]> {
 
   try {
     // Enable target discovery to get all targets including pages
-    await client.send('Target.setDiscoverTargets', { discover: true });
-    const result = (await client.send('Target.getTargets')) as {
+    await client.send('Target.setDiscoverTargets', { discover: true }, BROWSER_PROBE_TIMEOUT_MS);
+    const result = (await client.send('Target.getTargets', {}, BROWSER_PROBE_TIMEOUT_MS)) as {
       targetInfos: Array<{
         targetId: string;
         type: string;
@@ -109,19 +113,36 @@ export async function findTabById(
   return null;
 }
 
+/**
+ * A selector that matched nothing while some endpoint failed to list its tabs
+ * is not "no such tab": the failure is the answer. `tab list` reports the same
+ * failure as an unreachable endpoint, so the two commands name the same fact.
+ */
+function unlistedTargetError(query: string, failures: ReadonlyArray<{ port: number; error: unknown }>): Error {
+  const detail = failures.map(({ port, error }) => `port ${port}: ${error instanceof Error ? error.message : String(error)}`).join('; ');
+  return captureError(
+    'precondition',
+    'target_unavailable',
+    `No tab found for "${query}", and ${failures.length} endpoint(s) could not list their tabs (${detail}). Run "capture tab list" to see which endpoints answer.`,
+    failures[0]?.error,
+  );
+}
+
 export async function findTabByIdInPorts(
   targetId: string,
   ports: number[],
   finder: (port: number, targetId: string) => Promise<CDPTarget | null> = findTabById,
 ): Promise<{ port: number; tab: CDPTarget } | null> {
+  const failures: Array<{ port: number; error: unknown }> = [];
   for (const port of ports) {
     try {
       const tab = await finder(port, targetId);
       if (tab) return { port, tab };
-    } catch {
-      // Skip endpoints that fail or are ambiguous on a different port.
+    } catch (error) {
+      failures.push({ port, error });
     }
   }
+  if (failures.length > 0) throw unlistedTargetError(targetId, failures);
   return null;
 }
 
@@ -138,14 +159,17 @@ export async function findUnambiguousPageTabInPorts(
   lister: (port: number) => Promise<CDPTarget[]> = listTargets,
 ): Promise<{ port: number; tab: CDPTarget } | null> {
   const candidates: Array<{ port: number; tab: CDPTarget }> = [];
+  const failures: Array<{ port: number; error: unknown }> = [];
   for (const port of ports) {
     try {
       for (const tab of await lister(port)) if (tab.type === 'page') candidates.push({ port, tab });
-    } catch {
-      // An unavailable endpoint cannot supply a target.
+    } catch (error) {
+      failures.push({ port, error });
     }
   }
   if (candidates.length > 1) throw new AmbiguousPageTargetError(candidates);
+  // One page tab on a reachable endpoint is only "the" tab when no other endpoint hid a second one.
+  if (candidates.length === 0 && failures.length > 0) throw unlistedTargetError('(any page tab)', failures);
   return candidates[0] ?? null;
 }
 
@@ -232,6 +256,7 @@ export async function findTabByUrlAcrossEndpoints(
 ): Promise<{ port: number; tab: CDPTarget } | null> {
   const ports = resolveSearchPorts(await detectCdpPortsAsync(), preferredPort);
   let best: { port: number; tab: CDPTarget; score: number } | null = null;
+  const failures: Array<{ port: number; error: unknown }> = [];
 
   for (const port of ports) {
     try {
@@ -243,12 +268,14 @@ export async function findTabByUrlAcrossEndpoints(
           best = { port, tab, score };
         }
       }
-    } catch {
-      // Skip endpoints that fail to respond.
+    } catch (error) {
+      failures.push({ port, error });
     }
   }
 
-  return best ? { port: best.port, tab: best.tab } : null;
+  if (best) return { port: best.port, tab: best.tab };
+  if (failures.length > 0) throw unlistedTargetError(url, failures);
+  return null;
 }
 
 export function requireTargetId(