@basein/runner 0.2.12 → 0.3.0

package/dist/control/recorder-main.js

@@ -0,0 +1,778 @@
+/**
+ * recorder-main — the long-running half of `bir-hooks`: the control server
+ * that receives Claude Code's hooks and the proxies' step reports.
+ *
+ * Kept out of `bin/bir-hooks.ts` so the SessionStart hook (`bir-hooks ensure`),
+ * which runs on every session start, `/clear` and compaction, never loads the
+ * control server, the replay engine or the service client it does not use.
+ *
+ * THE ORDER OF START-UP IS THE POINT. Claude Code sends every hook of a
+ * session to this process's port. Until it listens, each one is refused, and
+ * Claude Code shows each refusal as a hook error. So, in order:
+ *
+ *   1. crash handlers — nothing after this can take the process down;
+ *   2. the log, the project's port and token, the journal — local files only;
+ *   3. the recorder, decided from disk alone (recorder-keeper.ts) — no network;
+ *   4. listen, and write the discovery file;
+ *   5. only then, in the background and bounded: refresh the token, check an
+ *      http address, notice a sign-in appearing — none of it ever delays a hook.
+ *
+ * It used to sign in (two network calls, no timeouts) between 2 and 4, and a
+ * slow service held the port closed for up to five minutes.
+ */
+import { hostname } from "node:os";
+import { ControlServer, DEFAULT_CONTROL_PORT } from "./server.js";
+import { DISCOVERY_CHECK_MS, HEARTBEAT_MS, pidAlive, readDiscovery, removeDiscoveryIfOwned, removeSupersededRecord, sweepStaleDiscovery, writeDiscovery, writeSupersededRecord, } from "./discovery.js";
+import { DAEMON_CWD_ENV, DAEMON_ENV, DAEMON_LOG_ENV, DERIVE_KEY_ENV, DaemonLog, USE_API_KEY_ENV, clearPortProblem, compareVersions, probeHealth, projectEndpoint, rediscover, validPort, writePortProblem, } from "./daemon.js";
+import { configDir, normalizePath, supersededLogPath } from "./paths.js";
+import { RecorderKeeper } from "./recorder-keeper.js";
+import { parseAllowList } from "../replay/coverage.js";
+import { sweepDeliveries } from "../replay/bash-channel.js";
+import { exemptLoopbackFromProxy, isWrapped, projectRecord, projectToken, readSidecar, } from "../config/generate.js";
+import { resolveServers } from "../config/resolve.js";
+import { isRecorderHealthReporter } from "../record/recorder.js";
+import { errText, logLine, logOnce } from "../util/log.js";
+import { openJournal } from "../util/journal.js";
+import { packageVersion } from "../util/version.js";
+/** How long `close()` may take on the way out: it flushes unfinished runs to the service. */
+const SHUTDOWN_CLOSE_MS = 3_000;
+/** After this the process exits whatever is still pending. */
+const SHUTDOWN_HARD_MS = 5_000;
+/**
+ * What a prompt waits for its scenario match by default (`BIR_MATCH_BUDGET_MS`).
+ * Past it the prompt goes on without one (K5): the service answering in 1-2 s
+ * must not add that to every prompt.
+ */
+export const DEFAULT_MATCH_BUDGET_MS = 1_500;
+/** How often records of dead recorders are swept from the control directory. */
+const SWEEP_EVERY_MS = 24 * 60 * 60 * 1000;
+/**
+ * How long a superseded recorder must have had nothing to serve before it
+ * exits (`BIR_SUPERSEDED_EXIT_MS`). "Nothing" is no open run, no session it
+ * still knows (the control server forgets one 10 min after its SessionEnd, or
+ * after 6 h of silence), no live proxy and nothing left to send. Generous on
+ * purpose: a window opened before the reinstall and left idle overnight still
+ * posts its hooks to this port when the person comes back, and a recorder
+ * that had exited would turn every one of them into a hook error.
+ */
+const SUPERSEDED_EXIT_MS = 24 * 60 * 60 * 1000;
+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;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** 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 [];
+    }
+}
+/**
+ * `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).
+ */
+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);
+}
+/**
+ * `BIR_CORRELATION_DECISION` as the operator set it — read the way the control
+ * server reads it (trimmed, any case) — or undefined when it is unset or not
+ * one of the three values.
+ */
+function correlationSetting() {
+    const value = (process.env.BIR_CORRELATION_DECISION ?? "").trim().toLowerCase();
+    return value === "allow" || value === "ask" || value === "auto" ? value : undefined;
+}
+/**
+ * `BIR_CORRELATION_DECISION`, passed on only when it was set to `allow` or
+ * `ask`. Unset, nothing is passed and the control server decides — and by
+ * default (`auto`) it never answers `allow` for an ordinary wrapped call,
+ * which skipped the person's permission prompt.
+ */
+export function correlationDecisionFromEnv() {
+    const value = correlationSetting();
+    return value === "allow" || value === "ask" ? value : undefined;
+}
+/**
+ * Which Anthropic key derivation may use, if any.
+ *
+ * In the background, only one the person set for this purpose. The
+ * hook-started recorder has Claude Code's environment, and an API-billed
+ * Claude Code carries its `ANTHROPIC_API_KEY` there: picking that up silently
+ * billed the person's own key for work the service does for a signed-in
+ * runner. It is dropped from this process (replay would otherwise read it
+ * from the environment) unless `BIR_USE_ANTHROPIC_API_KEY=1` says to use it.
+ *
+ * In a terminal (`bir-hooks` run by hand, `daemon` false) the environment is
+ * the operator's own, and older guides told them to set exactly this variable
+ * to keep derivation on the machine: it is used as it always was.
+ */
+export function derivationKey(daemon = process.env[DAEMON_ENV] === "1") {
+    const own = process.env[DERIVE_KEY_ENV]?.trim();
+    if (own)
+        return { apiKey: own, source: `this machine (${DERIVE_KEY_ENV})` };
+    const inherited = process.env.ANTHROPIC_API_KEY;
+    if (inherited && process.env[USE_API_KEY_ENV] === "1") {
+        return { apiKey: inherited, source: `this machine (ANTHROPIC_API_KEY, ${USE_API_KEY_ENV}=1)` };
+    }
+    if (inherited && !daemon) {
+        return { apiKey: inherited, source: "this machine (ANTHROPIC_API_KEY, from this terminal)" };
+    }
+    if (inherited) {
+        delete process.env.ANTHROPIC_API_KEY;
+        logLine("derive.api_key_ignored", {
+            why: "ANTHROPIC_API_KEY is in this recorder's environment (usually Claude Code's) and is not used, " +
+                `so nothing is billed to it — set ${DERIVE_KEY_ENV}, or ${USE_API_KEY_ENV}=1, to derive with a key here`,
+        });
+    }
+    return {};
+}
+/**
+ * Assemble the replay configuration (docs/calculatedReplay.md §5.3 of the guide).
+ *
+ * The steer threshold defaults **above** the service's own detection threshold
+ * (0.9). Detection decides "do not record this again", which is cheap — the worst
+ * case is a lost recording. Steering decides "do not think about this again",
+ * which is a much stronger claim, and a 0.90-similar prompt usually covers only
+ * part of the live task.
+ */
+function buildReplayOptions(keeper, policy, key) {
+    // 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: {
+            // What a prompt may wait for its match (K5). Past it the prompt goes on
+            // without one; a service slower than this must not cost every prompt.
+            matchMs: positiveInt(process.env.BIR_MATCH_BUDGET_MS, DEFAULT_MATCH_BUDGET_MS),
+            deriveMs: positiveInt(process.env.BIR_DERIVE_BUDGET_MS, 8_000),
+            // Only when the operator set it: the controller's own default (100 s,
+            // BIR_REPLAY_PLAN_BUDGET_MS) keeps a direct run inside Claude Code's
+            // 2-minute auto-background of an MCP call, and 120 000 here would
+            // silently override it.
+            ...(process.env.BIR_REPLAY_BUDGET_MS
+                ? { planMs: positiveInt(process.env.BIR_REPLAY_BUDGET_MS, 100_000) }
+                : {}),
+            stepMs: positiveInt(process.env.BIR_STEP_TIMEOUT_MS, 60_000),
+        },
+        // 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",
+            // The probe's own ceiling, not a wait on the hook's path: `PreToolUse`
+            // sends it and answers without it (hit counting only) unless arming is
+            // on (BIR_SEGMENT_ARM=1 or BIR_INTENT_ARM=1), and then waits at most
+            // BIR_INTENT_ARM_BUDGET_MS (500 ms), never while the service is failing
+            // (control/server.ts). 4 000 leaves a request whose best segment lands
+            // in the not-clear band its one live question under the service's own
+            // 2 500 ms attempt (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;
+        })(),
+        // Both read live, never captured (C5). The recorder signs in after it
+        // listens, refreshes the token as the session outlives it, and may sign
+        // in or out while it runs; replay reads whatever holds *now*. The old
+        // closure read the start-up session object, which a refresh never
+        // updated, so derivation got 401 a day into every recorder's life.
+        get authUrl() {
+            return keeper.authUrl;
+        },
+        authToken: () => keeper.currentAccessToken() ?? "",
+        apiKey: key.apiKey,
+    };
+    if (enabled) {
+        // Loud, at startup, on the operator's own terminal. A capability that
+        // runs tool calls without asking must never be discoverable only from a
+        // log file. What it runs without asking is a matched scenario's own steps,
+        // and nothing else: an ordinary wrapped call keeps its permission prompt
+        // (see the correlation line under `control.listening`).
+        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: key.source ??
+                (keeper.recording
+                    ? "the service"
+                    : "recorded sample values — sign in, or a scenario with a target will not run"),
+            intentMatch: opts.intentMatch?.enabled ? "on" : "off",
+            source,
+            why: "a prompt that matches a calculated scenario runs it: the scenario's own steps run without a " +
+                "permission prompt of their own (never in plan mode); every other tool call is asked about as " +
+                "usual — BIR_REPLAY=0 or `bir replay off` turns replay off",
+        });
+    }
+    return { opts, source };
+}
+/**
+ * The pinned port is taken. Find out by whom, say so where `bir doctor` and
+ * the next SessionStart will see it, and decide: `ours` (this project's
+ * recorder already serves it — step aside), `retry` (nothing answers: the
+ * holder is on its way out), or `exit`.
+ */
+async function portBusy(cwd, port, token, code, final) {
+    const fix = `run \`bir setup --port <another port>\` in ${cwd} (below 49152 avoids the ranges the system reserves); ` +
+        "the next Claude Code session then uses it";
+    let problem;
+    if (code === "EACCES") {
+        problem = {
+            port,
+            code,
+            holder: "excluded",
+            at: Date.now(),
+            detail: `port ${port} is reserved by the system (on Windows, Hyper-V, WSL and Docker reserve port ranges at boot)`,
+            fix,
+        };
+    }
+    else {
+        const probe = await probeHealth(`http://127.0.0.1:${port}`, token, 2_000);
+        if (probe.kind === "ok") {
+            const theirCwd = typeof probe.health.cwd === "string" ? probe.health.cwd : "";
+            if (normalizePath(theirCwd) === normalizePath(cwd)) {
+                // This project's recorder is up already — started a moment earlier by
+                // another window, or running without its discovery file. Make sure it
+                // can be found, and leave.
+                await rediscover(cwd, port, token, 2_000);
+                clearPortProblem(cwd);
+                logLine("control.already_running", {
+                    port,
+                    pid: probe.health.pid,
+                    why: "this project's recorder already serves this port; not starting a second one",
+                });
+                return "ours";
+            }
+            problem = {
+                port,
+                code,
+                holder: "other-project",
+                at: Date.now(),
+                detail: `port ${port} is served by the recorder of another project (${theirCwd || "unknown"})`,
+                fix,
+            };
+        }
+        else if (probe.kind === "refused" && !final) {
+            return "retry";
+        }
+        else if (probe.kind === "unauthorized") {
+            problem = {
+                port,
+                code,
+                holder: "unauthorized",
+                at: Date.now(),
+                detail: `port ${port} is held by a program that refused this project's token — possibly a recorder ` +
+                    "left from an earlier install of this project, which stops at the next restart of the computer",
+                fix,
+            };
+        }
+        else if (probe.kind === "foreign") {
+            problem = {
+                port,
+                code,
+                holder: "foreign",
+                at: Date.now(),
+                detail: `port ${port} is held by another program (it answered HTTP ${probe.status}); until the port ` +
+                    "changes, this project's hooks send their payloads — and this project's token — to it",
+                fix,
+            };
+        }
+        else {
+            problem = {
+                port,
+                code,
+                holder: "unknown",
+                at: Date.now(),
+                detail: `port ${port} is held by a program that did not answer`,
+                fix,
+            };
+        }
+    }
+    writePortProblem(cwd, problem);
+    logLine("control.port_busy", {
+        port,
+        code,
+        holder: problem.holder,
+        detail: problem.detail,
+        fix: problem.fix,
+    });
+    return "exit";
+}
+/**
+ * The control server's {@link RecorderActivity}. From its own accessor when it
+ * has one; otherwise the same, read from its `/health` body (heavier, and
+ * asked once a minute only while superseded).
+ */
+export function activityOf(server) {
+    const accessor = server.activity;
+    if (typeof accessor === "function")
+        return accessor.call(server);
+    const h = server.health();
+    const sessions = Array.isArray(h.sessions) ? h.sessions : [];
+    const proxies = Array.isArray(h.registeredProxies) ? h.registeredProxies : [];
+    const pids = new Set();
+    for (const p of proxies)
+        if (typeof p?.pid === "number" && pidAlive(p.pid))
+            pids.add(p.pid);
+    return {
+        openRuns: sessions.filter((s) => s.active === true).length,
+        knownSessions: typeof h.sessionCount === "number" ? h.sessionCount : sessions.length,
+        liveProxyPids: pids.size,
+    };
+}
+/** Steps this process has not handed to the service yet (0 when it cannot say). */
+function pendingSendsOf(recorder) {
+    try {
+        if (!isRecorderHealthReporter(recorder))
+            return 0;
+        const n = recorder.recorderHealth()?.pendingSends;
+        return typeof n === "number" && Number.isFinite(n) && n > 0 ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** The port of a recorder URL, or undefined. */
+function portOfUrl(url) {
+    try {
+        return validPort(new URL(url).port);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function runRecorder() {
+    // First, before anything can throw: this process answers every hook of every
+    // session in the project, and a crash turns each of them into a visible hook
+    // error. Log and keep serving.
+    process.on("uncaughtException", (err) => logLine("control.uncaught", { error: errText(err) }));
+    process.on("unhandledRejection", (err) => logLine("control.unhandled_rejection", { error: errText(err) }));
+    // Started with --use-env-proxy (a launcher written behind a proxy) in an
+    // environment whose NO_PROXY does not name 127.0.0.1: every loopback fetch
+    // this process makes — asking who holds its port, finding its own recorder
+    // again — would go to the proxy and fail. undici re-reads NO_PROXY per
+    // request, so adding loopback to it here is enough (generate.ts). Calls to
+    // the service still go through the proxy, as the flag asks.
+    exemptLoopbackFromProxy();
+    const daemon = process.env[DAEMON_ENV] === "1";
+    // A background recorder is started in the runner's state directory and told
+    // its project (daemon.ts, WHERE IT RUNS): holding the project folder as its
+    // working directory made the folder impossible to rename or delete on Windows.
+    const cwd = (daemon && process.env[DAEMON_CWD_ENV]) || process.cwd();
+    if (daemon) {
+        try {
+            process.chdir(configDir());
+        }
+        catch {
+            /* stays where it was started; only folder locking is at stake */
+        }
+    }
+    const logFile = daemon ? process.env[DAEMON_LOG_ENV] : undefined;
+    // 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 log = logFile ? new DaemonLog(logFile) : undefined;
+    log?.open();
+    const sidecar = readSidecar();
+    const record = projectRecord(sidecar, cwd);
+    // The port this project's hooks were written with. A valid BIR_CONTROL_PORT
+    // still wins; the per-project record is what lets two projects record at
+    // once. Read exactly as the SessionStart hook reads it (daemon.ts,
+    // projectEndpoint) — when the two disagreed, every session start replaced
+    // a recorder that could only bind the same wrong port again.
+    // BIR_CONTROL_PORT=0 is any free port (tests, the smoke run): it used to
+    // fall through to the default, and a test run took the real 53411.
+    const endpoint = projectEndpoint(cwd, process.env, sidecar);
+    const pinned = endpoint.pinned;
+    const preferredPort = endpoint.ephemeral
+        ? 0
+        : (endpoint.port ?? validPort(sidecar.controlPort) ?? DEFAULT_CONTROL_PORT);
+    // 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 key = derivationKey(daemon);
+    // From disk, no network: listening must never wait for the service.
+    const keeper = new RecorderKeeper({ cwd });
+    const replay = buildReplayOptions(keeper, record?.replay, key);
+    let closing = false;
+    let tick;
+    const finish = (event, exitCode) => {
+        removeDiscoveryIfOwned(cwd, process.pid);
+        removeSupersededRecord(cwd, process.pid);
+        logLine(event, {});
+        process.exit(exitCode);
+    };
+    const shutdown = async () => {
+        if (closing)
+            return;
+        closing = true;
+        if (tick)
+            clearInterval(tick);
+        keeper.stop();
+        // A deadline, not a hope. close() finalizes unfinished runs and flushes
+        // them to the service; a service that hangs must not keep `bir down`, a
+        // restart onto a new version, or the machine's shutdown waiting on it.
+        const hard = setTimeout(() => finish("control.stop_forced", 0), SHUTDOWN_HARD_MS);
+        await Promise.race([
+            server.close().catch((err) => logLine("control.close_failed", { error: errText(err) })),
+            sleep(SHUTDOWN_CLOSE_MS),
+        ]);
+        clearTimeout(hard);
+        finish("control.stopped", 0);
+    };
+    const onSignal = () => {
+        // A second signal while stopping means "now": on POSIX it used to be
+        // swallowed, and a recorder stuck in its shutdown could not be stopped.
+        if (closing)
+            finish("control.stop_forced", 1);
+        void shutdown();
+    };
+    const options = {
+        recorder: keeper.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: correlationDecisionFromEnv(),
+        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,
+        // Both live: the recorder may sign in, refresh or sign out while it runs.
+        // `/health` is how `bir doctor` and `bir setup` learn which.
+        get recording() {
+            return keeper.recording;
+        },
+        get account() {
+            return keeper.account;
+        },
+        // 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(),
+    };
+    const server = new ControlServer(options);
+    let address;
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            address = await server.listen();
+            break;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EADDRINUSE" && code !== "EACCES")
+                throw err;
+            // Nothing answering on a taken port is a holder on its way out (the
+            // recorder this one replaces, still closing): a few short retries.
+            const verdict = await portBusy(cwd, preferredPort, server.token, code, attempt >= 4);
+            if (verdict === "retry") {
+                await sleep(500);
+                continue;
+            }
+            process.exit(verdict === "ours" ? 0 : 1);
+        }
+    }
+    clearPortProblem(cwd);
+    const info = {
+        url: address.url,
+        token: address.token,
+        sessionId: address.sessionId,
+        pid: process.pid,
+        startedAt: Date.now(),
+        cwd,
+        version: packageVersion(),
+        ...(daemon ? { daemon: true, logFile } : {}),
+    };
+    let lastWrite = 0;
+    let discoveryFile;
+    /**
+     * False once the project's hooks post to another port than this recorder's
+     * (`bir install --port N`, or a reinstall that picked a new one). Such a
+     * recorder is kept running by the SessionStart hook for the sessions that
+     * started before — their hooks still name this port — but it is no longer
+     * the project's recorder: it does not put its record back when the file
+     * goes, so `bir down` of the new one is not undone a minute later.
+     */
+    const stillTheProjects = (now = projectEndpoint(cwd)) => {
+        if (!daemon)
+            return true;
+        return now.port === undefined || now.port === address.port;
+    };
+    /** A record of this process that says something else than it would (another writer wrote it). */
+    const differs = (onDisk) => onDisk.url !== info.url ||
+        onDisk.token !== info.token ||
+        onDisk.sessionId !== info.sessionId ||
+        onDisk.startedAt !== info.startedAt ||
+        onDisk.version !== info.version ||
+        Boolean(onDisk.daemon) !== Boolean(info.daemon) ||
+        onDisk.logFile !== info.logFile;
+    const publish = () => {
+        try {
+            discoveryFile = writeDiscovery({ ...info, heartbeatAt: Date.now() });
+            lastWrite = Date.now();
+        }
+        catch (err) {
+            // The hooks still reach this process at the port they name; only the
+            // proxies need the file. Keep serving and try again at the next check.
+            logLine("control.heartbeat_failed", { error: errText(err) });
+        }
+    };
+    publish();
+    /**
+     * Whether this recorder — the project's, where its hooks post — should take
+     * the discovery file back from the live recorder `onDisk` names. A 0.2.12
+     * recorder left running beside this one (a reinstall moved the port while a
+     * window was open) rewrites the file with its own address every half hour
+     * and never steps aside, and every proxy that read it then bound to the old
+     * recorder for its whole life. So: taken back when the record names a port
+     * the hooks do not post to, or an older (or unstated) version. Two recorders
+     * of this version never contend: only one can hold the hooks' port.
+     */
+    const mayReclaim = (onDisk, expected) => {
+        if (expected.port !== undefined) {
+            if (address.port !== expected.port)
+                return false; // not where the hooks post: not ours to take
+            if (portOfUrl(onDisk.url) !== expected.port)
+                return true;
+        }
+        if (!onDisk.version)
+            return true;
+        const order = compareVersions(onDisk.version, packageVersion());
+        return order !== undefined && order < 0;
+    };
+    const reclaimedFrom = new Set();
+    // ── superseded (LC-1) ────────────────────────────────────────────────────
+    // A recorder the hooks moved away from keeps serving the windows opened
+    // before — and used to do so invisibly until the machine restarted: out of
+    // `bir status`, `bir down` and `bir uninstall`, sharing (and breaking the
+    // rotation of) the project's log. Now it says where it is (a superseded
+    // record), writes a log of its own, and exits once it has had nothing to
+    // serve for SUPERSEDED_EXIT_MS.
+    const supersededGraceMs = nonNegativeInt(process.env.BIR_SUPERSEDED_EXIT_MS, SUPERSEDED_EXIT_MS);
+    let superseded;
+    let quietSince;
+    let exiting = false;
+    const becomeSuperseded = (now) => {
+        if (superseded)
+            return;
+        superseded = { since: now };
+        quietSince = undefined;
+        const ownLog = log ? supersededLogPath(cwd, address.port) : undefined;
+        const fields = {
+            port: address.port,
+            why: "this project's hooks now post to another port; this recorder keeps serving the sessions " +
+                "that started before that, no longer advertises itself, and exits once none is left",
+            log: ownLog,
+        };
+        logLine("control.superseded", fields);
+        if (log && ownLog) {
+            log.moveTo(ownLog);
+            logLine("control.superseded", fields);
+        }
+        writeSupersededRecord({
+            cwd,
+            pid: process.pid,
+            port: address.port,
+            url: address.url,
+            token: address.token,
+            since: now,
+            version: packageVersion(),
+            logFile: ownLog ?? logFile,
+        });
+    };
+    const backToTheProject = () => {
+        if (!superseded)
+            return;
+        superseded = undefined;
+        quietSince = undefined;
+        removeSupersededRecord(cwd, process.pid);
+        if (log && logFile)
+            log.moveTo(logFile);
+        logLine("control.project_recorder_again", {
+            port: address.port,
+            why: "this project's hooks post to this recorder's port again",
+        });
+    };
+    const maybeExitSuperseded = (now) => {
+        if (!superseded || exiting || closing)
+            return;
+        const a = activityOf(server);
+        const backlog = pendingSendsOf(keeper.recorder);
+        if (a.openRuns > 0 || a.knownSessions > 0 || a.liveProxyPids > 0 || backlog > 0) {
+            quietSince = undefined;
+            return;
+        }
+        quietSince ??= now;
+        if (now - quietSince < supersededGraceMs)
+            return;
+        exiting = true;
+        logLine("control.superseded_exit", {
+            port: address.port,
+            quiet_min: Math.round((now - quietSince) / 60_000),
+            why: "superseded, and no session, run, proxy or unsent step left to serve",
+        });
+        void shutdown();
+    };
+    // One check a minute, on the wall clock (discovery.ts, HEARTBEAT_MS): the
+    // discovery file rewritten when it has gone missing, when a heartbeat's
+    // worth of wall time has passed — timers stop while a laptop sleeps, the
+    // wall clock does not — or when another writer (daemon.ts, rediscover)
+    // wrote a record of this process without what only it knows (that it runs
+    // in the background, its log, its start time), or an older recorder took
+    // it; a superseded recorder noticed, recorded and eventually retired; the
+    // log rolled when it grows past its limit, or opened again after a failure
+    // or after another writer rolled it; and the control directory swept once
+    // a day. BIR_RECORDER_TICK_MS is for tests.
+    let lastSweep = Date.now();
+    tick = setInterval(() => {
+        try {
+            const now = Date.now();
+            const expected = projectEndpoint(cwd);
+            const onDisk = readDiscovery(cwd, { ignoreAge: true });
+            if (stillTheProjects(expected)) {
+                backToTheProject();
+                if (!onDisk) {
+                    publish();
+                }
+                else if (onDisk.pid === process.pid) {
+                    if (now - lastWrite >= HEARTBEAT_MS || differs(onDisk))
+                        publish();
+                }
+                else if (mayReclaim(onDisk, expected)) {
+                    publish();
+                    if (!reclaimedFrom.has(onDisk.pid)) {
+                        reclaimedFrom.add(onDisk.pid);
+                        logLine("control.discovery_reclaimed", {
+                            from_pid: onDisk.pid,
+                            from: onDisk.url,
+                            version: onDisk.version ?? null,
+                            why: "the project's discovery file named an older recorder, or one on a port the hooks no longer " +
+                                "post to; new proxies must bind to the recorder the hooks reach",
+                        });
+                    }
+                }
+                else {
+                    logOnce("discovery.claimed", "control.discovery_claimed", {
+                        pid: onDisk.pid,
+                        why: "another live recorder has written this project's discovery file; leaving it alone",
+                    });
+                }
+            }
+            else {
+                becomeSuperseded(now);
+                // Still named by the file (no recorder for the new port has started
+                // yet): keep the record fresh until one takes it.
+                if (onDisk?.pid === process.pid && (now - lastWrite >= HEARTBEAT_MS || differs(onDisk)))
+                    publish();
+                maybeExitSuperseded(now);
+            }
+            log?.rotateIfLarge();
+            if (now - lastSweep >= SWEEP_EVERY_MS) {
+                lastSweep = now;
+                sweepStaleDiscovery();
+                // Hand-over files hold live tool outputs; a recorder that crashed
+                // before its own scheduled sweep must not leave them on disk.
+                sweepDeliveries();
+            }
+        }
+        catch (err) {
+            logLine("control.heartbeat_failed", { error: errText(err) });
+        }
+    }, positiveInt(process.env.BIR_RECORDER_TICK_MS, DISCOVERY_CHECK_MS));
+    tick.unref();
+    const sweepSoon = setTimeout(() => {
+        sweepStaleDiscovery();
+        sweepDeliveries();
+    }, 5_000);
+    sweepSoon.unref();
+    keeper.start();
+    logLine("control.listening", {
+        url: address.url,
+        cwd,
+        discovery: discoveryFile,
+        journal: journalFile,
+        machine: hostname(),
+        version: packageVersion(),
+        background: daemon ? "yes" : undefined,
+        recorder: keeper.state,
+        wrapped: wrappedServersFor(cwd).join(",") || "(none)",
+        port: endpoint.ephemeral ? "any free (BIR_CONTROL_PORT=0)" : undefined,
+        // How PreToolUse answers an ordinary wrapped call. `auto` (unset) never
+        // answers `allow` for one, so the person's permission prompts are theirs.
+        correlation: process.env.BIR_NO_CORRELATION === "1" ? "off" : (correlationSetting() ?? "auto"),
+    });
+    if (correlationSetting() === "allow" && process.env.BIR_NO_CORRELATION !== "1") {
+        // Loud, because it changes what the person is asked: an operator's
+        // explicit choice, never a default.
+        logLine("control.correlation_allow", {
+            why: "BIR_CORRELATION_DECISION=allow — every wrapped MCP call is answered `allow` and runs without " +
+                "the permission prompt it would otherwise get; unset it to keep the prompts",
+        });
+    }
+    if (!endpoint.ephemeral && (preferredPort !== DEFAULT_CONTROL_PORT || sidecar.controlPort || record)) {
+        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",
+            });
+        }
+    }
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+}
+//# sourceMappingURL=recorder-main.js.map