@basein/runner 0.2.12 → 0.3.0

package/dist/bin/bir-hooks.js

@@ -5,7 +5,9 @@
  * Normally nobody runs it: `bir install` makes it the SessionStart hook
  * (`bir-hooks ensure`), which starts it in the background for the project when no
  * recorder is running there, and `bir up` / `bir down` start and stop that
- * background process by hand. Its audit lines then go to
+ * background process by hand. `bir-hooks revive --cwd <project>` starts it
+ * again mid-session: a bound proxy spawns it, detached, when the recorder it
+ * reported to is gone (control/daemon.ts, reviveDaemon). Its audit lines then go to
  * ~/.baseinstrunner/logs/<project-key>.log. It can still be run in a terminal:
  *
  *     bir-hooks                       # start; Ctrl-C to stop
@@ -16,31 +18,69 @@
  *   2. accepts step reports from every `bir-proxy` that finds it;
  *   3. owns run identity, the monotonic `stepIndex`, and the recorder chain (D5).
  *
+ * The recorder listens first and signs in afterwards, in the background, so a
+ * slow or unreachable BaseIn service never holds a hook; it starts recording
+ * by itself when a sign-in appears (`bir login`) — no restart
+ * (control/recorder-main.ts, control/recorder-keeper.ts).
+ *
  * Environment:
  *   BIR_AUTH_URL              BaseIn auth-service. Unset, the address `bir setup`
  *                             stored in ~/.baseinstrunner/config.json is used
- *   BIR_CONTROL_PORT          preferred port (default 53411; falls back if busy)
- *   BIR_CORRELATION_DECISION  `allow` (default) or `ask` — see below
+ *   BIR_CONTROL_PORT          the port to listen on, over the project's own
+ *                             (default: the project's, else 53411, falling
+ *                             back if busy). 0 is any free port — the one
+ *                             taken is in the discovery file, /health and the
+ *                             log (tests and the smoke run; a project's hooks
+ *                             name a fixed port). A value that is not a port
+ *                             is ignored
+ *   BIR_CORRELATION_DECISION  unset (default: `auto`), `auto`, `allow` or
+ *                             `ask` — see below
  *   BIR_NO_CORRELATION=1      never inject a call id; join on fingerprints
  *   BIR_VERBOSE=1             per-step detail lines
+ *   BIR_SERVICE_TIMEOUT_MS    ceiling for one call to the service made off a
+ *                             hook's path (default 10000)
+ *   BIR_SUPERSEDED_EXIT_MS    how long a recorder the project's hooks moved
+ *                             away from (a reinstall on another port) must
+ *                             have had no session, run, live proxy or unsent
+ *                             step before it exits (default 86400000, a day)
+ *   BIR_WINDOWS_LAUNCH=spawn  Windows only: start the background recorder with
+ *                             a direct hidden spawn instead of PowerShell's
+ *                             Start-Process (faster by about a second; unsafe
+ *                             only when something above Claude Code captures
+ *                             its output — see control/daemon.ts)
  *
  *   BIR_REPLAY=0              turn OFF calculated replay — running a scenario on
  *                             a similar-meaning match (docs/calculatedReplay.md).
  *                             ON by default; unset or any value other than "0"
- *                             keeps it on. Read §13.2: a replayed step is
- *                             auto-approved, and a directly executed one never
- *                             reaches the permission system at all.
+ *                             keeps it on (`bir replay off` stores the same
+ *                             for one project). Read §13.2: only when a prompt
+ *                             matches a scenario, that scenario's own steps run
+ *                             without a prompt of their own — a steered step is
+ *                             answered `allow`, a directly executed one never
+ *                             reaches the permission system. Never in plan
+ *                             mode; every other tool call is asked as usual.
  *   BIR_REPLAY_ALLOW_SERVERS  comma-separated server keys eligible for *direct*
  *                             execution. Unset means every wrapped server
  *   BIR_MIN_STEER_SIMILARITY  minimum match similarity to replay (default 0.92)
- *   ANTHROPIC_API_KEY         OPTIONAL. Derivation — reading what this turn acts
+ *   BIR_DERIVE_API_KEY        OPTIONAL. Derivation — reading what this turn acts
  *                             on — is done by the service for a signed-in
