qz-browser-agent 0.1.3 → 0.1.5

package/src/daemon.mjs

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { closeSync, openSync, readFileSync, readdirSync, realpathSync } from "node:fs";
-import { chmod, mkdir, readFile, readdir, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
+import { closeSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
+import { chmod, lstat, mkdir, readFile, readdir, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -23,8 +23,15 @@ export function buildIdentity(directory = packageDir) {
 export function daemonPaths(options = {}) {
   const identity = options.scopeId && options.buildId ? options : buildIdentity();
   const scopeId = options.scopeId || identity.scopeId;
-  const directory = resolve(options.stateDir || process.env.QZ_STATE_DIR || join(homedir(), ".qz-browser-agent", "run"));
-  return { scopeId, buildId: options.buildId || identity.buildId, directory, state: join(directory, `${scopeId}.json`), lock: join(directory, `${scopeId}.lock`), log: join(directory, `${scopeId}.log`) };
+  return { scopeId, buildId: options.buildId || identity.buildId, ...scopePaths(stateDirectory(options), scopeId) };
+}
+
+function stateDirectory(options) {
+  return resolve(options.stateDir || process.env.QZ_STATE_DIR || join(homedir(), ".qz-browser-agent", "run"));
+}
+
+function scopePaths(directory, scopeId) {
+  return { directory, state: join(directory, `${scopeId}.json`), lock: join(directory, `${scopeId}.lock`), log: join(directory, `${scopeId}.log`) };
 }
 
 async function readJson(path) {
@@ -55,29 +62,41 @@ function processExists(pid) {
   }
 }
 
+function pidNamespace() {
+  if (process.platform !== "linux") return "";
+  try { return readlinkSync("/proc/self/ns/pid"); } catch { return ""; }
+}
+
+function processMayExist(owner) {
+  // A PID from another namespace cannot prove that its owner has exited.
+  return Boolean(owner.pidNamespace && owner.pidNamespace !== pidNamespace()) || processExists(owner.processId);
+}
+
 export async function findDaemon(options = {}) {
   const paths = daemonPaths(options);
   const record = await readJson(paths.state);
-  if (!record || record.scopeId !== paths.scopeId || !processExists(record.processId)) return null;
+  if (!record || record.scopeId !== paths.scopeId || !Number.isSafeInteger(record.processId) || record.processId <= 0) return null;
   for (let attempt = 0; attempt < 2; attempt += 1) {
     try {
-      const health = await (options.readHealth || readHealth)(record.endpoint, { timeoutMs: 1000 });
+      const health = await (options.readHealth || readHealth)(record.endpoint, { timeoutMs: 1000, ...(options.allowIncompatible ? { allowIncompatible: true } : {}) });
       if (health.scopeId !== paths.scopeId || health.instanceId !== record.instanceId || health.processId !== record.processId) return null;
-      return { ...record, health, compatible: true, updateAvailable: health.buildId !== paths.buildId };
+      return { ...record, health, compatible: health.protocolVersion === PROTOCOL_VERSION, updateAvailable: health.buildId !== paths.buildId };
     } catch (error) {
-      if (!processExists(record.processId) || ["invalid_endpoint", "incompatible_service"].includes(error.code)) return null;
+      if (!processMayExist(record) || ["INVALID_ENDPOINT", "INCOMPATIBLE_SERVICE"].includes(error.code)) return null;
       if (attempt === 0) await delay(100);
     }
   }
-  throw new QzError("connection_unavailable", "The qz local service is running but did not respond. Try qz status again shortly.", {
+  throw new QzError("CONNECTION_UNAVAILABLE", "The qz local service is running but did not respond. Try qz status again shortly.", {
     endpoint: record.endpoint, processId: record.processId, log: paths.log,
   });
 }
 
-async function withLock(paths, operation, { timeoutMs = 15000 } = {}) {
+async function withLock(paths, operation, { timeoutMs = 15000, signal } = {}) {
+  signal?.throwIfAborted();
   await mkdir(paths.directory, { recursive: true, mode: 0o700 });
   await chmod(paths.directory, 0o700);
-  const owner = { processId: process.pid, id: randomUUID() };
+  const namespace = pidNamespace();
+  const owner = { processId: process.pid, id: randomUUID(), ...(namespace ? { pidNamespace: namespace } : {}) };
   const ownerFile = `${owner.processId}-${owner.id}.json`;
   const candidate = `${paths.lock}.${owner.id}.pending`;
   await mkdir(candidate, { mode: 0o700 });
@@ -85,8 +104,10 @@ async function withLock(paths, operation, { timeoutMs = 15000 } = {}) {
   let acquired = false;
   let missingTargetPermissionError;
   try {
+    signal?.throwIfAborted();
     await writeFile(join(candidate, ownerFile), JSON.stringify(owner), { mode: 0o600 });
     while (true) {
+      signal?.throwIfAborted();
       try {
         // The lock becomes visible already containing its unique owner file.
         await rename(candidate, paths.lock);
@@ -104,11 +125,11 @@ async function withLock(paths, operation, { timeoutMs = 15000 } = {}) {
             // A persistent denial remains EPERM rather than becoming a busy lock.
             if (missingTargetPermissionError || Date.now() >= deadline) throw missingTargetPermissionError || error;
             missingTargetPermissionError = error;
-            await delay(50);
+            await delay(50, undefined, { signal });
             continue;
           }
           if (!["EEXIST", "ENOTEMPTY", "ENOTDIR"].includes(error.code)) throw error;
-          if (Date.now() >= deadline) throw new QzError("connection_busy", "Another qz command is starting the local service. Try qz status shortly.");
+          if (Date.now() >= deadline) throw new QzError("CONNECTION_BUSY", "Another qz command is starting the local service. Try qz status shortly.");
           continue;
         }
         missingTargetPermissionError = undefined;
@@ -117,21 +138,22 @@ async function withLock(paths, operation, { timeoutMs = 15000 } = {}) {
             if (!/^\d+-[\da-f-]+\.json$/.test(name)) continue;
             const oldPath = join(paths.lock, name);
             const oldOwner = await readJson(oldPath);
-            if (oldOwner ? !processExists(oldOwner.processId) : Date.now() - existing.mtimeMs > 30000) await rm(oldPath, { force: true });
+            if (oldOwner ? !processMayExist(oldOwner) : Date.now() - existing.mtimeMs > 30000) await rm(oldPath, { force: true });
           }
           // A concurrent new owner keeps its directory non-empty and survives cleanup.
           await rmdir(paths.lock).catch(error => { if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code)) throw error; });
         } else {
           // Recover the file-lock format used by earlier local development builds.
           const oldOwner = await readJson(paths.lock);
-          if (oldOwner ? !processExists(oldOwner.processId) : Date.now() - existing.mtimeMs > 30000) {
+          if (oldOwner ? !processMayExist(oldOwner) : Date.now() - existing.mtimeMs > 30000) {
             await rm(paths.lock, { force: true }).catch(error => { if (!["EISDIR", "ERR_FS_EISDIR"].includes(error.code)) throw error; });
           }
         }
-        if (Date.now() >= deadline) throw new QzError("connection_busy", "Another qz command is starting the local service. Try qz status shortly.");
-        await delay(50);
+        if (Date.now() >= deadline) throw new QzError("CONNECTION_BUSY", "Another qz command is starting the local service. Try qz status shortly.");
+        await delay(50, undefined, { signal });
       }
     }
+    signal?.throwIfAborted();
     return await operation();
   } finally {
     if (acquired) {
@@ -144,11 +166,21 @@ async function withLock(paths, operation, { timeoutMs = 15000 } = {}) {
 
 function recordFromHealth(endpoint, health) {
   return { service: SERVICE_NAME, protocolVersion: PROTOCOL_VERSION, endpoint, scopeId: health.scopeId,
-    buildId: health.buildId, instanceId: health.instanceId, processId: health.processId };
+    buildId: health.buildId, instanceId: health.instanceId, processId: health.processId,
+    ...(health.pidNamespace ? { pidNamespace: health.pidNamespace } : {}) };
 }
 
 async function stopProcess(running) {
-  if (running.processId === process.pid) throw new QzError("stop_failed", "The service is running inside this process.");
+  if (running.processId === process.pid) throw new QzError("STOP_FAILED", "The service is running inside this process.");
+  if (process.platform === "linux") {
+    let args = [];
+    try { args = readFileSync(`/proc/${running.processId}/cmdline`, "utf8").split("\0"); } catch {}
+    const index = args.indexOf("--run");
+    if (index < 1 || basename(args[index - 1]) !== "daemon.mjs"
+      || args[index + 2] !== running.scopeId || args[index + 5] !== running.instanceId) {
+      throw new QzError("STOP_FAILED", "The service process cannot be verified from this environment. Run qz cleanup from the terminal that started it.");
+    }
+  }
   try { process.kill(running.processId, "SIGTERM"); }
   catch (error) { if (error.code === "ESRCH") return { stopped: true, connected: false }; throw error; }
   const deadline = Date.now() + 5000;
@@ -156,7 +188,7 @@ async function stopProcess(running) {
     if (!processExists(running.processId)) return { stopped: true, connected: false };
     await delay(50);
   }
-  throw new QzError("stop_failed", "The local service has not stopped yet. Check qz status.");
+  throw new QzError("STOP_FAILED", "The local service has not stopped yet. Check qz status.");
 }
 
 function childExited(child) {
@@ -180,24 +212,36 @@ async function discardStartup(child, paths, instanceId) {
     child.kill(signal);
     if (await waitForChildExit(child, 1000)) break;
   }
-  if (!childExited(child)) throw new QzError("start_failed", "The failed qz startup process has not stopped.", { processId: child.pid, log: paths.log });
+  if (!childExited(child)) throw new QzError("START_FAILED", "The failed qz startup process has not stopped.", { processId: child.pid, log: paths.log });
   const record = await readJson(paths.state);
   if (record?.processId === child.pid && record.instanceId === instanceId) await rm(paths.state, { force: true });
 }
 
 export async function ensureDaemon(options = {}) {
+  options.signal?.throwIfAborted();
   const paths = daemonPaths(options);
+  // Reuse without writes, but honor an in-progress startup, cleanup or upgrade.
+  if (!await lstat(paths.lock).catch(missing)) {
+    const existing = await findDaemon({ ...options, stateDir: paths.directory, scopeId: paths.scopeId, buildId: paths.buildId });
+    options.signal?.throwIfAborted();
+    if (existing && !await lstat(paths.lock).catch(missing)) return existing;
+  }
+  return withLock(paths, () => ensureDaemonLocked(paths, options), options);
+}
+
+async function ensureDaemonLocked(paths, options) {
+  options.signal?.throwIfAborted();
   const lookup = { ...options, stateDir: paths.directory, scopeId: paths.scopeId, buildId: paths.buildId };
-  return withLock(paths, async () => {
-    // A running service keeps its loaded code until an explicit stop. Editing files or
-    // invoking another npx cache copy must not interrupt browser tasks or MCP clients.
+    // Compatible services retain their loaded code across source edits or npx copies.
     const existing = await findDaemon(lookup);
+    options.signal?.throwIfAborted();
     if (existing) return existing;
     const port = options.preferredPort ?? 18765;
     if (port) {
       const endpoint = `http://127.0.0.1:${port}`;
       const health = await (options.readHealth || readHealth)(endpoint, { timeoutMs: 500 }).catch(() => null);
-      if (health?.scopeId === paths.scopeId && processExists(health.processId)) {
+      options.signal?.throwIfAborted();
+      if (health?.scopeId === paths.scopeId && Number.isSafeInteger(health.processId) && health.processId > 0) {
         const record = recordFromHealth(endpoint, health);
         await atomicJson(paths.state, record);
         return { ...record, health, compatible: true, updateAvailable: health.buildId !== paths.buildId };
@@ -208,6 +252,7 @@ export async function ensureDaemon(options = {}) {
     try {
       const log = openSync(paths.log, "a", 0o600);
       try {
+        options.signal?.throwIfAborted();
         child = (options.spawnProcess || spawn)(process.execPath, [fileURLToPath(import.meta.url), "--run", paths.state, paths.scopeId, String(port), paths.buildId, instanceId], {
           detached: true, stdio: ["ignore", "ignore", log], windowsHide: true,
         });
@@ -215,27 +260,45 @@ export async function ensureDaemon(options = {}) {
           child.once("spawn", resolveSpawn);
           child.once("error", reject);
         });
+        options.signal?.throwIfAborted();
         child.unref();
       } finally { closeSync(log); }
       const deadline = Date.now() + (options.startTimeoutMs || 10000);
       while (Date.now() < deadline) {
+        options.signal?.throwIfAborted();
         const running = await findDaemon(lookup);
+        options.signal?.throwIfAborted();
         if (running) {
           if (running.instanceId !== instanceId || running.processId !== child.pid) {
-            throw new QzError("start_failed", "Another qz service claimed the startup state. Check qz status.", { log: paths.log });
+            throw new QzError("START_FAILED", "Another qz service claimed the startup state. Check qz status.", { log: paths.log });
           }
           return running;
         }
         if (childExited(child) || !processExists(child.pid)) break;
-        await delay(50);
+        await delay(50, undefined, { signal: options.signal });
       }
-      throw new QzError("start_failed", "The qz local service did not start.", { log: paths.log });
+      throw new QzError("START_FAILED", "The qz local service did not start.", { log: paths.log });
     } catch (error) {
       // Hold the startup lock until this invocation's child is gone. Otherwise a
       // delayed child could overwrite the state published by a concurrent retry.
       await discardStartup(child, paths, instanceId);
       throw error;
     }
+}
+
+/** Replace only the exact service inspected by the caller, under the same startup lock. */
+export async function restartDaemon({ expected, ...options } = {}) {
+  options.signal?.throwIfAborted();
+  const paths = daemonPaths(options);
+  return withLock(paths, async () => {
+    const running = await findDaemon({ ...options, stateDir: paths.directory, scopeId: paths.scopeId, buildId: paths.buildId, allowIncompatible: true });
+    options.signal?.throwIfAborted();
+    if (!running || !expected || ["scopeId", "instanceId", "processId"].some(key => running[key] !== expected[key])) {
+      throw new QzError("CONNECTION_CHANGED", "The local service changed before its upgrade. Retry the command.");
+    }
+    await stopProcess(running);
+    options.signal?.throwIfAborted();
+    return ensureDaemonLocked(paths, options);
   }, options);
 }
 
@@ -243,22 +306,108 @@ export async function stopDaemon(options = {}) {
   const paths = daemonPaths(options);
   return withLock(paths, async () => {
     const running = await findDaemon(options);
+    options.signal?.throwIfAborted();
     if (!running) return { stopped: false, connected: false };
     return stopProcess(running);
   }, options);
 }
 
+// Only daemon-owned runtime names participate; pairing registries and unrelated files stay intact.
+const runtimeName = /^([a-f\d]{24})(?:\.json(?:\.[a-f\d-]{36}\.tmp)?|\.log|\.lock(?:\.[a-f\d-]{36}\.pending)?)$/;
+const sameInstance = (left, right) => ["service", "scopeId", "instanceId", "processId", "endpoint"].every(key => left?.[key] === right?.[key]);
+const missing = error => { if (error.code !== "ENOENT") throw error; return null; };
+
+/** Stop registered installations under their startup locks, without creating a service or browser. */
+export async function cleanupDaemons(options = {}) {
+  const directory = stateDirectory(options);
+  options.signal?.throwIfAborted();
+  const names = await readdir(directory).catch(error => missing(error) || []);
+  const scopes = [...new Set(names.map(name => runtimeName.exec(name)?.[1]).filter(Boolean))].sort();
+  const result = { stopped: 0, removedFiles: 0, skipped: 0, services: [] };
+  for (const scopeId of scopes) {
+    options.signal?.throwIfAborted();
+    const paths = scopePaths(directory, scopeId);
+    const item = { scopeId, status: "cleaned" };
+    try {
+      const lock = await lstat(paths.lock).catch(missing);
+      if (lock?.isSymbolicLink()) throw new QzError("CLEANUP_UNVERIFIED", "The service lock is a symbolic link.");
+      await withLock(paths, async () => {
+        const state = await lstat(paths.state).catch(missing);
+        if (state && !state.isFile()) throw new QzError("CLEANUP_UNVERIFIED", "The service record is not a regular file.");
+        const record = state ? await readJson(paths.state) : null;
+        if (state && (!record || record.service !== SERVICE_NAME || record.scopeId !== scopeId
+          || !record.instanceId || !Number.isSafeInteger(record.processId) || record.processId <= 0)) {
+          throw new QzError("CLEANUP_UNVERIFIED", "The service record is invalid; its process cannot be identified.");
+        }
+        if (record) {
+          Object.assign(item, { processId: record.processId, endpoint: record.endpoint });
+          const running = await findDaemon({ ...options, stateDir: directory, scopeId, buildId: record.buildId || "cleanup", allowIncompatible: true });
+          options.signal?.throwIfAborted();
+          if (running ? !sameInstance(record, running) || !sameInstance(record, await readJson(paths.state)) : processMayExist(record)) {
+            throw new QzError("CLEANUP_UNVERIFIED", "The live process does not match its registered qz service.");
+          }
+          options.signal?.throwIfAborted();
+          if (running) {
+            await stopProcess(running);
+            result.stopped++;
+            item.status = "stopped";
+          }
+          const current = await readJson(paths.state);
+          if (current && !sameInstance(record, current)) throw new QzError("CONNECTION_CHANGED", "The service record changed during cleanup.");
+        }
+        options.signal?.throwIfAborted();
+        const remaining = await readdir(directory);
+        for (const name of remaining) {
+          if (runtimeName.exec(name)?.[1] !== scopeId || name === `${scopeId}.lock`) continue;
+          const path = join(directory, name);
+          const entry = await lstat(path).catch(missing);
+          if (!entry) continue;
+          if (entry.isFile()) {
+            await rm(path, { force: true });
+            result.removedFiles++;
+          } else if (entry.isDirectory() && name.endsWith(".pending")) {
+            // A pending starter may already be waiting on our lock. Only dead owners can be removed.
+            let removedOwner = false;
+            for (const ownerName of await readdir(path).catch(error => missing(error) || [])) {
+              if (!/^\d+-[a-f\d-]{36}\.json$/.test(ownerName)) continue;
+              const ownerPath = join(path, ownerName);
+              const owner = await readJson(ownerPath);
+              if (owner && Number.isSafeInteger(owner.processId) && owner.processId > 0 && !processMayExist(owner)) {
+                await rm(ownerPath, { force: true });
+                result.removedFiles++;
+                removedOwner = true;
+              }
+            }
+            // A starter publishes its owner just after mkdir; leave that fresh empty directory alone.
+            if (removedOwner || Date.now() - entry.mtimeMs > 30000) {
+              await rmdir(path).catch(error => { if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code)) throw error; });
+            }
+          }
+        }
+      }, options);
+    } catch (error) {
+      options.signal?.throwIfAborted();
+      result.skipped++;
+      Object.assign(item, { status: "skipped", code: error.code || "CLEANUP_FAILED", message: error.message });
+    }
+    result.services.push(item);
+  }
+  return result;
+}
+
 export async function startManagedBridge({ stateFile, scopeId, buildId = "", instanceId = randomUUID(), port = 18765, startBridge } = {}) {
   const start = startBridge || (await import("./server.mjs")).startBridge;
   const registryPath = stateFile.replace(/\.json$/, "") + ".browsers.json";
+  const namespace = pidNamespace();
+  const identity = { scopeId, instanceId, buildId, ...(namespace ? { pidNamespace: namespace } : {}) };
   let running;
-  try { running = await start({ port, scopeId, instanceId, buildId, registryPath }); }
+  try { running = await start({ port, ...identity, registryPath }); }
   catch (error) {
     if (error.code !== "EADDRINUSE" || !port) throw error;
-    running = await start({ port: 0, scopeId, instanceId, buildId, registryPath });
+    running = await start({ port: 0, ...identity, registryPath });
   }
   const record = { service: SERVICE_NAME, protocolVersion: PROTOCOL_VERSION, endpoint: running.endpoint,
-    processId: process.pid, scopeId, instanceId, buildId };
+    processId: process.pid, ...identity };
   try { await atomicJson(stateFile, record); }
   catch (error) { await running.close(); throw error; }
   let closing;

package/src/drive-guide.mjs

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+
+const MARKER_START = "<!-- qz-drive-guide:en -->";
+const MARKER_END = "<!-- qz-drive-guide:end -->";
+const candidates = [
+  new URL("./qz-drive-SKILL.md", import.meta.url),
+  new URL("../../../skills/qz-browser-agent/SKILL.md", import.meta.url),
+];
+
+let cached = "";
+
+function loadGuideSource() {
+  if (cached) return cached;
+  const errors = [];
+  for (const url of candidates) {
+    try {
+      cached = readFileSync(url, "utf8");
+      return cached;
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      errors.push(url.pathname);
+    }
+  }
+  throw new Error(`direct-drive guide is missing. Looked in ${errors.join(", ")}.`);
+}
+
+/** Read the direct-drive usage guide. */
+export function driveGuide() {
+  const text = loadGuideSource();
+  const start = text.indexOf(MARKER_START);
+  const end = text.indexOf(MARKER_END, start + MARKER_START.length);
+  if (start < 0 || end < 0) throw new Error("direct-drive guide content is missing.");
+  return `${text.slice(start + MARKER_START.length, end).trim()}\n`;
+}
+
+export function resetDriveGuideCache() {
+  cached = "";
+}

package/src/drive-timeout.mjs

@@ -0,0 +1,21 @@
+/** Shared CLI/bridge wait budget. Never rewrites script or batch execution deadlines. */
+export function driveExtensionTimeoutSeconds(params, fallback = 180) {
+  const client = Number(params?.timeoutSeconds);
+  const base = Number.isFinite(client) && client > 0 ? client : Number(fallback) || 180;
+  const scripts = [];
+  if (params?.name === "run_script") scripts.push(params.args);
+  if (Array.isArray(params?.calls)) {
+    for (const call of params.calls) if (call?.name === "run_script") scripts.push(call.args);
+  }
+  let scriptMax = 0;
+  let unlimited = false;
+  for (const raw of scripts) {
+    const timeout = Number(raw && typeof raw === "object" ? raw.timeout : undefined);
+    if (!Number.isFinite(timeout)) continue;
+    if (timeout <= 0) unlimited = true;
+    else scriptMax = Math.max(scriptMax, timeout);
+  }
+  if (unlimited) return 86400;
+  if (scriptMax > 0) return Math.max(base, scriptMax + 60);
+  return base;
+}

package/src/open-browser.mjs

@@ -1,20 +1,49 @@
 import { spawn } from "node:child_process";
 import { QzError } from "./client.mjs";
 
-export async function openBrowser(url, { platform = process.platform, spawnProcess = spawn } = {}) {
-  const target = new URL(url);
-  if (!["http:", "https:"].includes(target.protocol)) throw new QzError("browser_open_failed", "Only web URLs can be opened.", { url });
+const connectionHint = "Open the connection URL in the browser profile where qz is installed, then retry.";
+
+/** Open the connection page once with the system URL opener; the page guides browsers without qz. */
+export async function openConnectionBrowser(url, { platform = process.platform, spawnProcess = spawn, signal, timeoutMs = 10000 } = {}) {
+  try {
+    return { ...await openBrowser(url, { platform, spawnProcess, signal, waitForExit: false, timeoutMs }), browser: "System default browser" };
+  } catch (error) {
+    signal?.throwIfAborted();
+    throw new QzError("BROWSER_OPEN_FAILED", error.message, { url, hint: connectionHint });
+  }
+}
+
+export async function openBrowser(url, { platform = process.platform, spawnProcess = spawn, signal, timeoutMs = 10000, waitForExit = true } = {}) {
+  webUrl(url);
+  signal?.throwIfAborted();
   const [command, args] = platform === "darwin" ? ["open", [url]]
     : platform === "win32" ? ["rundll32.exe", ["url.dll,FileProtocolHandler", url]] : ["xdg-open", [url]];
+  const failure = () => new QzError("BROWSER_OPEN_FAILED", "Could not open the system default browser. Open the URL manually.", { url });
   await new Promise((resolve, reject) => {
-    const child = spawnProcess(command, args, { stdio: "ignore", windowsHide: true });
-    const timer = setTimeout(() => {
-      child.kill();
-      reject(new QzError("browser_open_failed", "The browser did not open. Open the URL in Chrome with qz installed.", { url }));
-    }, 10000);
-    const finish = error => { clearTimeout(timer); error ? reject(error) : resolve(); };
-    child.once("error", () => finish(new QzError("browser_open_failed", "Could not open a browser. Open the URL in Chrome with qz installed.", { url })));
-    child.once("exit", code => finish(code === 0 ? null : new QzError("browser_open_failed", "Could not open a browser. Open the URL in Chrome with qz installed.", { url })));
+    const child = spawnProcess(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+    let settled = false;
+    const finish = error => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      // The system opener may itself become the browser process. Never kill it on timeout or cancellation.
+      child.unref?.();
+      error ? reject(error) : resolve();
+    };
+    const onAbort = () => finish(signal.reason);
+    const timer = setTimeout(() => finish(failure()), Math.max(1, timeoutMs));
+    if (!waitForExit) child.once("spawn", () => finish());
+    child.once("error", () => finish(failure()));
+    child.once("exit", code => finish(code === 0 ? null : failure()));
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) onAbort();
   });
   return { url, opened: true };
 }
+
+function webUrl(url) {
+  const target = new URL(url);
+  if (!["http:", "https:"].includes(target.protocol)) throw new QzError("BROWSER_OPEN_FAILED", "Only web URLs can be opened.", { url });
+  return target;
+}