agent-dag 3.0.0 → 3.2.0

package/src/server/log-tail.mjs

@@ -0,0 +1,139 @@
+// Reading a log backwards, because only its end is ever kept.
+//
+// #742. The event log is replayed before the port opens, and the replay parsed
+// every line in it from the beginning — 12,079 lines and 31 MB on the machine
+// this was measured on, 690ms of JSON.parse, growing with every session until
+// rotation cuts it at 50 MB. The ring it fills holds MAX_BUFFER = 2000 events.
+// So roughly five sixths of that work was parsing events that were evicted by
+// the ones parsed after them, on the critical path of a boot, every time.
+//
+// Reading from the end fixes the asymmetry rather than the constant: the loop
+// stops as soon as the ring is full, so the cost becomes a property of the ring
+// instead of a property of how long the user has been running the deck. When
+// the ring cannot be filled — a young log, or a workspace-scoped deck whose
+// events are a thin slice of a shared one — it reads all the way back to the
+// start and costs exactly what the forward read did. There is no case where
+// this is slower and no case where it sees less.
+//
+// Bytes, not characters. Lines are split on 0x0A and decoded one at a time,
+// which is safe in UTF-8 because no byte of a multi-byte sequence can be 0x0A —
+// a chunk boundary landing inside a three-byte character joins back together
+// before anything is decoded. Decoding the chunk first and splitting the string
+// is what would corrupt it, and it is the obvious way to write this.
+import { open } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+
+/** One line out of a buffer, minus the carriage return a CRLF file leaves on
+ *  the end of it. Sliced before decoding — see the note about 0x0A above. */
+function line(buf, from, to) {
+  const end = to > from && buf[to - 1] === 0x0D ? to - 1 : to;
+  return buf.subarray(from, end).toString("utf8");
+}
+
+/** How much is read at a time. One megabyte holds about 400 events at the size
+ *  this log's lines actually run to, so a full ring is usually five reads. */
+export const CHUNK_BYTES = 1 << 20;
+
+/**
+ * The file's lines, newest first, as an async iterable.
+ *
+ * Stops reading the moment the consumer stops asking — that is the whole point,
+ * and it is why this is a generator rather than a function returning an array.
+ * A `break` in the caller closes the handle through the generator's `finally`.
+ *
+ * Lines are yielded WITHOUT their newline, and the sequence is exactly the
+ * reverse of what `readline` yields reading the same file forwards — empty
+ * lines included, and a trailing newline at EOF is a line terminator rather
+ * than an empty line after it. A CRLF file reads the same as it does forwards,
+ * because the carriage return is stripped here too. That equivalence is the
+ * contract, and it is what the round-trip case in the test file checks against
+ * readline itself rather than against a hand-written expectation.
+ *
+ * The ONE difference: `readline` also breaks on a lone carriage return, for the
+ * sake of files written by software that predates OS X. Walking those backwards
+ * would mean scanning every byte of every chunk instead of asking Buffer for
+ * the next 0x0A, and nothing that writes a line into this deck's log has
+ * produced one since 2001. A file full of lone carriage returns reads here as a
+ * single very long line, which JSON.parse then declines — one skipped line,
+ * counted and reported, rather than a wrong answer.
+ */
+export async function* linesFromEnd(filePath, { chunkBytes = CHUNK_BYTES, openFile = open } = {}) {
+  const fh = await openFile(filePath, "r");
+  try {
+    const { size } = await fh.stat();
+    let pos = size;
+    // The bytes at the front of what has been read that have no newline before
+    // them yet: the first line of the chunk, which may continue into the chunk
+    // that comes before it. Carried, never yielded, until a newline turns up or
+    // the start of the file does.
+    let carry = Buffer.alloc(0);
+    // The newline that ends the last line is a terminator, not the start of an
+    // empty line after it. Trimmed once, on the chunk that holds EOF.
+    let atEof = true;
+
+    while (pos > 0) {
+      const len = Math.min(chunkBytes, pos);
+      pos -= len;
+      const buf = Buffer.alloc(len);
+      // Node reads short at the end of a file and at a pipe; a regular file
+      // opened for reading at a known offset does not, but the loop is written
+      // to survive it rather than to assume it.
+      let got = 0;
+      while (got < len) {
+        const { bytesRead } = await fh.read(buf, got, len - got, pos + got);
+        if (bytesRead === 0) break;
+        got += bytesRead;
+      }
+      const hay = carry.length ? Buffer.concat([buf.subarray(0, got), carry]) : buf.subarray(0, got);
+
+      // Walk the newlines from the end. `end` is one past the last byte of the
+      // line being cut; every cut is a complete line, because everything to its
+      // right has already been yielded.
+      let end = hay.length;
+      if (atEof && end > 0 && hay[end - 1] === 0x0A) end--;
+      atEof = false;
+      while (end > 0) {
+        const nl = hay.lastIndexOf(0x0A, end - 1);
+        if (nl === -1) break;
+        yield line(hay, nl + 1, end);
+        end = nl;
+      }
+      carry = hay.subarray(0, end);
+    }
+
+    // Whatever is left has the start of the file in front of it, so it is a
+    // whole line — and an EMPTY one is still a line, which is why this is not
+    // conditional on `carry.length`. A file that opens with a newline opens
+    // with an empty line, and reading it forwards says so.
+    if (size > 0) yield line(carry, 0, carry.length);
+  } finally {
+    await fh.close().catch(() => {});
+  }
+}
+
+/**
+ * The same file, the ordinary way round.
+ *
+ * Here rather than at the one call site so the two readers sit together and a
+ * reader of either finds the other: replayLog picks between them per boot, on
+ * whether its scope predicate can be fed a log backwards, and a pair of
+ * functions in one file is what makes that choice legible.
+ *
+ * Streams, so a scoped deck on a 50 MB log holds one line at a time exactly as
+ * it did before any of this.
+ */
+export async function* linesFromStart(filePath) {
+  const input = createReadStream(filePath, { encoding: "utf8" });
+  const rl = createInterface({ input });
+  try {
+    for await (const line of rl) yield line;
+  } finally {
+    // Both, and the stream second. `rl.close()` stops the interface and leaves
+    // the descriptor under it open, which is fine for the one caller here
+    // because it reads to the end — and is a leak the day somebody breaks out
+    // of this loop the way the backwards reader is designed to be broken out of.
+    rl.close();
+    input.destroy();
+  }
+}

