@basein/runner 0.2.12 → 0.3.1

package/dist/control/discovery.d.ts

@@ -19,7 +19,12 @@
  * STALENESS. A discovery file outlives its process on a crash. Every read checks
  * that the recorded pid is still alive (`kill(pid, 0)`) and that the file is not
  * older than {@link MAX_DISCOVERY_AGE_MS}; a stale file is treated as absent, so
- * a dead session can never capture a live proxy's steps.
+ * a dead session can never capture a live proxy's steps. The age rule is for
+ * proxies, which cannot afford a network probe per start; the ensure hook and
+ * `bir down` ask the recorder itself (`readDiscovery(cwd, { ignoreAge: true })`
+ * plus `/health`), because a laptop that slept over a weekend wakes with a live
+ * recorder whose file reads as days old — and treating that as dead started a
+ * duplicate that could not bind, and hid the live one from every proxy.
  *
  * SECURITY (§9). Files are mode 0600 and carry the loopback bearer token. A local
  * port that accepts unauthenticated step reports is a local exfiltration channel.
@@ -29,11 +34,17 @@ export declare const MAX_DISCOVERY_AGE_MS: number;
 /**
  * How often a running control server rewrites its discovery file.
  *
- * Well inside {@link MAX_DISCOVERY_AGE_MS}: a background recorder that misses
- * a few beats (a laptop asleep over a weekend) is still found on Monday, and a
- * dead one is still forgotten within a day.
+ * Well inside {@link MAX_DISCOVERY_AGE_MS}, so a dead recorder is still
+ * forgotten within a day. It is measured on the wall clock, not by a timer
+ * alone: on macOS and Linux a timer's clock stops while the machine sleeps, so
+ * a recorder woken after a weekend would wait up to this long for its next beat
+ * while its file read as stale. `bir-hooks` checks every
+ * {@link DISCOVERY_CHECK_MS} and rewrites when this much wall time has passed
+ * since the last write, or when the file has gone missing.
  */
 export declare const HEARTBEAT_MS: number;
