pi-browser-harness 0.10.2 → 0.11.0

package/src/profile/browser-process.ts

@@ -1,55 +1,24 @@
-/**
- * Identifying the browser process the harness is attached to.
- *
- * Two questions, deliberately kept apart:
- *
- *   1. Is a Chromium-family browser RUNNING? (`detectRunningBrowser().running`)
- *      Only live-process evidence may answer this — an installed-but-closed
- *      browser must read as "not running", which is why the registry lookup
- *      below is never consulted here.
- *
- *   2. Which binary do we invoke to open a window for a chosen profile?
- *      (`resolveBrowserExecutable()`) Chromium's ProcessSingleton hands a second
- *      launch's argv to the already-running browser instead of starting another
- *      one — Windows via WM_COPYDATA (process_singleton_win.cc), Linux and macOS
- *      via the socket in the user-data-dir (process_singleton_posix.cc, which is
- *      compiled on macOS too). Here an installed path is a fine fallback.
- *
- * Whether the running browser carries an explicit `--user-data-dir` matters:
- * ProcessSingleton keys on that directory, so passing a path that differs from
- * the running browser's by case or normalisation would start a SECOND browser
- * rather than delegating. The flag is forwarded only when the running process
- * already has one.
- *
- * Every probe is best-effort; when nothing can be determined, profile launching
- * degrades to a clear message rather than guessing.
- *
- * Windows note: `wmic` is deliberately unused — Microsoft removed it by default
- * in Windows 11 24H2 and entirely in 25H2. PowerShell CIM is the supported
- * replacement, with `tasklist` for liveness and the documented App Paths
- * registry key for install location.
- */
+// `running` is derived only from live-process evidence: an installed-but-closed browser must read as "not running".
+// `wmic` is deliberately unused — Microsoft removed it by default in Windows 11 24H2 and entirely in 25H2, so PowerShell CIM plus tasklist replace it.
 
 import { execFile } from "node:child_process";
 import { access, readFile, readlink } from "node:fs/promises";
 import { join } from "node:path";
 import { promisify } from "node:util";
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { parseJson } from "../schemas/parse";
 import { browserNameForUserDataDir } from "./paths";
 
-// execFile, not exec: arguments are passed as an array, with no shell involved.
 const run = promisify(execFile);
 const EXEC_TIMEOUT_MS = 5_000;
 
 export type RunningBrowser = {
-  /** True when a Chromium-family browser process is live. */
   readonly running: boolean;
-  /** Absolute path to the running browser's binary, when determinable. */
   readonly exePath?: string;
-  /** Value of an explicit --user-data-dir on the running process, if any. */
   readonly explicitUserDataDir?: string;
 };
 