- *                             runner. Set this only to keep that reading on this
- *                             machine; signed out and unset, a scenario with a
- *                             target does not run (segmented.md R-PARAM-5)
+ *                             runner. Set this (an Anthropic key) only to keep
+ *                             that reading on this machine; signed out and
+ *                             unset, a scenario with a target does not run
+ *                             (segmented.md R-PARAM-5)
+ *   BIR_USE_ANTHROPIC_API_KEY=1  let the background recorder use an
+ *                             ANTHROPIC_API_KEY from its environment for
+ *                             derivation, as older versions did. Off by
+ *                             default: a recorder the SessionStart hook starts
+ *                             has Claude Code's environment, and using the key
+ *                             found there billed the person's own account. A
+ *                             `bir-hooks` run by hand in a terminal uses that
+ *                             terminal's ANTHROPIC_API_KEY as it always did
  *   BIR_DERIVE_MODEL          derivation model (default claude-haiku-4-5-…)
- *   BIR_MATCH_BUDGET_MS       prompt-hook match wait (default 2500)
- *   BIR_DERIVE_BUDGET_MS      first PreToolUse derivation wait (default 8000)
+ *   BIR_MATCH_BUDGET_MS       prompt-hook match wait (default 1500)
+ *   BIR_DERIVE_BUDGET_MS      derivation wait before a direct run (default 8000);
+ *                             inside a hook it is at most BIR_HOOK_DERIVE_BUDGET_MS
+ *                             (default 4000)
  *   BIR_DERIVE_RECENT_RESULTS how many of this prompt's tool results derivation
  *                             reads, so a target named by an earlier step can be
  *                             found (default 5; 0 off)
@@ -49,310 +89,162 @@
  *   BIR_INTENT_REQUESTS_PER_TURN  probes one turn may send (default 40).
  *                             Separate from BIR_INTENT_MATCHES_PER_TURN: arming
  *                             is a claim on the turn, counting hits is not
+ *   BIR_INTENT_MATCH_BUDGET_MS  one intent probe's own ceiling (default 4000).
+ *                             Not a wait: PreToolUse does not wait for a probe
+ *                             unless arming is on (BIR_SEGMENT_ARM=1 or
+ *                             BIR_INTENT_ARM=1), and then at most
+ *                             BIR_INTENT_ARM_BUDGET_MS (default 500)
  *   BIR_SEGMENT_ARM           1 lets a handed-out segment actually run mid-task.
  *                             Unset is observe-only: what would have armed is
  *                             logged and nothing is replaced
  *   BIR_MIN_SEGMENT_STEER_SIMILARITY  minimum similarity to steer a segment
  *                             (default 0.95)
