@verax-ai/body 0.3.0 → 0.4.0

package/dist/desktop.js

@@ -1,10 +1,23 @@
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, unlinkSync } from "node:fs";
 import { get } from "node:http";
-import { createConnection } from "node:net";
-import { dirname, join } from "node:path";
+import { createConnection, createServer } from "node:net";
+import { basename, dirname, join, parse, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { DESKTOP_PARENT_PID } from "./desktop-parent.js";
+import { defaultExec, foreignAclPrincipals, posixOthersCanReplace, readSddlBatch, restrictToOwnerWin32, sddlOwner, systemToolEnv, systemToolPath, toolArgv, windowsDirectorySids, windowsInvokingSid, windowsUserCanWrite, } from "./install.js";
+import { hasRegisteredOperator } from "./operator-credentials.js";
 import { pidAlive, readLockFile } from "./unlock.js";
+/** One stderr line when this state has no enrolled operator. */
+export const DESKTOP_PASSKEY_HINT = "the panel reads the ledger after a passkey sign-in; run verax operator enroll\n";
+/**
+ * The credentials file is written only when an operator enrolls. Its presence
+ * is the whole answer; a missing file means the panel's audit doors will
+ * refuse the session that has no passkey.
+ */
+export function desktopPasskeyHint(stateDir) {
+    return hasRegisteredOperator(stateDir) ? null : DESKTOP_PASSKEY_HINT;
+}
 const here = dirname(fileURLToPath(import.meta.url));
 export function resolveRepoRoot() {
     return join(here, "..", "..", "..");
@@ -58,7 +71,11 @@ export function panelBuildNeeded(distIndex, sourceRoots) {
     }
     return sourceRoots.some((root) => newestUnder(root, builtAt));
 }
-export function parseDesktopArgs(argv) {
+/** UNC share or a Win32 device path (`\\?\`, `\\.\`, `\\?\UNC\`, `//host`): all start with two separators. */
+export function desktopStateUncOrDevice(stateDir) {
+    return stateDir.replaceAll("/", "\\").startsWith("\\\\");
+}
+export function parseDesktopArgs(argv, platform = process.platform) {
     const rest = argv.slice(1);
     let stateDir = "";
     let panelPort = 5173;
@@ -97,6 +114,8 @@ export function parseDesktopArgs(argv) {
     }
     if (!stateDir)
         return { error: "usage" };
+    if (platform === "win32" && desktopStateUncOrDevice(stateDir))
+        return { error: "desktop-state-unc" };
     if (![panelPort, issuerPort, bodyPort].every((n) => Number.isInteger(n) && n > 0 && n < 65536)) {
         return { error: "port-invalid" };
     }
@@ -112,14 +131,131 @@ export function portOpen(port, host = "127.0.0.1") {
         sock.once("error", () => resolve(false));
     });
 }
-async function waitPort(port, ms) {
-    const start = Date.now();
-    while (Date.now() - start < ms) {
-        if (await portOpen(port))
-            return true;
-        await new Promise((r) => setTimeout(r, 100));
+function bindLoopback(port, host) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", (err) => {
+            if (err.code === "EADDRNOTAVAIL" || err.code === "EAFNOSUPPORT")
+                resolve("unsupported");
+            else
+                resolve("busy");
+        });
+        server.listen({ port, host, ipv6Only: host === "::1" }, () => {
+            server.close(() => resolve("free"));
+        });
+    });
+}
+/**
+ * Bind 127.0.0.1 and [::1], then close both. True only when this process held
+ * 127.0.0.1 and [::1] was free or this host has no IPv6 loopback. A connect
+ * probe is not this: whoever is already listening would answer it.
+ */
+export function desktopPortFree(port) {
+    return bindLoopback(port, "127.0.0.1").then(async (v4) => {
+        if (v4 !== "free")
+            return false;
+        const v6 = await bindLoopback(port, "::1");
+        return v6 !== "busy";
+    });
+}
+/** True when a socket can bind [::1]. False when the host has no IPv6 loopback. */
+export function ipv6LoopbackAvailable() {
+    return bindLoopback(0, "::1").then((held) => held !== "unsupported");
+}
+/**
+ * Hold `[::1]:port` and pipe each accepted socket to `127.0.0.1:port`.
+ * `unsupported` means this host cannot bind the IPv6 loopback.
+ */
+export function forwardIpv6Loopback(port) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const server = createServer((inbound) => {
+            const upstream = createConnection({ host: "127.0.0.1", port });
+            const drop = () => {
+                inbound.destroy();
+                upstream.destroy();
+            };
+            inbound.on("error", drop);
+            upstream.on("error", drop);
+            inbound.pipe(upstream);
+            upstream.pipe(inbound);
+        });
+        server.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            if (err.code === "EADDRNOTAVAIL" || err.code === "EAFNOSUPPORT")
+                resolve({ ok: false, reason: "unsupported" });
+            else
+                resolve({ ok: false, reason: "busy" });
+        });
+        server.listen({ port, host: "::1", ipv6Only: true }, () => {
+            if (settled) {
+                server.close();
+                return;
+            }
+            settled = true;
+            resolve({ ok: true, server });
+        });
+    });
+}
+function listeningPort(server) {
+    const addr = server.address();
+    return addr && typeof addr !== "string" ? addr.port : null;
+}
+export function desktopPortBusyLine(name, port, ipv6 = false) {
+    return ipv6 ? `desktop-port-busy:${name}:${port}:ipv6\n` : `desktop-port-busy:${name}:${port}\n`;
+}
+/** JWKS document the dev issuer rewrites under the state directory on every start. */
+export function issuerJwksPinPath(stateDir) {
+    return join(stateDir, "dev-issuer", "jwks.json");
+}
+/** Drop a file left by an earlier run. A missing file is the state we want. */
+export function discardStaleFile(file) {
+    try {
+        unlinkSync(file);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
     }
-    return false;
+}
+/**
+ * The pin is the file the issuer just wrote. Compact JSON, or a throw when
+ * it is not a key set. Nothing is fetched.
+ */
+export function readIssuerJwksPin(stateDir) {
+    let text;
+    try {
+        text = readFileSync(issuerJwksPinPath(stateDir), "utf8");
+    }
+    catch {
+        throw new Error("desktop-jwks-pin-failed");
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.keys) || parsed.keys.length === 0) {
+            throw new Error("desktop-jwks-pin-failed");
+        }
+        return JSON.stringify({ keys: parsed.keys });
+    }
+    catch (err) {
+        if (err instanceof Error && err.message === "desktop-jwks-pin-failed")
+            throw err;
+        throw new Error("desktop-jwks-pin-failed");
+    }
+}
+export function issuerReadyLine(port) {
+    return `dev-issuer listening on http://127.0.0.1:${port}/`;
+}
+export function bodyReadyLine(port) {
+    return `listening 127.0.0.1:${port}`;
+}
+export function panelReadyLine(port) {
+    return `http://127.0.0.1:${port}`;
+}
+export function childStillAlive(child) {
+    return child.exitCode === null && child.signalCode === null;
 }
 /** GET /healthz on the loopback port; true only for a 200. */
 export function healthzUp(port) {
@@ -135,33 +271,493 @@ export function healthzUp(port) {
         req.once("error", () => resolve(false));
     });
 }