+/** How often a running control server checks its discovery file (see {@link HEARTBEAT_MS}). */
+export declare const DISCOVERY_CHECK_MS: number;
 export interface DiscoveryInfo {
     url: string;
     /** Random 32 bytes hex; required on every control-server route. */
@@ -61,13 +72,74 @@ export interface DiscoveryInfo {
 }
 export declare function writeDiscovery(info: DiscoveryInfo): string;
 export declare function removeDiscovery(cwd: string): void;
+/**
+ * Remove the discovery file for `cwd` only if it still names `pid`.
+ *
+ * A recorder that is shutting down must not delete the file of the one that
+ * replaced it, and a process that found this project's port already served by
+ * this project's recorder must leave that recorder's file alone.
+ */
+export declare function removeDiscoveryIfOwned(cwd: string, pid: number): void;
 /** True when a pid is still running (or when we cannot tell, which we treat as alive). */
 export declare function pidAlive(pid: number): boolean;
+export interface ReadDiscoveryOptions {
+    /**
+     * Skip the {@link MAX_DISCOVERY_AGE_MS} rule and let the caller decide by
+     * asking the process (`/health`). The pid must still be alive.
+     */
+    ignoreAge?: boolean;
+}
 /**
  * Read the discovery file for `cwd`, or undefined when there is none, it is
  * malformed, or it is stale.
  */
-export declare function readDiscovery(cwd: string): DiscoveryInfo | undefined;
+export declare function readDiscovery(cwd: string, opts?: ReadDiscoveryOptions): DiscoveryInfo | undefined;
+/** Newest of a record's two stamps, epoch ms (0 when it has neither). */
+export declare function discoveryStamp(info: Pick<DiscoveryInfo, "startedAt" | "heartbeatAt">): number;
+/**
+ * Delete the control directory's records of recorders that are gone.
+ *
+ * Each discovery file carries its project's loopback token, and nothing ever
+ * removed the file of a recorder that crashed, or of a project that was
+ * deleted: one machine had seven of them, months old. Removed: records whose
+ * pid is dead, unreadable records older than a day, and temp files a writer
+ * left behind. A record whose pid is alive is kept whatever its age — that
+ * process is asked, not guessed about (see {@link readDiscovery}).
+ *
+ * Never throws. Returns how many files it removed.
+ */
+export declare function sweepStaleDiscovery(now?: number): number;
+/**
+ * A recorder that no longer serves the port its project's hooks post to — a
+ * reinstall (`bir install --port N`, `bir uninstall` + `bir setup`) moved
+ * them while a Claude Code window was open — and is kept for the windows
+ * opened before, whose hooks still name its port. The project's discovery
+ * file names the new recorder only, so without this record the old one could
+ * not be listed or stopped. Mode 0600: it carries the old token.
+ */
+export interface SupersededRecorder {
+    cwd: string;
+    pid: number;
+    port: number;
+    url: string;
+    /** Its loopback token, so it can be asked to stop rather than killed. */
+    token: string;
+    /** When it was first seen superseded, epoch ms. */
+    since: number;
+    version?: string;
+    logFile?: string;
+}
+/** Write (or rewrite) the record of a superseded recorder. Never throws; the path, or undefined. */
+export declare function writeSupersededRecord(record: SupersededRecorder): string | undefined;
+/** Remove the record of superseded recorder `pid` of `cwd`. Never throws. */
+export declare function removeSupersededRecord(cwd: string, pid: number): void;
+/**
+ * The superseded recorders of `cwd` still running — or of every project when
+ * `cwd` is undefined — oldest first. A record whose process is gone is removed
+ * on the way. Nothing here asks the process who it is: stopping one goes
+ * through `/health` first (daemon.ts, stopSupersededRecorder).
+ */
+export declare function listSupersededRecorders(cwd?: string): SupersededRecorder[];
 /**
  * Resolve the control server for `cwd`, retrying until `timeoutMs` elapses.
  * `BIR_CONTROL_URL` short-circuits the search (with `BIR_CONTROL_TOKEN` for auth).

package/dist/control/discovery.js

@@ -19,24 +19,37 @@
  * STALENESS. A discovery file outlives its process on a crash. Every read checks
  * that the recorded pid is still alive (`kill(pid, 0)`) and that the file is not
  * older than {@link MAX_DISCOVERY_AGE_MS}; a stale file is treated as absent, so
- * a dead session can never capture a live proxy's steps.
+ * a dead session can never capture a live proxy's steps. The age rule is for
+ * proxies, which cannot afford a network probe per start; the ensure hook and
+ * `bir down` ask the recorder itself (`readDiscovery(cwd, { ignoreAge: true })`
+ * plus `/health`), because a laptop that slept over a weekend wakes with a live
+ * recorder whose file reads as days old — and treating that as dead started a
+ * duplicate that could not bind, and hid the live one from every proxy.
  *
  * SECURITY (§9). Files are mode 0600 and carry the loopback bearer token. A local
  * port that accepts unauthenticated step reports is a local exfiltration channel.
  */
-import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { controlDir, discoveryPath, ensureDir } from "./paths.js";
+import { existsSync, readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { controlDir, controlKey, discoveryPath, ensureDir, normalizePath, supersededPath } from "./paths.js";
 import { logDetail, errText } from "../util/log.js";
+import { writeFileAtomic } from "../util/atomic-write.js";
 /** A discovery file older than this is ignored even if its pid is somehow alive. */
 export const MAX_DISCOVERY_AGE_MS = 24 * 60 * 60 * 1000;
 /**
  * How often a running control server rewrites its discovery file.
  *
- * Well inside {@link MAX_DISCOVERY_AGE_MS}: a background recorder that misses
- * a few beats (a laptop asleep over a weekend) is still found on Monday, and a
- * dead one is still forgotten within a day.
+ * Well inside {@link MAX_DISCOVERY_AGE_MS}, so a dead recorder is still
+ * forgotten within a day. It is measured on the wall clock, not by a timer
+ * alone: on macOS and Linux a timer's clock stops while the machine sleeps, so
+ * a recorder woken after a weekend would wait up to this long for its next beat
+ * while its file read as stale. `bir-hooks` checks every
+ * {@link DISCOVERY_CHECK_MS} and rewrites when this much wall time has passed
+ * since the last write, or when the file has gone missing.
  */
 export const HEARTBEAT_MS = 30 * 60 * 1000;
+/** How often a running control server checks its discovery file (see {@link HEARTBEAT_MS}). */
+export const DISCOVERY_CHECK_MS = 60 * 1000;
 export function writeDiscovery(info) {
     ensureDir(controlDir());
     const path = discoveryPath(info.cwd);
@@ -44,9 +57,9 @@ export function writeDiscovery(info) {
     // The heartbeat rewrites this every half hour, and a proxy or the ensure
     // hook reading an empty file in that instant would conclude "no recorder"
     // and start a second one.
-    const tmp = `${path}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify(info, null, 2), { mode: 0o600 });
-    renameSync(tmp, path);
+    // writeFileAtomic also retries the rename that a reader's open handle can
+    // refuse for a moment on Windows.
+    writeFileAtomic(path, JSON.stringify(info, null, 2), { mode: 0o600 });
     return path;
 }
 export function removeDiscovery(cwd) {
@@ -59,6 +72,26 @@ export function removeDiscovery(cwd) {
         /* best effort */
     }
 }
+/**
+ * Remove the discovery file for `cwd` only if it still names `pid`.
+ *
+ * A recorder that is shutting down must not delete the file of the one that
+ * replaced it, and a process that found this project's port already served by
+ * this project's recorder must leave that recorder's file alone.
+ */
+export function removeDiscoveryIfOwned(cwd, pid) {
+    try {
+        const path = discoveryPath(cwd);
+        if (!existsSync(path))
+            return;
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed.pid === pid)
+            unlinkSync(path);
+    }
+    catch {
+        /* best effort */
+    }
+}
 /** True when a pid is still running (or when we cannot tell, which we treat as alive). */
 export function pidAlive(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
@@ -76,7 +109,7 @@ export function pidAlive(pid) {
  * Read the discovery file for `cwd`, or undefined when there is none, it is
  * malformed, or it is stale.
  */
-export function readDiscovery(cwd) {
+export function readDiscovery(cwd, opts = {}) {
     const path = discoveryPath(cwd);
     try {
         if (!existsSync(path))
@@ -92,7 +125,7 @@ export function readDiscovery(cwd) {
         // every `HEARTBEAT_MS` precisely so this check keeps saying so. A file
         // whose process died keeps its last stamp and ages out as before.
         const freshest = Math.max(parsed.startedAt ?? 0, parsed.heartbeatAt ?? 0);
-        if (Date.now() - freshest > MAX_DISCOVERY_AGE_MS) {
+        if (!opts.ignoreAge && Date.now() - freshest > MAX_DISCOVERY_AGE_MS) {
             logDetail("discovery.stale", { path, reason: "too old" });
             return undefined;
         }
@@ -107,6 +140,148 @@ export function readDiscovery(cwd) {
         return undefined;
     }
 }
+/** Newest of a record's two stamps, epoch ms (0 when it has neither). */
+export function discoveryStamp(info) {
+    return Math.max(info.startedAt ?? 0, info.heartbeatAt ?? 0);
+}
+/** A temp file older than this was left by a writer that died mid-write. */
+const TMP_STALE_MS = 60 * 60 * 1000;
+/**
+ * Delete the control directory's records of recorders that are gone.
+ *
+ * Each discovery file carries its project's loopback token, and nothing ever
+ * removed the file of a recorder that crashed, or of a project that was
+ * deleted: one machine had seven of them, months old. Removed: records whose
+ * pid is dead, unreadable records older than a day, and temp files a writer
+ * left behind. A record whose pid is alive is kept whatever its age — that
+ * process is asked, not guessed about (see {@link readDiscovery}).
+ *
+ * Never throws. Returns how many files it removed.
+ */
+export function sweepStaleDiscovery(now = Date.now()) {
+    let removed = 0;
+    let names;
+    try {
+        names = readdirSync(controlDir());
+    }
+    catch {
+        return 0;
+    }
+    for (const name of names) {
+        const path = join(controlDir(), name);
+        try {
+            if (name.endsWith(".tmp")) {
+                if (now - statSync(path).mtimeMs > TMP_STALE_MS) {
+                    unlinkSync(path);
+                    removed += 1;
+                }
+                continue;
+            }
+            // Discovery records and superseded recorders' records only: `<key>.json`
+            // and `<key>.superseded.<pid>.json` — not `<key>.port.json`, a lock, a
+            // down marker, or the journal directory.
+            if (!/^[0-9a-f]{16}(?:\.superseded\.\d+)?\.json$/.test(name))
+                continue;
+            let pid;
+            try {
+                pid = JSON.parse(readFileSync(path, "utf8")).pid;
+            }
+            catch {
+                if (now - statSync(path).mtimeMs > MAX_DISCOVERY_AGE_MS) {
+                    unlinkSync(path);
+                    removed += 1;
+                }
+                continue;
+            }
+            if (typeof pid !== "number" || !pidAlive(pid)) {
+                unlinkSync(path);
+                removed += 1;
+            }
+        }
+        catch {
+            /* best effort: somebody else removed it, or is writing it */
+        }
+    }
+    if (removed > 0)
+        logDetail("discovery.swept", { removed });
+    return removed;
+}
+/** Write (or rewrite) the record of a superseded recorder. Never throws; the path, or undefined. */
+export function writeSupersededRecord(record) {
+    try {
+        ensureDir(controlDir());
+        const path = supersededPath(record.cwd, record.pid);
+        writeFileAtomic(path, JSON.stringify(record, null, 2), { mode: 0o600 });
+        return path;
+    }
+    catch (err) {
+        logDetail("discovery.superseded_write_failed", { error: errText(err) });
+        return undefined;
+    }
+}
+/** Remove the record of superseded recorder `pid` of `cwd`. Never throws. */
+export function removeSupersededRecord(cwd, pid) {
+    try {
+        const path = supersededPath(cwd, pid);
+        if (existsSync(path))
+            unlinkSync(path);
+    }
+    catch {
+        /* best effort; the sweep removes it once the pid is gone */
+    }
+}
+/**
+ * The superseded recorders of `cwd` still running — or of every project when
+ * `cwd` is undefined — oldest first. A record whose process is gone is removed
+ * on the way. Nothing here asks the process who it is: stopping one goes
+ * through `/health` first (daemon.ts, stopSupersededRecorder).
+ */
+export function listSupersededRecorders(cwd) {
+    let names;
+    try {
+        names = readdirSync(controlDir());
+    }
+    catch {
+        return [];
+    }
+    const prefix = cwd === undefined ? undefined : `${controlKey(cwd)}.superseded.`;
+    const found = [];
+    for (const name of names) {
+        if (!/^[0-9a-f]{16}\.superseded\.\d+\.json$/.test(name))
+            continue;
+        if (prefix && !name.startsWith(prefix))
+            continue;
+        const path = join(controlDir(), name);
+        try {
+            const r = JSON.parse(readFileSync(path, "utf8"));
+            if (typeof r.pid !== "number" ||
+                typeof r.url !== "string" ||
+                typeof r.token !== "string" ||
+                typeof r.cwd !== "string" ||
+                (cwd !== undefined && normalizePath(r.cwd) !== normalizePath(cwd))) {
+                continue;
+            }
+            if (!pidAlive(r.pid)) {
+                unlinkSync(path);
+                continue;
+            }
+            found.push({
+                cwd: r.cwd,
+                pid: r.pid,
+                port: typeof r.port === "number" ? r.port : Number(new URL(r.url).port) || 0,
+                url: r.url,
+                token: r.token,
+                since: typeof r.since === "number" ? r.since : 0,
+                version: typeof r.version === "string" ? r.version : undefined,
+                logFile: typeof r.logFile === "string" ? r.logFile : undefined,
+            });
+        }
+        catch {
+            /* unreadable, or removed meanwhile */
+        }
+    }
+    return found.sort((a, b) => a.since - b.since);
+}
 /**
  * Resolve the control server for `cwd`, retrying until `timeoutMs` elapses.
  * `BIR_CONTROL_URL` short-circuits the search (with `BIR_CONTROL_TOKEN` for auth).

package/dist/control/ensure-hook.d.ts

@@ -17,12 +17,65 @@
  * stderr and a session that records Tier 2, exactly what happened before this
  * hook existed.
  *
+ * THE BUDGET. Claude Code waits for this hook — the session does not start
+ * until it answers — up to the timeout `bir install` wrote (15 s). The whole
+ * hook stays inside {@link ENSURE_HOOK_BUDGET_MS}: reading the payload, finding
+ * or starting the recorder, the relay, and the override check (which is
+ * skipped when little is left). A warm start (the recorder is
+ * running) is one loopback round trip; a cold one is the recorder's start-up,
+ * about a second, because the recorder listens before it touches the network.
+ * Nothing here waits on the BaseIn service. When the budget runs out the hook
+ * exits 0 and the recorder finishes coming up in the background; the next
+ * hook finds it.
+ *
+ * THE OFF SWITCH (`bir off`) does not skip this hook. The recorder is still
+ * started, because it is what answers every other hook at once with `{}` while
+ * off — without it Claude Code would show each of them a refused connection.
+ * Only the override check below is skipped while off. `BIR_OFF=1` in the
+ * environment Claude Code was started with is this window's switch, not the
+ * recorder's: the recorder serves every window of the project and never
+ * inherits it (daemon.ts, daemonEnv), so the relay tells it that this
+ * session is off (`bir_off: true`) and it answers this session's hooks `{}`.
+ *
+ * STALE OVERRIDES. Once the recorder is started or kept, the hook looks at the
+ * local-scope copies `bir install` made of this project's `.mcp.json` and
+ * user-scope servers (config/overrides.ts, checkOverrides): a copy whose
+ * source changed, or whose source is gone or no longer approved, is named in
+ * one line of the project's recorder log, with the fix (`bir setup`). It is
+ * read-only. It used to repair them here, and that meant rewriting
+ * `~/.claude.json` at the very moment Claude Code, starting, writes its own
+ * state there — without Claude Code's lock, so either write could be lost.
+ * `bir setup` and `bir doctor` repair; local files only, never throws, and
+ * only with enough of the budget left.
+ *
  * STDOUT IS CONTEXT. For SessionStart, Claude Code adds whatever a command hook
  * prints on stdout to the model's context. So nothing is printed unless the
  * control server answered with something (today it answers `{}`), and then it
  * is the answer, verbatim, as JSON.
  */
 import { type EnsureOptions } from "./daemon.js";
+/**
+ * The whole hook's budget. Inside the 15 s SessionStart timeout `bir install`
+ * writes (C9: the hook's own work stays at or under 12 s), with room for node
+ * to start and load this module.
+ */
+export declare const ENSURE_HOOK_BUDGET_MS = 11000;
+/**
+ * The least of the budget the override check needs to be started. It is
+ * synchronous and local — a few JSON files, plus a `git ls-files` capped at
+ * 2 s in the rare case an approval depends on it — so with less than this
+ * left it waits for the next session start instead of running past the hook's
+ * budget.
+ */
+export declare const OVERRIDE_CHECK_RESERVE_MS = 3000;
+/** The earlier name of {@link OVERRIDE_CHECK_RESERVE_MS}. */
+export declare const RESYNC_RESERVE_MS = 3000;
+/** What the override check reports: one entry per local copy that no longer copies its source. */
+export type StaleOverrides = Array<{
+    name: string;
+    state: string;
+    why?: string;
+}>;
 export interface EnsureHookOptions extends EnsureOptions {
     stdin?: NodeJS.ReadableStream & {
         isTTY?: boolean;
@@ -31,6 +84,14 @@ export interface EnsureHookOptions extends EnsureOptions {
     stderr?: NodeJS.WritableStream;
     /** How long to wait for the payload on stdin before going on without it. */
     stdinTimeoutMs?: number;
+    /** The whole hook's budget. Defaults to {@link ENSURE_HOOK_BUDGET_MS}. */
+    budgetMs?: number;
+    /**
+     * The read-only stale-override check run once the recorder is started or
+     * kept: the stale entries of `checkOverrides` by default, `false` to skip
+     * it. Injected by tests. It must not write anything.
+     */
+    overrideCheck?: ((projectCwd: string) => StaleOverrides) | false;
 }
 /**
  * Run the hook for `cwd`. Resolves the exit code, which is always 0.

package/dist/control/ensure-hook.js

@@ -17,13 +17,146 @@
  * stderr and a session that records Tier 2, exactly what happened before this
  * hook existed.
  *
+ * THE BUDGET. Claude Code waits for this hook — the session does not start
+ * until it answers — up to the timeout `bir install` wrote (15 s). The whole
+ * hook stays inside {@link ENSURE_HOOK_BUDGET_MS}: reading the payload, finding
+ * or starting the recorder, the relay, and the override check (which is
+ * skipped when little is left). A warm start (the recorder is
+ * running) is one loopback round trip; a cold one is the recorder's start-up,
+ * about a second, because the recorder listens before it touches the network.
+ * Nothing here waits on the BaseIn service. When the budget runs out the hook
+ * exits 0 and the recorder finishes coming up in the background; the next
+ * hook finds it.
+ *
+ * THE OFF SWITCH (`bir off`) does not skip this hook. The recorder is still
+ * started, because it is what answers every other hook at once with `{}` while
+ * off — without it Claude Code would show each of them a refused connection.
+ * Only the override check below is skipped while off. `BIR_OFF=1` in the
+ * environment Claude Code was started with is this window's switch, not the
+ * recorder's: the recorder serves every window of the project and never
+ * inherits it (daemon.ts, daemonEnv), so the relay tells it that this
+ * session is off (`bir_off: true`) and it answers this session's hooks `{}`.
+ *
+ * STALE OVERRIDES. Once the recorder is started or kept, the hook looks at the
+ * local-scope copies `bir install` made of this project's `.mcp.json` and
+ * user-scope servers (config/overrides.ts, checkOverrides): a copy whose
+ * source changed, or whose source is gone or no longer approved, is named in
+ * one line of the project's recorder log, with the fix (`bir setup`). It is
+ * read-only. It used to repair them here, and that meant rewriting
+ * `~/.claude.json` at the very moment Claude Code, starting, writes its own
+ * state there — without Claude Code's lock, so either write could be lost.
+ * `bir setup` and `bir doctor` repair; local files only, never throws, and
+ * only with enough of the budget left.
+ *
  * STDOUT IS CONTEXT. For SessionStart, Claude Code adds whatever a command hook
  * prints on stdout to the model's context. So nothing is printed unless the
  * control server answered with something (today it answers `{}`), and then it
  * is the answer, verbatim, as JSON.
  */
-import { ensureDaemon } from "./daemon.js";
-import { errText } from "../util/log.js";
+import { appendFileSync } from "node:fs";
+import { Console } from "node:console";
+import { dirname } from "node:path";
+import { Writable } from "node:stream";
+import { ensureDaemon, RecorderBusyError } from "./daemon.js";
+import { daemonLogPath, ensureDir } from "./paths.js";
+import { checkOverrides } from "../config/overrides.js";
+import { isRunnerOff } from "../util/off-switch.js";
+import { timeoutSignal } from "../util/service-health.js";
+import { errText, logLine } from "../util/log.js";
+/**
+ * The whole hook's budget. Inside the 15 s SessionStart timeout `bir install`
+ * writes (C9: the hook's own work stays at or under 12 s), with room for node
+ * to start and load this module.
+ */
+export const ENSURE_HOOK_BUDGET_MS = 11_000;
+/** Kept back from the recorder start for the relay that follows it. */
+const RELAY_RESERVE_MS = 1_000;
+/** The relay's own ceiling; the control server answers SessionStart in well under this. */
+const RELAY_TIMEOUT_MS = 2_500;
+/** Claude Code writes the payload and closes stdin at once; a person at a terminal writes nothing. */
+const STDIN_TIMEOUT_MS = 2_000;
+/**
+ * The least of the budget the override check needs to be started. It is
+ * synchronous and local — a few JSON files, plus a `git ls-files` capped at
+ * 2 s in the rare case an approval depends on it — so with less than this
+ * left it waits for the next session start instead of running past the hook's
+ * budget.
+ */
+export const OVERRIDE_CHECK_RESERVE_MS = 3_000;
+/** The earlier name of {@link OVERRIDE_CHECK_RESERVE_MS}. */
+export const RESYNC_RESERVE_MS = OVERRIDE_CHECK_RESERVE_MS;
+/** The copies `checkOverrides` finds stale. Reads files only. */
+function staleOverrides(projectCwd) {
+    return checkOverrides(projectCwd)
+        .filter((c) => c.state !== "current")
+        .map((c) => ({ name: c.name, state: c.state, why: c.why }));
+}
+/**
+ * Run `fn` with every audit line it logs appended to `file` — the project's
+ * recorder log, where `bir doctor` and a person looking for "what changed my
+ * MCP config" read — instead of this hook's stderr, which nobody sees.
+ * Synchronous and best-effort: a line that cannot be written is dropped, and
+ * never costs the hook anything.
+ */
+function logInto(file, fn) {
+    ensureDir(dirname(file));
+    const sink = new Writable({
+        write(chunk, _encoding, callback) {
+            try {
+                appendFileSync(file, chunk);
+            }
+            catch {
+                /* dropped: the log is not worth a failed session start */
+            }
+            callback();
+        },
+    });
+    const saved = globalThis.console;
+    globalThis.console = new Console({ stdout: sink, stderr: sink });
+    try {
+        fn();
+    }
+    finally {
+        globalThis.console = saved;
+    }
+}
+/**
+ * The stale-override check (see STALE OVERRIDES above): one line in the
+ * project's log naming what is stale and the fix. Skipped while the runner is
+ * off and when less than {@link OVERRIDE_CHECK_RESERVE_MS} of the budget is
+ * left. Never throws; writes nothing to stdout, and nothing to Claude Code's
+ * files.
+ */
+function reportStaleOverrides(projectCwd, logFile, msLeft, check) {
+    if (msLeft < OVERRIDE_CHECK_RESERVE_MS)
+        return;
+    try {
+        if (isRunnerOff(projectCwd))
+            return;
+        const stale = check(projectCwd);
+        if (stale.length === 0)
+            return;
+        logInto(logFile, () => {
+            logLine("overrides.stale", {
+                servers: stale.map((s) => `${s.name} (${s.state})`).join(", "),
+                why: stale
+                    .map((s) => s.why)
+                    .filter(Boolean)
+                    .join("; ") || undefined,
+                fix: `run \`bir setup\` in ${projectCwd} — it copies them again (or removes them); \`bir doctor\` names each`,
+                effect: "until then this project's sessions run the old copies",
+            });
+        });
+    }
+    catch {
+        /* a check that failed leaves things as they were; `bir doctor` names what is stale */
+    }
+}
+/** True when this process's own environment switches the runner off (`BIR_OFF=1` or `true`). */
+function offInThisEnvironment() {
+    const value = (process.env.BIR_OFF ?? "").trim().toLowerCase();
+    return value === "1" || value === "true";
+}
 /** Read stdin to its end, or give up after `timeoutMs` with what arrived. */
 function readStdin(stream, timeoutMs) {
     // A person running `bir-hooks ensure` by hand has nothing to paste; do not
@@ -53,26 +186,34 @@ function readStdin(stream, timeoutMs) {
  * Run the hook for `cwd`. Resolves the exit code, which is always 0.
  */
 export async function runEnsureHook(cwd, opts = {}) {
+    const startedAt = Date.now();
+    const budgetMs = opts.budgetMs ?? ENSURE_HOOK_BUDGET_MS;
+    const left = () => budgetMs - (Date.now() - startedAt);
     const stdout = opts.stdout ?? process.stdout;
     const stderr = opts.stderr ?? process.stderr;
-    const raw = await readStdin(opts.stdin ?? process.stdin, opts.stdinTimeoutMs ?? 3_000);
+    const raw = await readStdin(opts.stdin ?? process.stdin, Math.min(opts.stdinTimeoutMs ?? STDIN_TIMEOUT_MS, Math.max(100, budgetMs / 4)));
     let payload = {};
     if (raw.trim()) {
         try {
-            payload = JSON.parse(raw);
+            const parsed = JSON.parse(raw);
+            payload = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
         }
         catch {
             // Not our problem to diagnose; the control server copes with an empty one.
             payload = {};
         }
     }
+    /** Set once the recorder is started or kept: the project it serves, and its log. */
+    let kept;
     try {
         const { status, started, restarted } = await ensureDaemon(cwd, {
             hooksScript: opts.hooksScript,
             env: opts.env,
-            timeoutMs: opts.timeoutMs,
+            timeoutMs: Math.min(opts.timeoutMs ?? Number.POSITIVE_INFINITY, Math.max(1_000, left() - RELAY_RESERVE_MS)),
             restartOnSkew: opts.restartOnSkew ?? true,
         });
+        const project = status.info.cwd || cwd;
+        kept = { project, logFile: status.info.logFile ?? daemonLogPath(project) };
         if (started) {
             stderr.write(`[bir] recorder ${restarted ? "restarted" : "started"} in the background (pid ${status.info.pid}, log ${status.info.logFile ?? "?"})\n`);
         }
@@ -82,8 +223,9 @@ export async function runEnsureHook(cwd, opts = {}) {
                 "content-type": "application/json",
                 authorization: `Bearer ${status.info.token}`,
             },
-            body: JSON.stringify(payload),
-            signal: AbortSignal.timeout(5_000),
+            // BIR_OFF=1 where this window was started is this session's switch (K2).
+            body: JSON.stringify(offInThisEnvironment() ? { ...payload, bir_off: true } : payload),
+            signal: timeoutSignal(Math.max(300, Math.min(RELAY_TIMEOUT_MS, left()))),
         });
         const answer = (await res.json().catch(() => ({})));
         if (res.ok && answer && typeof answer === "object" && Object.keys(answer).length > 0) {
@@ -91,7 +233,17 @@ export async function runEnsureHook(cwd, opts = {}) {
         }
     }
     catch (err) {
-        stderr.write(`[bir] ensure: ${errText(err)} — this session records standalone (Tier 2)\n`);
+        // stderr of a command hook that exits 0 is not shown in the session; it is
+        // for someone running this by hand, or Claude Code's debug output.
+        const tail = err instanceof RecorderBusyError
+            ? " — the hooks reach it once it catches up"
+            : " — this session records standalone (Tier 2)";
+        stderr.write(`[bir] ensure: ${errText(err)}${tail}\n`);
+    }
+    // After the relay, so it never takes the relay's time; whether or not the
+    // relay answered, the recorder is there.
+    if (kept && opts.overrideCheck !== false) {
+        reportStaleOverrides(kept.project, kept.logFile, left(), opts.overrideCheck ?? staleOverrides);
     }
     return 0;
 }