package/src/server/macmon.mjs

@@ -0,0 +1,299 @@
+// The one thermal reading a Mac will not give up on its own.
+//
+// #747. On Apple Silicon there is no command shipped with macOS that prints a
+// CPU or GPU temperature. `powermetrics` needs root. `pmset -g therm` records
+// nothing on M-series and answers "No CPU power status has been recorded", so
+// there is no throttle row either. The AGX driver does not publish the
+// `"Temperature(C)"` that ioreg reads on Intel GPUs. And the SMC keys changed
+// with M1 and are inconsistent between models sharing one chip — an M1 Mac mini
+// uses different FourCCs from an M1 MacBook Pro, with no public mapping — so
+// there is nothing to hard-code either.
+//
+// The sensors are reachable, and without root: they come through a HID sensor
+// hub, which is a private C API. Every tool that shows a temperature on Apple
+// Silicon calls it, and every one of them is native code. A Node process cannot,
+// and this package has zero runtime dependencies, which is worth more than a
+// number.
+//
+// So it asks a tool the user already has, exactly the way the deck already asks
+// `cswap` about accounts and `ccusage` about spend. `macmon` is in
+// homebrew-core — `brew install macmon`, no third-party tap — runs without
+// sudo, supports M1 through M5, and prints JSON.
+//
+// COSTS INTEL NOTHING. This is reached only when ioreg has already answered
+// with nothing, which on an Intel Mac it never does. Deliberately not gated on
+// `process.arch`: a Node built for x64 running under Rosetta on an Apple
+// Silicon Mac reports "x64", and gating on that would skip the one machine this
+// exists for.
+import { run } from "./exec.mjs";
+import { renameWithRetry } from "./installer.mjs";
+import { existsSync } from "node:fs";
+import { chmod, copyFile, mkdir, mkdtemp, open, rm, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const TOOL_DIR   = join(homedir(), ".agents-deck", "tools");
+const MACMON_DIR = join(TOOL_DIR, "macmon");
+
+/** Where the deck puts its own copy, and where brew puts one on both prefixes —
+ *  because ~/.local/bin's lesson applies here too: a tool the user installed is
+ *  not always on the PATH of the shell that launched the deck. Ours first, so a
+ *  machine that has both uses the one whose version this code was written
+ *  against. Apple Silicon's brew prefix before Intel's; that is the only
+ *  machine that reaches this file. */
+export const MACMON_CANDIDATES = [
+  join(MACMON_DIR, "macmon"),
+  "/opt/homebrew/bin/macmon",
+  "/usr/local/bin/macmon",
+];
+
+/** One sample, then exit. `-i` is the sampling window and its default is a full
+ *  second; 200ms is long enough for an average the tool is willing to publish
+ *  and short enough that a poll every ten seconds costs nothing anybody can
+ *  feel. */
+export const MACMON_ARGS = ["pipe", "-s", "1", "-i", "200"];
+
+/**
+ * The resolution, remembered — including the failure.
+ *
+ * `null` means "not looked yet" and `false` means "looked, not there", which is
+ * the distinction that keeps a machine without macmon from paying a lookup
+ * every ten seconds forever. cswapBin memoizes only success and re-probes on
+ * failure; that is right for a tool the deck installs and wrong for one it
+ * never will.
+ */
+let _bin = null;
+
+/** Forget it. For the test, and for the day something installs macmon while the
+ *  deck is up — nothing calls this on that path yet, and it is one line. */
+export function resetMacmonBin() { _bin = null; }
+
+export async function macmonBin({
+  exists = existsSync, probe = defaultProbe, candidates = MACMON_CANDIDATES,
+} = {}) {
+  if (_bin !== null) return _bin || null;
+  // The bare name first, because PATH is the cheap answer and the one a user
+  // who installed it themselves will usually have.
+  if (await probe("macmon")) return (_bin = "macmon");
+  for (const c of candidates) {
+    if (exists(c) && await probe(c)) return (_bin = c);
+  }
+  _bin = false;
+  return null;
+}
+
+async function defaultProbe(bin) {
+  return (await run(bin, ["--version"], { timeout: 4_000 })).ok;
+}
+
+/**
+ * CPU and GPU degrees out of one `macmon pipe` sample.
+ *
+ * The shape is `{ temp: { cpu_temp_avg, gpu_temp_avg } }`, both in Celsius —
+ * read off macmon's own `TempMetrics` struct rather than guessed from an
+ * example, because a field renamed upstream should read as "no sensor" and not
+ * as zero.
+ *
+ * A zero is dropped rather than shown. macmon defaults both fields to 0.0 and
+ * fills what it read, so a machine that answered for the CPU and not the GPU
+ * arrives as `{ cpu_temp_avg: 47.3, gpu_temp_avg: 0 }` — and 0 °C is not a
+ * reading, it is the absence of one wearing a number.
+ */
+export function tempsFromMacmonJson(json) {
+  let d;
+  try { d = typeof json === "string" ? JSON.parse(json) : json; }
+  catch { return {}; }
+  const t = d?.temp;
+  if (!t || typeof t !== "object") return {};
+  const out = {};
+  for (const [key, field] of [["cpu", "cpu_temp_avg"], ["gpu", "gpu_temp_avg"]]) {
+    const v = Number(t[field]);
+    // The same plausibility floor the rest of the thermal code uses, stated
+    // here rather than imported so this module has no opinion to disagree with.
+    if (Number.isFinite(v) && v > 0 && v < 150) out[key] = Math.round(v);
+  }
+  return out;
+}
+
+/**
+ * Ask macmon, or answer nothing.
+ *
+ * Never throws and never waits long: `run` does not reject, the sample is
+ * capped, and a machine without macmon returns before it spawns anything at
+ * all after the first lookup.
+ */
+export async function readMacmonTemps(deps = {}) {
+  const bin = await macmonBin(deps);
+  if (!bin) return {};
+  const r = await run(bin, MACMON_ARGS, { timeout: 6_000 });
+  if (!r.ok) return {};
+  // `pipe` prints one JSON object per sample and `-s 1` asks for one, but a
+  // build that ever printed a banner first would put it on the same stream.
+  const line = r.stdout.split("\n").find(l => l.trim().startsWith("{"));
+  return line ? tempsFromMacmonJson(line) : {};
+}
+
+// ── fetching it, so the user does not have to ────────────────────────────────
+//
+// `npx ccdeck` should work, and on Apple Silicon "work" includes the two rows
+// this file exists for. Telling somebody to run a brew command first is a step,
+// and a step is a thing most people will not take.
+//
+// So the deck fetches macmon the same way it already fetches uv — see
+// uv-bootstrap.mjs, whose shape this follows including the parts that were
+// learned the hard way. NOT through Homebrew: a machine without brew would then
+// need brew installed first, which is a very large thing to do to somebody who
+// asked for a dashboard.
+//
+// WHAT MAKES THIS SAFE TO RUN ON SOMEBODY'S MACHINE, each verified against the
+// real release rather than assumed:
+//
+//   * There is a prebuilt binary. `macmon-v0.8.2.tar.gz`, 746 KB, containing a
+//     `Mach-O 64-bit executable arm64`. No compiler, no toolchain, no Rust.
+//   * There is a checksum. The release publishes no `.sha256` file, but the
+//     GitHub releases API carries a `digest` field per asset, and it matched
+//     the bytes actually downloaded. An unverified binary is not something to
+//     run on someone's machine, which is uv-bootstrap's rule and is kept here.
+//   * It will execute. Apple Silicon refuses an unsigned binary; this one is
+//     `adhoc, linker-signed`, which is what the Rust toolchain emits and what
+//     macOS accepts. And a programmatic download carries no
+//     com.apple.quarantine — only com.apple.provenance, which blocks nothing —
+//     so there is no Gatekeeper prompt and nothing for the user to click.
+//
+// NEVER ON THE BOOT'S CRITICAL PATH. It is started by the thermal sampler, on
+// the tick where it found no reading, and nothing waits for it. The boot was
+// just taught not to wait for an install (#742) and this does not undo that.
+
+const RELEASE_API = "https://api.github.com/repos/vladkens/macmon/releases/latest";
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+
+/** One attempt per process. A machine that is offline, or behind a proxy that
+ *  refuses GitHub, must not re-download every ten seconds for as long as the
+ *  deck runs — and a success does not need a second attempt either. */
+let _fetched = false;
+
+/** Cleared with the resolution, so a test can run the whole thing twice. */
+export function resetMacmonFetch() { _fetched = false; }
+
+/**
+ * The asset to download, out of what the release actually published.
+ *
+ * Pure and exported: this is the part that has to keep working when the project
+ * changes its file names, and the only way to check that from here is to feed
+ * it a release document. `digest` is `sha256:<hex>` — the prefix is part of the
+ * field and dropping it silently would make every download fail verification.
+ */
+export function macmonAsset(release) {
+  const tag = release?.tag_name;
+  const a = (release?.assets ?? []).find(x => typeof x?.name === "string" && x.name.endsWith(".tar.gz"));
+  if (!a?.browser_download_url) return null;
+  const m = /^sha256:([0-9a-f]{64})$/.exec(String(a.digest ?? ""));
+  if (!m) return null;
+  return { version: typeof tag === "string" ? tag : "unknown", url: a.browser_download_url, sha256: m[1] };
+}
+
+/** A macmon this function installed earlier, or null. */
+export function existingBootstrappedMacmon() {
+  const bin = join(MACMON_DIR, "macmon");
+  return existsSync(bin) ? bin : null;
+}
+
+/**
+ * Download macmon into ~/.agents-deck/tools/macmon.
+ *
+ * Returns `{ ok: true, bin, version }` or `{ ok: false, reason }`, and never
+ * throws: every caller treats a missing macmon as an ordinary state.
+ *
+ * Apple Silicon only, because that is the only build published and the only
+ * machine that has anything to gain — an Intel Mac already answers through
+ * ioreg and never reaches this file at all.
+ */
+export async function bootstrapMacmon({
+  platform = process.platform, env = process.env, fetchFn = fetch, dir = MACMON_DIR,
+} = {}) {
+  if (platform !== "darwin") return { ok: false, reason: "unsupported_platform" };
+  // Both switches, for the reason uv-bootstrap has both: downloading an
+  // executable is a bigger step than installing a package with a tool the user
+  // already chose, so somebody may want the managed installs and not this.
+  if (env.AGENTS_DECK_NO_INSTALL === "1") return { ok: false, reason: "installs_disabled" };
+  if (env.AGENTS_DECK_NO_DOWNLOAD === "1") return { ok: false, reason: "download_disabled" };
+  if (_fetched) return { ok: false, reason: "already_tried" };
+  _fetched = true;
+
+  let staging = null;
+  let partial = null;
+  try {
+    const res = await fetchFn(RELEASE_API, {
+      headers: { accept: "application/vnd.github+json", "user-agent": "agents-deck" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) return { ok: false, reason: "release_lookup_failed" };
+    const asset = macmonAsset(await res.json());
+    // No published digest means no way to know what was downloaded. There is no
+    // fallback version here on purpose: uv can have one because any recent uv
+    // installs claude-swap, while a hard-coded macmon URL would be a checksum
+    // this file invented for bytes it has never seen.
+    if (!asset) return { ok: false, reason: "no_verifiable_asset" };
+
+    const dl = await fetchFn(asset.url, {
+      redirect: "follow",
+      headers: { "user-agent": "agents-deck" },
+      signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+    });
+    if (!dl.ok) return { ok: false, reason: "download_failed" };
+    const archive = Buffer.from(await dl.arrayBuffer());
+    if (createHash("sha256").update(archive).digest("hex") !== asset.sha256) {
+      return { ok: false, reason: "checksum_mismatch" };
+    }
+
+    // mkdtemp under a directory the user already owns, for every reason
+    // uv-bootstrap gives: the name cannot be guessed, and mkdtemp CREATES
+    // rather than accepting a directory somebody else made.
+    // Staged beside the destination rather than in the system temp directory,
+    // so the rename below is same-filesystem and therefore atomic.
+    await mkdir(dir, { recursive: true });
+    staging = await mkdtemp(join(dir, "macmon-staging-"));
+    const archivePath = join(staging, "macmon.tar.gz");
+    await writeFile(archivePath, archive);
+    if (!(await run("tar", ["-xzf", archivePath, "-C", staging], { timeout: 60_000 })).ok) {
+      return { ok: false, reason: "extract_failed" };
+    }
+
+    // The archive is flat — readme.md, LICENSE, macmon — so this is a name
+    // rather than a search. It is checked instead of assumed because a layout
+    // change upstream should read as "not in the archive", not as a crash.
+    const found = join(staging, "macmon");
+    if (!existsSync(found)) return { ok: false, reason: "not_in_archive" };
+
+    // Copied to a name of its own inside the destination — same filesystem, so
+    // the rename below is the atomic kind — and only becomes `macmon` once it
+    // is whole, flushed, executable, and has answered `--version`. Interrupt
+    // this and all that is left is an inert temp file.
+    partial = join(dir, `.macmon-${process.pid}-${Date.now().toString(36)}`);
+    await copyFile(found, partial);
+    const handle = await open(partial, "r+");
+    try { await handle.sync(); } finally { await handle.close(); }
+    await chmod(partial, 0o755);
+
+    // The binary is adhoc/linker-signed and carries no quarantine, so this
+    // should simply run — and if some future build does not, the deck finds out
+    // here rather than by leaving a file every later boot trusts.
+    if (!(await run(partial, ["--version"], { timeout: 20_000 })).ok) {
+      return { ok: false, reason: "does_not_run" };
+    }
+
+    const dest = join(dir, "macmon");
+    await renameWithRetry(partial, dest);
+    partial = null;
+    // The resolution memo remembers a failure, and the failure it remembers is
+    // "there is no macmon". There is one now.
+    resetMacmonBin();
+    return { ok: true, bin: dest, version: asset.version };
+  } catch (err) {
+    return { ok: false, reason: "error", detail: String(err?.message ?? err).slice(0, 200) };
+  } finally {
+    if (staging) await rm(staging, { recursive: true, force: true, maxRetries: 10, retryDelay: 25 }).catch(() => {});
+    if (partial) await rm(partial, { force: true }).catch(() => {});
+  }
+}

package/src/server/open-url.mjs

@@ -0,0 +1,226 @@
+// Opening the browser, without the ten packages it used to cost.
+//
+// `open@10` was this package's ONLY runtime dependency, and it brought nine
+// more with it — bundle-name, default-browser, default-browser-id,
+// define-lazy-prop, is-docker, is-inside-container, is-wsl, run-applescript,
+// wsl-utils. Ten tarballs to fetch, extract and link on a machine whose npm
+// cache is empty, for one call, made once, whose whole job is to hand a
+// localhost URL to whatever the desktop already uses. On a fast link that is a
+// second; on the links the people who reported a hung `npx ccdeck` are on, it
+// is ten more round trips before the deck's own tarball is even unpacked.
+//
+// What it did that is worth keeping is the platform knowledge, and that is
+// small enough to hold here: three commands, plus the WSL case where
+// `process.platform` says linux and the browser is on the Windows side.
+//
+// DELIBERATELY FIRE AND FORGET. `open` returned a promise the boot awaited;
+// nothing downstream of that await needed the child, and a launcher that takes
+// its time — xdg-open on a machine with no desktop session hunting through
+// every handler it knows — held the boot behind it. Here the candidates are
+// tried in order, the failures move to the next one on their own, and the boot
+// never waits for any of it.
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+/** How long a launcher gets to prove it worked before the next one is tried.
+ *  A launcher that is still running is a launcher that found something: macOS
+ *  `open` and cmd's `start` both exit at once, and xdg-open stays up as the
+ *  browser's parent. So only an EARLY non-zero exit moves on. */
+export const LAUNCH_GRACE_MS = 1_500;
+
+/**
+ * Is this a Linux that is really Windows?
+ *
+ * WSL reports `process.platform === "linux"`, has no desktop session of its
+ * own on a default install, and its browser lives on the Windows side — so
+ * xdg-open there either is not installed or opens nothing anybody can see.
+ * Both signals are read because either can be absent: the env var is set by
+ * the WSL launcher and lost by anything that scrubs the environment, and
+ * /proc/version is the kernel's own answer and cannot be.
+ */
+export function isWsl(platform = process.platform, env = process.env, readProcVersion = defaultProcVersion) {
+  if (platform !== "linux") return false;
+  if (env.WSL_DISTRO_NAME || env.WSL_INTEROP) return true;
+  return /microsoft/i.test(readProcVersion());
+}
+
+function defaultProcVersion() {
+  try {
+    return readFileSync("/proc/version", "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * The launchers to try for `url`, best first.
+ *
+ * A list rather than one answer, because every platform below has a case where
+ * the first choice is missing: a Linux without xdg-utils, a WSL without
+ * wslview, a Windows whose comspec has been moved. Each entry is exactly what
+ * `spawn` is given, so the test can read the command line rather than infer it.
+ *
+ * Exported with platform and env as parameters for the reason exec.mjs exports
+ * its own that way: the Windows and Linux answers have to be checkable from the
+ * Mac this is written on.
+ */
+export function launchers(url, { platform = process.platform, env = process.env, wsl } = {}) {
+  const inWsl = wsl === undefined ? isWsl(platform, env) : wsl;
+
+  if (platform === "darwin") {
+    // The absolute path first: `open` is also a shell builtin in a few setups
+    // and a user's own script called `open` on the PATH is not unheard of, and
+    // /usr/bin/open has been on every macOS this package supports.
+    return [
+      { file: "/usr/bin/open", args: [url] },
+      { file: "open", args: [url] },
+    ];
+  }
+
+  if (platform === "win32") {
+    // PowerShell FIRST, and this order is the one thing here that was decided by
+    // evidence rather than by taste.
+    //
+    // `open@10` — the dependency this file replaces — launches a Windows URL
+    // through `powershell -EncodedCommand` running `Start "<url>"`. That is what
+    // every ccdeck install on Windows has been using, so it is the path with a
+    // year of field evidence behind it and `cmd /c start` has none.
+    //
+    // And the fallback below cannot rescue a wrong first choice. `start` exits 0
+    // whether or not anything opened — measured on a real Windows 10 box, exit
+    // code 0 with no browser process created — so a candidate list that led with
+    // it would never reach a second candidate, however badly the first had done.
+    // Leading with the one whose failure is visible is the only ordering where
+    // having a fallback means anything.
+    //
+    // The cost is PowerShell's startup, a few hundred milliseconds, and it is
+    // paid by nobody: openUrl does not wait for the launcher and the boot does
+    // not wait for openUrl.
+    const tries = [{
+      file: "powershell.exe",
+      // The URL as its own argv entry rather than inside a script string, where
+      // `;` and `&` are PowerShell's own operators.
+      args: ["-NoProfile", "-NonInteractive", "-Command", "Start-Process", url],
+    }];
+    const viaCmd = startCommand(url, env);
+    tries.push(viaCmd);
+    // comspec is read by startCommand, and a comspec pointing somewhere that is
+    // no longer there is the one way that line fails on a machine which is
+    // otherwise fine. The bare name is what the PATH would have answered.
+    if (viaCmd.file.toLowerCase() !== "cmd.exe") tries.push(startCommand(url, env, "cmd.exe"));
+    return tries;
+  }
+
+  if (inWsl) {
+    return [
+      // Ships with wslu and is what a WSL user's own `xdg-open` is usually
+      // symlinked to anyway. It knows how to hand a URL across the boundary.
+      { file: "wslview", args: [url] },
+      // No wslu: go to Windows directly. cmd.exe is reachable from WSL through
+      // the interop path and needs no PATH entry of its own.
+      startCommand(url, env, "/mnt/c/Windows/System32/cmd.exe"),
+      startCommand(url, env, "cmd.exe"),
+      // Last, and only useful on a WSL that really does run a desktop.
+      { file: "xdg-open", args: [url] },
+    ];
+  }
+
+  // Plain Linux, and every other Unix. xdg-open is the standard answer; the
+  // rest are the ones that exist on machines that never installed xdg-utils,
+  // in the order of how likely they are to be configured rather than merely
+  // present.
+  return [
+    { file: "xdg-open", args: [url] },
+    { file: "gio", args: ["open", url] },
+    { file: "x-www-browser", args: [url] },
+    { file: "sensible-browser", args: [url] },
+    { file: "wslview", args: [url] },
+  ];
+}
+
+/**
+ * `start` the way cmd.exe needs to be given it.
+ *
+ * Three details, each of which is a bug if it is missing. The empty `""` is the
+ * window TITLE — `start "http://…"` opens a console window titled with the URL
+ * and nothing else happens. The URL is quoted so an `&` in a query string ends
+ * the argument instead of the command. And `windowsVerbatimArguments` stops
+ * Node quoting the line a second time, which is exactly what exec.mjs's
+ * `viaCmd` does for the same reason.
+ */
+export function startCommand(url, env = process.env, comspec) {
+  const shell = comspec || env.comspec || env.ComSpec || "cmd.exe";
+  return {
+    file: shell,
+    args: ["/d", "/s", "/c", `start "" "${url}"`],
+    opts: { windowsVerbatimArguments: true },
+  };
+}
+
+/**
+ * Refuse anything that is not an http(s) URL.
+ *
+ * The one caller passes a localhost address it built itself, so this is not
+ * guarding against a hostile input today — it is guarding against the day a
+ * second caller passes a path, because every launcher above would happily open
+ * it and `start` would run it.
+ */
+export function isOpenable(url) {
+  try {
+    const u = new URL(String(url));
+    return u.protocol === "http:" || u.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Hand `url` to the desktop. Returns nothing, waits for nothing, throws never.
+ *
+ * The boot calls this between binding the port and starting the pulse line, and
+ * neither of those has anything to learn from how it went — a browser that does
+ * not open leaves a URL on screen that the user can click or paste, which is
+ * the same recovery an error row would have offered.
+ */
+export function openUrl(url, { platform = process.platform, env = process.env, spawnFn = spawn } = {}) {
+  if (!isOpenable(url)) return;
+  const tries = launchers(url, { platform, env });
+
+  const attempt = (i) => {
+    if (i >= tries.length) return;
+    const { file, args, opts } = tries[i];
+    let child;
+    try {
+      child = spawnFn(file, args, {
+        stdio: "ignore",
+        // The launcher outlives us on purpose: xdg-open is the browser's parent
+        // process on a cold start, and a deck stopped with Ctrl+C two seconds
+        // later should not take the window with it. Not on Windows, where a
+        // detached child is a child with its own console — the thing
+        // windowsHide exists to prevent.
+        detached: platform !== "win32",
+        windowsHide: true,
+        ...opts,
+      });
+    } catch {
+      attempt(i + 1);
+      return;
+    }
+    // ENOENT and EACCES both land here rather than throwing, because the failure
+    // happens after spawn returns.
+    child.on("error", () => attempt(i + 1));
+    // An early non-zero exit is xdg-open saying it found no handler (exit 3) or
+    // cmd saying it could not find `start`. A launcher still alive after the
+    // grace period is one that worked, so the timer is what closes the question.
+    let open = true;
+    const settled = setTimeout(() => { open = false; }, LAUNCH_GRACE_MS);
+    settled.unref?.();
+    child.on("exit", (code) => {
+      clearTimeout(settled);
+      if (open && code !== 0) attempt(i + 1);
+    });
+    child.unref?.();
+  };
+
+  attempt(0);
+}