@basein/runner 0.2.12 → 0.3.0

package/dist/control/daemon.js

@@ -22,8 +22,11 @@
  * with a working directory that must equal the project's, each needing the
  * person to know which one they are on. The hook already runs in the right
  * directory with the right environment at exactly the right moment, and Claude
- * Code already supervises it. What is lost is restart-on-crash mid-session,
- * which the proxies already survive (they fall to Tier 2 and say so).
+ * Code already supervises it. Restart-on-crash mid-session is the proxies'
+ * part: a bound proxy (or `bir-scenario`) that finds the recorder gone —
+ * refusing connections, its pid dead — spawns `bir-hooks revive`
+ * ({@link reviveDaemon}), rate limited, unless `bir down` stopped it on
+ * purpose.
  *
  * HOW IT IS LAUNCHED. The daemon opens its own log file (`BIR_DAEMON_LOG`) and
  * inherits nothing from our stdio. On POSIX that is a `detached` spawn with
@@ -32,139 +35,821 @@
  * short-lived `powershell.exe`: libuv's CreateProcess inherits *every*
  * inheritable handle of the parent, not only the three it was told about, and
  * a node started under a PowerShell layer (the `irm | iex` bootstrap, a `.ps1`
- * shim, a captured `bir up`) carries an extra copy of its own stdout pipe. A
- * daemon that inherits it holds that pipe open for days, and whoever is reading
- * it never sees EOF. `Start-Process` passes the environment and no handles.
+ * shim, a captured `bir up`, a `$r = claude -p …`) carries an extra copy of its
+ * own stdout pipe. A daemon that inherits it holds that pipe open for days, and
+ * whoever is reading it never sees EOF. `Start-Process` passes the environment
+ * and no handles. It costs about a second, once per project per boot; a direct
+ * spawn is faster but only safe when nothing above the hook captured its
+ * output, so it is an opt-in (`BIR_WINDOWS_LAUNCH=spawn`), not the default.
+ *
+ * WHERE IT RUNS. The daemon's working directory is the runner's own state
+ * directory, never the project: on Windows a process's current directory
+ * cannot be renamed or deleted, and an invisible recorder holding the project
+ * folder made "delete the folder", `git worktree remove` and a re-clone fail
+ * with "in use by another program". The project is passed as `BIR_DAEMON_CWD`.
+ *
+ * WHAT IT MAY NOT DO. Every path is bounded: the SessionStart hook has a budget
+ * well inside Claude Code's hook timeout (ensure-hook.ts), a recorder that is
+ * alive but slow is never mistaken for a dead one (that started a duplicate
+ * that could not bind), and nothing here touches the network — the recorder
+ * listens before it signs in (recorder-keeper.ts).
  */
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync, closeSync, } from "node:fs";
-import { dirname, join, resolve as resolvePath } from "node:path";
+import { Console } from "node:console";
+import { closeSync, createWriteStream, existsSync, fstatSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
+import { Writable } from "node:stream";
+import { dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ControlClient } from "./client.js";
-import { pidAlive, readDiscovery, removeDiscovery } from "./discovery.js";
-import { controlDir, controlKey, daemonLogPath, ensureDir, logsDir } from "./paths.js";
-import { nodeFlagsToCarry } from "../config/generate.js";
+import { listSupersededRecorders, pidAlive, readDiscovery, removeDiscovery, removeDiscoveryIfOwned, removeSupersededRecord, writeDiscovery, writeSupersededRecord, } from "./discovery.js";
+import { configDir, controlDir, controlKey, daemonLogPath, downMarkerPath, ensureDir, logsDir, normalizePath, portProblemPath, } from "./paths.js";
+import { nodeFlagsToCarry, projectRecord, projectToken, readSidecar, } from "../config/generate.js";
+import { writeFileAtomic } from "../util/atomic-write.js";
+import { timeoutSignal } from "../util/service-health.js";
 import { errText, logLine } from "../util/log.js";
 import { packageVersion } from "../util/version.js";
-/** A log file larger than this is rolled over to `.1` when a daemon starts. */
+export { listSupersededRecorders } from "./discovery.js";
+/** A log file larger than this is rolled over to `.1` (at start, and while it runs). */
 export const LOG_ROTATE_BYTES = 8 * 1024 * 1024;
 /** Marks a `bir-hooks` as started by this module; it says so in its discovery file. */
 export const DAEMON_ENV = "BIR_DAEMON";
 /** Where that process writes its audit lines. It opens the file itself. */
 export const DAEMON_LOG_ENV = "BIR_DAEMON_LOG";
+/**
+ * The project a background recorder serves. It runs in the runner's state
+ * directory, not the project (see WHERE IT RUNS above), so it cannot learn the
+ * project from its own working directory.
+ */
+export const DAEMON_CWD_ENV = "BIR_DAEMON_CWD";
 /**
  * The setup token's environment variable (`bir setup` reads it when `--token`
  * is absent). Never handed to the recorder: it is a one-use secret for signing
  * in, and a process that lives for days has no business holding it.
  */
 export const SETUP_TOKEN_ENV = "BIR_SETUP_TOKEN";
+/**
+ * An Anthropic key meant for the runner's derivation, and nothing else. Set
+ * explicitly; it is the only key the recorder uses by default.
+ */
+export const DERIVE_KEY_ENV = "BIR_DERIVE_API_KEY";
+/**
+ * `1` lets the recorder use an `ANTHROPIC_API_KEY` from its environment for
+ * derivation, as it did before. Off by default: the hook-started recorder has
+ * Claude Code's environment, and an API-billed Claude Code has its key there —
+ * using it silently spent the person's own money on something the service
+ * does for a signed-in runner.
+ */
+export const USE_API_KEY_ENV = "BIR_USE_ANTHROPIC_API_KEY";
+/** `spawn` launches the Windows daemon directly instead of through PowerShell. */
+export const WINDOWS_LAUNCH_ENV = "BIR_WINDOWS_LAUNCH";
+/**
+ * `bir-hooks revive --cwd <project>`: bring the project's recorder back when
+ * it is gone. Spawned detached by a bound `bir-proxy` or `bir-scenario` whose
+ * recorder refuses connections and whose pid is dead (see {@link reviveDaemon}).
+ */
+export const REVIVE_ARG = "revive";
 /** A start lock older than this belongs to a starter that died; it is ignored. */
 const LOCK_STALE_MS = 30_000;
+/** How long a recorder has to answer `/health` before it counts as busy. */
+const HEALTH_TIMEOUT_MS = 3_000;
+/**
+ * {@link EnsureOptions.probeIdle}: the gap between the two `/health` probes
+ * that tell a recorder that only *reports* a run open from one doing work.
+ */
+export const IDLE_PROBE_GAP_MS = 2_500;
+/** What must be left of the budget after that gap to stop and start a recorder. */
+const IDLE_PROBE_RESERVE_MS = 6_000;
+/** The recorder is running but did not answer in time: busy, not gone. */
+export class RecorderBusyError extends Error {
+    pid;
+    constructor(pid) {
+        super(`the recorder (pid ${pid}) is running but did not answer within ${HEALTH_TIMEOUT_MS / 1000}s — ` +
+            "it is busy, not gone, so no second one was started");
+        this.name = "RecorderBusyError";
+        this.pid = pid;
+    }
+}
+/** A revive found the project's recorder stopped on purpose (`bir down`): it is left down. */
+export class RecorderStoppedError extends Error {
+    constructor() {
+        super("the recorder was stopped on purpose (`bir down`); the next session start or `bir up` starts it");
+        this.name = "RecorderStoppedError";
+    }
+}
 /** Absolute path of `dist/bin/bir-hooks.js` in the package this module runs from. */
 export function hooksScriptPath() {
     return resolvePath(dirname(fileURLToPath(import.meta.url)), "..", "bin", "bir-hooks.js");
 }
+/**
+ * `GET /health` with the bearer token, bounded, with the failure kept apart:
+ * "refused" means gone, "timeout" means busy, and the difference is the one
+ * that decides whether a second recorder is started.
+ */
+export async function probeHealth(url, token, timeoutMs = HEALTH_TIMEOUT_MS) {
+    let res;
+    try {
+        res = await fetch(`${url.replace(/\/+$/, "")}/health`, {
+            headers: { authorization: `Bearer ${token}` },
+            signal: timeoutSignal(Math.max(1, timeoutMs)),
+        });
+    }
+    catch (err) {
+        const e = err;
+        if (e?.name === "TimeoutError" || e?.name === "AbortError")
+            return { kind: "timeout" };
+        return { kind: "refused", reason: e?.cause?.code ?? errText(err) };
+    }
+    if (res.status === 401 || res.status === 403) {
+        await res.body?.cancel().catch(() => undefined);
+        return { kind: "unauthorized", status: res.status };
+    }
+    if (!res.ok) {
+        await res.body?.cancel().catch(() => undefined);
+        return { kind: "foreign", status: res.status };
+    }
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch (err) {
+        const e = err;
+        if (e?.name === "TimeoutError" || e?.name === "AbortError")
+            return { kind: "timeout" };
+        return { kind: "foreign", status: res.status };
+    }
+    if (body && typeof body === "object" && typeof body.pid === "number") {
+        return { kind: "ok", health: body };
+    }
+    return { kind: "foreign", status: res.status };
+}
+async function lookup(cwd, timeoutMs = HEALTH_TIMEOUT_MS) {
+    // Age is not evidence here: a recorder woken after a weekend is live with a
+    // days-old file. The pid and the recorder's own answer decide.
+    const info = readDiscovery(cwd, { ignoreAge: true });
+    if (!info)
+        return { kind: "none" };
+    const probe = await probeHealth(info.url, info.token, timeoutMs);
+    if (probe.kind === "ok" && probe.health.pid === info.pid) {
+        return { kind: "live", status: { info, health: probe.health } };
+    }
+    // A timeout is busy whatever the file's age. The pid is alive (readDiscovery
+    // checked), and a recorder just woken from a long sleep has an old file
+    // *and* a busy event loop — the first minute after a wake is exactly when
+    // its heartbeat has not caught up yet. Calling that dead removed the live
+    // recorder's file and started a duplicate that could not bind.
+    if (probe.kind === "timeout")
+        return { kind: "busy", info };
+    return { kind: "dead", info };
+}
 /**
  * The live control server for `cwd`, or undefined.
  *
- * "Live" means the discovery file is fresh, its pid is alive, **and** it
- * answers `/health` with its token. A file left by a crash fails the second
- * test; a process that hung, or a recycled pid, fails the third.
+ * "Live" means the discovery file names a pid that is alive **and** that
+ * answers `/health` with its token. A file left by a crash fails the first
+ * test; a process that hung, or a recycled pid, fails the second.
  */
 export async function daemonStatus(cwd) {
-    const info = readDiscovery(cwd);
-    if (!info)
+    const found = await lookup(cwd);
+    return found.kind === "live" ? found.status : undefined;
+}
+/**
+ * This project's recorder, found by its port rather than its discovery file,
+ * and its file written again. For a recorder whose file was removed (by hand,
+ * by an older runner that took a slow recorder for a dead one): starting a
+ * second one would only find the port taken.
+ *
+ * A file that already names the recorder that answered is left as it is. What
+ * is written here is rebuilt from `/health`, which does not say whether the
+ * process runs in the background or where its log is: overwriting the
+ * recorder's own, complete record with it made `bir status` lose the log path
+ * and the start time, and hid the recorder from the reinstall check (which
+ * only replaces background recorders) — for the half hour until its own
+ * heartbeat. The recorder also rewrites a record of itself that differs from
+ * what it would write (recorder-main.ts), so what this writes is short-lived.
+ */
+export async function rediscover(cwd, port, token, timeoutMs = HEALTH_TIMEOUT_MS) {
+    const url = `http://127.0.0.1:${port}`;
+    const probe = await probeHealth(url, token, timeoutMs);
+    if (probe.kind !== "ok")
         return undefined;
-    const health = await new ControlClient(info.url, info.token, 3_000).health();
-    if (!health || health.pid !== info.pid)
+    const h = probe.health;
+    if (typeof h.cwd !== "string" || normalizePath(h.cwd) !== normalizePath(cwd))
         return undefined;
-    return { info, health };
+    const pid = h.pid;
+    if (!pidAlive(pid))
+        return undefined;
+    const existing = readDiscovery(cwd, { ignoreAge: true });
+    if (existing && existing.pid === pid && portOf(existing.url) === port && existing.token === token) {
+        return { info: existing, health: h };
+    }
+    const now = Date.now();
+    const info = {
+        url,
+        token,
+        sessionId: typeof h.sessionId === "string" ? h.sessionId : "",
+        pid,
+        startedAt: now,
+        heartbeatAt: now,
+        cwd,
+        version: typeof h.hooksVersion === "string" ? h.hooksVersion : undefined,
+    };
+    try {
+        writeDiscovery(info);
+    }
+    catch (err) {
+        logLine("daemon.rediscover_failed", { error: errText(err) });
+    }
+    logLine("daemon.rediscovered", {
+        pid,
+        url,
+        why: "this project's recorder was running without its discovery file; wrote it again",
+    });
+    return { info, health: h };
 }
 /** How many of the recorder's sessions are mid-run right now. */
 export function activeSessions(health) {
     const sessions = health.sessions ?? [];
     return sessions.filter((s) => s.active === true).length;
 }
+/**
+ * How many sessions the recorder has seen at all, mid-run or between turns.
+ * The control server keeps a session until it exits, so this counts every
+ * Claude Code window that may still send it a hook.
+ */
+function knownSessions(health) {
+    const sessions = health.sessions;
+    return Array.isArray(sessions) ? sessions.length : 0;
+}
+/**
+ * `a` against `b` as versions: -1, 0 or 1, or undefined when either is not
+ * `x.y.z` (with an optional pre-release, which sorts below its release, and
+ * build metadata, which is ignored).
+ */
+export function compareVersions(a, b) {
+    const parse = (v) => {
+        const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(v.trim());
+        if (!m)
+            return undefined;
+        return { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4]?.split(".") };
+    };
+    const x = parse(a);
+    const y = parse(b);
+    if (!x || !y)
+        return undefined;
+    for (let i = 0; i < 3; i += 1) {
+        if (x.nums[i] !== y.nums[i])
+            return x.nums[i] < y.nums[i] ? -1 : 1;
+    }
+    if (!x.pre && !y.pre)
+        return 0;
+    if (!x.pre)
+        return 1;
+    if (!y.pre)
+        return -1;
+    for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i += 1) {
+        const p = x.pre[i];
+        const q = y.pre[i];
+        if (p === undefined)
+            return -1;
+        if (q === undefined)
+            return 1;
+        const pn = /^\d+$/.test(p);
+        const qn = /^\d+$/.test(q);
+        if (pn && qn) {
+            if (Number(p) !== Number(q))
+                return Number(p) < Number(q) ? -1 : 1;
+            continue;
+        }
+        if (pn !== qn)
+            return pn ? -1 : 1;
+        if (p !== q)
+            return p < q ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * True for the `/health` of a recorder that predates the idle bound (0.2.12
+ * and older): it lists sessions, and none of them says how long it has been
+ * idle. Its `active` is then "a run is open", with nothing to close one that
+ * was abandoned. An empty list says nothing either way (and counts none active).
+ */
+export function isLegacyHealth(health) {
+    const sessions = health.sessions;
+    if (!Array.isArray(sessions) || sessions.length === 0)
+        return false;
+    return sessions.every((s) => !s || typeof s !== "object" || typeof s.idleMs !== "number");
+}
+/** How many of the proxies a recorder lists as registered are alive right now. */
+function liveRegisteredProxies(health) {
+    const list = health.registeredProxies;
+    if (!Array.isArray(list))
+        return 0;
+    const pids = new Set();
+    for (const r of list) {
+        const pid = r?.pid;
+        if (typeof pid === "number" && pidAlive(pid))
+            pids.add(pid);
+    }
+    return pids.size;
+}
+/** Every listed session with its step count, in one comparable string. */
+function stepsSignature(health) {
+    const sessions = Array.isArray(health.sessions) ? health.sessions : [];
+    return sessions
+        .map((s) => `${String(s?.sessionId ?? "")}:${typeof s?.steps === "number" ? s.steps : "?"}`)
+        .sort()
+        .join("|");
+}
+/**
+ * {@link EnsureOptions.probeIdle}: whether a legacy recorder that reports a
+ * run open is in fact doing nothing — no registered proxy alive (an open
+ * window's MCP servers are its proxies), and nothing moved between two probes
+ * {@link IDLE_PROBE_GAP_MS} apart. False whenever it cannot tell, or when the
+ * budget has no room for the wait and a restart after it.
+ */
+async function legacyIdle(live, deadline) {
+    if (!isLegacyHealth(live.health))
+        return false;
+    if (liveRegisteredProxies(live.health) > 0)
+        return false;
+    if (remaining(deadline) < IDLE_PROBE_GAP_MS + IDLE_PROBE_RESERVE_MS)
+        return false;
+    const before = stepsSignature(live.health);
+    await sleep(IDLE_PROBE_GAP_MS);
+    const again = await probeHealth(live.info.url, live.info.token, clamp(remaining(deadline), 250, HEALTH_TIMEOUT_MS));
+    if (again.kind !== "ok" || again.health.pid !== live.info.pid)
+        return false;
+    if (liveRegisteredProxies(again.health) > 0)
+        return false;
+    return stepsSignature(again.health) === before;
+}
+/** A TCP port number, or undefined for anything that is not one. */
+export function validPort(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    const n = Number(value);
+    return Number.isInteger(n) && n > 0 && n < 65536 ? n : undefined;
+}
+/** The port a recorder URL listens on, or undefined when it names none. */
+function portOf(url) {
+    try {
+        return validPort(new URL(url).port);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `BIR_CONTROL_PORT` read once, for everything that reads it: `"0"` is any
+ * free port, a valid port is that port, and anything else (unset, empty, not
+ * a number, out of range) is no setting at all.
+ */
+export function controlPortFromEnv(env = process.env) {
+    const raw = env.BIR_CONTROL_PORT?.trim();
+    if (raw === "0")
+        return 0;
+    return validPort(raw);
+}
+/**
+ * The one reading of "which port and token does this project use", shared by
+ * the recorder (which binds it) and by {@link ensureDaemon} (which checks a
+ * running recorder against it). They used to read `BIR_CONTROL_PORT`
+ * differently: the recorder took an empty or invalid value as "the default
+ * port, pinned", the check ignored it and used the project's port — and every
+ * session start then "replaced" a recorder that could only ever bind the
+ * default port again. An invalid value is now ignored by both, and `0` means
+ * "any free port" to both (see {@link ProjectEndpoint.ephemeral}).
+ */
+export function projectEndpoint(cwd, env = process.env, sidecar) {
+    const setting = controlPortFromEnv(env);
+    const ephemeral = setting === 0;
+    const fromEnv = ephemeral ? undefined : setting;
+    let installed = sidecar;
+    if (!installed) {
+        try {
+            installed = readSidecar();
+        }
+        catch {
+            installed = undefined;
+        }
+    }
+    const record = installed ? projectRecord(installed, cwd) : undefined;
+    const port = ephemeral ? undefined : (fromEnv ?? validPort(record?.port));
+    return {
+        port,
+        token: installed && record ? projectToken(installed, cwd) : undefined,
+        pinned: port !== undefined,
+        ...(ephemeral ? { ephemeral: true } : {}),
+    };
+}
+/**
+ * Why a running background recorder does not serve this project's hooks as
+ * they are written now, or undefined when it does.
+ *
+ *   `port`   it listens where the hooks no longer post (`bir install --port N`,
+ *            or `bir uninstall` + `bir setup`, which picks a new port);
+ *   `token`  it listens on the right port but refuses the token the hooks now
+ *            send (the project was installed again).
+ *
+ * A recorder that also accepts the project's current token (a control server
+ * that re-reads it on a mismatch) is not a mismatch: it serves both the
+ * sessions that started before the reinstall and the ones after. A recorder
+ * somebody runs in a terminal is theirs to manage and is left alone.
+ */
+async function endpointMismatch(info, expected, timeoutMs) {
+    const port = portMismatch(info, expected);
+    if (port)
+        return { kind: "port", why: port };
+    if (info.daemon !== true)
+        return undefined;
+    if (expected.token !== undefined && info.token !== expected.token) {
+        const probe = await probeHealth(info.url, expected.token, timeoutMs);
+        if (probe.kind === "ok" && probe.health.pid === info.pid)
+            return undefined;
+        return {
+            kind: "token",
+            why: "its token is not the one this project's hooks send (the project was installed again)",
+        };
+    }
+    return undefined;
+}
+/** {@link endpointMismatch} for the port alone — no network. */
+function portMismatch(info, expected) {
+    if (info.daemon !== true || expected.port === undefined)
+        return undefined;
+    const port = portOf(info.url);
+    return port === expected.port ? undefined : `it listens on port ${port ?? "?"}, and the hooks post to ${expected.port}`;
+}
+function remaining(deadline) {
+    return Math.max(0, deadline - Date.now());
+}
+function clamp(n, lo, hi) {
+    return Math.min(hi, Math.max(lo, n));
+}
 /**
  * The control server for `cwd`, started in the background if none is live.
  *
- * Idempotent: a live one is returned as-is. Throws when a fresh process did
- * not come up in time, with the tail of its log, because "it did not start" is
- * the one message that must carry its own diagnosis.
+ * Idempotent: a live one is returned as-is — unless it is an older version
+ * with nothing mid-run (`restartOnSkew`; with `probeIdle`, a legacy
+ * recorder whose "mid-run" is a run nobody will finish counts as idle), or a
+ * background recorder that the project's current hooks do not reach
+ * (another port or token). Any call but a revive ends a `bir down`.
+ *
+ * WHAT A REINSTALL MAY NOT BREAK. Claude Code reads a session's hooks when the
+ * session starts and keeps them: every window opened before `bir install
+ * --port N` or `bir uninstall` + `bir setup` still posts to the old port with
+ * the old token, until it is closed. The old recorder is what answers them. So
+ *
+ *   - another **port**: the old recorder is left running for the sessions it
+ *     has seen, and a second one is started on the new port — two ports, no
+ *     conflict. The new one takes the discovery file; the old one steps back
+ *     from it, is recorded as superseded (`listSupersededRecorders`, so
+ *     `bir status`/`bir down` can find it), writes a log of its own, and
+ *     exits once it has had nothing left to serve for a day
+ *     (recorder-main.ts). A recorder that has never seen a session is simply
+ *     replaced;
+ *   - another **token** on the same port: only one process can listen there.
+ *     It is replaced between turns (a restart then costs the old windows their
+ *     next hooks, and gives every new one working hooks), never mid-run.
+ *
+ * A recorder that is alive but slow to answer is never replaced and never
+ * duplicated on its own port: this throws {@link RecorderBusyError} instead.
+ *
+ * Throws when a fresh process did not come up within the budget, with the
+ * tail of its log, because "it did not start" is the one message that must
+ * carry its own diagnosis.
  */
 export async function ensureDaemon(cwd, opts = {}) {
-    const timeoutMs = opts.timeoutMs ?? 15_000;
+    const budgetMs = opts.timeoutMs ?? 15_000;
+    const deadline = Date.now() + budgetMs;
+    const env = opts.env ?? process.env;
+    const expected = projectEndpoint(cwd, env);
     let restarted = false;
-    const live = await daemonStatus(cwd);
-    if (live) {
+    // Whoever asks for a recorder here — a session start, `bir up`, `bir setup`
+    // — ends a `bir down`. A revive is the one caller that must honour it.
+    if (opts.revive) {
+        if (isMarkedDown(cwd))
+            throw new RecorderStoppedError();
+    }
+    else {
+        clearDownMarker(cwd);
+    }
+    const found = await lookup(cwd, clamp(remaining(deadline), 250, HEALTH_TIMEOUT_MS));
+    if (found.kind === "live") {
+        const live = found.status;
+        const mismatch = await endpointMismatch(live.info, expected, clamp(remaining(deadline), 250, HEALTH_TIMEOUT_MS));
         const theirs = String(live.health.hooksVersion ?? live.info.version ?? "");
-        const skewed = opts.restartOnSkew && theirs && theirs !== packageVersion();
-        if (!skewed || activeSessions(live.health) > 0) {
+        const ours = packageVersion();
+        // Only an older recorder is replaced. Two runner copies on one machine
+        // (an old global install beside the install line's own) used to replace
+        // each other's recorder at every session start, each swap refusing the
+        // other windows' hooks for a moment. An unreadable version is skew, as before.
+        const order = theirs ? compareVersions(theirs, ours) : undefined;
+        const newer = order !== undefined && order > 0;
+        const skewed = Boolean(opts.restartOnSkew && theirs && (order === undefined ? theirs !== ours : order < 0));
+        const active = activeSessions(live.health);
+        const known = knownSessions(live.health);
+        // A legacy recorder's "mid-run" can be a run nobody will ever finish
+        // (EnsureOptions.probeIdle). Asked at most once, and only where it decides.
+        let idle;
+        const idleDespiteActive = async () => {
+            if (active === 0 || opts.probeIdle !== true)
+                return false;
+            idle ??= await legacyIdle(live, deadline);
+            return idle;
+        };
+        if (mismatch?.kind === "port" && known > 0) {
+            logLine("daemon.start_alongside", {
+                cwd,
+                pid: live.info.pid,
+                sessions: known,
+                why: `${mismatch.why}; it keeps serving the ${known} session(s) that started before that, ` +
+                    "and a recorder for the new port is started beside it",
+            });
+            // Findable and stoppable from now on (`bir status`, `bir down`): the
+            // discovery file is about to name the new one only. It rewrites this
+            // itself once it notices, and removes it when it exits.
+            noteSuperseded(cwd, live.info, theirs);
+        }
+        else if (mismatch?.kind === "token" && active > 0 && !(await idleDespiteActive())) {
+            logLine("daemon.restart_deferred", {
+                cwd,
+                pid: live.info.pid,
+                why: `${mismatch.why}; a session is mid-run, so it is replaced at the next session start between turns`,
+            });
+            return { status: live, started: false, restarted: false };
+        }
+        else if (!mismatch && (!skewed || (active > 0 && !(await idleDespiteActive())))) {
+            if (opts.restartOnSkew && newer) {
+                logLine("daemon.newer_kept", {
+                    cwd,
+                    pid: live.info.pid,
+                    running: theirs,
+                    package: ours,
+                    why: "the running recorder is a newer version than this package (another runner copy on this machine); it is kept",
+                });
+            }
             return { status: live, started: false, restarted: false };
         }
-        // An upgraded package with last week's recorder still running is the
-        // "half-upgraded machine" of docs/installRun.md §8 — the update that looks
-        // like success. Nothing is mid-run, so this is the free moment to fix it.
-        logLine("daemon.restart", {
+        else {
+            // An upgraded package with last week's recorder still running is the
+            // "half-upgraded machine" of docs/installRun.md §8 — the update that
+            // looks like success. Nothing is mid-run, so this is the free moment to
+            // fix it. The same moment replaces a recorder the hooks no longer reach.
+            logLine("daemon.restart", {
+                cwd,
+                from: theirs,
+                to: ours,
+                why: mismatch?.why ??
+                    (idle
+                        ? "the recorder is an older version than the package; it predates the idle bound and reports a run " +
+                            "open, but nothing moved between two looks and no proxy of it is alive"
+                        : "the recorder is an older version than the package; no session is mid-run"),
+            });
+            const stopped = await stopDaemon(cwd, {
+                timeoutMs: clamp(remaining(deadline) - 5_000, 1_000, 10_000),
+                markDown: false,
+            });
+            // A recorder on another port is no obstacle to the new one; on the same
+            // port it is, so keep the one that works rather than start one that
+            // cannot bind.
+            if (!stopped.stopped && mismatch?.kind !== "port") {
+                logLine("daemon.restart_skipped", {
+                    pid: live.info.pid,
+                    why: "the old recorder did not stop; it keeps serving, and the next session tries again",
+                });
+                return { status: live, started: false, restarted: false };
+            }
+            restarted = stopped.stopped;
+        }
+    }
+    else if (found.kind === "busy") {
+        // Busy on the port the hooks post to: a second recorder could not bind
+        // it, and the busy one answers once it catches up. Busy somewhere else:
+        // it is in nobody's way, and the hooks need a recorder where they post.
+        const elsewhere = portMismatch(found.info, expected);
+        if (!elsewhere)
+            throw new RecorderBusyError(found.info.pid);
+        logLine("daemon.start_alongside", {
             cwd,
-            from: theirs,
-            to: packageVersion(),
-            why: "the recorder is an older version than the package; no session is mid-run",
+            pid: found.info.pid,
+            why: `${elsewhere}; it is busy, and is left running — a recorder for the new port is started beside it`,
         });
-        await stopDaemon(cwd);
-        restarted = true;
+        noteSuperseded(cwd, found.info, found.info.version ?? "");
     }
-    else if (readDiscovery(cwd)) {
-        // A file whose pid is alive but that nothing answers for: a crash whose pid
-        // was recycled. Gone now, so no proxy resolves it in the moments before the
-        // new one writes its own.
-        removeDiscovery(cwd);
+    else if (found.kind === "dead") {
+        // A file whose pid is gone, or alive but not answering as ours (a crash
+        // whose pid was recycled). Gone now, so no proxy resolves it in the
+        // moments before the new one writes its own — and only that file: several
+        // revives may race here, and the recorder one of them just started must
+        // keep the record it wrote.
+        removeDiscoveryIfOwned(cwd, found.info.pid);
+    }
+    // No usable record (or only one for another port) — but this project's
+    // recorder may still be serving the port the hooks name. Ask the port before
+    // starting a second one that could not bind.
+    if (!restarted && expected.port !== undefined && expected.token !== undefined) {
+        const serving = await rediscover(cwd, expected.port, expected.token, clamp(remaining(deadline), 250, HEALTH_TIMEOUT_MS));
+        if (serving)
+            return { status: serving, started: false, restarted: false };
     }
+    // What is waited for below must be where the hooks post: a recorder left
+    // running on the old port (above) still owns the discovery file until the
+    // new one writes its own, and is not the answer.
+    const accept = (s) => portMismatch(s.info, expected) === undefined;
     // Two Claude Code windows opened together in one project both run the
     // SessionStart hook. The first to take the lock spawns; the second waits for
-    // that spawn rather than racing it onto another port.
+    // that spawn rather than racing it onto another port — but only while the
+    // first is alive and holds the lock, and never past this call's budget.
     const lock = lockPath(cwd);
+    const logFile = daemonLogPath(cwd);
     if (!acquireLock(lock)) {
-        const theirs = await waitForDaemon(cwd, undefined, timeoutMs);
-        if (theirs)
-            return { status: theirs, started: false, restarted: false };
-        releaseLock(lock); // theirs died or hung; the lock is ours to take
+        const holder = lockHolder(lock);
+        const waited = await waitForDaemon(cwd, {
+            deadline,
+            accept,
+            stopWhen: () => !existsSync(lock) || (holder !== undefined && !pidAlive(holder)),
+        });
+        if (waited.status)
+            return { status: waited.status, started: false, restarted };
+        if (holder !== undefined && pidAlive(holder) && existsSync(lock)) {
+            throw new Error(`another start of the recorder is still in progress (pid ${holder}) — ${tailOf(logFile)}`);
+        }
+        releaseLock(lock); // the holder died without releasing it
         if (!acquireLock(lock))
             throw new Error("another recorder start is in progress — try again");
     }
     try {
+        // A `bir down` that landed while this revive looked around wins.
+        if (opts.revive && isMarkedDown(cwd))
+            throw new RecorderStoppedError();
         const script = opts.hooksScript ?? hooksScriptPath();
-        const logFile = daemonLogPath(cwd);
         ensureDir(logsDir());
         rotateLog(logFile);
-        const env = {
-            ...(opts.env ?? process.env),
-            [DAEMON_ENV]: "1",
-            [DAEMON_LOG_ENV]: logFile,
-        };
-        delete env[SETUP_TOKEN_ENV];
-        const launched = process.platform === "win32"
-            ? launchWindows(script, cwd, env)
-            : launchPosix(script, cwd, env);
-        const status = await waitForDaemon(cwd, launched.pid, timeoutMs, () => {
-            if (launched.exited()) {
-                throw new Error(`the recorder exited before it was ready — ${tailOf(logFile)}`);
-            }
-        });
-        if (!status) {
-            throw new Error(`the recorder did not answer within ${Math.round(timeoutMs / 1000)}s — ${tailOf(logFile)}`);
+        const childEnv = daemonEnv(env, cwd, logFile);
+        const launchedAt = Date.now();
+        const launched = process.platform === "win32" && childEnv[WINDOWS_LAUNCH_ENV] !== "spawn"
+            ? launchWindows(script, childEnv, clamp(remaining(deadline) - 1_000, 2_000, 8_000))
+            : launchDetached(script, childEnv);
+        const waited = await waitForDaemon(cwd, { pid: launched.pid, deadline, exited: launched.exited, accept });
+        if (waited.status)
+            return { status: waited.status, started: waited.status.info.pid === launched.pid, restarted };
+        // Only a problem this launch reported; an older one may since have cleared.
+        const problem = readPortProblem(cwd);
+        const why = problem && problem.at >= launchedAt - 1_000 ? ` — ${problem.detail}; ${problem.fix}` : "";
+        if (waited.exited) {
+            throw new Error(`the recorder exited before it was ready${why} — ${tailOf(logFile)}`);
         }
-        return { status, started: true, restarted };
+        throw new Error(`the recorder did not answer within ${Math.round(budgetMs / 1000)}s${why} — ${tailOf(logFile)}`);
     }
     finally {
         releaseLock(lock);
     }
 }
-function launchPosix(script, cwd, env) {
-    const child = spawn(process.execPath, [...nodeFlagsToCarry(), script], {
+/** Record a recorder the hooks moved away from as superseded (see discovery.ts). */
+function noteSuperseded(cwd, info, version) {
+    const port = portOf(info.url);
+    if (port === undefined)
+        return;
+    writeSupersededRecord({
         cwd,
+        pid: info.pid,
+        port,
+        url: info.url,
+        token: info.token,
+        since: Date.now(),
+        version: version || info.version,
+        logFile: info.logFile,
+    });
+}
+// ── `bir down`, and bringing a recorder back ───────────────────────────────
+/**
+ * Mark `cwd`'s recorder as stopped on purpose. {@link stopDaemon} does it; a
+ * revive then leaves the project without a recorder until something that
+ * asks for one on purpose — a session start, `bir up`, `bir setup` — clears
+ * it. Never throws.
+ */
+export function markDown(cwd) {
+    try {
+        ensureDir(controlDir());
+        writeFileSync(downMarkerPath(cwd), `${process.pid} ${new Date().toISOString()}\n`, { mode: 0o600 });
+    }
+    catch {
+        /* without the marker a proxy may bring it back; that is all */
+    }
+}
+/** Remove the {@link markDown} marker. Never throws. */
+export function clearDownMarker(cwd) {
+    try {
+        unlinkSync(downMarkerPath(cwd));
+    }
+    catch {
+        /* not there */
+    }
+}
+/** True while `cwd`'s recorder is marked as stopped on purpose. */
+export function isMarkedDown(cwd) {
+    try {
+        return existsSync(downMarkerPath(cwd));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `bir-hooks revive --cwd <project>` (K1): the recorder of an installed
+ * project, started again when it is gone.
+ *
+ * Every hook but SessionStart is an HTTP hook to the recorder, and a refused
+ * one is shown in the session as a hook error — on every prompt and every tool
+ * call — until the next SessionStart. A recorder killed mid-session (an
+ * antivirus, the OOM killer, a restart that missed its budget) used to stay
+ * gone until then. A bound `bir-proxy` or `bir-scenario` that finds it
+ * refusing connections with its pid dead spawns this, detached and rate
+ * limited, so the window of refused hooks is seconds.
+ *
+ * {@link ensureDaemon} with `restartOnSkew: false`, under the same start lock,
+ * so several revives at once start one recorder. Only for a project with an
+ * install record, and never after `bir down` (the down marker). Started even
+ * while the runner is off: the off recorder is what answers every hook `{}`.
+ * Never throws.
+ */
+export async function reviveDaemon(cwd, opts = {}) {
+    try {
+        let installed = false;
+        try {
+            installed = projectRecord(readSidecar(), cwd) !== undefined;
+        }
+        catch {
+            installed = false;
+        }
+        if (!installed)
+            return { outcome: "not_installed" };
+        if (isMarkedDown(cwd))
+            return { outcome: "stopped_on_purpose" };
+        const result = await ensureDaemon(cwd, { ...opts, restartOnSkew: false, revive: true });
+        if (result.started) {
+            logLine("daemon.revived", {
+                cwd,
+                pid: result.status.info.pid,
+                url: result.status.info.url,
+                why: "the recorder was gone mid-session (its pid dead, its port refusing); a proxy of an open window started it again",
+            });
+        }
+        return { outcome: result.started ? "started" : "running", pid: result.status.info.pid };
+    }
+    catch (err) {
+        if (err instanceof RecorderStoppedError)
+            return { outcome: "stopped_on_purpose" };
+        if (err instanceof RecorderBusyError)
+            return { outcome: "busy", pid: err.pid };
+        logLine("daemon.revive_failed", { cwd, error: errText(err) });
+        return { outcome: "failed", error: errText(err) };
+    }
+}
+/**
+ * The environment a background recorder gets: the caller's, marked as a
+ * daemon, told its project, and without the secrets it has no use for.
+ *
+ * Nor `BIR_OFF` (K2), in any spelling: the recorder serves every window of
+ * the project, and a `BIR_OFF=1` in the environment of whichever window
+ * happened to start it switched all of them off for the recorder's life. That
+ * window's SessionStart hook tells the recorder its own session is off
+ * instead (ensure-hook.ts); the flag files still switch everything.
+ */
+export function daemonEnv(base, cwd, logFile) {
+    const env = { ...base };
+    deleteEnv(env, SETUP_TOKEN_ENV);
+    if (base[USE_API_KEY_ENV] !== "1")
+        deleteEnv(env, "ANTHROPIC_API_KEY");
+    for (const key of Object.keys(env)) {
+        if (key.toUpperCase() === "BIR_OFF")
+            delete env[key];
+    }
+    // The recorder runs in another directory than its starter, so nothing it is
+    // handed may be relative to the starter's.
+    if (env.BIR_HOME && !isAbsolute(env.BIR_HOME))
+        env.BIR_HOME = resolvePath(env.BIR_HOME);
+    env[DAEMON_ENV] = "1";
+    env[DAEMON_LOG_ENV] = resolvePath(logFile);
+    env[DAEMON_CWD_ENV] = isAbsolute(cwd) ? cwd : resolvePath(cwd);
+    return env;
+}
+/** Delete `name` from an env copy — case-insensitively on Windows, where env names are. */
+function deleteEnv(env, name) {
+    for (const key of Object.keys(env)) {
+        if (key === name || (process.platform === "win32" && key.toUpperCase() === name.toUpperCase())) {
+            delete env[key];
+        }
+    }
+}
+function launchDetached(script, env) {
+    const child = spawn(process.execPath, [...nodeFlagsToCarry(), script], {
+        cwd: resolvePath(configDir()),
         detached: true,
         stdio: "ignore",
+        // A detached child on Windows would get a console window of its own.
+        windowsHide: true,
         env,
     });
     let exited = false;
@@ -181,43 +866,65 @@ function launchPosix(script, cwd, env) {
 function psQuote(value) {
     return `'${value.replace(/'/g, "''")}'`;
 }
-function launchWindows(script, cwd, env) {
+function launchWindows(script, env, timeoutMs) {
     // Start-Process joins -ArgumentList with spaces and quotes nothing, so the
     // script path carries its own double quotes.
     const argumentList = [...nodeFlagsToCarry().map(psQuote), psQuote(`"${script}"`)].join(", ");
     const command = `$p = Start-Process -FilePath ${psQuote(process.execPath)} ` +
         `-ArgumentList @(${argumentList}) ` +
-        `-WorkingDirectory ${psQuote(cwd)} -WindowStyle Hidden -PassThru; ` +
+        `-WorkingDirectory ${psQuote(resolvePath(configDir()))} -WindowStyle Hidden -PassThru; ` +
         `Write-Output $p.Id`;
-    const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", command], { env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true, timeout: 30_000 });
+    const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", command], 
+    // Bounded well inside the hook's own budget: a PowerShell that hangs (an
+    // endpoint scanner, a policy prompt) must not hold SessionStart with it.
+    { env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true, timeout: timeoutMs });
     const pid = Number((result.stdout ?? "").trim().split(/\s+/).pop());
     if (result.status !== 0 || !Number.isInteger(pid) || pid <= 0) {
-        // No PowerShell, or it refused: fall back to a plain spawn. It records;
-        // the handle it may inherit is the lesser evil next to not recording.
+        // No PowerShell, or it refused: fall back to a plain hidden spawn. It
+        // records; the handle it may inherit is the lesser evil next to not recording.
         logLine("daemon.start_fallback", {
             why: "Start-Process failed; using a plain spawn",
             detail: (result.stderr ?? "").trim().slice(0, 200) || errText(result.error),
         });
-        return launchPosix(script, cwd, env);
+        return launchDetached(script, env);
     }
     return { pid, exited: () => !pidAlive(pid) };
 }
 /**
- * Poll until the recorder for `cwd` answers — with `pid` when the caller knows
- * which process it is waiting for — or `timeoutMs` passes.
+ * Poll until the recorder for `cwd` answers — the one with `pid` when the
+ * caller launched it — or the deadline passes. Fast at first (a recorder is
+ * usually up in a few hundred milliseconds), slower after.
+ *
+ * When the launched process has exited, any live recorder for the project is
+ * taken: `bir-hooks` steps aside, exit 0, when it finds this project's
+ * recorder already serving the port.
  */
-async function waitForDaemon(cwd, pid, timeoutMs, check) {
-    const deadline = Date.now() + timeoutMs;
+async function waitForDaemon(cwd, opts) {
+    const startedAt = Date.now();
+    const probeMs = () => clamp(remaining(opts.deadline), 200, HEALTH_TIMEOUT_MS);
+    const usable = (found) => found.kind === "live" && (!opts.accept || opts.accept(found.status)) ? found.status : undefined;
+    // One more look once the thing waited on has ended: what it did before
+    // ending (wrote a discovery file, released the lock) happened after the
+    // look this round was based on.
+    const lastLook = async () => usable(await lookup(cwd, probeMs()));
     for (;;) {
-        const status = await daemonStatus(cwd);
-        if (status && (pid === undefined || status.info.pid === pid))
-            return status;
-        check?.();
-        if (Date.now() >= deadline)
-            return undefined;
-        await sleep(200);
+        const live = usable(await lookup(cwd, probeMs()));
+        if (live && (opts.pid === undefined || live.info.pid === opts.pid))
+            return { status: live };
+        if (opts.exited?.()) {
+            const status = live ?? (await lastLook());
+            return status ? { status } : { exited: true };
+        }
+        if (opts.stopWhen?.()) {
+            const status = live ?? (await lastLook());
+            return status ? { status } : {};
+        }
+        if (Date.now() >= opts.deadline)
+            return live && opts.pid === undefined ? { status: live } : {};
+        await sleep(Math.min(Date.now() - startedAt < 1_000 ? 50 : 200, remaining(opts.deadline)));
     }
 }
+// ── stop ───────────────────────────────────────────────────────────────────
 /**
  * Stop the control server for `cwd`.
  *
@@ -227,42 +934,325 @@ async function waitForDaemon(cwd, pid, timeoutMs, check) {
  * the polite route exists. Only a process that answers `/health` as the
  * recorder is ever signalled: a discovery file survives a crash, and its pid
  * is recycled — on Windows quickly — so "the pid in the file is alive" is not
- * evidence that it is ours.
+ * evidence that it is ours. One that is alive but too busy to answer is asked
+ * and waited for, never signalled.
  */
 export async function stopDaemon(cwd, opts = {}) {
-    const info = readDiscovery(cwd);
+    const info = readDiscovery(cwd, { ignoreAge: true });
     if (!info)
         return { stopped: false };
-    const timeoutMs = opts.timeoutMs ?? 10_000;
-    const client = new ControlClient(info.url, info.token, 3_000);
-    const health = await client.health();
-    if (!health || health.pid !== info.pid) {
+    // Before it is asked: once it is gone, a proxy of an open window may look.
+    if (opts.markDown !== false)
+        markDown(cwd);
+    const result = await stopVerified(info, opts.timeoutMs ?? 10_000);
+    if (result.stale) {
         removeDiscovery(cwd);
-        return { stopped: false, pid: info.pid, stale: true };
+    }
+    else if (result.stopped) {
+        // Its own shutdown removes the file; a killed process could not.
+        removeDiscoveryIfOwned(cwd, info.pid);
+    }
+    return { ...result, pid: info.pid };
+}
+/**
+ * Stop the recorder at `target` — asked first, then signalled only if it
+ * answered `/health` as that very pid; one too busy to answer is asked and
+ * waited for, never signalled. `stale`: nothing there answers as it.
+ */
+async function stopVerified(target, timeoutMs) {
+    const client = new ControlClient(target.url, target.token, HEALTH_TIMEOUT_MS);
+    const probe = await probeHealth(target.url, target.token);
+    if (probe.kind === "timeout") {
+        // Its queue will get to the request; its own shutdown then exits.
+        void client.stop();
+        const deadline = Date.now() + timeoutMs;
+        while (pidAlive(target.pid) && Date.now() < deadline)
+            await sleep(100);
+        return { stopped: !pidAlive(target.pid) };
+    }
+    if (probe.kind !== "ok" || probe.health.pid !== target.pid) {
+        return { stopped: false, stale: true };
     }
     const asked = await client.stop();
     const deadline = Date.now() + timeoutMs;
-    while (asked && pidAlive(info.pid) && Date.now() < deadline) {
+    while (asked && pidAlive(target.pid) && Date.now() < deadline) {
         await sleep(100);
     }
     let forced = false;
-    if (pidAlive(info.pid)) {
+    if (pidAlive(target.pid)) {
         forced = true;
         try {
-            process.kill(info.pid, "SIGTERM");
+            process.kill(target.pid, "SIGTERM");
         }
         catch (err) {
-            logLine("daemon.kill_failed", { pid: info.pid, error: errText(err) });
+            logLine("daemon.kill_failed", { pid: target.pid, error: errText(err) });
         }
-        const hardDeadline = Date.now() + 3_000;
-        while (pidAlive(info.pid) && Date.now() < hardDeadline) {
+        let hardDeadline = Date.now() + 3_000;
+        while (pidAlive(target.pid) && Date.now() < hardDeadline) {
             await sleep(100);
         }
+        if (pidAlive(target.pid) && process.platform !== "win32") {
+            // POSIX only: a recorder stuck in its own shutdown ignores a repeated
+            // SIGTERM. (On Windows the SIGTERM above already was a hard kill.)
+            try {
+                process.kill(target.pid, "SIGKILL");
+            }
+            catch (err) {
+                logLine("daemon.kill_failed", { pid: target.pid, signal: "SIGKILL", error: errText(err) });
+            }
+            hardDeadline = Date.now() + 2_000;
+            while (pidAlive(target.pid) && Date.now() < hardDeadline) {
+                await sleep(100);
+            }
+        }
+    }
+    return { stopped: !pidAlive(target.pid), forced };
+}
+/**
+ * Stop one superseded recorder (see {@link listSupersededRecorders}) the same
+ * way {@link stopDaemon} stops the project's: asked, and signalled only when
+ * it answers `/health` as its own pid. Its record is removed once it is gone
+ * (its own exit does that too), or when nothing answers as it.
+ */
+export async function stopSupersededRecorder(record, opts = {}) {
+    const result = await stopVerified(record, opts.timeoutMs ?? 10_000);
+    if (result.stopped || result.stale)
+        removeSupersededRecord(record.cwd, record.pid);
+    return { ...result, pid: record.pid };
+}
+/**
+ * Stop every superseded recorder of `cwd` (or of every project, without
+ * one). For `bir down` and `bir uninstall`; the project's own recorder is
+ * {@link stopDaemon}'s.
+ */
+export async function stopSupersededRecorders(cwd, opts = {}) {
+    const out = [];
+    for (const record of listSupersededRecorders(cwd)) {
+        const r = await stopSupersededRecorder(record, opts);
+        out.push({ record, stopped: r.stopped, stale: r.stale, forced: r.forced });
+    }
+    return out;
+}
+export function readPortProblem(cwd) {
+    try {
+        const path = portProblemPath(cwd);
+        if (!existsSync(path))
+            return undefined;
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed.port !== "number" || typeof parsed.detail !== "string")
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writePortProblem(cwd, problem) {
+    try {
+        ensureDir(controlDir());
+        writeFileAtomic(portProblemPath(cwd), JSON.stringify(problem, null, 2), { mode: 0o600 });
+    }
+    catch {
+        /* the log line says it too */
+    }
+}
+export function clearPortProblem(cwd) {
+    try {
+        const path = portProblemPath(cwd);
+        if (existsSync(path))
+            unlinkSync(path);
+    }
+    catch {
+        /* best effort */
+    }
+}
+// ── the background recorder's own log ──────────────────────────────────────
+function silentConsole() {
+    const sink = new Writable({
+        write(_chunk, _encoding, callback) {
+            callback();
+        },
+    });
+    return new Console({ stdout: sink, stderr: sink });
+}
+/**
+ * The log a background recorder writes its audit lines to.
+ *
+ * Three things the plain stream did not do. It never fails the process: a
+ * file (or a logs directory) that cannot be opened or written — a full disk,
+ * a read-only or locked profile — used to be an unhandled `'error'` that
+ * killed the recorder at start, and with it every hook of the session. Now the
+ * lines are dropped instead. It comes back: a failure is usually brief (the
+ * disk full for a minute, an antivirus scan holding the file), and a recorder
+ * that runs for days must not stay silent for all of them — the minute tick
+ * ({@link rotateIfLarge}) opens the file again. And it stays bounded while the
+ * recorder runs for weeks: rolled to `.1` once it passes
+ * {@link LOG_ROTATE_BYTES}, not only when a new one starts.
+ *
+ * And it shares a path safely. Two recorders of one project can run at once
+ * (a reinstall moved the hooks to another port while a window was open), and
+ * `ensureDaemon` rolls the log before a start. Whoever rolled it, the other
+ * writer's stream follows the renamed file — all its lines went to `.1`, which
+ * then grew without bound, and on Windows the held `.1` made every later roll
+ * fail. So the minute tick first checks that the file at the path is the one
+ * it writes, and opens the path again when it is not. A recorder superseded
+ * like that also moves to a file of its own ({@link moveTo}).
+ */
+export class DaemonLog {
+    stream;
+    /** The descriptor {@link stream} writes to, once it is open. */
+    fd;
+    current;
+    maxBytes;
+    /** Set once lines have been dropped, so the reopen can say so. */
+    droppedSince;
+    constructor(path, maxBytes = LOG_ROTATE_BYTES) {
+        this.current = path;
+        this.maxBytes = maxBytes;
+    }
+    /** The file lines go to now. */
+    get path() {
+        return this.current;
+    }
+    /** Open the file and point `console` (every `logLine`) at it. Never throws. */
+    open() {
+        try {
+            ensureDir(dirname(this.current));
+        }
+        catch {
+            this.silence();
+            return;
+        }
+        this.attach();
+    }
+    /**
+     * Write to `path` from now on — a superseded recorder's own file, so the
+     * project's log keeps one writer and one rotation. Never throws.
+     */
+    moveTo(path) {
+        if (path === this.current)
+            return;
+        const old = this.stream;
+        this.current = path;
+        try {
+            ensureDir(dirname(path));
+        }
+        catch {
+            /* the open below fails and stays silent */
+        }
+        this.attach();
+        old?.end();
+    }
+    silence() {
+        this.stream = undefined;
+        this.fd = undefined;
+        this.droppedSince ??= Date.now();
+        globalThis.console = silentConsole();
+    }
+    attach() {
+        let stream;
+        try {
+            stream = createWriteStream(this.current, { flags: "a" });
+        }
+        catch {
+            this.silence();
+            return;
+        }
+        stream.on("error", () => {
+            if (this.stream !== stream)
+                return;
+            this.silence();
+        });
+        stream.once("open", (fd) => {
+            if (this.stream === stream)
+                this.fd = fd;
+        });
+        this.stream = stream;
+        this.fd = undefined;
+        globalThis.console = new Console({ stdout: stream, stderr: stream });
+    }
+    /**
+     * Roll the file to `.1` if it is past the limit, and open it again if it
+     * failed earlier, or if the file at the path is no longer the one written
+     * (another writer rolled or removed it). True when it rolled. Never throws.
+     */
+    rotateIfLarge() {
+        const old = this.stream;
+        if (!old) {
+            this.reopen();
+            return false;
+        }
+        this.droppedSince = undefined;
+        let size;
+        try {
+            const onDisk = statSync(this.current, { bigint: true });
+            if (!this.writes(onDisk)) {
+                this.attach();
+                old.end();
+                return false;
+            }
+            size = Number(onDisk.size);
+        }
+        catch (err) {
+            // Removed or rolled away by somebody else, and nothing there yet.
+            if (err.code === "ENOENT") {
+                this.attach();
+                old.end();
+            }
+            return false;
+        }
+        if (size <= this.maxBytes)
+            return false;
+        try {
+            // The open stream keeps writing to the renamed file until it is ended
+            // below; libuv opens files shareable for delete, so this works on
+            // Windows too.
+            renameSync(this.current, `${this.current}.1`);
+        }
+        catch {
+            return false;
+        }
+        this.attach();
+        old.end();
+        return true;
+    }
+    /** Whether `onDisk` is the file this log's stream writes (true when it cannot tell). */
+    writes(onDisk) {
+        if (this.fd === undefined)
+            return true;
+        try {
+            const mine = fstatSync(this.fd, { bigint: true });
+            // A file system without file ids says nothing either way.
+            if (mine.ino === 0n || onDisk.ino === 0n)
+                return true;
+            return mine.ino === onDisk.ino && mine.dev === onDisk.dev;
+        }
+        catch {
+            return true;
+        }
+    }
+    /** After a failure: try the file again. A stream that fails again just stays silent. */
+    reopen() {
+        try {
+            ensureDir(dirname(this.current));
+        }
+        catch {
+            return;
+        }
+        this.attach();
+        // Its own `'error'` arrives later if the file still cannot be written;
+        // then this line is dropped too, and the next tick tries again. The
+        // start of the gap is forgotten only once a stream has lasted a tick.
+        if (this.stream && this.droppedSince !== undefined) {
+            logLine("control.log_reopened", {
+                dropped_since: new Date(this.droppedSince).toISOString(),
+                why: "the log could not be written for a while; lines from that time are missing",
+            });
+        }
+    }
+    close() {
+        this.stream?.end();
     }
-    // Its own shutdown removes the file; a killed process could not.
-    if (!pidAlive(info.pid))
-        removeDiscovery(cwd);
-    return { stopped: !pidAlive(info.pid), pid: info.pid, forced };
 }
 // ── the start lock ─────────────────────────────────────────────────────────
 function lockPath(cwd) {
@@ -288,9 +1278,12 @@ function acquireLock(path) {
             // go ahead uncoordinated rather than sit out the whole timeout.
             if (err.code !== "EEXIST")
                 return true;
-            // Somebody holds it. Alive and recent: theirs. Old: they died holding it.
+            // Somebody holds it. Alive and recent: theirs. Old, or its process
+            // gone: they died holding it.
             try {
-                if (Date.now() - statSync(path).mtimeMs < LOCK_STALE_MS)
+                const holder = lockHolder(path);
+                const fresh = Date.now() - statSync(path).mtimeMs < LOCK_STALE_MS;
+                if (fresh && (holder === undefined || pidAlive(holder)))
                     return false;
                 unlinkSync(path);
             }
@@ -301,6 +1294,16 @@ function acquireLock(path) {
     }
     return false;
 }
+/** The pid that wrote the lock, when it can be read. */
+function lockHolder(path) {
+    try {
+        const pid = Number(readFileSync(path, "utf8").trim().split(/\s+/)[0]);
+        return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function releaseLock(path) {
     try {
         if (existsSync(path))