-/** Chromium-family process names, lowercase, as they appear per platform. */
 const LINUX_COMMS: ReadonlyArray<string> = [
   "chrome", "chromium", "chromium-browser", "msedge", "microsoft-edge",
   "google-chrome", "brave", "brave-browser",
@@ -59,22 +28,13 @@ const MAC_BROWSER_NAMES: ReadonlyArray<string> = [
 ];
 const WIN_IMAGE_NAMES: ReadonlyArray<string> = ["chrome.exe", "msedge.exe", "brave.exe"];
 
-/**
- * Chromium tags every child process with `--type=<role>`; only the browser
- * process omits it or carries `--type=browser`. Matching the flag (rather than
- * words like "renderer" anywhere in the string) keeps a user whose install path
- * contains such a word from being filtered out.
- */
+// Match the `--type=` flag, not words like "renderer" anywhere in the string, or an install path containing one is filtered out.
 const hasChildProcessType = (commandLine: string): boolean => {
   const lower = commandLine.toLowerCase();
   return lower.includes("--type=") && !lower.includes("--type=browser");
 };
 
-/**
- * macOS names its child processes in the executable path itself ("Google Chrome
- * Helper (Renderer)", crashpad, updaters), so the process NAME must be filtered
- * too — the same exclusions the previous setup.ts check applied.
- */
+// macOS names its child processes in the executable path itself, so the process NAME must be filtered too.
 const isMacChildProcessName = (comm: string): boolean => {
   const lower = comm.toLowerCase();
   return (
@@ -86,13 +46,36 @@ const isMacChildProcessName = (comm: string): boolean => {
   );
 };
 
-/** One running browser process, as much as the platform will tell us. */
 export type BrowserCandidate = {
   readonly exePath?: string;
   readonly explicitUserDataDir?: string;
 };
 
-/** Path comparison that tolerates separator and case differences per platform. */
+// A package upgrade under a running browser makes `/proc/<pid>/exe` read "… (deleted)", which fails to spawn with ENOENT unless the marker comes off.
+const DELETED_SUFFIX = " (deleted)";
+
+export const stripDeletedSuffix = (path: string): string | undefined =>
+  path.endsWith(DELETED_SUFFIX) && path.length > DELETED_SUFFIX.length
+    ? path.slice(0, -DELETED_SUFFIX.length)
+    : undefined;
+
+const exists = async (path: string): Promise<boolean> => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const spawnableExePath = async (raw: string): Promise<string | undefined> => {
+  if (raw.length === 0) return undefined;
+  if (await exists(raw)) return raw;
+  const stripped = stripDeletedSuffix(raw);
+  if (stripped && (await exists(stripped))) return stripped;
+  return undefined;
+};
+
 const samePath = (a: string, b: string): boolean => {
   const norm = (p: string): string => {
     const unified = p.replace(/\\/g, "/").replace(/\/+$/, "");
@@ -101,22 +84,11 @@ const samePath = (a: string, b: string): boolean => {
   return norm(a) === norm(b);
 };
 
-/**
- * Rank a candidate against the user-data-dir the harness is actually connected
- * to. Several Chromium browsers can run at once (Chrome plus Brave, or a second
- * instance on a custom dir), and launching a profile window into the wrong one
- * would open a window the harness cannot see — while disturbing a browser the
- * user never pointed us at.
- */
 export const rankBrowserCandidate = (candidate: BrowserCandidate, preferUserDataDir?: string): number => {
   if (!preferUserDataDir) return 1;
   if (candidate.explicitUserDataDir) {
-    // An explicit dir is decisive in both directions: exact match wins, and a
-    // different one means this is definitively another browser instance.
     return samePath(candidate.explicitUserDataDir, preferUserDataDir) ? 4 : 0;
   }
-  // No flag: the process uses its default dir. Prefer the one whose executable
-  // belongs to the same browser family as the target directory.
   const family = browserNameForUserDataDir(preferUserDataDir).toLowerCase();
   const exe = (candidate.exePath ?? "").toLowerCase();
   if (!exe) return 1;
@@ -127,7 +99,6 @@ export const rankBrowserCandidate = (candidate: BrowserCandidate, preferUserData
   return 1;
 };
 
-/** Extract `--user-data-dir=<path>` from a command line, quoted or bare. */
 export const parseUserDataDirFlag = (commandLine: string): string | undefined => {
   const match = /--user-data-dir=(?:"([^"]*)"|'([^']*)'|(\S+))/.exec(commandLine);
   if (!match) return undefined;
@@ -135,8 +106,6 @@ export const parseUserDataDirFlag = (commandLine: string): string | undefined =>
   return value && value.length > 0 ? value : undefined;
 };
 
-// ── Linux ──────────────────────────────────────────────────────────────────
-
 const collectLinux = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
   let pids: string[];
   try {
@@ -157,20 +126,19 @@ const collectLinux = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
   for (const pid of pids) {
     let cmdline: string;
     try {
-      // /proc/<pid>/cmdline is NUL-separated argv.
       cmdline = (await readFile(`/proc/${pid}/cmdline`, "utf8")).replace(/\0/g, " ").trim();
     } catch {
       continue;
     }
     if (!cmdline || hasChildProcessType(cmdline)) continue;
-    let exePath: string | undefined;
+    let link: string | undefined;
     try {
-      exePath = await readlink(`/proc/${pid}/exe`);
-    } catch {
-      // /proc/<pid>/exe is unreadable for processes we don't own; argv[0] is
-      // the next best thing.
-      exePath = cmdline.split(" ")[0];
-    }
+      link = await readlink(`/proc/${pid}/exe`);
+    } catch {}
+    // Chrome rewrites its argv to the bare executable path, so argv[0] is the live install location when /proc/<pid>/exe is unreadable or stale.
+    const exePath =
+      (link ? await spawnableExePath(link) : undefined) ??
+      (await spawnableExePath(cmdline.split(" ")[0] ?? ""));
     const explicit = parseUserDataDirFlag(cmdline);
     candidates.push({
       ...(exePath ? { exePath } : {}),
@@ -180,8 +148,6 @@ const collectLinux = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
   return candidates;
 };
 
-// ── macOS ──────────────────────────────────────────────────────────────────
-
 const collectDarwin = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
   let lines: string[];
   try {
@@ -206,9 +172,7 @@ const collectDarwin = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
     try {
       const { stdout } = await run("ps", ["-ww", "-o", "args=", "-p", pid], { timeout: EXEC_TIMEOUT_MS });
       args = stdout.trim();
-    } catch {
-      // args are optional — only the --user-data-dir probe needs them
-    }
+    } catch {}
     if (args && hasChildProcessType(args)) continue;
     const explicit = args ? parseUserDataDirFlag(args) : undefined;
     candidates.push({
@@ -219,8 +183,6 @@ const collectDarwin = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
   return candidates;
 };
 
-// ── Windows ────────────────────────────────────────────────────────────────
-
 const POWERSHELL_QUERY = [
   "$ErrorActionPreference='SilentlyContinue';",
   "Get-CimInstance Win32_Process",
@@ -229,7 +191,17 @@ const POWERSHELL_QUERY = [
   "| ConvertTo-Json -Compress",
 ].join(" ");
 
-type WinProcess = { ExecutablePath?: string | null; CommandLine?: string | null };
+const WinProcessSchema = Type.Object(
+  {
+    ExecutablePath: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    CommandLine: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  },
+  { additionalProperties: true },
+);
+
+const WinProcessesSchema = Type.Union([WinProcessSchema, Type.Array(WinProcessSchema)]);
+
+const winProcessesValidator = Compile(WinProcessesSchema);
 
 const collectWin32 = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
   try {
@@ -240,37 +212,31 @@ const collectWin32 = async (): Promise<ReadonlyArray<BrowserCandidate>> => {
     );
     const trimmed = stdout.trim();
     if (trimmed) {
-      const parsed: unknown = JSON.parse(trimmed);
-      // ConvertTo-Json emits an object for a single row, an array for many.
-      const rows: WinProcess[] = Array.isArray(parsed) ? (parsed as WinProcess[]) : [parsed as WinProcess];
-      const candidates = rows
-        .filter((row) => !hasChildProcessType(row.CommandLine ?? ""))
-        .map((row): BrowserCandidate => {
-          const explicit = parseUserDataDirFlag(row.CommandLine ?? "");
-          return {
-            ...(row.ExecutablePath ? { exePath: row.ExecutablePath } : {}),
-            ...(explicit ? { explicitUserDataDir: explicit } : {}),
-          };
-        });
-      if (candidates.length > 0) return candidates;
+      const parsed = parseJson(trimmed, winProcessesValidator);
+      if (parsed.success) {
+        const rows = Array.isArray(parsed.data) ? parsed.data : [parsed.data];
+        const candidates = rows
+          .filter((row) => !hasChildProcessType(row.CommandLine ?? ""))
+          .map((row): BrowserCandidate => {
+            const explicit = parseUserDataDirFlag(row.CommandLine ?? "");
+            return {
+              ...(row.ExecutablePath ? { exePath: row.ExecutablePath } : {}),
+              ...(explicit ? { explicitUserDataDir: explicit } : {}),
+            };
+          });
+        if (candidates.length > 0) return candidates;
+      }
     }
-  } catch {
-    // PowerShell missing or blocked by policy — fall through to tasklist.
-  }
+  } catch {}
 
-  // Liveness-only fallback: tasklist still ships on every supported Windows.
-  // It reveals no path, so the candidate is a bare "something is running".
   try {
     const { stdout } = await run("tasklist.exe", [], { timeout: EXEC_TIMEOUT_MS, windowsHide: true });
     const lower = stdout.toLowerCase();
     if (WIN_IMAGE_NAMES.some((n) => lower.includes(n))) return [{}];
-  } catch {
-    // best-effort
-  }
+  } catch {}
   return [];
 };
 
-/** Installed-browser locations to try when the live process reveals no path. */
 const winInstallCandidates = (): ReadonlyArray<string> => {
   const roots = [
     process.env["PROGRAMFILES"],
@@ -288,7 +254,6 @@ const winInstallCandidates = (): ReadonlyArray<string> => {
   return roots.flatMap((root) => suffixes.map((suffix) => join(root, suffix)));
 };
 
-/** Query the Shell's App Paths registration for a browser's install location. */
 const winRegistryExecutable = async (): Promise<string | undefined> => {
   for (const image of WIN_IMAGE_NAMES) {
     for (const hive of ["HKLM", "HKCU"]) {
@@ -301,23 +266,12 @@ const winRegistryExecutable = async (): Promise<string | undefined> => {
         const match = /REG_[A-Z_]+\s+(.+)$/m.exec(stdout.trim());
         const path = match?.[1]?.trim();
         if (path) return path;
-      } catch {
-        // key absent for this browser/hive — try the next
-      }
+      } catch {}
     }
   }
   return undefined;
 };
 
-// ── Public API ─────────────────────────────────────────────────────────────
-
-/**
- * Live-process facts about the running Chromium-family browser. `running` is
- * derived only from process evidence, never from an install location.
- *
- * `preferUserDataDir` should be the dir the harness is connected to; with more
- * than one browser running it decides which process is described.
- */
 export const detectRunningBrowser = async (preferUserDataDir?: string): Promise<RunningBrowser> => {
   const candidates =
     process.platform === "darwin"
@@ -327,9 +281,11 @@ export const detectRunningBrowser = async (preferUserDataDir?: string): Promise<
         : await collectLinux();
   if (candidates.length === 0) return { running: false };
 
-  let best = candidates[0] as BrowserCandidate;
+  const [first, ...rest] = candidates;
+  if (!first) return { running: false };
+  let best = first;
   let bestRank = rankBrowserCandidate(best, preferUserDataDir);
-  for (const candidate of candidates.slice(1)) {
+  for (const candidate of rest) {
     const rank = rankBrowserCandidate(candidate, preferUserDataDir);
     if (rank > bestRank) {
       best = candidate;
@@ -344,17 +300,12 @@ export const detectRunningBrowser = async (preferUserDataDir?: string): Promise<
   };
 };
 
-/** True when a Chromium-family browser process is running. */
 export const isBrowserRunning = async (): Promise<boolean> => (await detectRunningBrowser()).running;
 
-/**
- * The binary to invoke when opening a window for a chosen profile: the running
- * browser's own executable when known, otherwise a documented install location.
- * Undefined when nothing usable is found.
- */
 export const resolveBrowserExecutable = async (running?: RunningBrowser): Promise<string | undefined> => {
   const detected = running ?? (await detectRunningBrowser());
-  if (detected.exePath) return detected.exePath;
+  const usable = detected.exePath ? await spawnableExePath(detected.exePath) : undefined;
+  if (usable) return usable;
   if (process.platform !== "win32") return undefined;
 
   const fromRegistry = await winRegistryExecutable();
@@ -363,9 +314,7 @@ export const resolveBrowserExecutable = async (running?: RunningBrowser): Promis
     try {
       await access(candidate);
       return candidate;
-    } catch {
-      // not installed here
-    }
+    } catch {}
   }
   return undefined;
 };

package/src/profile/command.ts

@@ -1,27 +1,59 @@
-/**
- * /browser-profile — choose which browser profile the agent works in.
- *
- * The selection is durable (see store.ts) and applies immediately: the current
- * harness tabs are closed and a new window is opened in the chosen profile, so
- * the agent's next action happens where the user just asked for it rather than
- * one session later.
- */
-
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { BrowserClient } from "../client";
 import { discoverEndpoint } from "../cdp/discovery";
 import { type Result, err, ok } from "../util/result";
 import { type BrowserProfile, listProfiles } from "./list";
 import { browserNameForUserDataDir, userDataDirCandidates } from "./paths";
-import { pinFor, promptForProfile } from "./picker";
-import { clearPin, readPin, writePin } from "./store";
-
-/**
- * Which user-data-dir the picker should enumerate: the connected browser's
- * when known, otherwise a running browser's, otherwise the only installed one
- * that actually has profiles.
- */
-export const resolveUserDataDir = async (client: BrowserClient): Promise<Result<string, string>> => {
+import { clearPin, type ProfilePin, readPin, writePin } from "./store";
+
+// `ctx.ui.select` resolves to undefined both on Escape and in non-interactive modes, so "no answer" must mean "change nothing".
+
+const CLEAR_SELECTION_LABEL = "— Clear selection (use whichever window is focused) —";
+
+type ProfileChoice =
+  | { readonly kind: "profile"; readonly profile: BrowserProfile }
+  | { readonly kind: "clear" }
+  | { readonly kind: "cancelled" };
+
+const disambiguate = (profiles: ReadonlyArray<BrowserProfile>): ReadonlyArray<string> => {
+  const counts = new Map<string, number>();
+  for (const p of profiles) counts.set(p.label, (counts.get(p.label) ?? 0) + 1);
+  return profiles.map((p) => ((counts.get(p.label) ?? 0) > 1 ? `${p.label} [${p.dir}]` : p.label));
+};
+
+const promptForProfile = async (
+  ctx: ExtensionContext,
+  profiles: ReadonlyArray<BrowserProfile>,
+  currentPin: ProfilePin | null,
+  title = "Select browser profile",
+): Promise<ProfileChoice> => {
+  if (!ctx.hasUI || profiles.length === 0) return { kind: "cancelled" };
+
+  const labels = disambiguate(profiles);
+  const rows = labels.map((label, i) => {
+    const isPinned = currentPin?.profileDir === profiles[i]?.dir;
+    return isPinned ? `✓ ${label}` : `  ${label}`;
+  });
+  const options = [...rows, CLEAR_SELECTION_LABEL];
+
+  const answer = await ctx.ui.select(title, options);
+  if (answer === undefined) return { kind: "cancelled" };
+  if (answer === CLEAR_SELECTION_LABEL) return { kind: "clear" };
+
+  const index = options.indexOf(answer);
+  const profile = index >= 0 ? profiles[index] : undefined;
+  if (!profile) return { kind: "cancelled" };
+  return { kind: "profile", profile };
+};
+
+const pinFor = (userDataDir: string, profile: BrowserProfile): ProfilePin => ({
+  userDataDir,
+  profileDir: profile.dir,
+  label: profile.label,
+  savedAt: new Date().toISOString(),
+});
+
+const resolveUserDataDir = async (client: BrowserClient): Promise<Result<string, string>> => {
   const connected = client.userDataDir();
   if (connected) return ok(connected);
 
@@ -43,7 +75,6 @@ export const resolveUserDataDir = async (client: BrowserClient): Promise<Result<
   );
 };
 
-/** Enumerate profiles for the resolved dir, or explain why we cannot. */
 const loadProfiles = async (
   client: BrowserClient,
 ): Promise<Result<{ userDataDir: string; profiles: ReadonlyArray<BrowserProfile> }, string>> => {
@@ -56,11 +87,6 @@ const loadProfiles = async (
   return ok({ userDataDir: dir.data, profiles });
 };
 
-/**
- * Re-seed the live session so the new profile takes effect now. Closing the
- * owned tabs and restarting the client makes start() open a window in the
- * pinned profile and attach to it.
- */
 const applyToLiveSession = async (client: BrowserClient): Promise<Result<void, string>> => {
   if (!client.status().alive) return ok(undefined);
   await client.closeOwnedTabs();
@@ -127,11 +153,6 @@ export function registerProfileCommand(pi: ExtensionAPI, client: BrowserClient):
   });
 }
 
-/**
- * First-run prompt used by setup: pick a profile when none is pinned yet.
- * Returns a note to append to the setup output; the caller always continues,
- * because a cancelled or unavailable picker must leave existing behavior intact.
- */
 export const promptForProfileIfUnset = async (
   client: BrowserClient,
   ctx: ExtensionContext | undefined,

package/src/profile/launch.ts

@@ -1,19 +1,5 @@
-/**
- * Opening a browser window for a chosen profile.
- *
- * CDP cannot do this: `Target.createTarget` rejects another profile's
- * browserContextId ("Failed to find browser context with id"), and a bare
- * createTarget lands in `defaultBrowserContextId`, which follows window focus.
- * The only way in is the browser's own command line — Chromium's
- * ProcessSingleton hands a second launch's argv to the running browser, which
- * "does what it would have done", i.e. opens a window in `--profile-directory`.
- *
- * The window is then identified by a unique `file://` sentinel page. That
- * matters: a bare `about:blank#token` argument is discarded by Chrome (it opens
- * chrome://newtab instead), so the token has to ride on a real URL. Polling for
- * the sentinel URL — rather than diffing the target list — also keeps
- * identification correct when the user opens tabs at the same moment.
- */
+// CDP cannot open a window in another profile, so this goes through the command line: ProcessSingleton hands the argv to the running browser.
+// The sentinel must ride on a real `file://` URL — Chrome discards a bare `about:blank#token` argument and opens chrome://newtab instead.
 
 import { spawn, type ChildProcess } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -24,23 +10,13 @@ import { pathToFileURL } from "node:url";
 import { type Result, err, ok } from "../util/result";
 
 export type ProfileWindowRequest = {
-  /** Browser binary to invoke. */
   readonly exePath: string;
-  /** Profile subdirectory, e.g. "Profile 1". */
   readonly profileDir: string;
-  /**
-   * Only set when the RUNNING browser was launched with an explicit
-   * --user-data-dir. ProcessSingleton keys on this path, so passing one that
-   * differs by case or normalisation would start a second browser instead of
-   * delegating to the running one.
-   */
   readonly explicitUserDataDir?: string;
 };
 
 export type ProfileWindowHandle = {
-  /** file:// URL that will appear as the new window's page target. */
   readonly sentinelUrl: string;
-  /** Remove the sentinel file. Safe to call more than once. */
   readonly cleanup: () => Promise<void>;
   readonly kill: () => void;
 };
@@ -49,10 +25,6 @@ const SENTINEL_HTML = (token: string): string =>
   `<!doctype html><meta charset="utf-8"><title>${token}</title>` +
   `<body style="font:14px system-ui;padding:2rem;color:#555">pi browser harness — opening this profile…</body>`;
 
-/**
- * Ask the running browser to open a window in `profileDir`, marked with a
- * unique sentinel page the caller can then find over CDP.
- */
 export const openProfileWindow = async (
   req: ProfileWindowRequest,
 ): Promise<Result<ProfileWindowHandle, string>> => {
@@ -69,29 +41,39 @@ export const openProfileWindow = async (
   if (req.explicitUserDataDir) args.push(`--user-data-dir=${req.explicitUserDataDir}`);
   args.push(`--profile-directory=${req.profileDir}`, "--new-window", sentinelUrl);
 
-  let child: ChildProcess | null = null;
+  let child: ChildProcess;
   try {
-    // No shell: arguments are passed as an array, so profile names and paths
-    // containing spaces survive intact on every platform.
     child = spawn(req.exePath, args, { detached: true, stdio: "ignore" });
-    child.unref();
-    // The launcher process exits as soon as the running browser takes over the
-    // command line; an error here means the binary itself could not be started.
-    child.on("error", () => {});
   } catch (e) {
     await rm(file, { force: true }).catch(() => {});
     return err(`could not launch ${req.exePath}: ${e instanceof Error ? e.message : String(e)}`);
   }
 
+  // spawn() reports a bad binary asynchronously as an 'error' event rather than throwing; unhandled, an ENOENT looked like the 15s sentinel timeout.
+  const spawnFailure = await new Promise<string | undefined>((resolve) => {
+    child.once("spawn", () => resolve(undefined));
+    child.once("error", (e: Error) => resolve(e.message));
+  });
+  // A later 'error' event with no listener would throw, so keep one attached for the detached launcher's lifetime.
+  child.on("error", () => {});
+  child.unref();
+
+  if (spawnFailure) {
+    await rm(file, { force: true }).catch(() => {});
+    return err(`could not launch ${req.exePath}: ${spawnFailure}`);
+  }
+
+  let live: ChildProcess | null = child;
+
   return ok({
     sentinelUrl,
     cleanup: async () => {
       await rm(file, { force: true }).catch(() => {});
     },
     kill: () => {
-      if (child) {
-        try { child.kill("SIGTERM"); } catch {}
-        child = null;
+      if (live) {
+        try { live.kill("SIGTERM"); } catch {}
+        live = null;
       }
     },
   });