+function listenerArgv(port, platform) {
+    if (platform === "win32") {
+        // netstat, not Get-NetTCPConnection: loading the NetTCPIP module in PowerShell took long
+        // enough on a busy machine to time the lookup out, and a timed-out lookup is no listener.
+        return toolArgv("netstat", ["-ano", "-p", "TCP"], "win32");
+    }
+    if (platform === "darwin") {
+        return toolArgv("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-Fp"], "darwin");
+    }
+    if (platform === "linux") {
+        return toolArgv("ss", ["-ltnpH", `sport = :${port}`], "linux");
+    }
+    return null;
+}
+function onlyPid(pids) {
+    const unique = [...new Set(pids)];
+    return unique.length === 1 ? unique[0] : null;
+}
+/** Pid listening on 127.0.0.1:`port`, or null when the tool names nobody or more than one pid. */
+export function loopbackListenPid(port, platform = process.platform) {
+    if (!Number.isInteger(port) || port <= 0 || port >= 65536)
+        return null;
+    const argv = listenerArgv(port, platform);
+    const file = argv?.[0];
+    if (!argv || !file)
+        return null;
+    const ran = spawnSync(file, argv.slice(1), {
+        encoding: "utf8",
+        windowsHide: true,
+        shell: false,
+        timeout: 30_000,
+        env: systemToolEnv(platform),
+    });
+    if (ran.error)
+        return null;
+    const text = (ran.stdout ?? "").replace(/\u0000/g, "").replace(/^\uFEFF/, "");
+    if (platform === "darwin")
+        return onlyPid(lsofPids(text));
+    return onlyPid(loopbackPids(text, port));
+}
+function loopbackPids(text, port) {
+    const pids = [];
+    const at = new RegExp(`(?:^|[\\s\\[])127\\.0\\.0\\.1:${port}(?!\\d)`);
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === "")
+            continue;
+        // netstat -ano: "TCP  127.0.0.1:<port>  0.0.0.0:0  <state>  <pid>". The state word is localized;
+        // a listening socket is the one whose foreign address is 0.0.0.0:0.
+        const win = /^TCP\s+127\.0\.0\.1:(\d+)\s+0\.0\.0\.0:0\s+\S+\s+(\d+)$/i.exec(line);
+        if (win) {
+            if (Number(win[1]) === port)
+                pids.push(Number(win[2]));
+            continue;
+        }
+        if (!at.test(line))
+            continue;
+        const found = /pid=(\d+)/.exec(line);
+        if (found)
+            pids.push(Number(found[1]));
+    }
+    return pids;
+}
+function lsofPids(text) {
+    const pids = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const found = /^p(\d+)$/.exec(raw.trim());
+        if (found)
+            pids.push(Number(found[1]));
+    }
+    return pids;
+}
 /**
  * One ledger, one body. The desktop used to build its own issuer and body on
  * every open, which on a machine whose body starts at logon put the window on
  * a second, empty ledger: the panel looked broken while the real decisions sat
- * in the directory the lock names. So the lock is read first. Held by a live
- * process that answers /healthz where this run was told to look, the panel
- * joins that body. Held by a live process that does not answer there, the
- * desktop stops: someone owns the ledger and is not where we were pointed, and
- * a second body would be refused by the lock anyway. A dead or unreadable lock
- * is the body's own to clear (`verax unlock`); the desktop builds as before.
+ * in the directory the lock names. So the lock is read first. A live lock that
+ * records this port, whose pid is the listener on 127.0.0.1 there, is
+ * `attach`. 0.4.0 does not join that body: `runDesktop` stops before it
+ * claims a port or starts a child. A later release may join again, once that
+ * body is supervised. A 200 from /healthz is not the check. Any other live
+ * lock stops the desktop: `desktop-body-locked:<pid>:<port or unknown>`. A
+ * lock with no port is that stop until the body is started again. A dead or
+ * unreadable lock is left for `verax unlock`, which is only for a dead lock.
  */
