qz-browser-agent 0.1.2 → 0.1.5

package/src/commands.mjs

@@ -1,4 +1,5 @@
 const request = ["timeout", "client"];
+export const DRIVE_SESSION_REQUIRED = "Pass the sessionId from qz session create.";
 const waiting = [...request, "wait", "stream"];
 const output = ["json", "plain", "no-color", "help"];
 const filename = options => options.filename ? { filename: options.filename } : {};
@@ -8,13 +9,22 @@ const route = (tool, args = () => ({}), options = []) => ({ tool, args, options
 // CLI syntax, documentation, and direct MCP routes have one declaration per command.
 // Task execution and form responses retain their explicit handlers in cli.mjs.
 export const COMMANDS = {
-  connect: { options: [...request, "port", "no-open", "name"], summary: "Connect the browser",
-    help: ["qz connect [--client NAME|UUID] [--port PORT] [--timeout SECONDS]", "Reuse a connected browser or open the connection page for first pairing.", "qz connect --no-open [--name NAME] --json", "Return a binding URL immediately. Open it in the target browser profile.", "--name assigns or changes that profile's name. Without --no-open, its binding page opens immediately.", "Use --port for a custom local service port. An existing service remains running.", "qz browsers"],
+  cleanup: { options: [], summary: "Stop local services and clean runtime files",
+    help: ["qz cleanup", "Stop registered qz local services across installations and remove their runtime files and logs.",
+      "Uses ~/.qz-browser-agent/run, or QZ_STATE_DIR when set. Browser registrations, tabs, tasks and saved data are preserved.",
+      "Active CLI requests and direct-drive scripts are interrupted. Tasks running in the side panel continue.",
+      "The next browser command starts its service automatically. Use qz cancel TASK_ID or qz session cancel ID to stop a task.",
+      "Services whose identity cannot be verified are reported and left running; an incomplete cleanup exits with code 1."],
+  },
+  connect: { options: [...request, "port", "name"], summary: "Print a browser connection URI",
+    help: ["qz connect uri [--name NAME | --client NAME|UUID] [--port PORT]", "Print the connection URL without opening a browser or interrupting tasks.",
+      "Open the URL in the intended browser profile with qz installed. --name names a new profile; --client selects a registered profile.",
+      "Session and script commands prepare their connection automatically. Use this URL when choosing among browser profiles."],
   },
   create: { options: [...waiting, "title", "parent"], summary: "Start a task",
     help: ['qz create "PROMPT" [--title TITLE] [--wait | --stream]', "Start a browser task. The title is optional.",
       "--title, -t  Set the task title. --parent TASK_ID creates a child task.",
-      "--wait    Wait for completion, including pauses for user input.", "--stream  Show responses as they arrive; also wait.",
+      "--wait    Follow the task across runs until its work completes and accepted message queues are empty; user-input pauses keep waiting.", "--stream  Show responses as they arrive; also wait.",
       "Use - as the prompt to read stdin.",
       'qz create "Compare these two pages." --stream', 'qz create "Summarize this page." --title Research --wait'],
   },
@@ -22,7 +32,8 @@ export const COMMANDS = {
     help: ['qz send TASK_ID "MESSAGE" [--steer] [--wait | --stream]', "Send a follow-up or steer a specific task.",
       "A busy task queues a follow-up for its next run. --steer delivers the message to the current run at its next safe boundary.",
       "Both start a new run when the task is idle. Pending questions and permissions still require a response.",
-      "Use - as the message to read stdin. --wait follows the submitted message; --stream also shows its responses.",
+      "Use - as the message to read stdin. --wait follows the task until its work completes and queues are empty; removed queued messages no longer block completion.",
+      "--stream also shows responses from this message onward, including later runs.",
       'qz send TASK_ID "Add the source links." --stream', 'qz send TASK_ID "Focus on open-source options." --steer --stream'],
   },
   tasks: { options: [...request, "limit"], summary: "List tasks",
@@ -32,22 +43,23 @@ export const COMMANDS = {
     help: ["qz show TASK_ID", "Show task status, the latest response, and any pending form or permission request.", "Pending input includes field IDs, option values, and a submission template. Use --json for the complete snapshot.", "qz show TASK_ID --json"],
   },
   watch: { options: [...request, "stream"], summary: "Wait for a task",
-    help: ["qz watch TASK_ID [--stream]", "Wait for an existing task to finish, including pauses for user input.", "--stream  Show assistant responses as they arrive.", "Timeout or Ctrl-C ends watching without cancelling the task."],
+    help: ["qz watch TASK_ID [--stream]", "Follow an existing task across runs until its work completes and accepted message queues are empty; user-input pauses keep waiting.", "--stream  Show assistant responses as they arrive.", "Task failure or stopping ends observation. Timeout or Ctrl-C ends watching without cancelling the task.", "Resume with the returned watch command for the same task and browser; observation never resends messages."],
   },
   submit: { options: [...waiting, "wait-id"], summary: "Answer a form",
     help: ["qz submit TASK_ID JSON [--wait | --stream]", "Submit answers to the current form. Use - to read JSON from stdin.",
       "--wait-id ID  Bind the response to a previously read wait. Otherwise qz reads the current wait before submitting.",
+      "--wait and --stream follow the task across runs until its work completes and accepted message queues are empty.",
       'qz submit TASK_ID \'{"selectedIds":["option-a"]}\' --stream'],
   },
   approve: { options: [...waiting, "wait-id"], summary: "Continue a waiting task",
     help: ["qz approve TASK_ID [--wait | --stream]", "Continue after completing a requested action.",
-      "Review app consent notices with qz show before approving. Native browser permissions require a click in the qz side panel.", "--wait-id ID  Respond only to this wait."],
+      "Review app consent notices with qz show before approving. Native browser permissions require a click in the qz side panel.", "--wait-id ID  Respond only to this wait.", "--wait and --stream follow the task across runs until its work completes and accepted message queues are empty."],
   },
   reject: { options: [...waiting, "wait-id"], summary: "Decline a pending request",
-    help: ["qz reject TASK_ID [--wait-id ID] [--wait | --stream]", "Decline the pending request and optionally follow the task's next step. Use qz cancel TASK_ID to stop the whole task."],
+    help: ["qz reject TASK_ID [--wait-id ID] [--wait | --stream]", "Decline the pending request. --wait and --stream follow the task across runs until its work completes and accepted message queues are empty. Use qz cancel TASK_ID to stop the whole task."],
   },
   cancel: { options: request, summary: "Stop a task",
-    help: ["qz cancel TASK_ID", "Stop a task's active run.", "qz stop stops the local service instead."],
+    help: ["qz cancel TASK_ID", "Stop a task's active run.", "Use qz session cancel ID to end a direct-drive session."],
   },
   data: { options: request, summary: "List, export, or delete tables",
     help: ["qz data [list]", "List saved data tables with their exact names.",
@@ -107,16 +119,41 @@ export const COMMANDS = {
   status: { options: [], summary: "Check the connection",
     help: ["qz status", "Show the local service and browser connection status."],
   },
-  mcp: { options: [], summary: "Print the MCP URL",
-    help: ["qz mcp [--json]", "Print the running service's MCP URL for an external agent.", "Run qz connect first."],
+  session: { options: request, summary: "Create, inspect, or cancel a browser session",
+    help: ["qz session create --title TITLE", "Create a session with a readable title and print sessionId on stdout. --json also returns the session's available qz_skills.",
+      "qz session list", "List sessions and their current status.",
+      "qz session show ID", "Read one session's title and status.",
+      "qz session cancel ID [--keep TAB_REF ...]", "End the session and clean up its created tabs, including while a script is running. Repeat --keep to return selected tabs to the user.",
+      "Pass the same sessionId on every qz script --session ID call. Scripts never create or reuse a session implicitly."],
+    actions: {
+      create: route("qingzhou_create_drive_session", ({ options }) => ({ title: options.title.trim() }), ["title"]),
+      list: route("qingzhou_list_drive_sessions"),
+      show: route("qingzhou_get_drive_session", ({ id }) => ({ sessionId: id })),
+      cancel: route("qingzhou_stop_session", ({ id, options }) => ({ sessionId: id, ...(options.keep ? { keepTabRefs: options.keep } : {}) }), ["keep"]),
+    },
   },
-  install: { options: [], summary: "Install the Chrome extension",
-    help: ["qz install", "Open qz in the Chrome Web Store.", "Click Add to Chrome, then run qz connect."],
+  script: { options: [...request, "session", "args"], summary: "Run a browser script",
+    help: ["qz script --session ID [FILE|-] [--args JSON]", "Run JavaScript orchestration outside the page. stdout is {ok,result,trace}: execution status, the returned business value (or error), and ordered trace messages.",
+      "--session ID is required. Create one session per task with qz session create --title TITLE and pass its sessionId.",
+      "Read a local file or use - for stdin. Write top-level await and return; --args passes a JSON value as args (aliased as input).",
+      "Call browser tools via tools.<name>(...) with explicit tabRef values; awaited calls return business values directly and throw on failure. Use tools.evaluate({tabRef,code,args}) for in-page DOM/window access.",
+      "Discover compact signatures with tools.list_tools() and full schemas with tools.list_tools({names:[...]}).",
+      "--timeout sets the script timeout in seconds (0 < seconds <= 3600) and defaults to 120. The request waits 60 seconds longer.",
+      "stdout is always {ok,result,trace}: ok reports execution success, result holds the returned value (null for undefined) or {code,message,hint?,details?}, and trace lists errors and explicit trace()/console output in order without levels. Exit codes: 0 success, 1 execution or connection failure, 2 invalid arguments.",
+      "qz script --session ID task.js --args '{\"query\":\"example\"}'", "qz script --session ID - <<'JS'"],
   },
-  stop: { options: [], summary: "Stop the local service",
-    help: ["qz stop", "Stop the local service and disconnect all browsers.", "Use qz cancel TASK_ID to stop a task.", "qz connect"],
+  skill: { options: ["lang"], summary: "Print the browser guide",
+    help: ["qz skill", "Print the direct-drive browser guide without connecting.",
+      "Read this guide once at the start of a browser task."],
+  },
+  mcp: { options: ["profile"], summary: "Print the MCP URL",
+    help: ["qz mcp [--profile full|drive] [--json]", "Print the MCP URL. The default catalog is the direct-drive set.",
+      "--profile full prints the task and diagnostic catalog.", "The local service starts automatically."],
+  },
+  install: { options: [], summary: "Install the Chrome extension",
+    help: ["qz install", "Open qz in the Chrome Web Store.", "Click Add to Chrome, then run qz session create --title TITLE."],
   },
-  help: { options: [] },
+  help: { options: ["lang"] },
 };
 
 export function commandOptions(command, action = "list") {

package/src/connect-page.mjs

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { INSTALL_URL } from "./package-info.mjs";
+
+// The published CLI carries the same sail mark as the browser extension.
+export const CONNECT_LOGOS = new Map(["qz-logo.png", "qz-logo-day.png"].map(name =>
+  [`/${name}`, readFileSync(new URL(`./${name}`, import.meta.url))]));
+
+// Browsers without qz never mark the status element, so the help appears after a short wait.
+const CONNECT_SCRIPT = `
+const help = document.querySelector("[data-qz-connection-help]");
+const link = help.querySelector("[data-qz-connection-link]");
+const copy = help.querySelector("[data-qz-copy-link]");
+link.textContent = location.href;
+setTimeout(() => { help.hidden = false; }, 3000);
+copy.addEventListener("click", async () => {
+  try {
+    await navigator.clipboard.writeText(location.href);
+    copy.dataset.copied = "";
+    copy.setAttribute("aria-label", "Copied");
+    setTimeout(() => { delete copy.dataset.copied; copy.setAttribute("aria-label", "Copy link"); }, 1500);
+  } catch {
+    getSelection().selectAllChildren(link);
+  }
+});
+`;
+
+export const CONNECT_PAGE_CSP = `default-src 'none'; img-src 'self'; style-src 'unsafe-inline'; script-src 'sha256-${createHash("sha256").update(CONNECT_SCRIPT).digest("base64")}'; base-uri 'none'; frame-ancestors 'none'`;
+
+export const CONNECT_PAGE = `<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="color-scheme" content="light dark">
+<title>Connect qz</title>
+<style>
+:root { color-scheme: light dark; --bg: #f4f4f2; --surface: #fff; --text: #171717; --muted: #5f6368; --border: #e5e5e2; --green: #23815d; --red: #ba3c3c; }
+* { box-sizing: border-box; }
+body { margin: 0; min-height: 100svh; display: grid; place-items: center; padding: 32px 20px; background: var(--bg); color: var(--text); font: 16px/1.6 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+main { width: min(100%, 520px); padding: 44px; background: var(--surface); border: 1px solid var(--border); border-radius: 24px; box-shadow: 0 16px 48px #00000006, 0 2px 6px #00000003; }
+.brand { display: flex; align-items: center; gap: 16px; font-size: 24px; font-weight: 650; letter-spacing: -.6px; }
+.brand img { display: block; width: 64px; height: 64px; border-radius: 18px; }
+h1 { margin: 34px 0 8px; font-size: clamp(25px, 5vw, 30px); line-height: 1.25; font-weight: 620; letter-spacing: -.8px; }
+.intro { margin: 0; color: var(--muted); }
+[data-qz-connection-status] { position: relative; display: grid; align-content: center; margin: 28px 0 0; min-height: calc(2lh + 34px); padding: 16px 18px 16px 46px; border: 1px solid var(--border); border-radius: 12px; background: var(--bg); font-size: 14px; overflow-wrap: anywhere; transition: background-color 300ms ease, border-color 300ms ease; }
+[data-qz-connection-status]::before { content: ""; position: absolute; inset-inline-start: 18px; top: calc(50% - 6px); width: 12px; height: 12px; border: 1.5px solid var(--border); border-top-color: var(--muted); border-radius: 50%; animation: turn 1s linear infinite; transition: opacity 150ms ease; }
+[data-qz-connection-status]::after { content: ""; position: absolute; inset-inline-start: 18px; top: calc(50% - 5px); width: 11px; height: 7px; border: solid var(--green); border-width: 0 0 2px 2px; opacity: 0; transform: rotate(-45deg) scale(.8); transition: opacity 220ms ease 80ms, transform 220ms cubic-bezier(.2,.7,.2,1) 80ms; }
+[data-qz-connection-state="connected"] { border-color: color-mix(in srgb, var(--green) 22%, var(--border)); background: color-mix(in srgb, var(--green) 5%, var(--surface)); }
+[data-qz-connection-state="connected"]::before { opacity: 0; animation-play-state: paused; }
+[data-qz-connection-state="connected"]::after { opacity: 1; transform: rotate(-45deg); }
+[data-qz-connection-state="connected"] [data-qz-connection-message] { animation: message-in 240ms ease-out 60ms both; }
+[data-qz-connection-state="error"] { border-color: color-mix(in srgb, var(--red) 25%, var(--border)); }
+[data-qz-connection-state="error"]::before { border: 0; width: 8px; height: 8px; top: calc(50% - 4px); background: var(--red); animation: none; }
+footer { margin-top: 32px; padding-top: 24px; border-top: 1px solid var(--border); color: var(--muted); font-size: 13px; animation: message-in 240ms ease-out both; }
+footer p { margin: 0 0 6px; }
+footer .title { color: var(--text); font-size: 14px; font-weight: 600; }
+[data-qz-connection-status]:is([data-qz-extension], :not([data-qz-connection-state="connecting"])) ~ footer { display: none; }
+.link { display: flex; align-items: center; gap: 8px; margin-top: 8px; padding: 5px 5px 5px 12px; border: 1px solid var(--border); border-radius: 10px; background: var(--bg); }
+.link code { flex: 1; min-width: 0; color: var(--text); font: 12.5px/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; overflow-wrap: anywhere; user-select: all; }
+.link button { flex: none; display: grid; place-items: center; width: 30px; height: 30px; padding: 0; border: 0; border-radius: 7px; background: transparent; color: var(--muted); cursor: pointer; }
+.link button:hover { background: var(--surface); color: var(--text); }
+.link button:focus-visible { outline: 2px solid var(--text); outline-offset: 2px; }
+.link svg { width: 16px; height: 16px; }
+.link [data-icon="check"], .link [data-copied] [data-icon="copy"] { display: none; }
+.link button[data-copied] { color: var(--green); }
+.link [data-copied] [data-icon="check"] { display: block; }
+a { color: var(--text); text-underline-offset: 4px; text-decoration-color: var(--border); }
+a:hover { text-decoration-color: currentColor; }
+a:focus-visible { outline: 2px solid var(--text); outline-offset: 4px; border-radius: 2px; }
+@keyframes turn { to { transform: rotate(360deg); } }
+@keyframes message-in { from { opacity: 0; transform: translateY(2px); } to { opacity: 1; transform: translateY(0); } }
+@media (prefers-reduced-motion: reduce) { [data-qz-connection-status], [data-qz-connection-status]::before, [data-qz-connection-status]::after, [data-qz-connection-message], footer { animation: none !important; transition: none !important; } }
+@media (max-width: 420px) { body { padding: 20px 16px; } main { padding: 30px 24px; border-radius: 20px; } [data-qz-connection-status] { min-height: calc(3lh + 34px); } }
+@media (prefers-color-scheme: dark) { :root { --bg: #171717; --surface: #212121; --text: #f2f2f0; --muted: #a5a5a1; --border: #343434; --green: #6fc6a1; --red: #ec8b8b; } main { box-shadow: 0 16px 48px #00000020; } }
+</style>
+<main>
+  <div class="brand"><picture><source media="(prefers-color-scheme: dark)" srcset="/qz-logo.png"><img src="/qz-logo-day.png" alt="" width="64" height="64"></picture><div>qz</div></div>
+  <h1>Connect your browser</h1>
+  <p class="intro">Keep this page open while qz connects.</p>
+  <p data-qz-connection-status data-qz-connection-state="connecting" role="status" aria-live="polite"><span data-qz-connection-message>Connecting to the qz browser extension…</span></p>
+  <footer data-qz-connection-help hidden>
+    <p class="title">Not connecting?</p>
+    <p><a href="${INSTALL_URL}" target="_blank" rel="noopener noreferrer">Install qz from the Chrome Web Store</a>, then reload this page.</p>
+    <p>Using qz in another browser or profile? Open this link there:</p>
+    <div class="link"><code data-qz-connection-link></code><button type="button" data-qz-copy-link aria-label="Copy link" title="Copy link"><svg data-icon="copy" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="9" y="9" width="12" height="12" rx="2"/><path d="M5 15H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1v1"/></svg><svg data-icon="check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m5 12.5 4.5 4.5L19 7.5"/></svg></button></div>
+  </footer>
+</main>
+<script>${CONNECT_SCRIPT}</script>
+</html>`;

package/src/connection.mjs

@@ -0,0 +1,145 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { PROTOCOL_VERSION, QzError, readHealth } from "./client.mjs";
+import { ensureDaemon, findDaemon, restartDaemon } from "./daemon.mjs";
+import { openConnectionBrowser } from "./open-browser.mjs";
+
+import { SCRIPT_API_VERSION } from "./script-call.mjs";
+
+const offlineCodes = new Set(["BRIDGE_NOT_CONNECTED", "BRIDGE_CLIENT_OFFLINE", "BRIDGE_CLIENT_DISCONNECTED", "BRIDGE_REQUEST_TIMEOUT", -32001]);
+
+/** Upgrade a verified service at most once, before any browser operation is submitted. */
+export async function prepareService({ options = {}, script = false } = {}, dependencies = {}) {
+  const signal = dependencies.signal;
+  signal?.throwIfAborted();
+  const find = dependencies.findDaemon || findDaemon;
+  const ensure = dependencies.ensureDaemon || ensureDaemon;
+  let running = await find({ allowIncompatible: true });
+  signal?.throwIfAborted();
+  if (!running) {
+    running = await ensure({ ...(options.port === undefined ? {} : { preferredPort: options.port }), signal });
+    signal?.throwIfAborted();
+  }
+  const compatible = service => service.compatible !== false
+    && (service.health.protocolVersion === undefined || service.health.protocolVersion === PROTOCOL_VERSION)
+    && service.health.features?.browserPairing === 1 && (!script || service.health.features?.scriptApiVersion >= SCRIPT_API_VERSION);
+  if (!compatible(running)) {
+    running = await (dependencies.restartDaemon || restartDaemon)({ expected: running, preferredPort: Number(new URL(running.endpoint).port), signal });
+    signal?.throwIfAborted();
+    if (!compatible(running)) throw new QzError("UPGRADE_REQUIRED", "The local qz service is incompatible. No browser operation was submitted.", {
+      hint: "Update the installed CLI and browser extension, then retry the command.",
+    });
+  }
+  return running;
+}
+
+export function connectionUri(running, options = {}) {
+  const url = new URL("/qz-connect", running.endpoint);
+  let name = options.name;
+  if (options["client-id"]) {
+    const entry = [...(running.health.status?.browsers || []), ...(running.health.status?.clients || [])]
+      .find(client => client.clientId === options["client-id"] || client.name === options["client-id"]);
+    if (!entry) throw new QzError("CLIENT_NOT_FOUND", "The selected browser is not registered. Run qz browsers to inspect names and UUIDs.");
+    name = entry.name;
+  }
+  if (name) url.searchParams.set("name", name);
+  return url.href;
+}
+
+/** Select one responding identity; every later call in the command keeps that UUID. */
+export async function prepareConnection({ options = {}, timeoutSeconds = 30, sessionId = "", script = false } = {}, dependencies = {}) {
+  const running = await prepareService({ options, script }, dependencies);
+  const startedAt = Date.now(), commandDeadline = startedAt + timeoutSeconds * 1000;
+  let deadline = Math.min(commandDeadline, startedAt + 30000), reconnectUntil = 0;
+  const signal = dependencies.signal;
+  const selector = options["client-id"];
+  const registered = selector ? [...(running.health.status?.browsers || []), ...(running.health.status?.clients || [])]
+    .find(client => client.clientId === selector || client.name === selector) : undefined;
+  if (selector && !registered) throw new QzError("CLIENT_NOT_FOUND", "The selected browser is not registered. Run qz browsers to inspect names and UUIDs.");
+  const clientId = registered?.clientId;
+  const uri = connectionUri(running, options);
+  const call = async (name, args) => {
+    signal?.throwIfAborted();
+    const timeoutMs = Math.max(1, Math.min(2000, deadline - Date.now()));
+    return dependencies.callTool(running.endpoint, name, { ...args, timeoutSeconds: timeoutMs / 1000 }, { timeoutMs, signal });
+  };
+  const locate = async health => {
+    const clients = (health.status?.clients || []).filter(client => !clientId || client.clientId === clientId);
+    const matches = [];
+    for (const client of clients) {
+      try { await call("qingzhou_call", { method: "ping", clientId: client.clientId }); }
+      catch (error) {
+        signal?.throwIfAborted();
+        if (!offlineCodes.has(error.code)) throw error;
+        if (sessionId && clients.length > 1) throw error;
+        continue;
+      }
+      // A unique connection retains the tool producer's authoritative occupied/ended checks.
+      if (!sessionId || selector || clients.length === 1) return client.clientId;
+      try {
+        await call("qingzhou_get_drive_session", { sessionId, clientId: client.clientId });
+        matches.push(client.clientId);
+      } catch (error) {
+        if (error.code !== "DRIVE_SESSION_NOT_FOUND") throw error;
+        const snapshot = await call("qingzhou_get_session_snapshot", { sessionId, clientId: client.clientId, compact: true, tail: true });
+        if (snapshot?.session) matches.push(client.clientId);
+      }
+    }
+    if (matches.length > 1) throw new QzError("SELECTION_REQUIRED", "This session exists in more than one browser. Select its browser with --client NAME|UUID.");
+    if (matches.length === 1) return matches[0];
+    if (sessionId && clients.length > 1) throw new QzError("DRIVE_SESSION_NOT_FOUND", "The session was not found in the connected browsers.", {
+      hint: "Check the session ID and use --client NAME|UUID to select its browser.",
+    });
+    return "";
+  };
+  const observeReconnect = health => {
+    const waiting = (health.status?.connecting || []).filter(client => !clientId || client.clientId === clientId);
+    const retryAfterMs = Math.max(0, ...waiting.map(client => Number.isFinite(client.retryAfterMs) ? client.retryAfterMs : 0));
+    reconnectUntil = retryAfterMs > 0 ? Math.min(commandDeadline, Date.now() + retryAfterMs) : 0;
+    deadline = Math.max(deadline, reconnectUntil);
+  };
+  observeReconnect(running.health);
+  let selected = await locate(running.health);
+  if (selected) return { running, clientId: selected };
+  const attempted = [];
+  let opened = Boolean(selector);
+  while (Date.now() < deadline) {
+    signal?.throwIfAborted();
+    if (!opened && Date.now() >= reconnectUntil) {
+      const browser = await (dependencies.openConnectionBrowser || openConnectionBrowser)(uri, {
+        signal, timeoutMs: Math.max(1, Math.min(10000, deadline - Date.now())),
+      });
+      attempted.push(browser.browser || "System default browser");
+      opened = true;
+    }
+    if (Date.now() >= deadline) break;
+    const remainingMs = deadline - Date.now();
+    let health;
+    try {
+      health = await (dependencies.readHealth || readHealth)(running.endpoint, {
+        timeoutMs: Math.max(1, Math.ceil(Math.min(1000, remainingMs))), signal,
+      });
+    } catch (error) {
+      signal?.throwIfAborted();
+      // The read timer can fire just before Date.now() reaches the deadline it was sized to.
+      const budgetExpired = remainingMs <= 1000 && [error?.name, error?.cause?.name].includes("TimeoutError");
+      if (budgetExpired || Date.now() >= deadline) break;
+      throw error;
+    }
+    signal?.throwIfAborted();
+    if (Date.now() >= deadline) break;
+    if (running.instanceId && health.instanceId !== running.instanceId) throw new QzError("CONNECTION_CHANGED", "The local service changed during connection. Retry the command.");
+    observeReconnect(health);
+    selected = await locate(health);
+    if (selected) return { running: { ...running, health }, clientId: selected };
+    await delay(Math.max(1, Math.min(200, deadline - Date.now())), undefined, { signal });
+  }
+  throw new QzError(selector ? "CLIENT_OFFLINE" : "CONNECTION_PENDING", `${selector ? "The selected browser is not responding." : "qz is waiting for its browser extension."} No browser operation was submitted.`, {
+    stage: "browser-connection",
+    ...(registered ? { selectedBrowser: { clientId: registered.clientId, name: registered.name } } : {}),
+    attemptedBrowsers: attempted, operationSubmitted: false,
+    url: uri,
+    hint: selector
+      ? "Open qz in the selected browser profile, then retry. Use qz connect uri --client NAME|UUID to reconnect that profile."
+      : "Check the connection page in your default browser, then retry. Use qz connect uri to connect a different supported browser profile.",
+  });
+}