- *   BIR_REPLAY_BUDGET_MS      whole-plan ceiling, direct mode (default 120000)
+ *   BIR_REPLAY_BUDGET_MS      whole-plan ceiling, direct mode (unset: the
+ *                             controller's 100000, BIR_REPLAY_PLAN_BUDGET_MS)
  *   BIR_STEP_TIMEOUT_MS       one direct tools/call (default 60000)
  *
- * ABOUT `BIR_CORRELATION_DECISION`. Correlating a wrapped MCP call means
- * answering `PreToolUse` with `permissionDecision: "allow"` plus an extra
- * argument (Phase 6). That is what the design specifies — and it also
- * **auto-approves the call**, so a tool the user would have been asked about is
- * no longer asked about. Set `BIR_CORRELATION_DECISION=ask` to keep the prompt;
- * hosts that ignore `updatedInput` on a non-allow decision then fall back to
- * fingerprint matching, which is lossy under identical concurrent calls.
+ * ABOUT `BIR_CORRELATION_DECISION`. Correlating a wrapped MCP call exactly
+ * means answering `PreToolUse` with an extra argument, and Claude Code only
+ * takes that together with `permissionDecision: "allow"` — which also
+ * **auto-approves the call**, so a tool the user would have been asked about
+ * is no longer asked about. Unset (or `auto`), nothing is passed to the
+ * control server, which never does that for an ordinary call: it injects only
+ * where `allow` changes nothing the user is asked (a `bypassPermissions`
+ * session) and otherwise joins the proxy's report by fingerprint. `allow` is
+ * the behaviour of 0.2.12 and earlier, an explicit opt-in that is logged loudly at start
+ * — every wrapped call auto-approved and exactly correlated; `ask` keeps the
+ * prompt (a host that ignores the injection on a non-allow answer falls back
+ * to fingerprints).
  */
-import { hostname } from "node:os";
+import { appendFileSync } from "node:fs";
 import { Console } from "node:console";
-import { createWriteStream } from "node:fs";
-import { ControlServer, DEFAULT_CONTROL_PORT } from "../control/server.js";
-import { HEARTBEAT_MS, removeDiscovery, writeDiscovery, } from "../control/discovery.js";
-import { DAEMON_ENV, DAEMON_LOG_ENV } from "../control/daemon.js";
-import { runEnsureHook } from "../control/ensure-hook.js";
+import { dirname, resolve } from "node:path";
+import { Writable } from "node:stream";
 import { ENSURE_ARG } from "../config/adapters/claude-code.js";
-import { authenticate, clearCredentials, normalizeAuthUrl, resolveAuthUrl, } from "../auth/client.js";
-import { packageVersion } from "../util/version.js";
-import { NullRecorder } from "../record/recorder.js";
-import { RemoteRecorder } from "../record/remote-recorder.js";
-import { parseAllowList } from "../replay/coverage.js";
-import { projectRecord, projectToken, readSidecar } from "../config/generate.js";
-import { resolveServers } from "../config/resolve.js";
-import { isWrapped } from "../config/generate.js";
-import { logLine, errText } from "../util/log.js";
-import { openJournal } from "../util/journal.js";
-function parsePort(value) {
-    const n = Number(value);
-    return Number.isInteger(n) && n > 0 && n < 65536 ? n : DEFAULT_CONTROL_PORT;
+import { exemptLoopbackFromProxy } from "../config/generate.js";
+import { REVIVE_ARG } from "../control/daemon.js";
+import { daemonLogPath, ensureDir } from "../control/paths.js";
+import { errText, logLine } from "../util/log.js";
+/**
+ * The SessionStart hook. Claude Code holds the session start until it exits,
+ * so whatever happens it exits 0 and never outlives its budget.
+ */
+async function ensure(argv = []) {
+    const bail = (err) => {
+        try {
+            process.stderr.write(`[bir] ensure: ${errText(err)}\n`);
+        }
+        catch {
+            /* nothing left to tell */
+        }
+        process.exit(0);
+    };
+    process.on("uncaughtException", bail);
+    process.on("unhandledRejection", bail);
+    // Loaded here, not at the top: this runs on every session start, /clear and
+    // compaction, and the control server's module graph is not needed for it.
+    const { runEnsureHook, ENSURE_HOOK_BUDGET_MS } = await import("../control/ensure-hook.js");
+    // `--budget-ms <n>`: an npx-form hook spends part of the hook's timeout on
+    // npx itself before this code runs, so `bir install --npx` writes a smaller
+    // budget. It can only shorten the default, never lengthen it.
+    const asked = budgetArg(argv);
+    const budgetMs = asked !== undefined ? Math.min(asked, ENSURE_HOOK_BUDGET_MS) : ENSURE_HOOK_BUDGET_MS;
+    const ceiling = setTimeout(() => process.exit(0), budgetMs + 500);
+    ceiling.unref();
+    process.exitCode = await runEnsureHook(process.cwd(), { budgetMs });
 }
-/** Config keys already wrapped for this cwd, so `/tool/pre` knows what to correlate. */
-function wrappedServersFor(cwd) {
-    try {
-        return resolveServers(cwd)
-            .filter((s) => isWrapped(s.config))
-            .map((s) => s.name);
-    }
-    catch (err) {
-        logLine("config.unreadable", { error: errText(err) });
-        return [];
+/** The value of `--budget-ms <n>` or `--budget-ms=<n>` when it is a positive integer. */
+function budgetArg(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        const raw = a === "--budget-ms" ? argv[i + 1] : a.startsWith("--budget-ms=") ? a.slice("--budget-ms=".length) : undefined;
+        if (raw === undefined)
+            continue;
+        const n = Number(raw);
+        return Number.isInteger(n) && n > 0 ? n : undefined;
     }
+    return undefined;
 }
-async function buildRecorder() {
-    // BIR_AUTH_URL, or the address 'bir setup' stored. Read the same way by the
-    // proxies and the CLI, so a recorder started by a hook — with whatever
-    // environment the host had — still knows where the steps go.
-    const configured = resolveAuthUrl();
-    if (!configured) {
-        logLine("recorder.disabled", {
-            why: "no service address — run 'bir setup', or set BIR_AUTH_URL; running without recording",
-        });
-        return { recorder: new NullRecorder() };
+/** The longest a revive may take: {@link ensureDaemon}'s default budget, and a margin. */
+const REVIVE_CEILING_MS = 20_000;
+/** The value of `--cwd <dir>` or `--cwd=<dir>`, or undefined. */
+function cwdArg(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === "--cwd" && argv[i + 1] !== undefined)
+            return argv[i + 1];
+        if (a.startsWith("--cwd="))
+            return a.slice("--cwd=".length);
     }
-    // A plain-http URL fronted by a TLS proxy answers `308 → https`, and following
-    // that strips the bearer token: sign-in succeeds and every later call fails
-    // `401 missing_token`. Settle the base URL before anything authenticates.
-    const baseUrl = await normalizeAuthUrl(configured);
-    const session = await authenticate({ authUrl: baseUrl });
-    if (!session) {
-        logLine("recorder.disabled", { why: "no BaseIn session — run `bir login`" });
-        return { recorder: new NullRecorder() };
-    }
-    logLine("auth.ok", { user: session.user.email });
-    return { recorder: new RemoteRecorder({ baseUrl, session }), session, baseUrl };
-}
-function positiveInt(value, fallback) {
-    const n = Number(value);
-    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
-}
-/** Like {@link positiveInt}, but 0 is a meaningful setting rather than unset. */
-function nonNegativeInt(value, fallback) {
-    const n = Number(value);
-    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+    return undefined;
 }
 /**
- * `BIR_INTENT_SOURCES` — which text a step's intent may be read from
- * (segmented.md R-INTENT-3). Unset or unparseable means all three.
- *
- * It governs only what is *sent*. Turning every source off does not stop a
- * probe: the request still goes out with an empty text and the server builds a
- * line from the tool name and arguments (R-HIT-4).
+ * `bir-hooks revive --cwd <project>` (K1): start the project's recorder
+ * again when it is gone mid-session (control/daemon.ts, reviveDaemon).
+ * Spawned detached, with no stdio, by a bound `bir-proxy` or `bir-scenario`
+ * — possibly by several at once. It reads no stdin, writes nothing to stdout
+ * (its audit lines go to the project's recorder log), never throws, and exits
+ * 0 whatever happens, within {@link REVIVE_CEILING_MS}.
  */
-function parseIntentSources(value) {
-    if (value === undefined)
-        return undefined;
-    const allowed = ["text", "thinking", "tool"];
-    const wanted = value
-        .split(",")
-        .map((s) => s.trim().toLowerCase())
-        .filter((s) => allowed.includes(s));
-    return new Set(wanted);
-}
-function buildReplayOptions(auth, policy) {
-    // The environment still wins — an operator at a terminal is the most
-    // deliberate signal there is — but a recorder started by the SessionStart
-    // hook has Claude Code's environment, not that terminal's, and it reads the
-    // switches the project stored instead of forgetting them (generate.ts).
-    const envReplay = process.env.BIR_REPLAY;
-    const envAllow = process.env.BIR_REPLAY_ALLOW_SERVERS;
-    const envMin = Number(process.env.BIR_MIN_STEER_SIMILARITY);
-    const fromEnv = envReplay !== undefined || envAllow !== undefined || Number.isFinite(envMin);
-    const source = fromEnv ? "env" : policy ? "sidecar" : "default";
-    const enabled = envReplay !== undefined ? envReplay !== "0" : policy?.enabled !== false;
-    const allowServers = envAllow !== undefined
-        ? parseAllowList(envAllow)
-        : policy?.allowServers
-            ? parseAllowList(policy.allowServers.join(","))
-            : undefined;
-    const minSimilarity = Number.isFinite(envMin) ? envMin : (policy?.minSimilarity ?? 0.92);
-    const opts = {
-        enabled,
-        minSimilarity,
-        allowServers,
-        budgets: {
-            matchMs: positiveInt(process.env.BIR_MATCH_BUDGET_MS, 2_500),
-            deriveMs: positiveInt(process.env.BIR_DERIVE_BUDGET_MS, 8_000),
-            planMs: positiveInt(process.env.BIR_REPLAY_BUDGET_MS, 120_000),
-            stepMs: positiveInt(process.env.BIR_STEP_TIMEOUT_MS, 60_000),
+async function revive(argv) {
+    const done = () => process.exit(0);
+    process.on("uncaughtException", done);
+    process.on("unhandledRejection", done);
+    const ceiling = setTimeout(done, REVIVE_CEILING_MS);
+    ceiling.unref();
+    const cwd = resolve(cwdArg(argv) ?? process.cwd());
+    // Nobody reads this process's stdio: every line it logs (the start, why it
+    // did not) goes where `bir doctor` and a person looking read.
+    const file = daemonLogPath(cwd);
+    ensureDir(dirname(file));
+    const sink = new Writable({
+        write(chunk, _encoding, callback) {
+            try {
+                appendFileSync(file, chunk);
+            }
+            catch {
+                /* dropped */
+            }
+            callback();
         },
-        // Intent matching in the ReAct loop (fallbk.md §Runner 4). On with replay;
-        // BIR_INTENT_MATCH=0 turns it off on its own.
-        intentMatch: {
-            enabled: process.env.BIR_INTENT_MATCH !== "0",
-            // 4 000, not 1 500: a request whose best segment lands in the not-clear
-            // band has one live question to ask under the server's own 2 500 ms
-            // attempt, and must still answer inside the hook's 30 s (segmented.md
-            // R-HIT-11).
-            budgetMs: positiveInt(process.env.BIR_INTENT_MATCH_BUDGET_MS, 4_000),
-            maxPerTurn: positiveInt(process.env.BIR_INTENT_MATCHES_PER_TURN, 3),
-            maxRequestsPerTurn: positiveInt(process.env.BIR_INTENT_REQUESTS_PER_TURN, 40),
-        },
-        // Observe-only until an operator has read the logs and turned it on
-        // (segmented.md R-OUT-10, R-LIFE-7). Arming is never the way to find out.
-        segmentArm: process.env.BIR_SEGMENT_ARM === "1",
-        minSegmentSimilarity: (() => {
-            const n = Number(process.env.BIR_MIN_SEGMENT_STEER_SIMILARITY);
-            return Number.isFinite(n) ? n : 0.95;
-        })(),
-        authUrl: auth.baseUrl,
-        // Read late, not captured: `RemoteRecorder` refreshes the access token as the
-        // session outlives it, and a snapshot taken here would go stale mid-run.
-        authToken: auth.session ? () => auth.session.accessToken : undefined,
-    };
-    if (enabled) {
-        // Loud, at startup, on the operator's own terminal. A capability that
-        // auto-approves tool calls must never be discoverable only from a log file.
-        logLine("replay.enabled", {
-            minSimilarity: opts.minSimilarity,
-            allowServers: allowServers ? [...allowServers].join(",") : "(all wrapped)",
-            // Who reads what this turn acts on (segmented.md R-PARAM-5). Named at
-            // startup because the third state is a replay that silently never runs.
-            derive: process.env.ANTHROPIC_API_KEY
-                ? "this machine (ANTHROPIC_API_KEY)"
-                : auth.session && auth.baseUrl
-                    ? "the service"
-                    : "recorded sample values — sign in, or a scenario with a target will not run",
-            intentMatch: opts.intentMatch?.enabled ? "on" : "off",
-            source,
-            why: "matched prompts will run their calculated scenario — steered steps are auto-approved",
-        });
-    }
-    return { opts, source };
+    });
+    globalThis.console = new Console({ stdout: sink, stderr: sink });
+    const { reviveDaemon } = await import("../control/daemon.js");
+    await reviveDaemon(cwd);
+    done();
 }
 async function main() {
+    // Before any fetch: started with --use-env-proxy (a launcher written behind a
+    // proxy) where NO_PROXY does not name 127.0.0.1, the SessionStart hook's
+    // look at its own recorder and its relay would go to the proxy and fail —
+    // and a recorder it could not see is one it starts twice. As bir.ts does;
+    // the recorder does it again for itself (recorder-main.ts).
+    exemptLoopbackFromProxy();
     const argv = process.argv.slice(2);
     if (argv[0] === "logout") {
+        const { clearCredentials } = await import("../auth/client.js");
         clearCredentials();
         process.stderr.write("[bir] logged out — cached credentials cleared.\n");
         return;
     }
     if (argv[0] === ENSURE_ARG) {
-        // The SessionStart hook: start the recorder for this directory if there is
-        // none, then relay the payload. Always exit 0 (control/ensure-hook.ts).
-        process.exitCode = await runEnsureHook(process.cwd());
+        await ensure(argv.slice(1));
         return;
     }
-    const cwd = process.cwd();
-    const daemon = process.env[DAEMON_ENV] === "1";
-    const logFile = daemon ? process.env[DAEMON_LOG_ENV] : undefined;
-    if (logFile) {
-        // A background recorder owns its log. Nothing was inherited from whoever
-        // started it (control/daemon.ts says why), so the audit lines — every
-        // `logLine` goes through `console.error` — are pointed at the file here.
-        const stream = createWriteStream(logFile, { flags: "a" });
-        globalThis.console = new Console({ stdout: stream, stderr: stream });
-    }
-    const sidecar = readSidecar();
-    // The port this project's hooks were written with. An explicit BIR_CONTROL_PORT
-    // still wins; the per-project record is what lets two projects record at once.
-    const pinned = process.env.BIR_CONTROL_PORT !== undefined || projectRecord(sidecar, cwd) !== undefined;
-    const preferredPort = parsePort(process.env.BIR_CONTROL_PORT ??
-        String(projectRecord(sidecar, cwd)?.port ?? sidecar.controlPort ?? ""));
-    // Open before anything logs: the journal is what `bir investigate` reads
-    // later, and the startup lines are part of the story.
-    const journalFile = openJournal(cwd);
-    const auth = await buildRecorder();
-    const replay = buildReplayOptions(auth, projectRecord(sidecar, cwd)?.replay);
-    const server = new ControlServer({
-        recorder: auth.recorder,
-        cwd,
-        port: preferredPort,
-        // This project's token (generate.ts); the machine-wide one for a record
-        // written before tokens were per project.
-        token: projectToken(sidecar, cwd),
-        wrappedServers: wrappedServersFor(cwd),
-        host: { app: "claude-code" },
-        correlationDecision: process.env.BIR_CORRELATION_DECISION === "ask" ? "ask" : "allow",
-        noCorrelation: process.env.BIR_NO_CORRELATION === "1",
-        deriveRecentResults: nonNegativeInt(process.env.BIR_DERIVE_RECENT_RESULTS, 5),
-        intentSources: parseIntentSources(process.env.BIR_INTENT_SOURCES),
-        replay: replay.opts,
-        replaySource: replay.source,
-        account: auth.session?.user.email,
-        // In the background with a port the hooks name, a fallback port is a
-        // recorder every hook but SessionStart would miss. Exit with a reason instead.
-        portFallback: !(daemon && pinned),
-        // 'bir down', and the SessionStart hook replacing an out-of-date recorder,
-        // ask over HTTP rather than sending a signal: on Windows a signal is a kill.
-        onStopRequested: () => void shutdown(),
-    });
-    let address;
-    try {
-        address = await server.listen();
-    }
-    catch (err) {
-        const code = err.code;
-        if (code === "EADDRINUSE" || code === "EACCES") {
-            logLine("control.port_busy", {
-                port: preferredPort,
-                code,
-                fix: `port ${preferredPort} is held by another program or excluded by the system — run \`bir setup --port <another>\` in this directory`,
-            });
-            process.exit(1);
-        }
-        throw err;
-    }
-    const info = {
-        url: address.url,
-        token: address.token,
-        sessionId: address.sessionId,
-        pid: process.pid,
-        startedAt: Date.now(),
-        cwd,
-        version: packageVersion(),
-        ...(daemon ? { daemon: true, logFile: process.env[DAEMON_LOG_ENV] } : {}),
-    };
-    const discoveryFile = writeDiscovery(info);
-    // A background recorder outlives the discovery file's 24-hour freshness
-    // window; the heartbeat is what keeps it findable (discovery.ts).
-    const heartbeat = setInterval(() => {
-        try {
-            writeDiscovery({ ...info, heartbeatAt: Date.now() });
-        }
-        catch (err) {
-            logLine("control.heartbeat_failed", { error: errText(err) });
-        }
-    }, HEARTBEAT_MS);
-    heartbeat.unref();
-    logLine("control.listening", {
-        url: address.url,
-        cwd,
-        discovery: discoveryFile,
-        journal: journalFile,
-        machine: hostname(),
-        version: packageVersion(),
-        background: daemon ? "yes" : undefined,
-        wrapped: wrappedServersFor(cwd).join(",") || "(none)",
-    });
-    if (preferredPort !== DEFAULT_CONTROL_PORT || sidecar.controlPort || projectRecord(sidecar, cwd)) {
-        if (preferredPort !== address.port) {
-            // The hook URLs in settings.json name a port; if we could not take it,
-            // the hooks will POST into the void. Say so rather than looking healthy.
-            logLine("control.port_mismatch", {
-                installed: preferredPort,
-                actual: address.port,
-                why: "hooks point at the installed port — re-run `bir install` or free that port",
-            });
-        }
-    }
-    let closing = false;
-    async function shutdown() {
-        if (closing)
-            return;
-        closing = true;
-        clearInterval(heartbeat);
-        await server.close().catch((err) => logLine("control.close_failed", { error: errText(err) }));
-        removeDiscovery(cwd);
-        logLine("control.stopped", {});
-        process.exit(0);
+    if (argv[0] === REVIVE_ARG) {
+        await revive(argv.slice(1));
+        return;
     }
-    process.on("SIGINT", () => void shutdown());
-    process.on("SIGTERM", () => void shutdown());
-    process.on("uncaughtException", (err) => logLine("control.uncaught", { error: errText(err) }));
-    process.on("unhandledRejection", (err) => logLine("control.unhandled_rejection", { error: errText(err) }));
+    const { runRecorder } = await import("../control/recorder-main.js");
+    await runRecorder();
 }
 void main().catch((err) => {
+    if (process.argv[2] === REVIVE_ARG)
+        process.exit(0);
+    if (process.argv[2] === ENSURE_ARG) {
+        process.stderr.write(`[bir] ensure: ${errText(err)}\n`);
+        process.exit(0);
+    }
     logLine("control.fatal", { error: errText(err) });
     process.exit(1);
 });

package/dist/bin/bir-proxy.d.ts

@@ -15,17 +15,32 @@
  *   --no-correlation      never relax tool schemas; join on argument fingerprints
  *   --lazy                create the upstream on the first host message, not at
  *                         startup (see upstream/lazy-client.ts for the caveat)
- *   --restart             restart a dead stdio upstream once
- *   --discovery-ms <n>    how long to look for a control server (default 5000)
+ *   --restart             restart a dead stdio upstream once (in-flight calls
+ *                         are answered; the host's handshake is replayed to it)
+ *   --discovery-ms <n>    how long to look for a control server (default 10000)
  *
  * Environment:
  *   BIR_CONTROL_URL / BIR_CONTROL_TOKEN   control server, bypassing discovery
  *   BIR_AUTH_URL                          BaseIn service, for Tier 2 recording
+ *   BIR_UPSTREAM_HEADERS                  a remote upstream's headers, as a JSON
+ *                                         object of name → value; `--header`
+ *                                         wins on a clash. Read once, then
+ *                                         removed from the environment: no
+ *                                         process started from here sees it
+ *   BIR_OFF=1                             the kill switch (also `bir off`): run
+ *                                         the server as if it were not wrapped
+ *   BIR_PROXY_STAY_UP=1                   keep answering after the upstream
+ *                                         dies, instead of exiting with it
  *   BIR_VERBOSE=1                         per-message detail on stderr
  *
  * STDOUT IS SACRED. It is the host's JSON-RPC stream; every log line, every
  * upstream stderr line and every diagnostic goes to stderr instead. A single
  * stray byte here corrupts the session and surfaces somewhere else entirely.
+ *
+ * STDERR IS NOT FREE EITHER. Claude Code files every stderr line of an MCP
+ * server as a "Server stderr" error in its MCP logs, so routine lines (started,
+ * spawned, bound, stopped) are `BIR_VERBOSE`-only; what is left on stderr is a
+ * decision or a failure somebody may need to read.
  */
 interface ProxyArgs {
     serverName: string;