-export async function desktopMode(stateDir, bodyPort, probe = healthzUp) {
+export async function desktopMode(stateDir, bodyPort, listenerPid = loopbackListenPid) {
     const lockPath = join(stateDir, "ledger.lock");
     if (!existsSync(lockPath))
         return { mode: "spawn" };
     const lock = readLockFile(lockPath);
     if (!lock || !pidAlive(lock.pid))
         return { mode: "spawn" };
-    if (await probe(bodyPort))
-        return { mode: "attach", pid: lock.pid };
-    return { error: "desktop-body-locked", pid: lock.pid };
+    const lockPort = lock.port ?? null;
+    if (lockPort === null || lockPort !== bodyPort) {
+        return { error: "desktop-body-locked", pid: lock.pid, lockPort };
+    }
+    let heard;
+    try {
+        heard = listenerPid(bodyPort);
+    }
+    catch {
+        heard = null;
+    }
+    if (heard !== lock.pid)
+        return { error: "desktop-body-locked", pid: lock.pid, lockPort };
+    return { mode: "attach", pid: lock.pid };
+}
+/**
+ * The first of the issuer, the body or the panel to exit stops the rest.
+ * A later exit does not stop again. `stillWatching` is false once this run
+ * is shutting down on purpose, so those exits are not a child failure.
+ */
+export function superviseDesktopChildren(children, stopAll, stillWatching = () => true) {
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (name) => {
+            if (done || !stillWatching())
+                return;
+            done = true;
+            stopAll();
+            resolve(name);
+        };
+        for (const child of children)
+            child.onExit(() => finish(child.name));
+    });
+}
+export function desktopChildExitedLine(name) {
+    return `desktop-child-exited:${name}\n`;
+}
+const DIRECTORY_WRITABLE_BY_OTHERS = "the directory was writable by others; use a new directory";
+function refuseDesktopDirectory(dir, detail) {
+    throw new Error(detail === undefined ? `desktop-dir-refused:${dir}` : `desktop-dir-refused:${dir}\n${detail}`);
+}
+/** `dev-issuer` planted as a symlink or junction. A missing entry is not that. */
+function devIssuerIsLink(dir) {
+    try {
+        return lstatSync(join(dir, "dev-issuer")).isSymbolicLink();
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+/**
+ * SDDL of every path from one PowerShell process (the installer's batch
+ * reader). One process per path timed out on a loaded Windows runner: the
+ * ancestor walk alone reads four to six directories.
+ */
+function readWindowsAcls(paths) {
+    const read = readSddlBatch(defaultExec, paths);
+    const out = new Map();
+    for (const p of paths) {
+        const hit = read.get(p);
+        const text = (hit?.text ?? "").replace(/^\uFEFF/, "").trim();
+        if (hit && hit.status === 0 && text !== "") {
+            const aliased = /(?:[OG]:|;)L[AG](?=[)OGDS:]|$)/.test(text);
+            out.set(p, { sddl: aliased ? expandLocalAccountAliases(text, localAccountSids()) : text, why: "" });
+        }
+        else {
+            out.set(p, { sddl: null, why: text.split(/\r?\n/)[0]?.slice(0, 200) || "no answer" });
+        }
+    }
+    return out;
+}
+let localAccounts = null;
+/** This machine's built-in Administrator and Guest SIDs, which an SDDL writes as `LA` and `LG`. Empty when the lookup fails. */
+function localAccountSids() {
+    if (localAccounts)
+        return localAccounts;
+    const ran = defaultExec(toolArgv("powershell", [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        "[Security.Principal.SecurityIdentifier]::new('LA').Value; [Security.Principal.SecurityIdentifier]::new('LG').Value",
+    ], "win32"));
+    const sids = (ran.status ?? 1) === 0 ? (ran.stdout ?? "").match(/S-1-5-21-[0-9-]+/g) ?? [] : [];
+    localAccounts = sids.length === 2 && sids[0].endsWith("-500") && sids[1].endsWith("-501") ? { LA: sids[0], LG: sids[1] } : {};
+    return localAccounts;
+}
+/**
+ * The account SIDs in place of the `LA` / `LG` aliases, so the built-in
+ * Administrator's own entry compares equal to its SID (a GitHub Windows
+ * runner runs as that account). An alias with no SID given is left, and the
+ * judge treats it as someone else.
+ */
+export function expandLocalAccountAliases(sddl, sids) {
+    const sid = (alias) => (alias === "LA" ? sids.LA : alias === "LG" ? sids.LG : undefined);
+    return sddl
+        .replace(/([OG]:)(LA|LG)(?=[OGDS]:|$)/g, (whole, field, alias) => {
+        const full = sid(alias);
+        return full ? `${field}${full}` : whole;
+    })
+        .replace(/;(LA|LG)\)/g, (whole, alias) => {
+        const full = sid(alias);
+        return full ? `;${full})` : whole;
+    });
+}
+function unreadable(why) {
+    return why === "" ? "" : ` (${why})`;
+}
+/** Who the refused DACL names, so the operator (and a CI log) can see which entry was judged to be someone else. */
+function aclWho(sddl, you) {
+    const others = foreignAclPrincipals(sddl, you);
+    return ` (owner ${sddlOwner(sddl) ?? "unknown"}; other entries ${others.length > 0 ? others.join(", ") : "none"}; you ${you || "unknown"})`;
+}
+/** Last bytes kept from a child so a long log cannot grow without a bound. */
+export const DESKTOP_CHILD_OUTPUT_CAP = 64 * 1024;
+/** Keep the tail. A ready line at the end of a large chunk stays inside the cap. */
+export function rememberChildOutput(current, chunk, cap = DESKTOP_CHILD_OUTPUT_CAP) {
+    if (cap <= 0)
+        return "";
+    if (chunk.length >= cap)
+        return chunk.slice(chunk.length - cap);
+    if (current.length + chunk.length <= cap)
+        return current + chunk;
+    return (current + chunk).slice(current.length + chunk.length - cap);
+}
+function foldDesktopPath(p) {
+    if (process.platform !== "win32")
+        return p.length > 1 ? p.replace(/\/+$/, "") : p;
+    let s = p.replaceAll("/", "\\");
+    const lower = s.toLowerCase();
+    if (lower.startsWith("\\\\?\\unc\\"))
+        s = `\\\\${s.slice(8)}`;
+    else if (lower.startsWith("\\\\?\\"))
+        s = s.slice(4);
+    s = s.toLowerCase();
+    if (s.length > 3)
+        s = s.replace(/\\+$/, "");
+    return s;
+}
+function ancestorPaths(dir) {
+    const out = [];
+    let cur = resolve(dir);
+    for (let i = 0; i < 64; i += 1) {
+        const parent = dirname(cur);
+        if (parent === cur)
+            break;
+        out.push(parent);
+        cur = parent;
+    }
+    return out;
+}
+/**
+ * An intermediate link makes the real path differ from the path as given.
+ * 8.3 names are expanded with `realpathSync.native` on each component that is
+ * not a link, then compared case-insensitively on Windows. A missing leaf is
+ * the real path of the parent plus the leaf name. The leaf itself being a
+ * link is left to the directory check.
+ */
+function intermediateLink(dir) {
+    const abs = resolve(dir);
+    const root = parse(abs).root;
+    const segs = abs.slice(root.length).split(/[\\/]/).filter((seg) => seg.length > 0);
+    let cursor = root;
+    let expanded = root;
+    for (let i = 0; i < segs.length; i += 1) {
+        const next = join(cursor, segs[i]);
+        const leaf = i === segs.length - 1;
+        let st;
+        try {
+            st = lstatSync(next);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                expanded = join(expanded, ...segs.slice(i));
+                break;
+            }
+            throw err;
+        }
+        if (st.isSymbolicLink()) {
+            if (leaf)
+                return null;
+            return next;
+        }
+        try {
+            expanded = realpathSync.native(next);
+        }
+        catch {
+            return next;
+        }
+        cursor = next;
+    }
+    let real;
+    try {
+        real = realpathSync.native(abs);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        const parent = dirname(abs);
+        try {
+            real = join(realpathSync.native(parent), basename(abs));
+        }
+        catch {
+            return null;
+        }
+    }
+    if (foldDesktopPath(expanded) !== foldDesktopPath(real))
+        return dirname(abs);
+    return null;
 }
