@basein/runner 0.1.0

package/dist/control/server.js

@@ -0,0 +1,1131 @@
+/**
+ * control/server — the local control plane (Phase 5) and the Tier 1 recorder.
+ *
+ * WHY THIS EXISTS AT ALL (§3.2). Three proxies recording independently would
+ * produce three interleaved step streams with no shared ordering, and would
+ * double-record every call the hook also sees. One control server gives one
+ * `stepIndex` sequence, one run lifecycle, one HTTP chain to the recorder, and
+ * one place to dedupe.
+ *
+ * It is two things in one process, deliberately: the **Claude Code hook
+ * receiver** (Claude Code POSTs each lifecycle event to an HTTP hook) and the
+ * **control plane** the proxies report to. They share the run, so they must
+ * share the process.
+ *
+ * RUN BOUNDARIES follow RRepeat's: a Claude Code *session* holds many prompts,
+ * and each `UserPromptSubmit → Stop` turn is one run. Creation is deferred to
+ * the first prompt so the server's similar-prompt detection runs against the
+ * real prompt rather than an empty string; a proxy step that arrives before any
+ * prompt (an SDK session with no hooks) lazily opens a run with empty input,
+ * which is honest rather than lossy.
+ *
+ * SECURITY (§9): binds 127.0.0.1 only, requires the discovery file's bearer
+ * token on every route, and never echoes the token back. A loopback port that
+ * accepts unauthenticated step reports is a local exfiltration channel.
+ */
+import { createServer } from "node:http";
+import { randomBytes, randomUUID } from "node:crypto";
+import { FINGERPRINT_WINDOW_MS, fingerprint, newCallId, parseQualifiedName, qualifyToolName, } from "./correlation.js";
+import { StepIndexAllocator } from "./ordering.js";
+import { contextForToolUse, markTranscriptUsage, settledLastAssistantText, usageSince, } from "./transcript.js";
+import { isHousekeeping } from "../record/housekeeping.js";
+import { redact } from "../record/redact.js";
+import { serializeCapped } from "../record/truncate.js";
+import { StepQueue } from "../record/queue.js";
+import { NullRecorder, isMatchAware, isScenarioReporter, } from "../record/recorder.js";
+import { ReplayController, POLL_HOLD_MS, } from "../replay/controller.js";
+import { calculateCostUsd } from "../replay/pricing.js";
+import { logDetail, logLine, errText } from "../util/log.js";
+import { packageVersion } from "../util/version.js";
+/** How long a `/tool/post` waits for the proxy's own report before recording its own view. */
+const PROXY_REPORT_GRACE_MS = 1_500;
+export class ControlServer {
+    token;
+    sessionId = "birsess_" + randomUUID();
+    opts;
+    recorder;
+    queue;
+    sessions = new Map();
+    /** Config keys known to be wrapped: from install config plus live registrations. */
+    wrapped = new Set();
+    /** serverName → registration facts, for `bir doctor`. */
+    registrations = new Map();
+    server;
+    address;
+    lossy = false;
+    /** Seals whose answer text is still being waited for. Awaited before any flush. */
+    pendingSeals = [];
+    /** Calculated replay. Inert unless `opts.replay.enabled`. */
+    replay;
+    constructor(opts) {
+        this.opts = opts;
+        this.recorder = opts.recorder;
+        this.token = opts.token ?? randomBytes(32).toString("hex");
+        for (const name of opts.wrappedServers ?? [])
+            this.wrapped.add(name);
+        this.replay = new ReplayController(opts.replay ?? { enabled: false, minSimilarity: 1 });
+        this.queue = new StepQueue({
+            onDrop: (dropped) => {
+                // §10: drop oldest, flag the run lossy. The flag is louder than a
+                // verbose line because a lossy run must never be mistaken for a whole
+                // one — see the README's note on `metadata.lossy` and open question 1.
+                if (!this.lossy)
+                    logLine("run.lossy", { why: "step queue overflowed", dropped });
+                this.lossy = true;
+            },
+            onError: (err) => logLine("control.step_failed", { error: errText(err) }),
+        });
+    }
+    // ── lifecycle ────────────────────────────────────────────────────────────
+    listen() {
+        const preferred = this.opts.port ?? 0;
+        return new Promise((resolve, reject) => {
+            const server = createServer((req, res) => void this.handle(req, res));
+            this.server = server;
+            const bind = (port, allowFallback) => {
+                server.removeAllListeners("error");
+                server.once("error", (err) => {
+                    if (allowFallback && (err.code === "EADDRINUSE" || err.code === "EACCES")) {
+                        logLine("control.port_busy", { port, why: "falling back to an ephemeral port" });
+                        bind(0, false);
+                        return;
+                    }
+                    reject(err);
+                });
+                server.listen(port, "127.0.0.1", () => {
+                    const addr = server.address();
+                    const actual = typeof addr === "object" && addr ? addr.port : port;
+                    this.address = {
+                        url: `http://127.0.0.1:${actual}`,
+                        port: actual,
+                        token: this.token,
+                        sessionId: this.sessionId,
+                    };
+                    resolve(this.address);
+                });
+            };
+            bind(preferred, preferred !== 0);
+        });
+    }
+    async close() {
+        // Release parked pollers first: a `/proxy/poll` held for 25 s would otherwise
+        // keep the HTTP server's `close` callback waiting for exactly that long.
+        this.replay.close();
+        for (const session of this.sessions.values()) {
+            if (session.run && !session.run.finished)
+                await this.finalizeRun(session);
+        }
+        await this.queue.flush();
+        const server = this.server;
+        if (!server)
+            return;
+        await new Promise((resolve) => server.close(() => resolve()));
+        this.server = undefined;
+    }
+    /** Facts for `bir doctor` / `GET /health`. */
+    health() {
+        const sessions = [...this.sessions.values()].map((s) => ({
+            sessionId: s.sessionId,
+            runId: s.run?.runId,
+            steps: s.run?.ordering.next ?? 0,
+            recording: s.run?.recording ?? false,
+            replay: s.run?.replay
+                ? {
+                    scenarioId: s.run.replay.scenarioId,
+                    mode: s.run.replay.mode,
+                    similarity: s.run.replay.similarity,
+                    outcome: s.run.replay.outcome,
+                    stepsPlanned: s.run.replay.stepsPlanned,
+                    stepsPinned: s.run.replay.stepsPinned,
+                    armed: Boolean(s.run.replay.plan) && !s.run.replay.retired,
+                }
+                : null,
+        }));
+        return {
+            ok: true,
+            recorder: "baseinstrunner",
+            tier: "bound",
+            // The authoritative answer to "is anything actually being saved?".
+            recording: this.opts.recording ?? !(this.recorder instanceof NullRecorder),
+            authUrl: process.env.BIR_AUTH_URL ?? null,
+            sessionId: this.sessionId,
+            pid: process.pid,
+            cwd: this.opts.cwd,
+            url: this.address?.url,
+            wrappedServers: [...this.wrapped],
+            hooksVersion: packageVersion(),
+            registeredProxies: [...this.registrations].map(([serverName, r]) => ({
+                serverName,
+                pid: r.pid,
+                cwd: r.cwd,
+                registeredAt: r.at,
+                version: r.version,
+            })),
+            // A capability this sharp must never be discoverable only by reading a log
+            // (docs/calculatedReplay.md §13.2, mitigation 3).
+            replay: {
+                enabled: this.replay.enabled,
+                minSimilarity: this.opts.replay?.minSimilarity ?? null,
+                allowServers: this.opts.replay?.allowServers ? [...this.opts.replay.allowServers] : null,
+                deriveKey: Boolean(this.opts.replay?.apiKey ?? process.env.ANTHROPIC_API_KEY),
+                pollingProxies: this.replay.work.pollingServers(),
+            },
+            lossy: this.lossy,
+            queued: this.queue.size,
+            sessions,
+        };
+    }
+    // ── HTTP plumbing ────────────────────────────────────────────────────────
+    async handle(req, res) {
+        const route = (req.url ?? "").split("?")[0];
+        try {
+            const auth = req.headers["authorization"];
+            if (auth !== `Bearer ${this.token}`) {
+                this.send(res, 401, { error: "unauthorized" });
+                return;
+            }
+            if (route === "/health") {
+                this.send(res, 200, this.health());
+                return;
+            }
+            if (req.method !== "POST") {
+                this.send(res, 405, { error: "method_not_allowed" });
+                return;
+            }
+            const body = await this.readJson(req);
+            switch (route) {
+                case "/session/start":
+                    this.send(res, 200, this.onSessionStart(body));
+                    return;
+                case "/session/prompt":
+                    this.send(res, 200, await this.onPrompt(body));
+                    return;
+                case "/tool/pre":
+                    this.send(res, 200, await this.onToolPre(body));
+                    return;
+                case "/tool/post":
+                    this.send(res, 200, this.onToolPost(body));
+                    return;
+                case "/session/agent":
+                    this.send(res, 200, this.onAgent(body));
+                    return;
+                case "/session/stop":
+                    this.send(res, 200, this.onStop(body));
+                    return;
+                case "/session/end":
+                    this.send(res, 200, await this.onSessionEnd(body));
+                    return;
+                case "/proxy/register":
+                    this.send(res, 200, this.onProxyRegister(body));
+                    return;
+                case "/proxy/step":
+                    this.send(res, 200, this.onProxyStep(body));
+                    return;
+                case "/proxy/poll": {
+                    // A long poll is the one route whose client can vanish while we hold
+                    // it. Tie an abort signal to the request so a dead proxy's parked poll
+                    // is dropped rather than being handed work it can never run.
+                    const gone = new AbortController();
+                    const onClose = () => gone.abort();
+                    res.once("close", onClose);
+                    try {
+                        const answer = await this.onProxyPoll(body, gone.signal);
+                        if (gone.signal.aborted)
+                            return; // nobody left to answer
+                        this.send(res, 200, answer);
+                    }
+                    finally {
+                        res.off("close", onClose);
+                    }
+                    return;
+                }
+                case "/proxy/result":
+                    this.send(res, 200, this.onProxyResult(body));
+                    return;
+                case "/scenario/run":
+                    this.send(res, 200, await this.onScenarioRun());
+                    return;
+                case "/scenario/replay":
+                    this.send(res, 200, await this.onScenarioReplay(body));
+                    return;
+                default:
+                    this.send(res, 404, { error: "not_found" });
+                    return;
+            }
+        }
+        catch (err) {
+            // Rule 4 of §1: never be the reason a host session fails. A 200 with an
+            // empty hook object lets Claude Code proceed exactly as if we were absent.
+            logLine("control.route_failed", { route, error: errText(err) });
+            this.send(res, 200, {});
+        }
+    }
+    send(res, status, body) {
+        const text = JSON.stringify(body ?? {});
+        res.writeHead(status, {
+            "content-type": "application/json",
+            "content-length": Buffer.byteLength(text),
+        });
+        res.end(text);
+    }
+    readJson(req) {
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            let bytes = 0;
+            req.on("data", (chunk) => {
+                bytes += chunk.length;
+                if (bytes > 64 * 1024 * 1024) {
+                    reject(new Error("request body too large"));
+                    req.destroy();
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            req.on("end", () => {
+                const raw = Buffer.concat(chunks).toString("utf8");
+                if (!raw.trim()) {
+                    resolve({});
+                    return;
+                }
+                try {
+                    resolve(JSON.parse(raw));
+                }
+                catch (err) {
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                }
+            });
+            req.on("error", reject);
+        });
+    }
+    // ── session / run state ──────────────────────────────────────────────────
+    ensureSession(payload) {
+        const sessionId = payload.session_id ?? "unknown-session";
+        let session = this.sessions.get(sessionId);
+        if (!session) {
+            session = { sessionId };
+            this.sessions.set(sessionId, session);
+        }
+        if (payload.transcript_path)
+            session.transcriptPath = payload.transcript_path;
+        if (payload.cwd)
+            session.cwd = payload.cwd;
+        return session;
+    }
+    /** Open a run for `session`, or return the open one. */
+    ensureRun(session, input = "") {
+        if (session.run && !session.run.finished)
+            return session.run;
+        const runId = this.recorder.startRun(input, this.runMetadata(session));
+        const run = {
+            runId,
+            input,
+            startedAtMs: Date.now(),
+            ordering: new StepIndexAllocator(),
+            recording: true,
+            finished: false,
+            promptSeen: input.length > 0,
+            builtIns: new Map(),
+            correlations: new Map(),
+            // Taken here, beside `startedAtMs`, so the cost window and the duration
+            // window are the same window (docs/calculatedReplay.md §11.4).
+            usageMark: markTranscriptUsage(session.transcriptPath),
+        };
+        session.run = run;
+        logLine("run.start", { run: runId, sess: session.sessionId, tier: "bound" });
+        // Started here so the round trip overlaps whatever the caller does next;
+        // `onPrompt` awaits the same memoized promise under its own budget.
+        void this.watchForMatch(run);
+        return run;
+    }
+    runMetadata(session) {
+        return {
+            recorder: "baseinstrunner",
+            tier: "bound",
+            host: this.opts.host ?? { app: "claude-code" },
+            wrappedServers: [...this.wrapped],
+            // Known-at-start value. A run that turns lossy later says so on the audit
+            // log; carrying it here too would need a metadata patch the service does
+            // not expose in v1 (docs §13, open question 1).
+            lossy: this.lossy,
+            sessionId: session.sessionId,
+            cwd: session.cwd ?? this.opts.cwd,
+        };
+    }
+    /**
+     * A similar-prompt hit means the service created no run, so every later step
+     * post would 404. Stop recording it — that half is v1 and is mandatory.
+     *
+     * What replaces the recording is v2 (docs/calculatedReplay.md): the matched
+     * scenario is put through the gate ladder and, if every gate passes, armed as a
+     * plan. Memoized, because `ensureRun` is reached from five different hooks and
+     * arming twice would run the scenario twice.
+     *
+     * Resolves with the steering directive to inject, or undefined.
+     */
+    watchForMatch(run, prompt = "") {
+        if (run.matchWatch)
+            return run.matchWatch;
+        if (!isMatchAware(this.recorder))
+            return Promise.resolve(undefined);
+        const pending = this.recorder.getMatch(run.runId);
+        run.matchWatch = this.replay
+            .awaitMatch(pending)
+            .then((match) => {
+            if (!match)
+                return undefined;
+            run.recording = false;
+            logLine("run.matched", {
+                run: run.runId,
+                matchedRun: match.runId,
+                scenario: match.scenarioId ?? undefined,
+                similarity: match.similarity,
+                why: "similar prompt — the service kept its own run; not recording this one",
+            });
+            run.replay = this.replay.arm(match, prompt || run.input, this.wrapped);
+            return this.replay.directiveFor(run.replay);
+        })
+            .catch((err) => {
+            // Replay is an optimisation; a broken one must never cost a turn.
+            logLine("replay.arm_failed", { run: run.runId, error: errText(err) });
+            return undefined;
+        });
+        return run.matchWatch;
+    }
+    /**
+     * Close the run's books, without waiting for the network.
+     *
+     * SEALING IS SPLIT FROM FLUSHING ON PURPOSE. `Stop` — the end of the turn, and
+     * the run boundary this whole design names — is a synchronous hook the session
+     * is waiting on, so it must not block on an HTTP flush. And `SessionEnd`, the
+     * event that used to be the *only* thing that finished a run, does not reliably
+     * arrive at all: it fires as the host process is exiting and loses the race.
+     * A run whose completeness depends on winning that race is a run that is
+     * routinely left half-open, which is what happened in practice.
+     *
+     * Idempotent: the second caller sees `finished` and does nothing.
+     */
+    sealRun(session) {
+        const run = session.run;
+        if (!run || run.finished)
+            return;
+        run.finished = true;
+        for (const correlation of run.correlations.values()) {
+            if (correlation.fallback)
+                clearTimeout(correlation.fallback);
+            if (correlation.threadFallback)
+                clearTimeout(correlation.threadFallback);
+        }
+        const durationMs = Date.now() - run.startedAtMs;
+        // What this turn cost the model. Computed once, used twice: it is this run's
+        // `originalCostUsd` when recorded, and the `sessionCostUsd` of a matched
+        // turn's execution report.
+        const cost = this.runCost(session, run);
+        // A matched turn records nothing, but it still owes the ledger a number —
+        // including when it declined to steer, which is a *baseline* sample and is
+        // what every saving is measured against (docs/calculatedReplay.md §11).
+        this.reportExecution(run, durationMs, cost);
+        if (run.recording) {
+            const transcriptPath = session.transcriptPath;
+            // Resolve the answer *outside* the queue: the wait below is up to two
+            // seconds, and the queue is serial — blocking it here would delay the
+            // first step of the user's next turn by that much.
+            this.pendingSeals.push(settledLastAssistantText(transcriptPath)
+                .catch(() => "")
+                .then((answer) => {
+                this.queue.push(() => {
+                    if (answer) {
+                        this.recorder.recordFinalAnswer(run.runId, run.ordering.allocate(), { answer });
+                    }
+                    // WITHOUT `costUsd` THE SERVICE STORES ZERO, and a zero here is
+                    // not harmless: `original_cost_usd` is what the UI shows as
+                    // "LLM $/run", and it is the service's fallback baseline for a
+                    // scenario that has no samples yet. A run recorded at $0 makes
+                    // every later saving measured against nothing.
+                    this.recorder.finishRun(run.runId, answer || undefined, {
+                        durationMs,
+                        costUsd: cost.measured ? cost.usd : undefined,
+                    });
+                });
+            }));
+        }
+        logLine("run.finish", {
+            run: run.runId,
+            steps: run.ordering.next,
+            durationMs,
+            lossy: this.lossy,
+            recorded: run.recording,
+        });
+    }
+    /**
+     * Report what a matched turn cost (docs/calculatedReplay.md §11).
+     *
+     * The live session's tokens come from the transcript **delta** since this run
+     * opened — never the whole file, which would bill run 3 for runs 1+2+3 and hand
+     * the ledger a baseline several times the truth (§11.4). A run with no
+     * watermark (one opened lazily by a proxy step, before any prompt) is reported
+     * `measured: false`: saying "unmeasured" is better than quietly inflating a
+     * baseline.
+     *
+     * Queued rather than awaited — `Stop` is a synchronous hook the session is
+     * waiting on, and a report is never worth a stall.
+     */
+    /**
+     * What this turn cost the model, from the transcript **delta** since the run
+     * opened — never the whole file, which would bill run 3 for runs 1+2+3
+     * (docs/calculatedReplay.md §11.4).
+     *
+     * No watermark means the delta is unknowable, so this reports `measured:
+     * false` and zero rather than a number that is confidently wrong.
+     */
+    runCost(session, run) {
+        const measurable = run.usageMark !== undefined;
+        if (!measurable) {
+            logLine("run.unmeasured", {
+                run: run.runId,
+                why: "no transcript watermark — this run opened before any hook carried a transcript path",
+            });
+            return { usd: 0, measured: false };
+        }
+        const deltas = usageSince(session.transcriptPath, run.usageMark);
+        const usd = deltas.reduce((sum, u) => sum + calculateCostUsd(u.model, u), 0);
+        return { usd, measured: deltas.length > 0 };
+    }
+    reportExecution(run, durationMs, cost) {
+        const state = run.replay;
+        if (!state || !isScenarioReporter(this.recorder))
+            return;
+        const report = this.replay.buildReport(state, {
+            sessionCostUsd: cost.usd,
+            measured: cost.measured,
+            durationMs,
+            prompt: run.input || undefined,
+        });
+        if (!report)
+            return;
+        const recorder = this.recorder;
+        this.queue.push(() => recorder.reportExecution(report));
+    }
+    /** Seal the run *and* wait for everything queued to reach the service. */
+    async finalizeRun(session) {
+        const runId = session.run?.runId;
+        this.sealRun(session);
+        // Seals resolve their answer text off-queue, so they must be awaited before
+        // the queue is flushed — otherwise the flush finishes before the finish call
+        // has even been enqueued.
+        await Promise.all(this.pendingSeals.splice(0, this.pendingSeals.length)).catch(() => undefined);
+        await this.queue.flush();
+        if (runId)
+            await this.recorder.flush(runId).catch(() => undefined);
+    }
+    // ── hook events ──────────────────────────────────────────────────────────
+    onSessionStart(payload) {
+        const session = this.ensureSession(payload);
+        // Run creation is deferred to the first prompt so the service's
+        // similar-prompt detection sees the real prompt, not "".
+        logLine("session.start", {
+            sess: session.sessionId,
+            cwd: session.cwd,
+            why: "run deferred to prompt",
+        });
+        return {};
+    }
+    async onPrompt(payload) {
+        const session = this.ensureSession(payload);
+        const input = payload.prompt ?? "";
+        const open = session.run && !session.run.finished ? session.run : undefined;
+        if (open?.promptSeen) {
+            // A second prompt in the same session: close the previous turn's run and
+            // open a fresh one. Claude Code carries no prompt id, so UserPromptSubmit
+            // → Stop is the only honest run boundary.
+            await this.finalizeRun(session);
+            session.run = undefined;
+        }
+        else if (open && open.ordering.next === 0) {
+            // A run was opened early by a proxy step (the host spawned MCP servers
+            // before the prompt landed) and has recorded nothing. Close it and start
+            // again with the real prompt: `input` is what the service embeds, and a
+            // run created with "" would never match anything. The empty run is below
+            // the service's recording threshold and is pruned there.
+            await this.finalizeRun(session);
+            session.run = undefined;
+        }
+        else if (open) {
+            // Steps are already recorded under an empty input. Keep them — losing real
+            // steps to gain a prompt is the wrong trade — and say so.
+            open.promptSeen = true;
+            open.input = input;
+            logLine("run.prompt_late", {
+                run: open.runId,
+                steps: open.ordering.next,
+                why: "steps preceded the prompt; this run's input stays empty",
+            });
+            return {};
+        }
+        const run = this.ensureRun(session, input);
+        run.promptSeen = true;
+        run.input = input;
+        logDetail("session.prompt", { sess: session.sessionId, run: run.runId, chars: input.length });
+        // The one moment a directive can be injected. Bounded by the match budget so
+        // a slow or unreachable service costs the user nothing but an ordinary turn
+        // (docs/calculatedReplay.md §10); `additionalContext` carries no `decision`,
+        // so the prompt still reaches the model either way.
+        const directive = await this.watchForMatch(run, input);
+        if (!directive)
+            return {};
+        return {
+            hookSpecificOutput: {
+                hookEventName: "UserPromptSubmit",
+                additionalContext: directive,
+            },
+        };
+    }
+    /**
+     * `PreToolUse`. Two shapes of answer:
+     *
+     *  - **Wrapped MCP tool** → mint a call id and ask Claude Code to carry it in
+     *    the tool's arguments, so the proxy's report and this hook's view join into
+     *    one step (Phase 6). No step is recorded yet: the proxy owns the result and
+     *    allocates the index when it reports.
+     *  - **Anything else** (built-ins, unwrapped MCP) → allocate the pair now and
+     *    record `tool_selected`. The hook is this step's only observer.
+     */
+    async onToolPre(payload) {
+        const session = this.ensureSession(payload);
+        const run = this.ensureRun(session);
+        const toolName = payload.tool_name ?? "unknown";
+        const toolUseId = payload.tool_use_id ?? "";
+        const modelArgs = payload.tool_input ?? {};
+        // The host's own bookkeeping is not a step of anything (see
+        // `record/housekeeping.ts`). Recorded, `ToolSearch` becomes step 0 of the
+        // calculated scenario: its generated reasoning is injected into every
+        // matched turn's steering directive, and because it is not an MCP tool it
+        // drags the whole scenario out of `direct` mode. Observed in production.
+        if (isHousekeeping(toolName)) {
+            logDetail("tool.pre.skipped", { run: run.runId, tool: toolName, why: "host housekeeping" });
+            return {};
+        }
+        const agentId = payload.agent_id ?? session.agentId;
+        const reasoning = contextForToolUse(session.transcriptPath, toolUseId);
+        const context = agentId ? `[agent ${agentId}] ${reasoning}`.trim() : reasoning;
+        // ── replay steering (docs/calculatedReplay.md §7) ────────────────────────
+        // Runs before anything else, because two of its four answers end the call.
+        let pinned;
+        if (run.replay?.plan && !run.replay.retired) {
+            const action = await this.replay.preTool(run.replay, toolName, toolUseId);
+            switch (action.kind) {
+                case "pin":
+                    pinned = action.input;
+                    break;
+                case "bash":
+                    return {
+                        hookSpecificOutput: {
+                            hookEventName: "PreToolUse",
+                            permissionDecision: "allow",
+                            updatedInput: { command: action.command },
+                        },
+                    };
+                case "deny":
+                    return {
+                        hookSpecificOutput: {
+                            hookEventName: "PreToolUse",
+                            permissionDecision: "deny",
+                            permissionDecisionReason: action.reason,
+                        },
+                    };
+                case "abort":
+                case "passthrough":
+                    break;
+            }
+        }
+        // The arguments that will actually run — which is what must be correlated and
+        // recorded. Recording the arguments the model *proposed* rather than the ones
+        // that ran would put a lie in the corpus (§7.1).
+        const args = pinned ?? modelArgs;
+        const mcp = parseQualifiedName(toolName);
+        if (mcp && this.wrapped.has(mcp.serverName)) {
+            const correlation = {
+                callId: newCallId(),
+                toolUseId,
+                serverName: mcp.serverName,
+                toolName: mcp.toolName,
+                qualifiedName: toolName,
+                hookArgs: args,
+                context: context || undefined,
+                createdAt: Date.now(),
+                settled: false,
+                fingerprint: fingerprint(mcp.serverName, mcp.toolName, args),
+            };
+            run.correlations.set(correlation.callId, correlation);
+            logDetail("tool.pre.correlate", {
+                run: run.runId,
+                tool: toolName,
+                callId: correlation.callId,
+                mode: this.opts.noCorrelation ? "fingerprint" : "injected",
+                pinned: pinned ? true : undefined,
+            });
+            if (this.opts.noCorrelation) {
+                // No id ride-along, so no schema relaxation is needed either. The join
+                // happens on `(server, tool, hash(args))` — lossy under identical
+                // concurrent calls, and documented as such. Pinning still works: it is
+                // the `updatedInput` that steers, and only the *join* degrades here.
+                if (!pinned)
+                    return { callId: correlation.callId, correlation: "fingerprint" };
+                return {
+                    callId: correlation.callId,
+                    correlation: "fingerprint",
+                    hookSpecificOutput: {
+                        hookEventName: "PreToolUse",
+                        permissionDecision: "allow",
+                        updatedInput: pinned,
+                    },
+                };
+            }
+            return {
+                callId: correlation.callId,
+                correlation: "injected",
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    // A pinned call must be allowed, or the host may drop `updatedInput`
+                    // and the step would run with the model's own arguments.
+                    permissionDecision: pinned ? "allow" : (this.opts.correlationDecision ?? "allow"),
+                    updatedInput: { ...args, __bir_call_id__: correlation.callId },
+                },
+            };
+        }
+        // Built-in (or unwrapped MCP) step: the hook is the only observer.
+        const pair = run.ordering.allocatePair();
+        run.builtIns.set(toolUseId || `anon_${pair.selected}`, {
+            stepIndex: pair.selected,
+            responseIndex: pair.response,
+            toolName,
+        });
+        if (run.recording) {
+            this.queue.push(() => {
+                this.recorder.recordToolSelected(run.runId, pair.selected, {
+                    toolName,
+                    toolInput: serializeCapped(redact(args)),
+                    context: context || undefined,
+                });
+            });
+        }
+        logDetail("tool.pre", { run: run.runId, tool: toolName, step: pair.selected });
+        if (pinned) {
+            return {
+                stepIndex: pair.selected,
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "allow",
+                    updatedInput: pinned,
+                },
+            };
+        }
+        return { stepIndex: pair.selected };
+    }
+    /**
+     * `PostToolUse` / `PostToolUseFailure`. For a built-in this closes the pair.
+     * For a correlated MCP call it normally does nothing — the proxy owns that
+     * result — but it arms a short fallback: if the proxy never reports (it died,
+     * or the call never reached it), the hook's own view is recorded after
+     * {@link PROXY_REPORT_GRACE_MS} rather than the step being lost entirely.
+     */
+    onToolPost(payload) {
+        const session = this.ensureSession(payload);
+        const run = this.ensureRun(session);
+        const toolUseId = payload.tool_use_id ?? "";
+        const toolName = payload.tool_name ?? "unknown";
+        // `onToolPre` opened no step for these, so closing one here would record a
+        // `tool_response` with no `tool_selected` before it.
+        if (isHousekeeping(toolName))
+            return {};
+        const failed = payload.hook_event_name === "PostToolUseFailure" || payload.error !== undefined;
+        // ── replay threading (docs/calculatedReplay.md §7.2) ─────────────────────
+        // `toolOutputLogic` was authored against the bytes that were *recorded* for
+        // this step. For a wrapped MCP step those are the proxy's whole
+        // `CallToolResult`; the hook's `tool_response` is Claude Code's rendering,
+        // and feeding the wrong one derives nothing — silently — so every later step
+        // reading `respParams` gets a wrong input. Thread from the source that
+        // recorded, and only fall back to the hook's view if no report arrives.
+        const replay = run.replay;
+        const pinnedHere = replay && this.replay.isPinned(replay, toolUseId);
+        const correlation = [...run.correlations.values()].find((c) => c.toolUseId && c.toolUseId === toolUseId);
+        if (pinnedHere && replay) {
+            if (correlation && this.replay.threadsFromProxy(replay, toolUseId)) {
+                correlation.threadToolUseId = toolUseId;
+                correlation.threadFallback = setTimeout(() => {
+                    if (!this.replay.isPinned(replay, toolUseId))
+                        return;
+                    logLine("replay.thread_fallback", {
+                        run: run.runId,
+                        tool: toolName,
+                        why: "no proxy report — threading the hook's view; shapes may differ",
+                    });
+                    this.replay.postTool(replay, toolUseId, serializeCapped(payload.tool_response ?? {}));
+                }, PROXY_REPORT_GRACE_MS);
+                correlation.threadFallback.unref?.();
+            }
+            else {
+                this.replay.postTool(replay, toolUseId, serializeCapped(payload.tool_response ?? {}));
+            }
+        }
+        if (correlation) {
+            if (correlation.settled) {
+                logDetail("tool.post.deduped", { run: run.runId, tool: toolName });
+                return { deduped: true };
+            }
+            // Respond now; decide later. Blocking the hook on the proxy's report would
+            // put recording latency on the session's critical path.
+            correlation.fallback = setTimeout(() => {
+                if (correlation.settled)
+                    return;
+                logLine("tool.post.fallback", {
+                    run: run.runId,
+                    tool: correlation.qualifiedName,
+                    why: "no proxy report — recording the hook's view instead",
+                });
+                this.settle(run, correlation, {
+                    args: correlation.hookArgs,
+                    result: payload.tool_response,
+                    isError: failed,
+                    errorMessage: failed ? this.errorText(payload) : undefined,
+                    durationMs: Date.now() - correlation.createdAt,
+                });
+            }, PROXY_REPORT_GRACE_MS);
+            correlation.fallback.unref?.();
+            return { pending: true };
+        }
+        const builtIn = run.builtIns.get(toolUseId) ?? run.builtIns.get(`anon_${toolName}`);
+        const responseIndex = builtIn ? builtIn.responseIndex : run.ordering.allocate();
+        if (run.recording) {
+            const output = serializeCapped(redact(payload.tool_response ?? {}));
+            this.queue.push(() => {
+                this.recorder.recordToolResponse(run.runId, responseIndex, {
+                    toolName,
+                    toolOutput: failed ? undefined : output,
+                    toolError: failed ? this.errorText(payload) : undefined,
+                });
+            });
+        }
+        run.builtIns.delete(toolUseId);
+        logDetail("tool.post", { run: run.runId, tool: toolName, step: responseIndex, failed });
+        return { stepIndex: responseIndex };
+    }
+    errorText(payload) {
+        if (typeof payload.error === "string")
+            return payload.error;
+        if (payload.error !== undefined)
+            return serializeCapped(redact(payload.error));
+        return serializeCapped(redact(payload.tool_response ?? {}));
+    }
+    /**
+     * `SubagentStart` / `SubagentStop`. These carry `agent_id`, which is the only
+     * way to tell a subagent's tool calls from the main thread's — Claude Code
+     * interleaves them into one hook stream otherwise.
+     *
+     * v1 attributes rather than partitions: the active agent id is remembered and
+     * prefixed onto each step's `context`, because the recording schema has no
+     * agent column and inventing one server-side is out of scope (D6). The
+     * partition is available in the audit log for anyone who needs it sooner.
+     */
+    onAgent(payload) {
+        const session = this.ensureSession(payload);
+        const starting = payload.hook_event_name === "SubagentStart";
+        session.agentId = starting ? payload.agent_id : undefined;
+        logDetail("session.agent", {
+            sess: session.sessionId,
+            agent: payload.agent_id,
+            event: payload.hook_event_name,
+        });
+        return {};
+    }
+    onStop(payload) {
+        const session = this.ensureSession(payload);
+        const run = session.run;
+        if (!run || run.finished)
+            return {};
+        logDetail("session.stop", { run: run.runId });
+        // The final answer is written by {@link sealRun}, which waits for the
+        // transcript to catch up — reading it here, synchronously, is what produced
+        // runs with no answer at all.
+        // The turn is over, so the run is over — that is the boundary §bindClaude
+        // names, and sealing here is what stops a run depending on `SessionEnd`
+        // arriving. A later prompt in the same session opens a fresh run, exactly as
+        // it did before.
+        this.sealRun(session);
+        return {};
+    }
+    async onSessionEnd(payload) {
+        const session = this.ensureSession(payload);
+        await this.finalizeRun(session);
+        return {};
+    }
+    // ── proxy routes ─────────────────────────────────────────────────────────
+    onProxyRegister(body) {
+        const serverName = String(body.serverName ?? "");
+        if (!serverName)
+            return { error: "serverName required" };
+        this.wrapped.add(serverName);
+        const proxyVersion = body.version === undefined ? undefined : String(body.version);
+        this.registrations.set(serverName, {
+            pid: Number(body.pid ?? 0),
+            cwd: String(body.cwd ?? ""),
+            at: Date.now(),
+            version: proxyVersion,
+        });
+        logLine("proxy.registered", { server: serverName, pid: body.pid, version: proxyVersion });
+        // A half-upgraded machine is the update failure that looks like success:
+        // `npm i -g` replaced the package, but a config still points at an older
+        // copy, or this hooks process predates the upgrade and was never
+        // restarted. Both keep working, and both quietly run code you did not
+        // ship. Say so once per registering proxy; never fail on it.
+        const own = packageVersion();
+        if (proxyVersion && proxyVersion !== own) {
+            logLine("version.skew", {
+                server: serverName,
+                proxy: proxyVersion,
+                hooks: own,
+                fix: "restart bir-hooks after upgrading, and re-run `bir install` if the entry shape changed",
+            });
+        }
+        // The run may not exist yet (a proxy is usually spawned before the first
+        // prompt). That is fine: the proxy needs the session, and gets a run id only
+        // once one exists.
+        const run = [...this.sessions.values()].find((s) => s.run && !s.run.finished)?.run;
+        return {
+            ok: true,
+            sessionId: this.sessionId,
+            runId: run?.runId,
+            correlation: this.opts.noCorrelation ? "fingerprint" : "injected",
+            // Tells the proxy whether to open its work loop. A proxy that never polls
+            // is not an error — its steps simply fall back to recorded outputs.
+            replay: this.replay.enabled,
+            pollHoldMs: POLL_HOLD_MS,
+        };
+    }
+    /**
+     * `POST /proxy/poll` — the control→proxy channel (docs/calculatedReplay.md §16.2).
+     *
+     * The proxy dials out and parks; the server answers with work, or empty at the
+     * hold deadline so the proxy re-polls. Keeping the direction outbound is what
+     * avoids N new loopback listeners and N new tokens for a latency saving that
+     * would be invisible next to the upstream's own round trip (D12).
+     */
+    async onProxyPoll(body, signal) {
+        const serverName = String(body.serverName ?? "");
+        if (!serverName)
+            return { error: "serverName required" };
+        if (!this.replay.enabled)
+            return {};
+        const hold = Number(body.holdMs);
+        const work = await this.replay.work.waitForWork(serverName, Number.isFinite(hold) && hold > 0 ? Math.min(hold, POLL_HOLD_MS) : POLL_HOLD_MS, signal);
+        return work ? { work } : {};
+    }
+    /** `POST /proxy/result` — the answer to one dispatched `tools/call`. */
+    onProxyResult(body) {
+        const workId = String(body.workId ?? "");
+        if (!workId)
+            return { error: "workId required" };
+        const error = typeof body.error === "string" ? body.error : undefined;
+        // An unknown id is a late answer to work that already timed out. Not an
+        // error — the caller has long since fallen back.
+        const claimed = this.replay.work.complete(workId, body.result, error);
+        return { ok: true, claimed };
+    }
+    /**
+     * `POST /scenario/run` — `bir-scenario` asking for the armed plan to run.
+     *
+     * This is `direct` mode's whole execution: every step goes to the proxy that
+     * already owns its upstream, so the model spends nothing beyond the turn that
+     * reads the results. There is no hook timeout here, which is exactly why the
+     * derivation wait was deferred to it (§10).
+     */
+    async onScenarioRun() {
+        // The session whose plan is *armed*, not merely the first unfinished one. A
+        // `claude -p` run is never sealed when its process exits, so the previous
+        // trial's session stays first in insertion order with its plan retired —
+        // and picking it answered `no_plan` while the live plan sat at index 1
+        // (docs/mcpmark.md §12).
+        const live = [...this.sessions.values()]
+            .map((s) => s.run)
+            .filter((r) => r !== undefined && !r.finished);
+        const run = live.find((r) => r.replay?.plan && !r.replay.retired) ??
+            live.find((r) => r.replay) ??
+            live[0];
+        if (!run?.replay)
+            return { ok: false, why: "no_plan" };
+        const result = await this.replay.runArmed(run.replay);
+        return result;
+    }
+    /**
+     * `POST /scenario/replay` — `bir replay`, i.e. a scenario nobody matched.
+     *
+     * The CLI holds the credentials, so it fetches the scenario and posts it here;
+     * this process holds the proxies, so it runs it. Enabled independently of
+     * `BIR_REPLAY`: the operator typed a scenario id, which is a far more explicit
+     * consent than a similarity score, and the gate that flag guards is automatic
+     * arming rather than execution itself.
+     */
+    async onScenarioReplay(body) {
+        const scenario = body.scenario;
+        const prompt = String(body.prompt ?? "");
+        if (!scenario || typeof scenario !== "object")
+            return { ok: false, why: "scenario required" };
+        const result = await this.replay.runAdHoc(scenario, prompt, this.wrapped);
+        return result;
+    }
+    /**
+     * A proxy's `ProxyStepReport`. Three joins, tried in order:
+     *   1. the injected `callId` (Tier 1, exact);
+     *   2. the fingerprint, inside a 30 s window (`--no-correlation`, lossy under
+     *      identical concurrent calls — §6 says so, and so does this code);
+     *   3. nothing — record it standalone, which is what an SDK session with no
+     *      hooks produces and is a complete MCP step in its own right.
+     */
+    onProxyStep(report) {
+        const session = this.sessionForProxyStep();
+        const run = this.ensureRun(session);
+        this.wrapped.add(report.serverName);
+        let correlation = report.callId ? run.correlations.get(report.callId) : undefined;
+        if (!correlation)
+            correlation = this.matchByFingerprint(run, report);
+        if (correlation) {
+            // The truer output for a replay step: exactly the bytes that were recorded
+            // for it when the scenario was built (§7.2).
+            //
+            // Keyed off "is this call still pinned", not off the flag `/tool/post`
+            // sets, because the two events race: the proxy's report is fire-and-forget
+            // HTTP and can land either side of `PostToolUse`. Waiting for the flag
+            // would let a fast proxy fall through to the 1.5 s hook-view fallback —
+            // the degraded path firing precisely when everything worked.
+            const toolUseId = correlation.threadToolUseId ?? correlation.toolUseId;
+            if (run.replay && toolUseId && this.replay.isPinned(run.replay, toolUseId)) {
+                correlation.threadToolUseId = undefined;
+                if (correlation.threadFallback) {
+                    clearTimeout(correlation.threadFallback);
+                    correlation.threadFallback = undefined;
+                }
+                this.replay.postTool(run.replay, toolUseId, serializeCapped(redact(report.result)));
+            }
+            if (correlation.settled) {
+                logDetail("proxy.step.deduped", { run: run.runId, tool: report.qualifiedName });
+                return { deduped: true };
+            }
+            const pair = this.settle(run, correlation, {
+                args: correlation.hookArgs ?? report.args,
+                result: report.result,
+                isError: report.isError,
+                errorMessage: report.errorMessage,
+                durationMs: report.durationMs,
+            });
+            return { stepIndex: pair.selected, merged: true };
+        }
+        // Standalone: no hook ever saw this call.
+        const pair = run.ordering.allocatePair();
+        this.record(run, pair, {
+            toolName: report.qualifiedName || qualifyToolName(report.serverName, report.toolName),
+            args: report.args,
+            result: report.result,
+            isError: report.isError,
+            errorMessage: report.errorMessage,
+        });
+        logDetail("proxy.step", {
+            run: run.runId,
+            tool: report.qualifiedName,
+            step: pair.selected,
+            merged: false,
+            ms: report.durationMs,
+        });
+        return { stepIndex: pair.selected, merged: false };
+    }
+    /**
+     * Which session a proxy's step belongs to.
+     *
+     * A proxy has no session id of its own — stdio MCP servers are never told one
+     * — so the control server decides. The order matters: preferring *any known*
+     * session over minting a new one is what stops a step that lands between
+     * `SessionStart` and the first prompt from opening a second, parallel run,
+     * which would split one session's steps across two recordings.
+     */
+    sessionForProxyStep() {
+        const withOpenRun = [...this.sessions.values()].find((s) => s.run && !s.run.finished);
+        if (withOpenRun)
+            return withOpenRun;
+        const known = [...this.sessions.values()][0];
+        if (known)
+            return known;
+        // No hook has ever fired: an SDK or non-Claude host. We own the session.
+        return this.ensureSession({ session_id: this.sessionId, cwd: this.opts.cwd });
+    }
+    matchByFingerprint(run, report) {
+        const key = fingerprint(report.serverName, report.toolName, report.args);
+        const now = Date.now();
+        let best;
+        for (const candidate of run.correlations.values()) {
+            if (candidate.settled)
+                continue;
+            if (candidate.fingerprint !== key)
+                continue;
+            if (now - candidate.createdAt > FINGERPRINT_WINDOW_MS)
+                continue;
+            // Oldest unsettled match wins — FIFO is the best guess available, and it
+            // is a guess: two identical concurrent calls are indistinguishable here.
+            if (!best || candidate.createdAt < best.createdAt)
+                best = candidate;
+        }
+        return best;
+    }
+    /** Record the merged pair for a correlation and latch it against re-entry. */
+    settle(run, correlation, data) {
+        correlation.settled = true;
+        if (correlation.fallback)
+            clearTimeout(correlation.fallback);
+        if (correlation.threadFallback)
+            clearTimeout(correlation.threadFallback);
+        const pair = run.ordering.allocatePair();
+        this.record(run, pair, {
+            toolName: correlation.qualifiedName,
+            args: data.args,
+            result: data.result,
+            isError: data.isError,
+            errorMessage: data.errorMessage,
+            context: correlation.context,
+        });
+        logDetail("proxy.step.merged", {
+            run: run.runId,
+            tool: correlation.qualifiedName,
+            step: pair.selected,
+            ms: data.durationMs,
+        });
+        return pair;
+    }
+    /** The one place a tool step pair is written. Redaction and caps live here. */
+    record(run, pair, d) {
+        if (!run.recording)
+            return;
+        const toolInput = serializeCapped(redact(d.args));
+        const toolOutput = d.isError ? undefined : serializeCapped(redact(d.result));
+        const toolError = d.isError
+            ? (d.errorMessage ?? serializeCapped(redact(d.result)))
+            : undefined;
+        this.queue.push(() => {
+            this.recorder.recordToolSelected(run.runId, pair.selected, {
+                toolName: d.toolName,
+                toolInput,
+                context: d.context,
+            });
+            this.recorder.recordToolResponse(run.runId, pair.response, {
+                toolName: d.toolName,
+                toolOutput,
+                toolError,
+            });
+        });
+    }
+}
+/**
+ * The port `bir install` writes into the hook URLs, and the one `bir-hooks`
+ * prefers. Claude Code's `settings.json` needs a *static* URL, so the control
+ * server cannot be purely ephemeral: it asks for this port and falls back to an
+ * ephemeral one only if it is taken — in which case the installed hooks point at
+ * a port nobody is listening on, and both `bir-hooks` and `bir doctor` say so.
+ */
+export const DEFAULT_CONTROL_PORT = 53411;
+//# sourceMappingURL=server.js.map