@crouton-kit/capture 1.4.25 → 1.4.27

package/bin/capture

@@ -5930,7 +5930,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 +5952,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 +5991,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 +6091,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 +6102,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 +6148,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 +8692,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 +9052,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"() {
@@ -10174,7 +10198,8 @@ function resolveCliContext(parsed) {
       parsed.target = session.targetId;
       parsed.targetSource = "session";
     }
-    if (parsed.port === void 0 && session.port !== void 0 && session.port !== null) {
+    const discoveringEndpoints = parsed.command === "tab" && parsed.positional[0] === "list";
+    if (parsed.port === void 0 && !discoveringEndpoints && session.port !== void 0 && session.port !== null) {
       parsed.port = session.port;
       parsed.portSource = "session";
     }
@@ -10944,7 +10969,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.4.25";
+  const version = "1.4.27";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -13046,7 +13071,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.4.25";
+  const version = "1.4.27";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -16776,6 +16801,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"}`;
@@ -16863,7 +16906,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();
@@ -16915,8 +16958,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;
@@ -16933,8 +16976,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();
@@ -16962,7 +17005,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"));
@@ -16989,6 +17032,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;
   }
 });
 
@@ -229199,7 +229243,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,
@@ -229223,7 +229267,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",
@@ -229705,6 +229749,7 @@ async function cmdPageShot(parsed, _args) {
         fullPage: parsed.fullPage,
         crop: requestedCrop,
         zoom,
+        requestTimeoutMs: parsed.timeoutMs,
         ...colorScheme ? { beforeCapture: () => finishColorTransitions(client) } : {}
       });
       const outPath = await resolveOutPath(parsed);
@@ -229745,6 +229790,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
@@ -230583,7 +230629,7 @@ var init_list = __esm({
     USAGE11 = `capture tab list \u2014 discover CDP endpoints and list the page tabs on each.
 
 input:
-  --port <port>   probe one endpoint only, instead of discovering every localhost CDP endpoint
+  --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.`;
@@ -267595,7 +267641,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.25";
+  const declared = "1.4.27";
   if (declared) {
     console.log(declared);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.4.25",
+  "version": "1.4.27",
   "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/args.ts

@@ -625,7 +625,10 @@ export function resolveCliContext(parsed: ParsedArgs): ParsedArgs {
     // A session target is inseparable from the endpoint that created it.
     // Prefer that endpoint over ambient CDP_PORT, but retain an explicit
     // --port override for deliberate multi-browser work.
-    if (parsed.port === undefined && session.port !== undefined && session.port !== null) { parsed.port = session.port; parsed.portSource = 'session'; }
+    // `tab list` is the discovery probe: without --port it lists every
+    // localhost endpoint, so the session's endpoint must not narrow it.
+    const discoveringEndpoints = parsed.command === 'tab' && parsed.positional[0] === 'list';
+    if (parsed.port === undefined && !discoveringEndpoints && session.port !== undefined && session.port !== null) { parsed.port = session.port; parsed.portSource = 'session'; }
   }
   refuseUnownedEndpoint(parsed, sessionStart);
   if (parsed.port === undefined && process.env.CDP_PORT !== undefined) {

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/list.ts

@@ -30,7 +30,7 @@ import {
 const USAGE = `capture tab list — discover CDP endpoints and list the page tabs on each.
 
 input:
-  --port <port>   probe one endpoint only, instead of discovering every localhost CDP endpoint
+  --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.`;

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(