+function refusePosixAncestors(dir) {
+    const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+    for (const ancestor of ancestorPaths(dir)) {
+        let st;
+        try {
+            st = lstatSync(ancestor);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            refuseDesktopDirectory(dir, `ancestor ${ancestor} could not be read`);
+        }
+        if (!st)
+            continue;
+        const ownerIsOperator = st.uid === 0 || st.uid === uid;
+        if (posixOthersCanReplace({ uid: ownerIsOperator ? 0 : st.uid, mode: st.mode, symlink: st.isSymbolicLink() }, true)) {
+            refuseDesktopDirectory(dir, `ancestor ${ancestor} can be replaced by another user`);
+        }
+    }
+}
+function ancestorInvokingSid(dir, opts) {
+    const hooked = opts?.windowsDirectoryOwner?.(dir).invokingSid?.trim().toUpperCase() ?? "";
+    if (hooked !== "")
+        return hooked;
+    if (opts?.windowsDirectoryOwner || opts?.windowsDirectoryDacl || opts?.windowsAncestorDacl)
+        return "";
+    try {
+        return windowsInvokingSid()?.trim().toUpperCase() ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+function refuseWindowsAncestors(dir, opts) {
+    if ((opts?.windowsDirectoryDacl || opts?.windowsDirectoryOwner) && !opts?.windowsAncestorDacl)
+        return;
+    const svc = ancestorInvokingSid(dir, opts);
+    const ancestors = ancestorPaths(dir);
+    let read = null;
+    if (!opts?.windowsAncestorDacl) {
+        const present = ancestors.filter((ancestor) => {
+            try {
+                lstatSync(ancestor);
+                return true;
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return false;
+                return refuseDesktopDirectory(dir, `ancestor ${ancestor} could not be read`);
+            }
+        });
+        read = readWindowsAcls(present);
+    }
+    for (const ancestor of ancestors) {
+        let acl;
+        if (opts?.windowsAncestorDacl) {
+            acl = { sddl: opts.windowsAncestorDacl(ancestor), why: "" };
+        }
+        else {
+            const hit = read?.get(ancestor);
+            if (!hit)
+                continue;
+            acl = hit;
+        }
+        if (acl.sddl === null || windowsUserCanWrite(acl.sddl, { ancestor: true, svcSid: svc })) {
+            refuseDesktopDirectory(dir, acl.sddl === null
+                ? `ancestor ${ancestor} ACL could not be read${unreadable(acl.why)}`
+                : `ancestor ${ancestor} can be replaced by another user${aclWho(acl.sddl, svc)}`);
+        }
+    }
+}
+/** Intermediate link, or an ancestor another user can replace. Same rule for a new directory and an existing one. */
+function refuseDesktopAncestors(dir, platform, opts) {
+    const link = intermediateLink(dir);
+    if (link)
+        refuseDesktopDirectory(dir, `ancestor ${link} is a link`);
+    if (platform === "win32")
+        refuseWindowsAncestors(dir, opts);
+    else
+        refusePosixAncestors(dir);
+}
+/**
+ * Create `dir` as mode 0700. An existing directory another user could write
+ * is refused and left as it is: on POSIX that is `mode & 0o022`, on Windows
+ * a DACL `windowsUserCanWrite` accepts for someone other than the owner
+ * (passed as `svcSid`), Administrators, or SYSTEM. A directory with only
+ * owner access keeps the previous path, including a chmod of group/other
+ * read or execute bits down to 0700. `dev-issuer` as a symlink or junction
+ * is refused. A symbolic link, or a directory owned by another uid, is
+ * refused. On Windows an existing directory is refused unless its owner SID
+ * is the invoking SID, Administrators, or SYSTEM. An ancestor another user
+ * can replace, or an intermediate link, is refused the same way for a new
+ * directory and for one that already exists.
+ */
+function ensureDesktopDirectory(dir, restrict, opts) {
+    const platform = opts?.platform ?? process.platform;
+    refuseDesktopAncestors(dir, platform, opts);
+    let existing = null;
+    try {
+        existing = lstatSync(dir);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    if (existing) {
+        if (existing.isSymbolicLink() || !existing.isDirectory())
+            refuseDesktopDirectory(dir);
+        if (platform === "win32") {
+            // Production passes no hook: owner and DACL come from one SDDL read.
+            const daclHook = opts?.windowsDirectoryDacl;
+            const leaf = !opts?.windowsDirectoryOwner && !daclHook ? readWindowsAcls([dir]).get(dir) : undefined;
+            if (leaf && leaf.sddl === null) {
+                refuseDesktopDirectory(dir, `the directory ACL could not be read${unreadable(leaf.why)}; use a new directory`);
+            }
+            let owner;
+            let invoking;
+            if (leaf?.sddl) {
+                owner = sddlOwner(leaf.sddl)?.toUpperCase() ?? "";
+                invoking = windowsInvokingSid()?.trim().toUpperCase() ?? "";
+            }
+            else {
+                const found = (opts?.windowsDirectoryOwner ?? windowsDirectorySids)(dir);
+                owner = found.ownerSid?.trim().toUpperCase() ?? "";
+                invoking = found.invokingSid?.trim().toUpperCase() ?? "";
+            }
+            // An elevated administrator's new directories are owned by Administrators, not by the user;
+            // no other local user can make a directory with that owner, or with SYSTEM.
+            const ownerOk = owner === invoking || owner === "S-1-5-32-544" || owner === "S-1-5-18";
+            if (owner === "" || invoking === "" || !ownerOk)
+                refuseDesktopDirectory(dir);
+            // R16-12 injects the owner and not a DACL.
+            if (daclHook || !opts?.windowsDirectoryOwner) {
+                const sddl = daclHook ? daclHook(dir) : (leaf?.sddl ?? null);
+                // The invoking user's own entry is not "someone else", also when an elevated shell made Administrators the owner.
+                if (sddl === null || windowsUserCanWrite(sddl, { svcSid: invoking })) {
+                    refuseDesktopDirectory(dir, sddl === null
+                        ? "the directory ACL could not be read; use a new directory"
+                        : `${DIRECTORY_WRITABLE_BY_OTHERS}${aclWho(sddl, invoking)}`);
+                }
+            }
+            if (devIssuerIsLink(dir)) {
+                refuseDesktopDirectory(dir, "dev-issuer in that directory is a symlink or junction; use a new directory");
+            }
+            restrict(dir);
+            return;
+        }
+        const uid = typeof process.getuid === "function" ? process.getuid() : existing.uid;
+        if (existing.uid !== uid)
+            refuseDesktopDirectory(dir);
+        if ((existing.mode & 0o022) !== 0)
+            refuseDesktopDirectory(dir, DIRECTORY_WRITABLE_BY_OTHERS);
+        if (devIssuerIsLink(dir)) {
+            refuseDesktopDirectory(dir, "dev-issuer in that directory is a symlink or junction; use a new directory");
+        }
+        if ((existing.mode & 0o077) !== 0)
+            chmodSync(dir, 0o700);
+        return;
+    }
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // A missing intermediate directory another user created between the first check and mkdir is theirs now.
+    refuseDesktopAncestors(dir, platform, opts);
+    const created = lstatSync(dir);
+    if (created.isSymbolicLink() || !created.isDirectory())
+        refuseDesktopDirectory(dir);
+    if (platform === "win32") {
+        restrict(dir);
+        return;
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : created.uid;
+    if (created.uid !== uid)
+        refuseDesktopDirectory(dir);
+    chmodSync(dir, 0o700);
+}
+/** Synchronous: `spawnSync` on Windows, `process.kill` elsewhere. An `exit` handler can call it. */
 export function killTree(pid) {
-    if (pid == null)
+    // POSIX kill(-1) signals every process this user may signal, kill(0) our own group. No child has pid 0 or 1.
+    if (pid == null || !Number.isInteger(pid) || pid <= 1)
         return;
     if (process.platform === "win32") {
-        spawnSync("taskkill", ["/T", "/PID", String(pid), "/F"], { windowsHide: true, stdio: "ignore" });
+        spawnSync(systemToolPath("taskkill", "win32"), ["/T", "/PID", String(pid), "/F"], {
+            windowsHide: true,
+            stdio: "ignore",
+        });
         return;
     }
     try {
@@ -176,8 +772,24 @@ export function killTree(pid) {
         }
     }
 }
+function keptOr(base, key, value) {
+    const current = base[key]?.trim() ?? "";
+    return current !== "" ? current : value;
+}
+/** Comma-separated origins. An origin already listed is not added again. */
+export function mergeAllowedOrigin(existing, origin) {
+    const parts = (existing ?? "")
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item !== "");
+    if (!parts.includes(origin))
+        parts.push(origin);
+    return parts.join(",");
+}
 /** The panel's redirect is its own origin, so the issuer has to be told which port
- *  this run put it on: the allow-list default only holds 5173 and 4173. */
+ *  this run put it on: the allow-list default only holds 5173 and 4173.
+ *  The passkey ceremony runs on the issuer (`/authorize` and `/enroll`), so the
+ *  RP ID and RP origins name that origin unless the operator already set them. */
 export function issuerEnv(base, opts, audience, issuerUrl) {
     return {
         ...base,
@@ -186,7 +798,9 @@ export function issuerEnv(base, opts, audience, issuerUrl) {
         VERAX_DEV_ISSUER_PORT: String(opts.issuerPort),
         VERAX_AUDIENCE: audience,
         VERAX_ISSUER: issuerUrl,
-        VERAX_DEV_REDIRECT_URIS: `http://127.0.0.1:${opts.panelPort}/`,
+        VERAX_DEV_REDIRECT_URIS: `http://localhost:${opts.panelPort}/`,
+        VERAX_RP_ID: keptOr(base, "VERAX_RP_ID", "localhost"),
+        VERAX_RP_ORIGINS: keptOr(base, "VERAX_RP_ORIGINS", issuerUrl),
     };
 }
 function cleanEnv() {
@@ -229,78 +843,239 @@ function defaultBrowser() {
             return p;
     return null;
 }
-function collectOutput(child, sink) {
-    const feed = (c) => {
-        sink.text += String(c);
-    };
-    child.stdout?.on("data", feed);
-    child.stderr?.on("data", feed);
-}
-export async function runDesktop(opts, writeErr = (s) => process.stderr.write(s)) {
+export async function runDesktop(opts, writeErr = (s) => process.stderr.write(s), hooks) {
     const repoRoot = resolveRepoRoot();
     const cloneOnly = desktopCloneError(repoRoot);
     if (cloneOnly) {
         writeErr(cloneOnly);
         return 78;
     }
-    mkdirSync(opts.stateDir, { recursive: true });
+    // Before the issuer, the body, or the window: a first run with no operator
+    // file otherwise opens a panel that cannot read the ledger and does not say why.
+    const passkeyHint = desktopPasskeyHint(opts.stateDir);
+    if (passkeyHint)
+        writeErr(passkeyHint);
+    // Directories that may already hold the ledger and keys: the grants must be inheritable.
+    const restrictOwner = hooks?.restrictOwner ?? ((dir) => restrictToOwnerWin32(dir, undefined, true));
     const tokenPath = join(opts.stateDir, "dev-token");
     const issuerScript = join(repoRoot, "scripts", "dev-issuer.mjs");
     const mainTs = join(here, "main.ts");
     const viteJs = join(repoRoot, "node_modules", "vite", "bin", "vite.js");
     const panelDir = join(repoRoot, "apps", "panel");
     const policy = join(repoRoot, "packages", "proxy", "policy", "default.json");
-    const audience = `http://127.0.0.1:${opts.bodyPort}`;
-    const issuerUrl = `http://127.0.0.1:${opts.issuerPort}`;
+    // Browser-facing origins are localhost: an IP address cannot be a WebAuthn RP ID,
+    // and an RP ID of localhost does not match a page on 127.0.0.1. The audience is
+    // the same host so the token `aud` and the body's VERAX_AUDIENCE agree; it is
+    // not a page. The children bind 127.0.0.1. This process also holds [::1] on
+    // those ports and pipes each connection to 127.0.0.1, so a page fetched as
+    // localhost cannot land on another local user's socket. Node (the panel
+    // proxy, the JWKS URL) uses 127.0.0.1 so it does not follow a resolver that
+    // tries ::1 first.
+    const audience = `http://localhost:${opts.bodyPort}`;
+    const issuerUrl = `http://localhost:${opts.issuerPort}`;
+    const panelOrigin = `http://localhost:${opts.panelPort}`;
+    const bodyLoopback = `http://127.0.0.1:${opts.bodyPort}`;
+    const issuerLoopback = `http://127.0.0.1:${opts.issuerPort}`;
     const kids = [];
     const log = { text: "" };
+    const gate = { watch: true };
+    const exited = { name: null };
+    let resolveGone = () => { };
+    const childGone = new Promise((resolve) => {
+        resolveGone = resolve;
+    });
+    const forwarders = [];
+    const stopForwarders = () => {
+        for (const server of forwarders) {
+            server.close();
+            server.unref();
+        }
+        forwarders.length = 0;
+    };
+    const claimIpv6 = async (port) => {
+        if (forwarders.some((server) => listeningPort(server) === port))
+            return "held";
+        const opened = await forwardIpv6Loopback(port);
+        if (!opened.ok)
+            return opened.reason;
+        forwarders.push(opened.server);
+        return "held";
+    };
+    const killPid = hooks?.kill ?? killTree;
     const stopAll = () => {
+        gate.watch = false;
+        stopForwarders();
         for (const c of kids)
-            killTree(c.pid);
+            killPid(c.pid);
+    };
+    const signalHost = hooks?.signals ?? process;
+    const signalPlatform = hooks?.signals?.platform ?? process.platform;
+    let disarmSignals = () => { };
+    const launch = (name, cmd, args, env, cwd, hideWindow = true) => (hooks?.spawn ? hooks.spawn(name, cmd, args, env, cwd) : spawnLogged(cmd, args, env, cwd, hideWindow));
+    const pipe = (name, child, own) => {
+        const feed = (chunk) => {
+            const text = String(chunk);
+            own.text = rememberChildOutput(own.text, text);
+            log.text = rememberChildOutput(log.text, text);
+            hooks?.childOutput?.(name, own.text);
+        };
+        child.stdout?.on("data", feed);
+        child.stderr?.on("data", feed);
+    };
+    // Before the wait, so a child that dies during startup is the failure.
+    const arm = (name, child) => {
+        const note = () => {
+            if (!gate.watch || exited.name)
+                return;
+            exited.name = name;
+            resolveGone(name);
+            stopAll();
+        };
+        if (child.exitCode !== null || child.signalCode !== null)
+            note();
+        else
+            child.once("exit", note);
+    };
+    const waitReady = async (child, own, ready, ms) => {
+        const start = Date.now();
+        while (Date.now() - start < ms) {
+            if (exited.name || !childStillAlive(child))
+                return "exited";
+            if (ready(own.text))
+                return childStillAlive(child) && !exited.name ? "ready" : "exited";
+            await new Promise((r) => setTimeout(r, 20));
+        }
+        if (exited.name || !childStillAlive(child))
+            return "exited";
+        return ready(own.text) ? "ready" : "timeout";
+    };
+    const ipv4Free = (port) => bindLoopback(port, "127.0.0.1").then((held) => held === "free");
+    const busy = async (name, port) => {
+        const v6 = await claimIpv6(port);
+        if (v6 === "busy") {
+            writeErr(desktopPortBusyLine(name, port, true));
+            stopAll();
+            return true;
+        }
+        if (await ipv4Free(port))
+            return false;
+        writeErr(desktopPortBusyLine(name, port));
+        stopAll();
+        return true;
+    };
+    const childFailed = (name) => {
+        writeErr(desktopChildExitedLine(exited.name ?? name));
+        stopAll();
+        return 1;
     };
     try {
-        const decided = await desktopMode(opts.stateDir, opts.bodyPort);
+        disarmSignals = armDesktopStop(signalHost, signalPlatform, stopAll);
+        ensureDesktopDirectory(opts.stateDir, restrictOwner, {
+            platform: hooks?.platform,
+            windowsDirectoryOwner: hooks?.windowsDirectoryOwner,
+            windowsDirectoryDacl: hooks?.windowsDirectoryDacl,
+            windowsAncestorDacl: hooks?.windowsAncestorDacl,
+        });
+        const decided = await desktopMode(opts.stateDir, opts.bodyPort, hooks?.listenerPid);
         if ("error" in decided) {
-            writeErr(`${decided.error}:${decided.pid}\n`);
+            const named = decided.lockPort === null ? "unknown" : String(decided.lockPort);
+            writeErr(`${decided.error}:${decided.pid}:${named}\n`);
             return 1;
         }
-        // Joining a running body: its issuer is whatever the body's resource
-        // metadata names, and its token is not ours to read. The panel's own
-        // origin has to be on that issuer's allow-list (VERAX_DEV_REDIRECT_URIS on
-        // the running issuer), which this run cannot set after the fact.
-        let token = null;
-        if (decided.mode === "spawn") {
-            const issuer = spawnLogged(process.execPath, ["--experimental-strip-types", issuerScript, "--out", tokenPath], issuerEnv(cleanEnv(), opts, audience, issuerUrl), repoRoot);
-            kids.push(issuer);
-            collectOutput(issuer, log);
-            if (!(await waitPort(opts.issuerPort, 15_000))) {
-                writeErr("desktop-issuer-timeout\n");
-                stopAll();
-                return 1;
-            }
-            token = readFileSync(tokenPath, "utf8").trim();
-            if (token === "") {
-                writeErr("desktop-token-missing\n");
-                stopAll();
-                return 1;
-            }
-            const body = spawnLogged(process.execPath, ["--experimental-strip-types", mainTs], {
-                ...cleanEnv(),
-                VERAX_STATE_DIR: opts.stateDir,
-                VERAX_ISSUER: issuerUrl,
-                VERAX_JWKS_URL: `${issuerUrl}/.well-known/jwks.json`,
-                VERAX_AUDIENCE: audience,
-                VERAX_BIND: `127.0.0.1:${opts.bodyPort}`,
-                VERAX_POLICY_FILE: policy,
-                ...(opts.inventoryFile ? { VERAX_INVENTORY_FILE: opts.inventoryFile } : {}),
-            }, repoRoot);
-            kids.push(body);
-            collectOutput(body, log);
-            if (!(await waitPort(opts.bodyPort, 15_000))) {
-                writeErr("desktop-body-timeout\n");
-                stopAll();
+        // 0.4.0 does not join a body that is already running on this state directory.
+        // The attached body is not supervised: if it dies, another local user can
+        // bind 127.0.0.1 on its port and the panel would hand over the operator
+        // session. Stop before any port is claimed and before any child starts.
+        if (decided.mode === "attach") {
+            writeErr(`desktop-body-running:${opts.bodyPort}\n`);
+            writeErr("a body is already running on this state directory; use the panel of the desktop that started it, or stop that body first. verax unlock is for a dead lock only\n");
+            return 1;
+        }
+        // Only the ports this run will bind must be free.
+        const ports = [
+            ["issuer", opts.issuerPort],
+            ["body", opts.bodyPort],
+            ["panel", opts.panelPort],
+        ];
+        for (const [name, port] of ports) {
+            if (await busy(name, port))
                 return 1;
-            }
+        }
+        let token = null;
+        // A token or pin left on disk is the previous run's. This issuer must write both.
+        // This file is the dev issuer's --out token, not the install agent token
+        // (`%ProgramData%\Verax\agent-token\<SID>\agent.token` or `~/.verax/agent.token`).
+        discardStaleFile(tokenPath);
+        discardStaleFile(issuerJwksPinPath(opts.stateDir));
+        if (await busy("issuer", opts.issuerPort))
+            return 1;
+        const issuer = launch("issuer", process.execPath, ["--experimental-strip-types", issuerScript, "--out", tokenPath], { ...issuerEnv(cleanEnv(), opts, audience, issuerUrl), [DESKTOP_PARENT_PID]: String(process.pid) }, repoRoot);
+        kids.push(issuer);
+        arm("issuer", issuer);
+        const issuerOut = { text: "" };
+        pipe("issuer", issuer, issuerOut);
+        const issuerReady = await waitReady(issuer, issuerOut, (text) => text.includes(issuerReadyLine(opts.issuerPort)), hooks?.readyMs ?? 15_000);
+        if (issuerReady === "exited")
+            return childFailed("issuer");
+        if (issuerReady === "timeout") {
+            writeErr("desktop-issuer-timeout\n");
+            stopAll();
+            return 1;
+        }
+        // The --out file is the agent credential. It does not carry verax:audit.
+        // The panel reads the ledger with the passkey session, not this file.
+        let tokenText = "";
+        try {
+            tokenText = readFileSync(tokenPath, "utf8").trim();
+        }
+        catch {
+            tokenText = "";
+        }
+        if (tokenText === "") {
+            writeErr("desktop-token-missing\n");
+            stopAll();
+            return 1;
+        }
+        token = tokenText;
+        // The body verifies with the keys this issuer wrote at start. A fetch of
+        // the port would pin whoever answered. VERAX_JWKS_FILE is not this pin:
+        // that mode refuses operator scopes. The URL stays so config can load;
+        // the pin is what verification uses, and it does not refetch.
+        let pinnedJwks;
+        try {
+            pinnedJwks = readIssuerJwksPin(opts.stateDir);
+        }
+        catch {
+            writeErr("desktop-jwks-pin-failed\n");
+            stopAll();
+            return 1;
+        }
+        if (await busy("body", opts.bodyPort))
+            return 1;
+        const body = launch("body", process.execPath, ["--experimental-strip-types", mainTs], {
+            ...cleanEnv(),
+            VERAX_STATE_DIR: opts.stateDir,
+            VERAX_ISSUER: issuerUrl,
+            VERAX_JWKS_URL: `${issuerLoopback}/.well-known/jwks.json`,
+            VERAX_JWKS_PIN: pinnedJwks,
+            VERAX_AUDIENCE: audience,
+            VERAX_BIND: `127.0.0.1:${opts.bodyPort}`,
+            VERAX_ALLOWED_ORIGINS: mergeAllowedOrigin(process.env.VERAX_ALLOWED_ORIGINS, panelOrigin),
+            VERAX_POLICY_FILE: policy,
+            [DESKTOP_PARENT_PID]: String(process.pid),
+            ...(opts.inventoryFile ? { VERAX_INVENTORY_FILE: opts.inventoryFile } : {}),
+        }, repoRoot);
+        kids.push(body);
+        arm("body", body);
+        const bodyOut = { text: "" };
+        pipe("body", body, bodyOut);
+        const bodyReady = await waitReady(body, bodyOut, (text) => text.includes(bodyReadyLine(opts.bodyPort)), hooks?.readyMs ?? 15_000);
+        if (bodyReady === "exited")
+            return childFailed("body");
+        if (bodyReady === "timeout") {
+            writeErr("desktop-body-timeout\n");
+            stopAll();
+            return 1;
         }
         const panelSources = [
             join(panelDir, "src"),
@@ -308,10 +1083,10 @@ export async function runDesktop(opts, writeErr = (s) => process.stderr.write(s)
             join(panelDir, "vite.config.ts"),
             join(repoRoot, "packages"),
         ];
-        if (panelBuildNeeded(join(panelDir, "dist", "index.html"), panelSources)) {
+        if (!hooks?.spawn && panelBuildNeeded(join(panelDir, "dist", "index.html"), panelSources)) {
             const built = spawnSync(process.execPath, [viteJs, "build"], {
                 cwd: panelDir,
-                env: { ...cleanEnv(), VERAX_BODY_URL: audience },
+                env: { ...cleanEnv(), VERAX_BODY_URL: bodyLoopback },
                 encoding: "utf8",
                 windowsHide: true,
             });
@@ -322,18 +1097,28 @@ export async function runDesktop(opts, writeErr = (s) => process.stderr.write(s)
                 return 1;
             }
         }
-        const panel = spawnLogged(process.execPath, [viteJs, "preview", "--host", "127.0.0.1", "--port", String(opts.panelPort), "--strictPort"], {
+        if (await busy("panel", opts.panelPort))
+            return 1;
+        // vite preview has no parent-pid watch. stopAll kills it with the tree.
+        // A launcher killed outright does not run stopAll; the issuer and the body
+        // exit when VERAX_DESKTOP_PARENT_PID is gone, and without them this port is idle.
+        const panel = launch("panel", process.execPath, [viteJs, "preview", "--host", "127.0.0.1", "--port", String(opts.panelPort), "--strictPort"], {
             ...cleanEnv(),
-            VERAX_BODY_URL: audience,
+            VERAX_BODY_URL: bodyLoopback,
         }, panelDir);
         kids.push(panel);
-        collectOutput(panel, log);
-        if (!(await waitPort(opts.panelPort, 20_000))) {
+        arm("panel", panel);
+        const panelOut = { text: "" };
+        pipe("panel", panel, panelOut);
+        const panelReady = await waitReady(panel, panelOut, (text) => text.includes(panelReadyLine(opts.panelPort)), hooks?.readyMs ?? 20_000);
+        if (panelReady === "exited")
+            return childFailed("panel");
+        if (panelReady === "timeout") {
             writeErr("desktop-panel-timeout\n");
             stopAll();
             return 1;
         }
-        const url = `http://127.0.0.1:${opts.panelPort}`;
+        const url = panelOrigin;
         const scriptBrowser = Boolean(opts.browser && /\.(mjs|js|ts)$/.test(opts.browser));
         const browserBin = scriptBrowser ? process.execPath : (opts.browser ?? defaultBrowser());
         if (!browserBin) {
@@ -342,7 +1127,12 @@ export async function runDesktop(opts, writeErr = (s) => process.stderr.write(s)
             return 1;
         }
         const profileDir = join(opts.stateDir, "browser-profile");
-        mkdirSync(profileDir, { recursive: true });
+        ensureDesktopDirectory(profileDir, restrictOwner, {
+            platform: hooks?.platform,
+            windowsDirectoryOwner: hooks?.windowsDirectoryOwner,
+            windowsDirectoryDacl: hooks?.windowsDirectoryDacl,
+            windowsAncestorDacl: hooks?.windowsAncestorDacl,
+        });
         const browserArgv = scriptBrowser
             ? [opts.browser, url]
             : [
@@ -352,42 +1142,46 @@ export async function runDesktop(opts, writeErr = (s) => process.stderr.write(s)
                 `--app=${url}`,
                 "--window-size=1360,880",
             ];
-        const browser = spawnLogged(browserBin, browserArgv, cleanEnv(), repoRoot, false);
+        const browser = launch("browser", browserBin, browserArgv, cleanEnv(), repoRoot, false);
         kids.push(browser);
-        collectOutput(browser, log);
+        pipe("browser", browser, { text: "" });
         if (token !== null && log.text.includes(token)) {
             writeErr("desktop-token-leaked\n");
             stopAll();
             return 1;
         }
-        process.stdout.write(decided.mode === "attach"
-            ? `desktop-ready body=${opts.bodyPort} panel=${opts.panelPort} attached=1 pid=${decided.pid}\n`
-            : `desktop-ready issuer=${opts.issuerPort} body=${opts.bodyPort} panel=${opts.panelPort}\n`);
-        const onSignal = () => {
-            stopAll();
-            process.exit(1);
-        };
-        process.once("SIGINT", onSignal);
-        process.once("SIGTERM", onSignal);
+        process.stdout.write(`desktop-ready issuer=${opts.issuerPort} body=${opts.bodyPort} panel=${opts.panelPort}\n`);
         const closed = new Promise((resolve) => {
-            browser.once("close", () => resolve());
+            if (browser.exitCode !== null || browser.signalCode !== null)
+                resolve();
+            else
+                browser.once("close", () => resolve());
         });
+        const childExit = async (name) => {
+            writeErr(desktopChildExitedLine(name));
+            stopAll();
+            return 1;
+        };
         const exitedEarly = await Promise.race([
-            closed.then(() => true),
+            closed.then(() => ({ kind: "browser" })),
+            childGone.then((name) => ({ kind: "child", name })),
             new Promise((resolve) => {
-                setTimeout(() => resolve(false), 3_000);
+                setTimeout(() => resolve({ kind: "stay" }), 3_000);
             }),
         ]);
-        if (exitedEarly) {
+        if (exitedEarly.kind === "child")
+            return childExit(exitedEarly.name);
+        if (exitedEarly.kind === "browser") {
             writeErr("desktop-browser-exited-early\n");
-            process.removeListener("SIGINT", onSignal);
-            process.removeListener("SIGTERM", onSignal);
             stopAll();
             return 1;
         }
-        await closed;
-        process.removeListener("SIGINT", onSignal);
-        process.removeListener("SIGTERM", onSignal);
+        const ended = await Promise.race([
+            closed.then(() => ({ kind: "browser" })),
+            childGone.then((name) => ({ kind: "child", name })),
+        ]);
+        if (ended.kind === "child")
+            return childExit(ended.name);
         stopAll();
         return 0;
     }
@@ -397,6 +1191,40 @@ export async function runDesktop(opts, writeErr = (s) => process.stderr.write(s)
         writeErr(`desktop-failed:${msg}\n`);
         return 1;
     }
+    finally {
+        disarmSignals();
+    }
+}
+/** SIGHUP on POSIX, SIGBREAK on Windows, plus crash and process exit. `stopAll` is synchronous. */
+function armDesktopStop(host, platform, stopAll) {
+    const onSignal = () => {
+        stopAll();
+        host.exit(1);
+    };
+    const onCrash = () => {
+        stopAll();
+        host.exit(1);
+    };
+    const onExit = () => {
+        stopAll();
+    };
+    const paired = [
+        ["SIGINT", onSignal],
+        ["SIGTERM", onSignal],
+        // Node raises SIGHUP on Windows too, when the console window is closed.
+        ["SIGHUP", onSignal],
+        ...(platform === "win32" ? [["SIGBREAK", onSignal]] : []),
+        ["uncaughtException", onCrash],
+        ["unhandledRejection", onCrash],
+    ];
+    for (const [event, fn] of paired)
+        host.once(event, fn);
+    host.on("exit", onExit);
+    return () => {
+        for (const [event, fn] of paired)
+            host.removeListener(event, fn);
+        host.removeListener("exit", onExit);
+    };
 }
 export async function desktopMain(argv) {
     const parsed = parseDesktopArgs(argv);