@basein/runner 0.2.12 → 0.3.1

package/dist/control/server.js

@@ -25,22 +25,232 @@
  */
 import { createServer } from "node:http";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { FINGERPRINT_WINDOW_MS, fingerprint, newCallId, parseQualifiedName, qualifyToolName, } from "./correlation.js";
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { BIR_CALL_ID, fingerprint, newCallId, parseQualifiedName, qualifyToolName, } from "./correlation.js";
 import { StepIndexAllocator } from "./ordering.js";
+import { pidAlive } from "./discovery.js";
+import { pinCompatible } from "./pin-guard.js";
 import { contextForToolUse, intentForToolUse, markTranscriptUsage, recentToolResults, settledLastAssistantText, usageSince, } from "./transcript.js";
 import { isHousekeepingCall } from "../record/housekeeping.js";
 import { redact } from "../record/redact.js";
-import { serializeCapped } from "../record/truncate.js";
+import { DEFAULT_MAX_STRING_BYTES, serializeCapped, truncateStrings } from "../record/truncate.js";
 import { StepQueue } from "../record/queue.js";
-import { NullRecorder, isIntentMatcher, isMatchAware, isRunCreationAware, isScenarioReporter, } from "../record/recorder.js";
+import { NullRecorder, isIntentMatcher, isMatchAware, isRecorderHealthReporter, isRunCreationAware, 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 { logDetail, logLine, logOnce, errText } from "../util/log.js";
 import { journal } from "../util/journal.js";
 import { packageVersion } from "../util/version.js";
 import { resolveAuthUrl } from "../auth/client.js";
+import { awaitWithin, serviceHealth } from "../util/service-health.js";
+import { offSource } from "../util/off-switch.js";
+import { claudeJsonPath, resolveServers } from "../config/resolve.js";
+import { SCENARIO_SERVER_KEY, isScenarioServer, projectToken, readSidecar } from "../config/generate.js";
+import { installedPath } from "./paths.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;
+/**
+ * The hard ceiling on how long each hook route may hold the session.
+ *
+ * THE RUNNER MUST NEVER BE WHY A SESSION WAITS. Claude Code waits for an HTTP
+ * hook up to the timeout `bir install` wrote for it (UserPromptSubmit 10 s,
+ * PreToolUse 15 s, PostToolUse / Stop 5 s, SessionEnd 3 s, subagents 3 s), and
+ * a hook that times out is shown to the user as a hook error. Each route's own
+ * budgets keep the ordinary case to milliseconds; these are the backstop,
+ * well inside those timeouts: past them the route answers — `{}`, or an honest
+ * note when a replay was mid-flight — and whatever was still running finishes
+ * in the background. A route not listed here is not a hook route.
+ */
+const HOOK_DEADLINE_MS = {
+    "/session/start": 2_000,
+    "/session/prompt": 7_000,
+    "/tool/pre": 12_000,
+    "/tool/post": 2_000,
+    "/session/agent": 2_000,
+    "/session/stop": 2_000,
+    "/session/end": 1_000,
+};
+/**
+ * What a matched steer plan's parameter settle leaves the directive's argument
+ * preview (replay/plan.ts PREVIEW_BUDGET_MS is the preview's own ceiling).
+ */
+const PREVIEW_RESERVE_MS = 500;
+/**
+ * What `UserPromptSubmit` may spend on replay: the similar-prompt match plus
+ * any derivation a matched scenario with a target needs before its directive
+ * can go out (segmented.md R-PARAM-4). Below the route's 7 s deadline, so the
+ * decision to steer is always taken here and never by the guard.
+ */
+const PROMPT_WAIT_MS = 6_000;
+/**
+ * How long a `PreToolUse` waits for the intent probe when that probe may arm a
+ * plan in the call's place (`BIR_INTENT_ARM_BUDGET_MS`). A clear match or a
+ * miss answers well inside it; a probe that also asks the service a live
+ * question does not, and is counted without arming (segmented.md R-HIT-11).
+ */
+const INTENT_ARM_PROBE_MS = 500;
+/** What an intent-armed plan may spend arming — derivation — inside `PreToolUse`. */
+const INTENT_ARM_DERIVE_MS = 1_500;
+/** How long a fragment's `PreToolUse` waits to learn whether its run was created. */
+const FRAGMENT_CREATE_MS = 300;
+/** What `close()` spends draining the last runs to the service before it lets go. */
+const CLOSE_DRAIN_MS = 5_000;
+/** How long a background drain follows one run before it stops waiting for it. */
+const DRAIN_MAX_MS = 120_000;
+/**
+ * How long a proxy's report may follow the `PreToolUse` it joins by
+ * fingerprint. Not the 30 s the id-less join used to allow: without
+ * auto-approval the call runs only once the user has answered its permission
+ * prompt, and a user who reads before approving is not an error.
+ */
+const CONSENT_WINDOW_MS = 10 * 60_000;
+/** Clock skew tolerated between a proxy's `startedAt` and the hook's `createdAt`. */
+const FINGERPRINT_SKEW_MS = 5_000;
+/**
+ * How long a `PreToolUse` for `run_scenario` binds the `/scenario/run` that
+ * follows it to its session. Long, because a user's own `ask` rule for the
+ * tool still prompts; a record is consumed by its run long before this.
+ */
+const DIRECT_CALL_TTL_MS = 10 * 60_000;
+/**
+ * How long a session started with `BIR_OFF=1` (K2) stays off with no hook
+ * heard. Not the ordinary session's `forgetMs`: Claude Code fires no
+ * SessionStart when someone comes back to a session left open overnight, so
+ * nothing would relay `bir_off` again, and the session would be recorded.
+ */
+const OFF_SESSION_TTL_MS = 7 * 24 * 60 * 60_000;
+/** At most this many off sessions are remembered, the most recently heard kept. An entry is an id and two times. */
+const OFF_SESSIONS_MAX = 2_000;
+/** Whether an off session's last word was its `SessionEnd`. */
+function offSessionEnded(off) {
+    return off.endedAt !== undefined && off.at <= off.endedAt;
+}
+/** A `run_scenario` pre this recent is "the one being run right now" (see {@link ControlServer.takeDirectCall}). */
+const DIRECT_CALL_FRESH_MS = 30_000;
+/** How often the background recorder re-reads whether this project has a `bir` server. */
+const DELIVERY_TOOL_REFRESH_MS = 5 * 60_000;
+/**
+ * How long a `/scenario/hello` from a running `bir-scenario` counts as proof
+ * that the delivery tool is connected. It says hello on `initialize`, on
+ * `tools/list`, when its off state flips and every five minutes, so a live one
+ * is never near this; a process that died without a word is caught by its pid.
+ */
+const DELIVERY_HELLO_TTL_MS = 30 * 60_000;
+/** At most this many `bir-scenario` processes are remembered, newest kept. */
+const DELIVERY_HELLO_MAX = 256;
+/*
+ * `slowMs` is 2000: a healthy service answers the create-and-match in about
+ * 300-450 ms (a cold TLS connection adds ~250 ms), but a service that is only
+ * somewhat slow should keep replay on, so only an answer past 2 s counts as a
+ * degraded one, and waiting on it would add that much to every prompt.
+ * A false trip costs only replay for one hold, never latency.
+ */
+const DEFAULT_MATCH_GATE = {
+    slowMs: 2_000,
+    holdMs: 5 * 60_000,
+    maxHoldMs: 30 * 60_000,
+};
+/** Proxy ids that registered with this recorder, remembered for {@link ControlServer.onProxyPoll}. */
+const REGISTERED_PROXIES_MAX = 1_024;
+/**
+ * The two events Claude Code posts to `/tool/post`. Both accept the same
+ * `hookSpecificOutput` (`additionalContext`) — under their own name: the host
+ * rejects an answer whose `hookEventName` is not the event that fired.
+ */
+const POST_EVENTS = new Set(["PostToolUse", "PostToolUseFailure"]);
+/** How long "this server's proxy is alive" is believed before it is checked again. */
+const LIVE_PROXY_CACHE_MS = 2_000;
+/**
+ * How often a request carrying a token this recorder did not issue may look at
+ * the install sidecar for the project's *current* token (see
+ * {@link ControlServer.currentProjectToken}). The file is re-read only when
+ * its mtime or size changed, and stat'd at most this often.
+ */
+const SIDECAR_TOKEN_RECHECK_MS = 3_000;
+/**
+ * What a run's drain lets `recorder.flush` wait, by what sealed the run. No
+ * hook awaits a drain (see {@link ControlServer.closeRun}); these bound how long
+ * the recorder is asked to hold on for it, inside the hook budgets all the
+ * same, so a drain started on a hook path can never become that hook's wait.
+ * `close()` — `bir down`, an upgrade restart — may give it longer.
+ */
+const FLUSH_MS = {
+    /** `SessionEnd`: the host is exiting. */
+    sessionEnd: 800,
+    /** A new prompt sealing the turn before it (Esc), `Stop`, the reaper. */
+    hook: 1_000,
+    /** `close()`. */
+    close: 3_000,
+};
+const DEFAULT_SESSION_TIMINGS = {
+    // Long enough for one slow tool call — the host auto-backgrounds an MCP call
+    // after 2 minutes and Bash tops out at 10 — so a working turn is never
+    // mistaken for an abandoned one by an upgrade restart.
+    activeMs: 15 * 60_000,
+    idleSealMs: 2 * 60 * 60_000,
+    forgetMs: 6 * 60 * 60_000,
+    endedForgetMs: 10 * 60_000,
+    maxSessions: 500,
+    reapEveryMs: 60_000,
+};
+/** `/health` lists at most this many sessions, busiest first. */
+const HEALTH_SESSIONS_MAX = 50;
+/** What the model hears once a steer plan it had already left behind is retired. */
+const HANDBACK_NOTE = "[BaseInstRunner calculated replay] The recorded sequence is no longer being supplied: carry on with the task yourself, choosing each tool call's arguments from what you have seen so far.";
+/** What the model hears once a direct plan it never asked to run is retired. */
+const DIRECT_SKIPPED_NOTE = "[BaseInstRunner calculated replay] The recorded scenario is not being run for this request: carry on with the task yourself.";
+/** What a second `run_scenario` for a plan that is already running is told. */
+const ALREADY_RUNNING = "this scenario is already running for this turn — its results come back on the first run_scenario call; do not call it again or repeat its steps";
+/** Request bodies past this are read and discarded, never buffered. */
+const MAX_BODY_BYTES = 64 * 1024 * 1024;
+/** The one rejection {@link ControlServer.readJson} gives an over-size body. */
+class BodyTooLarge extends Error {
+    bytes;
+    constructor(bytes) {
+        super(`request body too large (${bytes} bytes)`);
+        this.bytes = bytes;
+    }
+}
+/**
+ * Whether `route` is one Claude Code posts hook events to. Those routes answer
+ * `200 {}` to anything they cannot or must not process — a stale token, an
+ * unknown event, an over-size body — because any other answer is shown to the
+ * user as a hook error. Every other route keeps strict HTTP answers.
+ */
+function isHookRoute(route) {
+    return route.startsWith("/session/") || route.startsWith("/tool/");
+}
+/** Plan mode: the user asked to see a plan first, so nothing is approved on their behalf. */
+function isPlanMode(payload) {
+    return payload.permission_mode === "plan";
+}
+/**
+ * Tool arguments as an older proxy reports them — redacted, long strings
+ * clipped — for joining a report that carries no `argsFingerprint` of its own.
+ */
+function reportedArgs(args) {
+    return truncateStrings(redact(args), DEFAULT_MAX_STRING_BYTES);
+}
+/**
+ * A score the service sent, for a log line: three decimals, or undefined when
+ * it is not a number. The answer is untyped JSON from another process — an
+ * older or newer service may leave a field out — and formatting it must never
+ * be what throws.
+ */
+function score(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value.toFixed(3) : undefined;
+}
+function positiveEnv(name, fallback) {
+    const n = Number(process.env[name]);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+/** A relayed flag that says yes: `true`, `1`, `"1"` or `"true"` (any case). */
+function isOn(value) {
+    if (value === true || value === 1)
+        return true;
+    return typeof value === "string" && ["1", "true"].includes(value.trim().toLowerCase());
+}
 /** One MCP call, as seen from up to two sides. */
 /**
  * Field separator for the probe's dedupe hash (segmented.md R-HIT-5). A NUL,
@@ -60,11 +270,113 @@ export class ControlServer {
     wrapped = new Set();
     /** serverName → registration facts, for `bir doctor`. */
     registrations = new Map();
+    /**
+     * serverName → every proxy pid that registered for it. A call id is carried
+     * only into a server one of these still serves: the proxy is what strips it,
+     * and a server unwrapped while this recorder ran must never receive it.
+     */
+    proxyPids = new Map();
+    /** serverName → the last answer of {@link hasLiveProxy}, briefly. */
+    liveProxyCache = new Map();
+    /**
+     * proxyId → the session its calls were joined to. Where a report no hook
+     * minted an id for is recorded — never "whichever session is first".
+     */
+    proxySessions = new Map();
+    /** `run_scenario` pres not yet consumed by a `/scenario/run`, oldest first. */
+    directCalls = [];
+    /** Plans a `/scenario/run` is executing right now: one run per plan. */
+    runningPlans = new Set();
+    /**
+     * Steer plans whose last pin the guard declined (control/pin-guard.ts): the
+     * model made the step's call its own way, so the plan is a step behind the
+     * model. See {@link abandonAfterDeclinedPin}.
+     */
+    declinedPins = new WeakSet();
+    /** Whether this project's `bir` server exists, from its MCP config (see {@link ControlServerOptions.deliveryTool}). */
+    deliveryFromConfig;
+    deliveryConfigStamp;
+    deliveryTimer;
+    /**
+     * A hook named an `mcp__bir__*` tool: the delivery tool is configured,
+     * whatever the config file said. Configured only — connected is what
+     * {@link scenarioHellos} proves.
+     */
+    birToolSeen = false;
+    /**
+     * `bir-scenario` pid → its last `/scenario/hello` (K3). The only evidence a
+     * direct plan's delivery tool is connected right now, rather than merely
+     * listed in a config file (see {@link deliveryToolAvailable}).
+     */
+    scenarioHellos = new Map();
+    /**
+     * Sessions started with `BIR_OFF=1` (K2), as the SessionStart ensure hook
+     * relays it, → when last heard, and when its `SessionEnd` came. Every hook
+     * of such a session is answered `{}` unprocessed, and its proxies' reports
+     * are dropped: the switch is the session's, and the long-lived recorder
+     * never inherits it. Kept for {@link OFF_SESSION_TTL_MS} of silence (not the
+     * ordinary `forgetMs`), or until a little after its `SessionEnd` — a resume
+     * fires SessionStart, which relays the switch again. Memory only: a
+     * recorder that restarts no longer knows the session is off until its next
+     * SessionStart.
+     */
+    offSessions = new Map();
+    /**
+     * Proxy ids that registered with *this* recorder (UPG-7). A poll from any
+     * other id is a proxy from before this recorder started — a 0.2.12 proxy
+     * never registers again — and is held rather than answered at once.
+     */
+    registeredProxies = new Map();
+    /** Releases for polls held with replay off (see {@link onProxyPoll}), for `close()`. */
+    heldPolls = new Set();
+    /**
+     * Direct plans whose `/scenario/run` caller went away mid-run (Esc). The
+     * turn was cut short by the user, so what it cost says nothing about the
+     * scenario: its report is sent unmeasured.
+     */
+    cancelledPlans = new WeakSet();
+    /** See {@link MatchGateTimings}. */
+    matchGateTimings;
+    /**
+     * The prompt match gate's state: until when prompts do not wait on the
+     * match, the hold that was last applied (doubles while slow), and when it
+     * was applied (a slow match that started before then says nothing new).
+     */
+    matchGate = { holdUntil: 0, holdMs: 0, since: 0 };
+    timings;
+    reaper;
     server;
     address;
     lossy = false;
-    /** Seals whose answer text is still being waited for. Awaited before any flush. */
-    pendingSeals = [];
+    /**
+     * The project's current token as the install sidecar last said, and the
+     * file stamp it was read at (see {@link currentProjectToken}).
+     */
+    sidecarToken;
+    /**
+     * Runs being drained to the service in the background, after a hook sealed
+     * them. Only `close()` waits for these, and only for so long.
+     */
+    drains = new Set();
+    /** Whether the service may be waited on right now (service-health.ts). */
+    service;
+    /**
+     * Hook requests answered `{}` without being processed, and why — surfaced on
+     * `/health`, because each is invisible to the user by design and `bir
+     * doctor` is where it has to be explained.
+     */
+    hookStats = {
+        /** A token this recorder did not issue: a reinstall while it ran. */
+        unauthorized: 0,
+        /** An event this recorder does not know: newer hooks, older recorder. */
+        unknownRoute: 0,
+        /** A body past {@link MAX_BODY_BYTES}. */
+        oversize: 0,
+        /** Answered by the deadline guard rather than by the route. */
+        overran: 0,
+        /** Answered at once because the runner is switched off. */
+        off: 0,
+    };
     /** Calculated replay. Inert unless `opts.replay.enabled`. */
     replay;
     /**
@@ -82,12 +394,19 @@ export class ControlServer {
     constructor(opts) {
         this.opts = opts;
         this.recorder = opts.recorder;
+        this.service = opts.serviceHealth ?? serviceHealth;
         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.deriveRecentResults = opts.deriveRecentResults ?? 5;
         this.intentSources = opts.intentSources ?? new Set(["text", "thinking", "tool"]);
+        this.timings = { ...DEFAULT_SESSION_TIMINGS, ...(opts.sessionTimings ?? {}) };
+        this.matchGateTimings = {
+            ...DEFAULT_MATCH_GATE,
+            slowMs: positiveEnv("BIR_MATCH_SLOW_MS", DEFAULT_MATCH_GATE.slowMs),
+            ...(opts.matchGate ?? {}),
+        };
         this.queue = new StepQueue({
             onDrop: (dropped) => {
                 // §10: drop oldest, flag the run lossy. The flag is louder than a
@@ -125,6 +444,7 @@ export class ControlServer {
                         token: this.token,
                         sessionId: this.sessionId,
                     };
+                    this.startHousekeeping();
                     resolve(this.address);
                 });
             };
@@ -132,14 +452,33 @@ export class ControlServer {
         });
     }
     async close() {
+        if (this.reaper)
+            clearInterval(this.reaper);
+        if (this.deliveryTimer)
+            clearInterval(this.deliveryTimer);
+        this.reaper = undefined;
+        this.deliveryTimer = undefined;
         // 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 release of [...this.heldPolls])
+            release();
+        this.heldPolls.clear();
         for (const session of this.sessions.values()) {
-            if (session.run && !session.run.finished)
-                await this.finalizeRun(session);
+            if (session.run && !session.run.finished) {
+                this.closeRun(session, { detach: false, flushMs: FLUSH_MS.close });
+            }
+        }
+        // Bounded: a recorder being stopped must stop, and a service that is down
+        // would otherwise hold it for as long as its sockets take to give up.
+        const drained = Promise.all([...this.drains]).then(() => this.queue.flush());
+        if ((await this.withinBudget(drained, CLOSE_DRAIN_MS)) === null && this.drains.size > 0) {
+            logLine("control.drain_abandoned", {
+                runs: this.drains.size,
+                ms: CLOSE_DRAIN_MS,
+                why: "the service did not take the last steps in time; they are lost with this process",
+            });
         }
-        await this.queue.flush();
         const server = this.server;
         if (!server)
             return;
@@ -148,13 +487,25 @@ export class ControlServer {
     }
     /** Facts for `bir doctor` / `GET /health`. */
     health() {
-        const sessions = [...this.sessions.values()].map((s) => ({
+        const now = Date.now();
+        // Busiest first, and bounded: `bir-hooks ensure` reads this on every
+        // SessionStart, and a recorder that has seen a thousand sessions must not
+        // answer with all of them. Every session still mid-turn is always listed —
+        // that is what `ensureDaemon` counts before it restarts anything.
+        const listed = [...this.sessions.values()]
+            .sort((a, b) => Number(this.isActive(b, now)) - Number(this.isActive(a, now)) || b.lastSeenAt - a.lastSeenAt)
+            .filter((s, i) => i < HEALTH_SESSIONS_MAX || this.isActive(s, now));
+        const sessions = listed.map((s) => ({
             sessionId: s.sessionId,
             runId: s.run?.runId,
             // Mid-run right now. What 'ensureDaemon' reads before it dares to restart
             // an out-of-date recorder: a restart between turns costs nothing, one
-            // during a turn loses the turn.
-            active: Boolean(s.run) && !s.run.finished,
+            // during a turn loses the turn. A run whose session has gone quiet for
+            // longer than any tool call takes is an interrupted turn nobody came
+            // back to, and must not hold an upgrade off forever.
+            active: this.isActive(s, now),
+            idleMs: now - s.lastSeenAt,
+            ended: s.endedAt !== undefined ? true : undefined,
             steps: s.run?.ordering.next ?? 0,
             recording: s.run?.recording ?? false,
             replay: s.run?.replay
@@ -165,7 +516,11 @@ export class ControlServer {
                     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,
+                    // Steering now: armed, and announced to the model. A plan an intent
+                    // match armed mid-call waits for its PostToolUse to be announced.
+                    armed: this.livePlan(s.run) !== undefined,
+                    unannounced: s.run.pendingDirective?.state === s.run.replay ? true : undefined,
+                    running: this.runningPlans.has(s.run.replay) ? true : undefined,
                     armedBy: s.run.replay.armedBy,
                     handover: s.run.replay.handover
                         ? { kind: s.run.replay.handover.kind, stepIndex: s.run.replay.handover.stepIndex }
@@ -186,6 +541,7 @@ export class ControlServer {
                 : null,
             fragment: s.run?.fragment ? { state: s.run.fragment.state } : null,
         }));
+        const sending = this.recorderBacklog();
         return {
             ok: true,
             recorder: "baseinstrunner",
@@ -231,17 +587,176 @@ export class ControlServer {
                         : "samples",
                 pollingProxies: this.replay.work.pollingServers(),
             },
-            lossy: this.lossy,
+            // Steps were lost: this queue overflowed, or the recorder dropped sends
+            // (its backlog bound, a signed-out session, a run the service never made).
+            lossy: this.lossy || (sending?.droppedSends ?? 0) > 0,
             queued: this.queue.size,
+            // The real backlog. This server's queue drains into the recorder at
+            // once; what has not reached the service yet waits there. Null when the
+            // recorder cannot say (no service, or an older recorder).
+            sending,
+            // Whether hot paths may wait on the service right now, and its last
+            // failure: the one place a user who noticed nothing can see that the
+            // runner stepped aside during an incident. Always present.
+            service: this.service.snapshot(),
+            // `bir off` in force for this project, and from where; null when on.
+            // Always present.
+            off: offSource(this.opts.cwd) ?? null,
+            // Hook requests answered `{}` unprocessed, by reason (see `hookStats`).
+            hooks: { ...this.hookStats },
+            // Which PreToolUse answers may carry a correlation id (see `correlation`),
+            // and whether a direct plan has a delivery tool to be announced through.
+            correlation: this.opts.noCorrelation ? "fingerprint" : this.correlationPolicy(),
+            deliveryTool: this.deliveryToolAvailable(),
+            // What that answer rests on: the bir-scenario processes that said hello
+            // and still run (K3). Empty means no direct plan is announced.
+            scenarioServers: this.liveHellos(now).slice(0, 10).map(([pid, h]) => ({
+                pid,
+                tools: h.tools,
+                off: h.off,
+                version: h.version ?? null,
+                ageMs: now - h.at,
+            })),
+            // Whether prompts are waiting on the match right now (the K5 gate).
+            matchGate: {
+                holding: now < this.matchGate.holdUntil,
+                holdMs: this.matchGate.holdMs || null,
+                until: now < this.matchGate.holdUntil ? this.matchGate.holdUntil : null,
+            },
+            // Sessions started with BIR_OFF=1, whose hooks are answered `{}` (K2).
+            offSessions: this.offSessions.size,
+            sessionCount: this.sessions.size,
             sessions,
         };
     }
+    /**
+     * What this recorder is doing right now, for the daemon deciding whether a
+     * superseded recorder may exit (K4). Cheap: no I/O beyond pid checks.
+     *
+     * `knownSessions` counts the sessions started with `BIR_OFF=1` that have not
+     * ended, too: only this recorder knows they are off, and a recorder that
+     * replaced it would record them.
+     */
+    activity() {
+        let openRuns = 0;
+        for (const session of this.sessions.values()) {
+            if (session.run && !session.run.finished)
+                openRuns += 1;
+        }
+        let offLive = 0;
+        for (const [sessionId, off] of this.offSessions) {
+            if (!offSessionEnded(off) && !this.sessions.has(sessionId))
+                offLive += 1;
+        }
+        const live = new Set();
+        for (const [serverName, pids] of this.proxyPids) {
+            for (const pid of [...pids]) {
+                if (live.has(pid))
+                    continue;
+                if (pidAlive(pid))
+                    live.add(pid);
+                else
+                    pids.delete(pid);
+            }
+            if (pids.size === 0)
+                this.proxyPids.delete(serverName);
+        }
+        return { openRuns, knownSessions: this.sessions.size + offLive, liveProxyPids: live.size };
+    }
+    /**
+     * The recorder's own sending state (record/recorder.ts `RecorderHealth`),
+     * for `/health`, or null when it has none to give. A recorder that swaps
+     * backends may answer nothing for one that has no service; and `/health`
+     * must answer whatever this throws.
+     */
+    recorderBacklog() {
+        try {
+            if (!isRecorderHealthReporter(this.recorder))
+                return null;
+            const h = this.recorder.recorderHealth();
+            if (!h || typeof h !== "object")
+                return null;
+            const count = (v) => (typeof v === "number" && Number.isFinite(v) && v > 0 ? v : 0);
+            return {
+                state: typeof h.state === "string" ? h.state : "unknown",
+                pendingSends: count(h.pendingSends),
+                pendingBytes: count(h.pendingBytes),
+                droppedSends: count(h.droppedSends),
+                failedSends: count(h.failedSends),
+            };
+        }
+        catch (err) {
+            logDetail("control.recorder_health_failed", { error: errText(err) });
+            return null;
+        }
+    }
     // ── HTTP plumbing ────────────────────────────────────────────────────────
+    /**
+     * Whether `header` carries a token this recorder accepts: the one it was
+     * started with, or — after a reinstall on the same port rewrote the hooks
+     * with a new one — the project's *current* token from the install sidecar.
+     * Without the second, every hook of every session answered `{}` unprocessed
+     * and nothing was recorded until the recorder happened to restart.
+     */
+    authorized(header) {
+        if (header === `Bearer ${this.token}`)
+            return true;
+        if (typeof header !== "string" || !header.startsWith("Bearer "))
+            return false;
+        const current = this.currentProjectToken();
+        if (!current || current === this.token || header !== `Bearer ${current}`)
+            return false;
+        logOnce(`control.token_current:${current.slice(0, 8)}`, "control.token_current", {
+            why: "a reinstall issued this project a new token — accepted, as the sidecar names it now",
+        });
+        return true;
+    }
+    /**
+     * This project's token as the install sidecar names it now. The sidecar is
+     * stat'd at most once per {@link SIDECAR_TOKEN_RECHECK_MS} and parsed only
+     * when its mtime or size changed, so a stale token on every hook costs a
+     * cached comparison. Never throws: an unreadable sidecar is "no token".
+     */
+    currentProjectToken() {
+        const now = Date.now();
+        const cached = this.sidecarToken;
+        if (cached && now - cached.checkedAt < SIDECAR_TOKEN_RECHECK_MS)
+            return cached.token;
+        let stamp = "-";
+        try {
+            const st = statSync(installedPath());
+            stamp = `${st.mtimeMs}:${st.size}`;
+        }
+        catch {
+            /* no sidecar: no current token */
+        }
+        if (cached && cached.stamp === stamp) {
+            cached.checkedAt = now;
+            return cached.token;
+        }
+        let token;
+        if (stamp !== "-") {
+            try {
+                const t = projectToken(readSidecar(), this.opts.cwd);
+                token = typeof t === "string" && t.length > 0 ? t : undefined;
+            }
+            catch {
+                token = undefined;
+            }
+        }
+        this.sidecarToken = { token, stamp, checkedAt: now };
+        return token;
+    }
     async handle(req, res) {
         const route = (req.url ?? "").split("?")[0];
+        if (isHookRoute(route)) {
+            await this.handleHook(route, req, res);
+            return;
+        }
         try {
             const auth = req.headers["authorization"];
-            if (auth !== `Bearer ${this.token}`) {
+            if (!this.authorized(auth)) {
+                req.resume();
                 this.send(res, 401, { error: "unauthorized" });
                 return;
             }
@@ -250,6 +765,7 @@ export class ControlServer {
                 return;
             }
             if (req.method !== "POST") {
+                req.resume();
                 this.send(res, 405, { error: "method_not_allowed" });
                 return;
             }
@@ -261,27 +777,6 @@ export class ControlServer {
                     if (this.opts.onStopRequested)
                         setImmediate(() => this.opts.onStopRequested?.());
                     return;
-                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;
@@ -309,12 +804,32 @@ export class ControlServer {
                 case "/proxy/result":
                     this.send(res, 200, this.onProxyResult(body));
                     return;
-                case "/scenario/run":
-                    this.send(res, 200, await this.onScenarioRun());
+                case "/scenario/run": {
+                    // Like a long poll, a run can outlive its caller: bir-scenario drops
+                    // the request when the host cancels the call or its timeout fires.
+                    // Tie that to an abort, so the plan stops starting new steps.
+                    const gone = new AbortController();
+                    const onClose = () => gone.abort();
+                    res.once("close", onClose);
+                    try {
+                        const answer = await this.onScenarioRun(body, gone.signal);
+                        if (gone.signal.aborted) {
+                            logLine("replay.run_abandoned", { why: "the caller went away; no further step was started" });
+                            return;
+                        }
+                        this.send(res, 200, answer);
+                    }
+                    finally {
+                        res.off("close", onClose);
+                    }
                     return;
+                }
                 case "/scenario/replay":
                     this.send(res, 200, await this.onScenarioReplay(body));
                     return;
+                case "/scenario/hello":
+                    this.send(res, 200, this.onScenarioHello(body));
+                    return;
                 default:
                     this.send(res, 404, { error: "not_found" });
                     return;
@@ -327,7 +842,314 @@ export class ControlServer {
             this.send(res, 200, {});
         }
     }
+    /**
+     * One Claude Code hook event. Always `200`, always inside the route's
+     * deadline, and never an error the user would see.
+     *
+     * Everything that is not a hook this recorder can process is answered `{}`
+     * without reading the payload: a token it did not issue and that is not the
+     * project's current one either (a reinstall's new token is accepted — see
+     * {@link authorized}), an event it does not know
+     * (settings from a newer `bir install`), a method that is not POST, a body
+     * past the size cap, and every hook while the runner is switched off. Each
+     * would otherwise be a "hook error" on every prompt and tool call until the
+     * recorder restarts, which the user can neither silence nor explain. They
+     * are counted on `/health` instead, where `bir doctor` reads them.
+     */
+    async handleHook(route, req, res) {
+        let answered = false;
+        /** The event that fired, once the payload is read: every answer is checked against it. */
+        let firing;
+        const answer = (body) => {
+            if (answered)
+                return;
+            answered = true;
+            this.send(res, 200, this.forEvent(route, firing, body));
+        };
+        const deadlineMs = this.deadlineFor(route);
+        if (!this.authorized(req.headers["authorization"])) {
+            this.hookStats.unauthorized += 1;
+            logOnce("control.hook_unauthorized", "control.hook_unauthorized", {
+                route,
+                why: "a hook carried a token this recorder neither issued nor finds in the install sidecar — answered {} unprocessed",
+                fix: "restart the recorder (bir down, then bir up) so it serves the installed hooks",
+            });
+            req.resume();
+            answer({});
+            return;
+        }
+        if (deadlineMs === undefined || req.method !== "POST") {
+            this.hookStats.unknownRoute += 1;
+            logOnce(`control.hook_unknown:${route}`, "control.hook_unknown", {
+                route,
+                method: req.method,
+                why: "not a hook this recorder serves — answered {} unprocessed; the hooks may be newer than the recorder",
+            });
+            req.resume();
+            answer({});
+            return;
+        }
+        // Off means inert, and inert means before the transcript, the queue or the
+        // service is touched. The recorder stays up only so that this answer is an
+        // instant `{}` rather than a refused connection.
+        if (offSource(this.opts.cwd)) {
+            this.hookStats.off += 1;
+            if (route === "/session/start") {
+                // Answered at once all the same. Its body is still read, after the
+                // answer: a session started with BIR_OFF=1 (K2) must stay off when
+                // `bir on` turns the rest back on.
+                answer({});
+                void this.readJson(req)
+                    .then((payload) => void this.sessionOff(route, payload))
+                    .catch(() => undefined);
+                return;
+            }
+            req.resume();
+            answer({});
+            return;
+        }
+        // What to answer if the route overruns. `{}` unless the route says better.
+        let late;
+        const timer = setTimeout(() => {
+            if (answered)
+                return;
+            this.hookStats.overran += 1;
+            let body = {};
+            try {
+                body = late?.() ?? {};
+            }
+            catch (err) {
+                logLine("control.route_failed", { route, error: errText(err) });
+            }
+            logLine("control.hook_deadline", {
+                route,
+                ms: deadlineMs,
+                why: "answered before the route finished, so the session is not held; the rest finishes in the background",
+            });
+            answer(body);
+        }, deadlineMs);
+        timer.unref?.();
+        try {
+            let payload;
+            try {
+                payload = (await this.readJson(req));
+            }
+            catch (err) {
+                if (err instanceof BodyTooLarge) {
+                    this.hookStats.oversize += 1;
+                    logLine("control.hook_oversize", {
+                        route,
+                        bytes: err.bytes,
+                        why: "read and discarded, answered {} — this event is not recorded",
+                    });
+                    answer({});
+                    return;
+                }
+                throw err;
+            }
+            // A hook the guard already answered while its body was still arriving is
+            // not processed: whatever it would decide can no longer reach the host.
+            if (answered)
+                return;
+            firing = typeof payload.hook_event_name === "string" ? payload.hook_event_name : undefined;
+            // A session started with BIR_OFF=1 (K2): inert, like `bir off`, but for
+            // this session only.
+            if (this.sessionOff(route, payload)) {
+                this.hookStats.off += 1;
+                answer({});
+                return;
+            }
+            const out = await this.dispatchHook(route, payload, (fn) => {
+                late = fn;
+            });
+            if (answered) {
+                logDetail("control.hook_late", { route, why: "finished after the deadline answer" });
+                return;
+            }
+            answer(out);
+        }
+        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) });
+            answer({});
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * `body` as the event that fired may carry it.
+     *
+     * CLAUDE CODE CHECKS THE NAME. An answer whose `hookSpecificOutput.hookEventName`
+     * is not the event that fired is rejected: the user is shown a hook error
+     * with this answer's JSON in it, and the context never reaches the model.
+     * `/tool/post` serves both `PostToolUse` and `PostToolUseFailure`, which take
+     * the same output, so that name is echoed. Any other mismatch would be a
+     * bug here, and the output is dropped rather than shown to the user as one.
+     * A payload that names no event (an older host, a test) is answered as is.
+     */
+    forEvent(route, firing, body) {
+        const out = body.hookSpecificOutput;
+        if (!firing || !out || typeof out !== "object")
+            return body;
+        const named = out.hookEventName;
+        if (named === firing)
+            return body;
+        if (POST_EVENTS.has(firing) && typeof named === "string" && POST_EVENTS.has(named)) {
+            return { ...body, hookSpecificOutput: { ...out, hookEventName: firing } };
+        }
+        logOnce(`control.hook_event_mismatch:${route}:${firing}`, "control.hook_event_mismatch", {
+            route,
+            fired: firing,
+            answered: typeof named === "string" ? named : undefined,
+            why: "an answer named another event than the one that fired — its output was dropped, since the host would show it as a hook error",
+        });
+        const rest = { ...body };
+        delete rest.hookSpecificOutput;
+        return rest;
+    }
+    /**
+     * Whether this hook belongs to a session started with `BIR_OFF=1` (K2), and
+     * so is answered `{}` unprocessed. The SessionStart ensure hook relays that
+     * as `bir_off: true` — the only way the long-lived recorder can learn it,
+     * since HTTP hooks carry no environment. A SessionStart for the same id
+     * without it (the session resumed from a shell without BIR_OFF) turns the
+     * session back on.
+     */
+    sessionOff(route, payload) {
+        const sessionId = typeof payload.session_id === "string" ? payload.session_id : undefined;
+        if (!sessionId)
+            return false;
+        if (route === "/session/start") {
+            if (isOn(payload.bir_off)) {
+                this.markSessionOff(sessionId);
+                return true;
+            }
+            if (this.offSessions.delete(sessionId)) {
+                logLine("session.on", { sess: sessionId, why: "resumed without BIR_OFF=1 — recorded again" });
+            }
+            return false;
+        }
+        const off = this.offSessions.get(sessionId);
+        if (!off)
+            return false;
+        const now = Date.now();
+        off.at = now;
+        if (route === "/session/end")
+            off.endedAt = now;
+        return true;
+    }
+    /** Mark `sessionId` off (see {@link sessionOff}), sealing whatever it had open. */
+    markSessionOff(sessionId) {
+        if (!this.offSessions.has(sessionId)) {
+            logLine("session.off", {
+                sess: sessionId,
+                why: "started with BIR_OFF=1 — its hooks are answered {} and nothing of it is recorded or replayed",
+            });
+        }
+        this.offSessions.set(sessionId, { at: Date.now() });
+        const session = this.sessions.get(sessionId);
+        if (session?.run && !session.run.finished)
+            this.closeRun(session, { detach: true });
+    }
+    /** Whether `sessionId` is a session started with `BIR_OFF=1`. */
+    isSessionOff(sessionId) {
+        return sessionId !== undefined && this.offSessions.has(sessionId);
+    }
+    /** The route's hook deadline, or undefined when `route` is not a hook this recorder serves. */
+    deadlineFor(route) {
+        const builtIn = HOOK_DEADLINE_MS[route];
+        if (builtIn === undefined)
+            return undefined;
+        const override = this.opts.hookDeadlinesMs?.[route];
+        return override !== undefined && override > 0 ? Math.min(override, builtIn) : builtIn;
+    }
+    /** What the prompt hook may spend on the match and arming: a second inside its deadline. */
+    promptWaitMs() {
+        return Math.max(0, Math.min(PROMPT_WAIT_MS, (this.deadlineFor("/session/prompt") ?? 0) - 1_000));
+    }
+    async dispatchHook(route, payload, onLate) {
+        switch (route) {
+            case "/session/start":
+                return this.onSessionStart(payload);
+            case "/session/prompt": {
+                // What a cancelled direct run left this session to tell (see
+                // `SessionState.stashedNote`). Claimed before the wait, so the
+                // deadline's answer carries it too.
+                const stashed = this.claimStashedNote(payload.session_id);
+                // The guard answering first means no directive went out: a plan that
+                // arms after that must never steer a model that was not told of it.
+                onLate(() => {
+                    const run = this.sessions.get(payload.session_id ?? "unknown-session")?.run;
+                    if (run) {
+                        run.matchExpired = true;
+                        run.awaitingDirective = false;
+                    }
+                    return stashed ? this.withContext({}, "UserPromptSubmit", stashed) : {};
+                });
+                const out = await this.onPrompt(payload);
+                return stashed ? this.withContext(out, "UserPromptSubmit", stashed) : out;
+            }
+            case "/tool/pre":
+                return await this.onToolPre(payload, onLate);
+            case "/tool/post":
+                return this.onToolPost(payload);
+            case "/session/agent":
+                return this.onAgent(payload);
+            case "/session/stop":
+                return this.onStop(payload);
+            case "/session/end":
+                return this.onSessionEnd(payload);
+            default:
+                return {};
+        }
+    }
+    /**
+     * `body` with `text` put in front of whatever `additionalContext` it
+     * already carries, under `event` — the event that fired.
+     */
+    withContext(body, event, text) {
+        const out = body.hookSpecificOutput;
+        const existing = typeof out?.additionalContext === "string" && out.additionalContext ? out.additionalContext : undefined;
+        return {
+            ...body,
+            hookSpecificOutput: {
+                ...(out ?? {}),
+                hookEventName: event,
+                additionalContext: existing ? `${text}\n\n${existing}` : text,
+            },
+        };
+    }
+    /**
+     * The note a cancelled direct run left `sessionId` (see
+     * `SessionState.stashedNote`), claimed for delivery — or undefined when
+     * there is none, or the run's own hooks already delivered it.
+     *
+     * With `forTool`, only when that tool is one of the cancelled plan's own:
+     * a call that could repeat a step that already ran (see {@link onToolPre}).
+     */
+    claimStashedNote(sessionId, forTool) {
+        const session = this.sessions.get(sessionId ?? "unknown-session");
+        const state = session?.stashedNote;
+        if (!session || !state)
+            return undefined;
+        if (forTool !== undefined && !state.plan?.usesTool(forTool))
+            return undefined;
+        session.stashedNote = undefined;
+        const note = this.replay.takeNote(state);
+        if (note) {
+            logLine("replay.note_delivered", {
+                sess: session.sessionId,
+                scenario: state.scenarioId ?? undefined,
+                why: "the steps a cancelled run already did, told to the model before it can repeat them",
+            });
+        }
+        return note;
+    }
     send(res, status, body) {
+        if (res.headersSent || res.writableEnded)
+            return;
         const text = JSON.stringify(body ?? {});
         res.writeHead(status, {
             "content-type": "application/json",
@@ -335,27 +1157,46 @@ export class ControlServer {
         });
         res.end(text);
     }
+    /**
+     * The request body as JSON. Past {@link MAX_BODY_BYTES} the rest is read and
+     * thrown away, then {@link BodyTooLarge} is rejected — the socket is never
+     * destroyed, because a reset is what a hook's caller would show as an error.
+     */
     readJson(req) {
         return new Promise((resolve, reject) => {
             const chunks = [];
             let bytes = 0;
+            let overflow = false;
             req.on("data", (chunk) => {
                 bytes += chunk.length;
-                if (bytes > 64 * 1024 * 1024) {
-                    reject(new Error("request body too large"));
-                    req.destroy();
+                if (overflow)
+                    return;
+                if (bytes > MAX_BODY_BYTES) {
+                    overflow = true;
+                    chunks.length = 0;
                     return;
                 }
                 chunks.push(chunk);
             });
             req.on("end", () => {
+                if (overflow) {
+                    reject(new BodyTooLarge(bytes));
+                    return;
+                }
                 const raw = Buffer.concat(chunks).toString("utf8");
                 if (!raw.trim()) {
                     resolve({});
                     return;
                 }
                 try {
-                    resolve(JSON.parse(raw));
+                    const value = JSON.parse(raw);
+                    // A payload is an object. `null`, a number or an array is as
+                    // malformed as a torn body, and is answered the same way.
+                    if (!value || typeof value !== "object" || Array.isArray(value)) {
+                        reject(new Error("request body is not a JSON object"));
+                        return;
+                    }
+                    resolve(value);
                 }
                 catch (err) {
                     reject(err instanceof Error ? err : new Error(String(err)));
@@ -369,19 +1210,138 @@ export class ControlServer {
         const sessionId = payload.session_id ?? "unknown-session";
         let session = this.sessions.get(sessionId);
         if (!session) {
-            session = { sessionId };
+            session = { sessionId, lastSeenAt: Date.now(), prompts: 0 };
             this.sessions.set(sessionId, session);
         }
+        session.lastSeenAt = Date.now();
         if (payload.transcript_path)
             session.transcriptPath = payload.transcript_path;
         if (payload.cwd)
             session.cwd = payload.cwd;
         return session;
     }
+    /**
+     * Whether `session` is mid-turn: an open run, heard from recently enough to
+     * be working rather than abandoned (see {@link SessionTimings.activeMs}).
+     */
+    isActive(session, now = Date.now()) {
+        const run = session.run;
+        if (!run || run.finished)
+            return false;
+        return now - session.lastSeenAt <= this.timings.activeMs;
+    }
+    /** Start the reaper and, for the background recorder, the delivery-tool refresh. Both unref'd. */
+    startHousekeeping() {
+        if (!this.reaper) {
+            this.reaper = setInterval(() => {
+                try {
+                    this.reap();
+                }
+                catch (err) {
+                    logLine("control.reap_failed", { error: errText(err) });
+                }
+            }, Math.max(10, this.timings.reapEveryMs));
+            this.reaper.unref?.();
+        }
+        if (this.opts.deliveryTool === undefined && process.env.BIR_DAEMON === "1" && !this.deliveryTimer) {
+            // Read once now, then again only when the files changed — and never on
+            // a hook's path: ~/.claude.json is often megabytes and the host rewrites
+            // it constantly.
+            this.refreshDeliveryTool();
+            this.deliveryTimer = setInterval(() => this.refreshDeliveryTool(), DELIVERY_TOOL_REFRESH_MS);
+            this.deliveryTimer.unref?.();
+        }
+    }
+    /**
+     * Forget what a long-lived recorder no longer needs, and stop an abandoned
+     * turn from looking like a live one.
+     *
+     * A turn interrupted with Esc gets no `Stop`, and a window closed after it
+     * often gets no `SessionEnd` either: its run stayed open for the recorder's
+     * whole life — counted `active`, so an upgrade never restarted the
+     * recorder; first in line for another session's proxy steps; and holding
+     * its plan and outputs in memory. And every `/clear` and every `claude -p`
+     * added a session that was never removed. So:
+     *
+     *  - an open run silent for {@link SessionTimings.idleSealMs} is sealed —
+     *    idleness, never age: one long tool call sends no hooks;
+     *  - a session with no open run is forgotten once it has been silent for
+     *    {@link SessionTimings.forgetMs}, or {@link SessionTimings.endedForgetMs}
+     *    after its `SessionEnd`;
+     *  - past {@link SessionTimings.maxSessions}, the least recently heard
+     *    sessions without an open run go first.
+     */
+    reap(now = Date.now()) {
+        const t = this.timings;
+        for (const session of [...this.sessions.values()]) {
+            const run = session.run;
+            if (run && !run.finished && now - session.lastSeenAt >= t.idleSealMs) {
+                logLine("run.idle_sealed", {
+                    run: run.runId,
+                    sess: session.sessionId,
+                    idleMin: Math.round((now - session.lastSeenAt) / 60_000),
+                    why: "no hook for this session in a long time — the turn was interrupted and never resumed",
+                });
+                this.closeRun(session, { detach: false });
+            }
+            if (session.run && !session.run.finished)
+                continue;
+            const ended = session.endedAt !== undefined &&
+                session.lastSeenAt <= session.endedAt &&
+                now - session.endedAt >= t.endedForgetMs;
+            if (ended || now - session.lastSeenAt >= t.forgetMs)
+                this.forgetSession(session);
+        }
+        if (this.sessions.size > t.maxSessions) {
+            const idle = [...this.sessions.values()]
+                .filter((s) => !s.run || s.run.finished)
+                .sort((a, b) => a.lastSeenAt - b.lastSeenAt);
+            for (const session of idle) {
+                if (this.sessions.size <= t.maxSessions)
+                    break;
+                this.forgetSession(session);
+            }
+        }
+        this.directCalls = this.directCalls.filter((c) => now - c.at < DIRECT_CALL_TTL_MS);
+        // A BIR_OFF=1 session is NOT forgotten on `forgetMs`: coming back to one
+        // left idle overnight fires no SessionStart, so nothing would say it is
+        // off again. It goes a while after its SessionEnd (a resume relays the
+        // switch again), after days of silence, or past the count cap.
+        for (const [sessionId, off] of this.offSessions) {
+            const ended = offSessionEnded(off) && now - off.endedAt >= t.endedForgetMs;
+            if (ended || now - off.at >= OFF_SESSION_TTL_MS)
+                this.offSessions.delete(sessionId);
+        }
+        if (this.offSessions.size > OFF_SESSIONS_MAX) {
+            const oldest = [...this.offSessions].sort((a, b) => a[1].at - b[1].at);
+            for (const [sessionId] of oldest.slice(0, this.offSessions.size - OFF_SESSIONS_MAX)) {
+                this.offSessions.delete(sessionId);
+            }
+        }
+        for (const [pid, hello] of this.scenarioHellos) {
+            if (now - hello.at > DELIVERY_HELLO_TTL_MS || !pidAlive(pid))
+                this.scenarioHellos.delete(pid);
+        }
+    }
+    /** Drop a session and everything keyed on it. Its last run was sealed and drained already. */
+    forgetSession(session) {
+        this.sessions.delete(session.sessionId);
+        this.replay.work.releaseSession(session.sessionId);
+        this.directCalls = this.directCalls.filter((c) => c.sessionId !== session.sessionId);
+        for (const [proxyId, sessionId] of this.proxySessions) {
+            if (sessionId === session.sessionId)
+                this.proxySessions.delete(proxyId);
+        }
+        logDetail("session.forgotten", { sess: session.sessionId });
+    }
     /** Open a run for `session`, or return the open one. */
     ensureRun(session, input = "") {
         if (session.run && !session.run.finished)
             return session.run;
+        // The sealed run stays reachable for a moment: a report or a post that
+        // arrives just after its turn ended is that turn's, not this one's.
+        if (session.run)
+            session.previous = session.run;
         const runId = this.recorder.startRun(input, this.runMetadata(session));
         const run = {
             runId,
@@ -427,7 +1387,10 @@ export class ControlServer {
     }
     /**
      * 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.
+     * post would 404. Stop recording it — that half is v1 and is mandatory, and
+     * it is applied whenever the answer lands, however late: a hit that arrived
+     * after the prompt's budget used to leave recording on, and every step of the
+     * turn then failed against a run that did not exist.
      *
      * 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
@@ -441,37 +1404,465 @@ export class ControlServer {
             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(async (match) => {
-            if (!match)
-                return undefined;
+        const runId = run.runId;
+        const startedAt = Date.now();
+        const pending = this.recorder.getMatch(runId).catch(() => null);
+        void pending.then((match) => {
+            if (!match || run.runId !== runId)
+                return;
             run.recording = false;
             logLine("run.matched", {
-                run: run.runId,
+                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",
             });
-            // Awaited: a scenario with a target derives before the directive goes
-            // out, so a plan that cannot find its target is never delivered
-            // (segmented.md R-PARAM-4). Inside `UserPromptSubmit`'s 15 s.
-            const state = await this.replay.arm(match, prompt || run.input, this.wrapped, "prompt", {
-                recentResults: recentToolResults(session.transcriptPath, this.deriveRecentResults),
+        });
+        run.matchWatch = this.armFromMatch(session, run, pending, prompt, startedAt).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;
+    }
+    /**
+     * The v2 half of {@link watchForMatch}: wait for the match — briefly, and not
+     * at all while the service is failing — and arm what it found.
+     *
+     * Both waits are bounded by {@link promptWaitMs} from the start of the
+     * match. A match that misses its budget, or a plan still deriving when the
+     * budget runs out, is never delivered: the turn runs as an ordinary one, and
+     * one `replay.decision` line says why (docs/calculatedReplay.md §10).
+     */
+    async armFromMatch(session, run, pending, prompt, startedAt) {
+        if (!this.replay.enabled)
+            return this.noteDisabledMatch(session, run, pending, prompt);
+        const promptWaitMs = this.promptWaitMs();
+        const matchBudget = Math.min(this.replay.budgets.matchMs, promptWaitMs);
+        if (Date.now() < this.matchGate.holdUntil) {
+            // THE MATCH GATE (K5). A service that answers, but slowly, never opens
+            // the breaker for long — each late answer closes it again — so without
+            // this every prompt would wait the whole match for as long as the
+            // incident lasts. The match is still asked (a hit still stops the
+            // recording, v1); it is only not waited for, and a plan it would arm
+            // now could never be announced.
+            logDetail("replay.decision", {
+                verdict: "no-steer",
+                code: "match_slow",
+                run: run.runId,
+                why: "the service has been answering matches slowly — not waited on; this turn runs normally",
+            });
+            void pending.then((late) => {
+                if (!late)
+                    return;
+                logLine("replay.decision", {
+                    verdict: "no-steer",
+                    code: "match_late",
+                    run: run.runId,
+                    scenario: late.scenarioId ?? undefined,
+                    ms: Date.now() - startedAt,
+                    why: "the match landed while prompts were not waiting on it — not steered, and not recorded",
+                });
             });
-            state.sessionId = session.sessionId;
-            run.replay = state;
-            run.replays.push(state);
-            return this.replay.directiveFor(state);
+            return undefined;
+        }
+        const cooling = !this.service.canWait();
+        const match = await awaitWithin(pending, matchBudget, "match", this.service);
+        // Measured only when it was waited on: a match not asked for says nothing
+        // about how fast the service is. Nor does an answer that came quickly
+        // because the service failed (a run-create whose first attempt failed
+        // answers "no match" at once, and opens the cool-down): that is not the
+        // service answering fast, and must not end a hold.
+        if (!cooling && matchBudget > 0 && (match === undefined || this.service.canWait())) {
+            this.noteMatchLatency(match === undefined ? undefined : Date.now() - startedAt, startedAt);
+        }
+        if (match === undefined) {
+            if (this.replay.enabled) {
+                logLine("replay.decision", {
+                    verdict: "no-steer",
+                    code: cooling ? "service_unhealthy" : "match_timeout",
+                    run: run.runId,
+                    ms: cooling ? undefined : matchBudget,
+                    why: cooling
+                        ? "the service is failing — not waited on; this turn runs normally"
+                        : "the match did not answer inside its budget; this turn runs normally",
+                });
+                void pending.then((late) => {
+                    if (!late)
+                        return;
+                    logLine("replay.decision", {
+                        verdict: "no-steer",
+                        code: "match_late",
+                        run: run.runId,
+                        scenario: late.scenarioId ?? undefined,
+                        ms: Date.now() - startedAt,
+                        why: "the match landed after the prompt was answered — not steered, and not recorded",
+                    });
+                });
+            }
+            return undefined;
+        }
+        if (!match)
+            return undefined;
+        // Awaited: a scenario with a target derives before the directive goes
+        // out, so a plan that cannot find its target is never delivered
+        // (segmented.md R-PARAM-4). Inside the prompt's own budget.
+        const arming = this.armOrLog(run, this.replay.arm(match, prompt || run.input, this.wrapped, "prompt", {
+            recentResults: recentToolResults(session.transcriptPath, this.deriveRecentResults),
+        }));
+        const remaining = Math.max(0, promptWaitMs - (Date.now() - startedAt));
+        const state = await this.withinBudget(arming, remaining);
+        if (state === undefined)
+            return undefined; // it threw, and said so
+        // Armed live only while the prompt hook is still waiting to announce it.
+        // `onPrompt` stops waiting at its own budget (and the deadline guard at
+        // the route's), so a plan that lands after that — or for a run a proxy
+        // step opened, with no prompt hook to announce anything — was never told
+        // to the model and must never steer or diverge a call.
+        if (state === null || run.matchExpired || run.finished || !run.awaitingDirective) {
+            if (this.replay.enabled) {
+                const ready = state !== null;
+                logLine("replay.decision", {
+                    verdict: "no-steer",
+                    code: ready ? "arm_unannounced" : "arm_timeout",
+                    run: run.runId,
+                    scenario: match.scenarioId ?? undefined,
+                    ms: Date.now() - startedAt,
+                    why: ready
+                        ? "the plan armed after the prompt had been answered without it — retired unannounced, so never run"
+                        : "the plan was not ready before the prompt had to be answered — never delivered, so never run",
+                });
+            }
+            if (state) {
+                this.shelve(session, run, state);
+            }
+            else {
+                void arming.then((late) => {
+                    if (late)
+                        this.shelve(session, run, late);
+                });
+            }
+            return undefined;
+        }
+        state.sessionId = session.sessionId;
+        this.declineWithoutDeliveryTool(state);
+        // A steer plan with a shell or file-write step can only be followed if the
+        // directive shows its computed arguments (the pin guard holds those steps
+        // to their exact shape), so give its parameters a moment to settle —
+        // inside what is left of this prompt's budget, keeping room for the
+        // preview itself. It returns at once for any other plan, or while the
+        // service is cooling down.
+        const settleMs = promptWaitMs - (Date.now() - startedAt) - PREVIEW_RESERVE_MS;
+        if (state.plan && settleMs > 0)
+            await this.replay.settleForPreview(state, settleMs);
+        // The argument preview runs logic; it spends what is left of the prompt's
+        // own budget, never time on top of it (under 10 ms left, none is shown).
+        const previewMs = Math.max(0, promptWaitMs - (Date.now() - startedAt));
+        const directive = state.plan ? this.replay.directiveFor(state, { previewMs }) : undefined;
+        if (state.plan && !directive) {
+            // A plan with nothing to announce is a plan the model is never told of.
+            logLine("replay.decision", {
+                verdict: "no-steer",
+                code: "no_directive",
+                run: run.runId,
+                scenario: state.scenarioId ?? undefined,
+                why: "the plan produced no directive to announce — retired unannounced, so never run",
+            });
+            this.shelve(session, run, state);
+            return undefined;
+        }
+        run.replay = state;
+        run.replays.push(state);
+        return directive;
+    }
+    /**
+     * The match gate's verdict on one waited match: `ms` it took to answer, or
+     * undefined when it did not answer inside its budget. Slow opens a hold —
+     * {@link MatchGateTimings.holdMs}, doubled on each slow match that follows a
+     * hold, up to {@link MatchGateTimings.maxHoldMs}; fast ends it. Each
+     * transition is one line; the prompts in between say nothing at line level.
+     *
+     * A slow match that `startedAt` before the current hold began is ignored:
+     * prompts already waiting when the service turned slow are one slowness,
+     * not several, so the hold doubles at most once per hold (on its probe).
+     */
+    noteMatchLatency(ms, startedAt) {
+        const t = this.matchGateTimings;
+        const gate = this.matchGate;
+        const slow = ms === undefined || ms > t.slowMs;
+        if (slow) {
+            if (gate.holdMs > 0 && startedAt < gate.since)
+                return;
+            const holdMs = gate.holdMs > 0 ? Math.min(t.maxHoldMs, gate.holdMs * 2) : Math.min(t.maxHoldMs, t.holdMs);
+            const now = Date.now();
+            gate.holdMs = holdMs;
+            gate.holdUntil = now + holdMs;
+            gate.since = now;
+            logLine("replay.match_gate", {
+                state: "holding",
+                matchMs: ms ?? "timeout",
+                slowMs: t.slowMs,
+                holdMs,
+                why: "the similar-prompt match answered slowly — prompts stop waiting on it for a while (it is still asked, in the background)",
+            });
+            return;
+        }
+        if (gate.holdMs === 0)
+            return;
+        gate.holdMs = 0;
+        gate.holdUntil = 0;
+        gate.since = 0;
+        logLine("replay.match_gate", {
+            state: "open",
+            matchMs: ms,
+            why: "the match answered fast again — prompts wait on it as before",
+        });
+    }
+    /**
+     * {@link armFromMatch} with replay off: nothing can be announced, and no hook
+     * waits for the answer (`onPrompt` has already returned). So there is no
+     * budget and no `awaitWithin` — a slow create-run here is not a wait anyone
+     * had, and must not mark the service slow (that would open the process-wide
+     * cool-down, and `/health` would report a degradation the user never had).
+     * A hit still books its decline — the ledger's baseline sample — whenever
+     * it lands, as long as the turn is still open to carry it.
+     */
+    async noteDisabledMatch(session, run, pending, prompt) {
+        const match = await pending;
+        if (!match || run.finished)
+            return undefined;
+        // Declined at its first gate, before derivation: no transcript is read for it.
+        const state = await this.armOrLog(run, this.replay.arm(match, prompt || run.input, this.wrapped, "prompt"));
+        if (!state || run.finished || run.replays.includes(state))
+            return undefined;
+        if (state.plan) {
+            // Never, with replay off — but a plan nobody announced must not steer
+            // whatever the controller decided.
+            this.shelve(session, run, state);
+            return undefined;
+        }
+        state.sessionId = session.sessionId;
+        run.replay = state;
+        run.replays.push(state);
+        return undefined;
+    }
+    /**
+     * A `direct` plan is announced as "call mcp__bir__run_scenario". In a project
+     * with no `bir` server that is a tool the model does not have: it would say
+     * so, or reach for its own tools — and that first call would diverge and run
+     * the scenario unattended, in a project that never installed replay's
+     * delivery tool. Such a plan is declined here, before it is announced, and
+     * the agent does the task (a baseline sample, as any decline).
+     *
+     * Returns true when it declined.
+     */
+    declineWithoutDeliveryTool(state) {
+        if (!state.plan || state.mode !== "direct" || this.deliveryToolAvailable())
+            return false;
+        const configured = this.deliveryConfigured();
+        logLine("replay.decision", {
+            verdict: "no-steer",
+            code: "no_delivery_tool",
+            scenario: state.scenarioId ?? undefined,
+            why: configured
+                ? "a direct plan is delivered through mcp__bir__run_scenario, and no running bir server has said it serves that tool — the agent does this task"
+                : "a direct plan is delivered through mcp__bir__run_scenario, and this project has no bir server — the agent does this task",
+            fix: configured
+                ? "check the bir server in /mcp (connected, not disabled) and that the session was not started with BIR_OFF=1"
+                : "bir install --replay adds the bir server to this project",
+        });
+        state.plan = undefined;
+        state.mode = "none";
+        state.stepsPlanned = 0;
+        state.pinned.clear();
+        state.declined = "coverage";
+        return true;
+    }
+    /**
+     * Whether the tool a direct plan is delivered through is connected here
+     * right now. See {@link ControlServerOptions.deliveryTool}: the caller's
+     * boolean when it gave one; otherwise the configuration must not say there
+     * is none, and a `bir-scenario` must have proved it serves the tool.
+     */
+    deliveryToolAvailable() {
+        const opt = this.opts.deliveryTool;
+        if (typeof opt === "boolean")
+            return opt;
+        if (!this.deliveryConfigured())
+            return false;
+        return this.liveHellos(Date.now()).some(([, h]) => h.tools >= 1 && !h.off);
+    }
+    /**
+     * Whether this project's configuration has the `bir` server, as far as
+     * anything here knows: a hook that named one of its tools, the caller's
+     * answer, the file the background recorder reads. Unknown means yes — the
+     * live evidence decides.
+     */
+    deliveryConfigured() {
+        if (this.birToolSeen)
+            return true;
+        const opt = this.opts.deliveryTool;
+        if (typeof opt === "boolean")
+            return opt;
+        if (typeof opt === "function") {
+            try {
+                const answer = opt();
+                if (typeof answer === "boolean")
+                    return answer;
+            }
+            catch (err) {
+                logDetail("replay.delivery_tool_unknown", { error: errText(err) });
+            }
+        }
+        return this.deliveryFromConfig ?? true;
+    }
+    /**
+     * The `bir-scenario` processes whose hello is recent and whose pid still
+     * runs, newest first. A dead or stale one is forgotten here. Pid checks
+     * only — no other I/O.
+     */
+    liveHellos(now) {
+        const out = [];
+        for (const [pid, hello] of this.scenarioHellos) {
+            if (now - hello.at > DELIVERY_HELLO_TTL_MS || !pidAlive(pid)) {
+                this.scenarioHellos.delete(pid);
+                continue;
+            }
+            out.push([pid, hello]);
+        }
+        return out.sort((a, b) => b[1].at - a[1].at);
+    }
+    /**
+     * `POST /scenario/hello` — a running `bir-scenario` saying what it serves
+     * (K3): on `initialize`, on `tools/list`, when its off state flips and every
+     * few minutes. It is the only proof that a direct plan's delivery tool is
+     * connected, so a direct plan is announced only while one that lists a tool
+     * and is not off still runs. Always `{ ok: true }`; never slow.
+     */
+    onScenarioHello(body) {
+        const pid = Number(body.pid);
+        if (!Number.isInteger(pid) || pid <= 0)
+            return { ok: true };
+        const toolsRaw = Number(body.tools);
+        const tools = Number.isFinite(toolsRaw) && toolsRaw > 0 ? Math.floor(toolsRaw) : 0;
+        const off = body.off === true;
+        const version = typeof body.version === "string" ? body.version.slice(0, 40) : undefined;
+        const before = this.scenarioHellos.get(pid);
+        // Re-inserted, so the map's order is oldest hello first.
+        this.scenarioHellos.delete(pid);
+        this.scenarioHellos.set(pid, { at: Date.now(), tools, off, version });
+        while (this.scenarioHellos.size > DELIVERY_HELLO_MAX) {
+            const oldest = this.scenarioHellos.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.scenarioHellos.delete(oldest);
+        }
+        const serves = tools >= 1 && !off;
+        if (!before || (before.tools >= 1 && !before.off) !== serves) {
+            logLine("replay.delivery_tool", {
+                pid,
+                tools,
+                off: off || undefined,
+                version,
+                why: serves
+                    ? "a bir server is running and serves run_scenario: direct plans may be announced"
+                    : "a bir server is running but serves no tool (off, or none listed): it cannot deliver a direct plan",
+            });
+        }
+        return { ok: true };
+    }
+    /**
+     * Re-read whether this project configures the `bir` server — only when
+     * ~/.claude.json or .mcp.json changed since the last read. A file the host is
+     * halfway through rewriting keeps the previous answer.
+     */
+    refreshDeliveryTool() {
+        const files = [claudeJsonPath(), join(this.opts.cwd, ".mcp.json")];
+        const stamp = files
+            .map((f) => {
+            try {
+                const st = statSync(f);
+                return `${st.mtimeMs}:${st.size}`;
+            }
+            catch {
+                return "-";
+            }
         })
-            .catch((err) => {
+            .join("|");
+        if (stamp === this.deliveryConfigStamp)
+            return;
+        try {
+            const found = resolveServers(this.opts.cwd).some((s) => s.name === SCENARIO_SERVER_KEY && isScenarioServer(s.config));
+            this.deliveryConfigStamp = stamp;
+            if (found !== this.deliveryFromConfig) {
+                logLine("replay.delivery_tool", {
+                    present: found,
+                    why: found
+                        ? "this project has the bir server: direct plans may be announced while it runs"
+                        : "this project has no bir server: a direct plan is declined rather than announced",
+                });
+            }
+            this.deliveryFromConfig = found;
+        }
+        catch (err) {
+            logDetail("replay.delivery_tool_unread", { error: errText(err) });
+        }
+    }
+    /** `arming`, never rejecting: a broken arm is logged and is no plan at all. */
+    armOrLog(run, arming) {
+        return arming.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;
+    }
+    /**
+     * The prompt hook answered without a directive: retire any prompt-armed plan
+     * of `run` that could still steer. `armFromMatch` arms one live only while
+     * that hook waits, so this finds nothing in the ordinary course; it is what
+     * keeps a directive-less plan from ever running as a later divergence, even
+     * if an arm and the hook's answer cross.
+     */
+    retireUnannounced(session, run) {
+        const states = run.replay && !run.replays.includes(run.replay) ? [...run.replays, run.replay] : run.replays;
+        for (const state of [...states]) {
+            if (state.armedBy !== "prompt" || !state.plan || state.retired)
+                continue;
+            logLine("replay.decision", {
+                verdict: "no-steer",
+                code: "arm_unannounced",
+                run: run.runId,
+                scenario: state.scenarioId ?? undefined,
+                why: "the prompt was answered without this plan's directive — retired unannounced, so never run",
+            });
+            this.shelve(session, run, state);
+        }
+    }
+    /**
+     * A prompt plan that armed after its hook had answered. The model was never
+     * told of it, so it must never steer or diverge a call: it is kept only as
+     * what it now is — a matched turn the agent does itself, which still owes the
+     * ledger its baseline sample (§11.1) — exactly like a declined match.
+     */
+    shelve(session, run, late) {
+        if (late.plan && !late.retired) {
+            logDetail("replay.shelved", {
+                run: run.runId,
+                scenario: late.scenarioId ?? undefined,
+                why: "armed without its directive reaching the model — retired, never steers",
+            });
+        }
+        late.sessionId = session.sessionId;
+        late.plan = undefined;
+        late.mode = "none";
+        late.stepsPlanned = 0;
+        late.retired = true;
+        late.pinned.clear();
+        if (run.finished || run.replays.includes(late))
+            return;
+        run.replays.push(late);
+        run.replay ??= late;
     }
     /**
      * Close the run's books, without waiting for the network.
@@ -497,6 +1888,14 @@ export class ControlServer {
             if (correlation.threadFallback)
                 clearTimeout(correlation.threadFallback);
         }
+        // A plan whose directive never reached the model did nothing and was never
+        // a choice the model made: it books nothing, like any unannounced plan.
+        const unannounced = run.pendingDirective?.state;
+        run.pendingDirective = undefined;
+        if (unannounced)
+            this.shelveUnannounced(unannounced);
+        // A `run_scenario` still waiting for this run's plan will never get it.
+        this.directCalls = this.directCalls.filter((c) => c.run !== run);
         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
@@ -515,11 +1914,17 @@ export class ControlServer {
             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)
+            // first step of the user's next turn by that much. Kept on the run, so a
+            // drain of this run waits for this seal and for nobody else's.
+            run.sealing = settledLastAssistantText(transcriptPath)
                 .catch(() => "")
                 .then((answer) => {
+                run.finishQueued = true;
                 this.queue.push(() => {
+                    // A similar-prompt hit that landed during the wait: the service
+                    // kept its own run, and this one does not exist to finish.
+                    if (!run.recording)
+                        return;
                     if (answer) {
                         this.recorder.recordFinalAnswer(run.runId, run.ordering.allocate(), { answer });
                     }
@@ -533,7 +1938,7 @@ export class ControlServer {
                         costUsd: recordedCost.measured ? recordedCost.usd : undefined,
                     });
                 });
-            }));
+            });
         }
         logLine("run.finish", {
             run: run.runId,
@@ -619,7 +2024,9 @@ export class ControlServer {
             }
             const report = this.replay.buildReport(state, {
                 sessionCostUsd: windowCost.usd,
-                measured: windowCost.measured,
+                // A direct run the user cancelled cut its turn short: its cost is no
+                // baseline, and no saving is measured against it.
+                measured: windowCost.measured && !this.cancelledPlans.has(state),
                 durationMs: Math.max(0, windowMs),
                 prompt: run.input || undefined,
                 siblings: states,
@@ -637,21 +2044,75 @@ export class ControlServer {
             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;
+    /**
+     * Seal the session's run now, and drain it to the service in the background.
+     *
+     * NO HOOK EVER WAITS FOR THE NETWORK TO CLOSE A RUN. The prompt after an
+     * interrupted turn (Claude Code sends no `Stop` on Esc) and `SessionEnd`
+     * used to await the whole drain — the seal's answer wait, the queue, and
+     * every send still in flight for the run — so an Esc followed by a new prompt
+     * cost 0.5-2 s on a healthy service and the full hook timeout on a hung one,
+     * and `/clear` or exit waited up to 30 s. The daemon outlives the hook, so
+     * the drain simply finishes after it: sealing is synchronous and already
+     * queues the final answer, the finish and the execution report.
+     *
+     * `detach` also forgets the run on the session — but only if it is still
+     * the run that was sealed, never one another hook opened meanwhile.
+     */
+    closeRun(session, opts) {
+        const run = session.run;
+        if (!run)
+            return;
         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);
+        if (opts.detach && session.run === run) {
+            session.run = undefined;
+            session.previous = run;
+        }
+        this.drainInBackground(run, opts.flushMs ?? FLUSH_MS.hook);
+    }
+    /**
+     * Start {@link drainRun} for `run`, tracked so `close()` can wait for it.
+     * Each entry leaves {@link drains} the moment its drain settles, so the set
+     * holds the drains still running — never one per turn the recorder has seen.
+     */
+    drainInBackground(run, flushMs) {
+        const drain = this.drainRun(run, flushMs);
+        this.drains.add(drain);
+        void drain.finally(() => this.drains.delete(drain));
+    }
+    /**
+     * Everything queued for `run` reaches the service, or fails trying. Never
+     * rejects. The seal resolves its answer text off-queue, so it is awaited
+     * before the queue is flushed — otherwise the flush would finish before the
+     * finish call had even been enqueued.
+     */
+    async drainRun(run, flushMs) {
+        try {
+            await run.sealing;
+            await this.queue.flush();
+            // Bounded, so an outage cannot pin every sealed turn in memory until the
+            // service returns; the recorder keeps sending on its own either way.
+            // `timeoutMs` bounds how long the recorder waits for the sends, never
+            // whether they happen; DRAIN_MAX_MS is the backstop for a recorder that
+            // does not honour it.
+            // A fragment swapped the run id mid-turn; the turn's first id still holds
+            // its match (a whole scenario payload) in the recorder, and is forgotten
+            // with it.
+            const ids = run.turnId !== run.runId ? [run.runId, run.turnId] : [run.runId];
+            const flushed = await this.withinBudget(Promise.all(ids.map((id) => this.recorder.flush(id, { timeoutMs: flushMs }))).then(() => true), DRAIN_MAX_MS);
+            if (flushed === null) {
+                logDetail("run.drain_abandoned", { run: run.runId, ms: DRAIN_MAX_MS });
+            }
+        }
+        catch (err) {
+            logDetail("run.drain_failed", { run: run.runId, error: errText(err) });
+        }
     }
     // ── hook events ──────────────────────────────────────────────────────────
     onSessionStart(payload) {
         const session = this.ensureSession(payload);
+        // A resumed session is a live one again, whatever its SessionEnd said.
+        session.endedAt = undefined;
         // Run creation is deferred to the first prompt so the service's
         // similar-prompt detection sees the real prompt, not "".
         logLine("session.start", {
@@ -668,9 +2129,10 @@ export class ControlServer {
         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;
+            // → Stop is the only honest run boundary. The previous turn was
+            // interrupted — Stop does not fire on Esc — so it is sealed here, and its
+            // drain runs behind this prompt rather than in front of it.
+            this.closeRun(session, { detach: true });
         }
         else if (open && open.ordering.next === 0) {
             // A run was opened early by a proxy step (the host spawned MCP servers
@@ -678,14 +2140,30 @@ export class ControlServer {
             // 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;
+            this.closeRun(session, { detach: true });
+        }
+        else if (open && session.prompts > 0) {
+            // A run a stray hook opened after this session's last turn had ended — a
+            // background task's late PostToolUse, a proxy report after Stop. Its
+            // steps are not this prompt's, and keeping them would record this whole
+            // turn under an empty input that never matches anything, and never ask
+            // the service about this prompt at all. Sealed as what it is; this
+            // prompt gets a run, and a match, of its own.
+            logLine("run.stray_sealed", {
+                run: open.runId,
+                steps: open.ordering.next,
+                why: "steps arrived between turns; kept apart from the new prompt's run",
+            });
+            this.closeRun(session, { detach: true });
         }
         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;
+            // This hook announces nothing, so no plan of this run may steer.
+            open.matchExpired = true;
+            this.retireUnannounced(session, open);
             logLine("run.prompt_late", {
                 run: open.runId,
                 steps: open.ordering.next,
@@ -696,14 +2174,44 @@ export class ControlServer {
         const run = this.ensureRun(session, input);
         run.promptSeen = true;
         run.input = input;
+        session.prompts += 1;
         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(session, run, input);
-        if (!directive)
+        // With replay off there is nothing this hook could say, so it says nothing
+        // at once: the match still stops recording on a hit (v1), in the
+        // background, and no prompt waits on the service for it.
+        const watch = this.watchForMatch(session, run, input);
+        if (!this.replay.enabled)
             return {};
+        // Plan mode is the user asking to see a plan before anything runs. A
+        // replay would run tools, auto-approved: nothing is announced, and a plan
+        // that arms anyway is shelved unannounced (see `armFromMatch`).
+        if (isPlanMode(payload)) {
+            run.matchExpired = true;
+            return {};
+        }
+        // The one moment a directive can be injected. Bounded by the match and
+        // arming budgets — and not waited on at all while the service is failing —
+        // 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.
+        //
+        // `awaitingDirective` is what lets a plan arm live (see `armFromMatch`):
+        // set before the wait, cleared the moment it ends either way, so a plan
+        // that lands a tick after this hook gave up is retired, never armed.
+        run.awaitingDirective = true;
+        let directive;
+        try {
+            directive = await this.withinBudget(watch, this.promptWaitMs() + 250);
+        }
+        finally {
+            run.awaitingDirective = false;
+        }
+        if (!directive) {
+            // Whatever arms after this answer was never announced: it must not steer.
+            run.matchExpired = true;
+            this.retireUnannounced(session, run);
+            return {};
+        }
         return {
             hookSpecificOutput: {
                 hookEventName: "UserPromptSubmit",
@@ -714,19 +2222,29 @@ export class ControlServer {
     /**
      * `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.
+     *  - **Wrapped MCP tool** → remember the call 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. The join
+     *    is by fingerprint, and the hook answers with **no decision**: the user's
+     *    permission prompt for the tool is exactly what it would be without the
+     *    runner. A call id rides in `updatedInput` only where answering `allow`
+     *    changes nothing, or the operator opted in (see `injectionDecision`).
      *  - **Anything else** (built-ins, unwrapped MCP) → allocate the pair now and
      *    record `tool_selected`. The hook is this step's only observer.
+     *
+     * `onLate` tells the route's deadline guard what to answer if this call is
+     * still running when the deadline passes — see {@link replayOverran}.
      */
-    async onToolPre(payload) {
+    async onToolPre(payload, onLate) {
         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 ?? {};
+        const planning = isPlanMode(payload);
+        // A hook naming one of the `bir` server's tools proves the server exists.
+        if (toolName.startsWith(`mcp__${SCENARIO_SERVER_KEY}__`))
+            this.birToolSeen = true;
         // 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
@@ -742,14 +2260,61 @@ export class ControlServer {
             logDetail("tool.pre.skipped", { run: run.runId, tool: toolName, why: "host housekeeping" });
             return {};
         }
-        // `run_scenario` with no live plan does nothing but answer "no scenario is
-        // armed". Recorded, that answer is a failed tool call, and a recording with
-        // one is never picked for calculation — observed in production on every
-        // first run in a project with the scenario server installed. With a live
-        // plan it is still recorded below, tagged `pinnedBy`.
-        if (this.replay.isDirectTool(toolName) && (!run.replay?.plan || run.replay.retired)) {
-            logDetail("tool.pre.skipped", { run: run.runId, tool: toolName, why: "no scenario armed" });
-            return {};
+        // What a cancelled direct run left this session to tell (see
+        // `SessionState.stashedNote`), when it was stashed after the next prompt
+        // had already gone by: a call of one of that plan's own tools could
+        // repeat a step that already ran, so the note reaches the model in its
+        // place — as the same-turn path delivers a hand-over. Any other call runs,
+        // and its PostToolUse carries the note. Never in plan mode.
+        if (!planning) {
+            const stashed = this.claimStashedNote(session.sessionId, toolName);
+            if (stashed)
+                return this.preToolAnswer(this.replay.deliverInstead(stashed, toolName)) ?? {};
+        }
+        const live = this.livePlan(run);
+        /** `run_scenario` for this session's own announced direct plan: allowed, see below. */
+        let allowDirect = false;
+        if (this.replay.isDirectTool(toolName)) {
+            // `run_scenario` with no live plan does nothing but answer "no scenario
+            // is armed". Recorded, that answer is a failed tool call, and a recording
+            // with one is never picked for calculation — observed in production on
+            // every first run in a project with the scenario server installed. A plan
+            // the model was never told of is no plan for it either. With a live plan
+            // it is still recorded below, tagged `pinnedBy`.
+            if (!live) {
+                logDetail("tool.pre.skipped", { run: run.runId, tool: toolName, why: "no scenario armed" });
+                return {};
+            }
+            // Which session is about to ask `/scenario/run` for its plan. bir-scenario
+            // cannot say — a stdio MCP server is never told its session — so this is
+            // how its request finds the plan of the session that called it rather
+            // than whichever plan was armed first.
+            this.directCalls.push({ sessionId: session.sessionId, toolUseId, at: Date.now(), run, state: live });
+            // The runner announced this call and asked for exactly it: it must not
+            // arrive as a permission prompt for a tool the user never asked for (and
+            // be denied outright under `-p`). Only for a direct plan — the one kind
+            // `run_scenario` exists to deliver — never in plan mode, and never for a
+            // plan already running. The user's own deny or ask rules still apply.
+            allowDirect = live.mode === "direct" && !planning && !this.runningPlans.has(live);
+        }
+        else if (live?.mode === "direct" && !this.runningPlans.has(live) && this.hasDirectCall(live)) {
+            // The model called `run_scenario`, and the run never came: the call was
+            // refused (the user said no, or a rule denied it) or it failed on the way.
+            // Refused means refused. The plan retires without running anything — it
+            // must not come back as a divergence that runs every step unattended.
+            this.vetoPlan(run, live, "run_scenario was called but never reached the runner — refused or failed");
+        }
+        else if (live?.mode === "direct" && !live.directRequested && !live.running && !this.runningPlans.has(live)) {
+            // A direct plan whose first call is not `run_scenario`, and which never
+            // asked for it. The likeliest reason is that the model has no such tool
+            // — the bir server failed to start, was disabled in /mcp, or lists
+            // nothing — and a divergence would then execute every step, writes
+            // included, inside this hook with no permission prompt, and deny the
+            // model's call: a broken delivery tool turned into an unattended run.
+            // The plan retires running nothing; this call runs as written, and the
+            // model hears on its PostToolUse that the task is its own.
+            this.vetoPlan(run, live, `the model's first call was ${toolName}, not run_scenario`);
+            run.handback = DIRECT_SKIPPED_NOTE;
         }
         const agentId = payload.agent_id ?? session.agentId;
         // The real intent, read from every line sharing this message's id
@@ -765,35 +2330,137 @@ export class ControlServer {
         const thinkingIntent = intent?.source === "thinking" ? { text: intent.text, source: "thinking" } : undefined;
         // ── replay steering (docs/calculatedReplay.md §7) ────────────────────────
         // Runs before anything else, because two of its four answers end the call.
+        // Not in plan mode (nothing is approved on the user's behalf there), not
+        // while `/scenario/run` is executing this very plan (a second execution of
+        // it would repeat its steps), and not before its directive has reached the
+        // model (see `RunState.pendingDirective`).
         let pinned;
-        if (run.replay?.plan && !run.replay.retired) {
-            const action = await this.replay.preTool(run.replay, toolName, toolUseId, modelArgs);
-            // A hand-over inside `preTool` (an input logic that threw) must still
-            // schedule the fragment, even though this call ends here.
-            this.noteHandover(run);
-            if (action.kind === "pin")
-                pinned = action.input;
-            const answer = this.preToolAnswer(action);
-            if (answer)
-                return answer;
+        /** The deadline guard answered this call already; see below. */
+        let overran = false;
+        const declinedEarlier = this.livePlan(run);
+        if (declinedEarlier && !planning && !this.runningPlans.has(declinedEarlier)) {
+            this.abandonAfterDeclinedPin(run, declinedEarlier, toolName);
         }
-        if (!pinned && (!run.replay?.plan || run.replay.retired)) {
+        const steering = this.livePlan(run);
+        /** Whether the deadline guard already has this call's late answer (and sets `overran`). */
+        let lateSet = false;
+        if (steering && !planning && !this.runningPlans.has(steering)) {
+            let lateNote = false;
+            lateSet = true;
+            // The controller's own ceiling on replay work in this hook
+            // (BIR_PRETOOL_REPLAY_BUDGET_MS) is already held under this route's
+            // deadline. What it cannot know is when the guard has answered first:
+            // from then on the model has been told to carry on, so no further step
+            // may start beside its own work.
+            const answeredLate = new AbortController();
+            onLate?.(() => {
+                overran = true;
+                answeredLate.abort();
+                const body = this.replayOverran(steering, toolName);
+                lateNote = Object.keys(body).length > 0;
+                return body;
+            });
+            const action = await this.replay.preTool(steering, toolName, toolUseId, modelArgs, {
+                signal: answeredLate.signal,
+            });
+            if (overran) {
+                // The host already has its answer. A divergence was answered with its
+                // note, and that call did not run as written: nothing to record.
+                if (lateNote)
+                    return {};
+                // Otherwise it was answered `{}` and ran as the model wrote it. A pin
+                // decided now never reached it, so the plan would be threading an
+                // output its step did not produce: it stops here, and the call is
+                // recorded below as the model's own.
+                if (!steering.retired) {
+                    steering.pinned.clear();
+                    steering.retired = true;
+                    logLine("replay.pin_overran", {
+                        scenario: steering.scenarioId ?? undefined,
+                        tool: toolName,
+                        why: "the plan was not ready before the call had to go ahead — it steers nothing more this turn",
+                    });
+                }
+            }
+            else {
+                // A hand-over inside `preTool` (an input logic that threw) must still
+                // schedule the fragment, even though this call ends here.
+                this.noteHandover(run);
+                if (action.kind === "pin") {
+                    // The same tool is not the same call. A pin swaps the model's
+                    // arguments for the step's and approves them, so it is kept only for
+                    // a call that is plausibly the step (control/pin-guard.ts); anything
+                    // else runs exactly as the model wrote it, and the plan stays armed
+                    // for the call that is.
+                    const verdict = pinCompatible(toolName, modelArgs, action.input);
+                    if (verdict.ok) {
+                        pinned = action.input;
+                        this.declinedPins.delete(steering);
+                    }
+                    else {
+                        steering.pinned.delete(toolUseId);
+                        this.declinedPins.add(steering);
+                        logLine("replay.pin_declined", {
+                            scenario: steering.scenarioId ?? undefined,
+                            tool: toolName,
+                            step: action.stepIndex,
+                            why: `not the step — ${verdict.why}; it runs as the model wrote it, and the plan stays armed for the call that is`,
+                        });
+                    }
+                }
+                else {
+                    const answer = this.preToolAnswer(action);
+                    if (answer)
+                        return answer;
+                }
+            }
+        }
+        // Past the deadline nothing new may start: a probe answered now could arm
+        // a plan nobody would ever hear of.
+        if (!overran && !pinned && (!run.replay?.plan || run.replay.retired)) {
             // ── falling back to the model (fallbk.md) ──────────────────────────────
             // 1. A hand-over noticed where no hook answer could carry it — a proxy
             //    report threaded after its PostToolUse had already answered — reaches
             //    the model in place of this call. Never silence (D4).
-            const note = this.replay.takeNote(run.replay);
+            const note = planning ? undefined : this.replay.takeNote(run.replay);
             if (note) {
                 this.noteHandover(run);
                 return this.preToolAnswer(this.replay.deliverInstead(note, toolName));
             }
             // 2. The model is driving: look for a scenario by this iteration's intent.
-            const armed = await this.tryIntentMatch(session, run, toolName, intent, modelArgs);
-            if (armed)
-                return armed;
+            //    Never in plan mode, where nothing may run on the user's behalf.
+            //    If the deadline answers first, it answers `{}`: the call runs as
+            //    written, and a plan armed in its place was never announced.
+            if (!planning && !lateSet) {
+                onLate?.(() => {
+                    overran = true;
+                    return {};
+                });
+            }
+            const armed = planning
+                ? undefined
+                : await this.tryIntentMatch(session, run, toolName, intent, modelArgs);
+            if (armed) {
+                if (!overran)
+                    return armed;
+                const late = run.replay;
+                if (late && late.armedBy === "intent" && late.plan && !late.retired) {
+                    logLine("replay.decision", {
+                        verdict: "no-steer",
+                        code: "arm_unannounced",
+                        run: run.runId,
+                        scenario: late.scenarioId ?? undefined,
+                        why: "the call had to go ahead before this plan's directive could replace it — retired unannounced, so never run",
+                    });
+                    this.shelveUnannounced(late);
+                }
+                // The call ran as the model wrote it: recorded below as its own.
+            }
             // 3. No scenario took over: the model's own work after a hand-over is
             //    recorded as a fragment, starting with this call.
-            if (run.fragment?.state === "due") {
+            // Not for the call an intent match just armed a plan beside: the plan
+            //    runs next, and the fragment opens on the model's own work after it.
+            if (run.fragment?.state === "due" && !run.pendingDirective) {
                 await this.openFragment(session, run, reasoning, toolName, modelArgs);
             }
         }
@@ -803,6 +2470,7 @@ export class ControlServer {
         const args = pinned ?? modelArgs;
         const mcp = parseQualifiedName(toolName);
         if (mcp && this.wrapped.has(mcp.serverName)) {
+            const decision = this.injectionDecision(payload, pinned !== undefined, mcp.serverName, session);
             const correlation = {
                 callId: newCallId(),
                 toolUseId,
@@ -813,7 +2481,12 @@ export class ControlServer {
                 context: context || undefined,
                 createdAt: Date.now(),
                 settled: false,
+                // Raw, as the proxy hashes its report's `argsFingerprint`: hashing the
+                // redacted, clipped copy instead missed every call whose arguments
+                // redaction or clipping changed, and recorded it twice.
                 fingerprint: fingerprint(mcp.serverName, mcp.toolName, args),
+                reportedFingerprint: fingerprint(mcp.serverName, mcp.toolName, reportedArgs(args)),
+                injected: decision !== undefined,
                 // Captured here because this is the last moment the code knows: by the
                 // time `settle` records the step, `postTool` has consumed the pin
                 // (segmented.md R-INTENT-7).
@@ -825,14 +2498,14 @@ export class ControlServer {
                 run: run.runId,
                 tool: toolName,
                 callId: correlation.callId,
-                mode: this.opts.noCorrelation ? "fingerprint" : "injected",
+                mode: decision ? "injected" : "fingerprint",
                 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 (!decision) {
+                // No id ride-along: 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 {
@@ -852,8 +2525,8 @@ export class ControlServer {
                     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 },
+                    permissionDecision: decision,
+                    updatedInput: { ...args, [BIR_CALL_ID]: correlation.callId },
                 },
             };
         }
@@ -894,8 +2567,168 @@ export class ControlServer {
                 },
             };
         }
+        if (allowDirect) {
+            return {
+                stepIndex: pair.selected,
+                hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow" },
+            };
+        }
         return { stepIndex: pair.selected };
     }
+    /** This run's plan, when it is armed, still live, and announced to the model. */
+    livePlan(run) {
+        const state = run.replay;
+        if (!state?.plan || state.retired)
+            return undefined;
+        if (run.pendingDirective?.state === state)
+            return undefined;
+        return state;
+    }
+    /** Whether a `run_scenario` pre for `state` is still waiting for its `/scenario/run`. */
+    hasDirectCall(state) {
+        const now = Date.now();
+        return this.directCalls.some((c) => c.state === state && now - c.at < DIRECT_CALL_TTL_MS);
+    }
+    /**
+     * Retire `state` without running anything: the model's `run_scenario` was
+     * refused or failed. Books a baseline sample (`not_steered`) — the agent did
+     * the task — never a divergence.
+     */
+    vetoPlan(run, state, why) {
+        if (state.retired)
+            return;
+        state.retired = true;
+        state.retiredAt = Date.now();
+        state.pinned.clear();
+        this.directCalls = this.directCalls.filter((c) => c.state !== state);
+        logLine("replay.vetoed", {
+            run: run.runId,
+            scenario: state.scenarioId ?? undefined,
+            why: `${why} — the plan is retired without running any step`,
+        });
+    }
+    /**
+     * A steer plan whose pin the guard declined, now facing a call to another
+     * tool: retire it, running nothing, and let this call run as written.
+     *
+     * The declined call was the model doing the step its own way (told that the
+     * system supplies the arguments, it often writes a guess), so the model has
+     * moved on while the plan still waits at that step. Left armed, this call to
+     * the *next* step's tool reads as a divergence: the model's call is denied,
+     * the rest of the scenario runs unattended inside this hook, and the step it
+     * already did comes back as a stale recorded output. Retiring here costs
+     * only the rest of this replay; the model is told on the next PostToolUse
+     * that the arguments are its own from now on. A call to the step's own tool
+     * keeps the plan armed — that may be the step at last.
+     */
+    abandonAfterDeclinedPin(run, state, toolName) {
+        if (!this.declinedPins.has(state) || state.mode !== "steer" || state.retired)
+            return;
+        if (this.replay.isDirectTool(toolName) || state.plan?.expectedTool() === toolName)
+            return;
+        this.declinedPins.delete(state);
+        state.retired = true;
+        state.retiredAt = Date.now();
+        state.pinned.clear();
+        run.handback = HANDBACK_NOTE;
+        logLine("replay.pin_abandoned", {
+            run: run.runId,
+            scenario: state.scenarioId ?? undefined,
+            expected: state.plan?.expectedTool() ?? undefined,
+            tool: toolName,
+            why: "the model did the expected step its own way and moved on — the plan is retired without running anything, and this call runs as written",
+        });
+    }
+    /** An intent plan whose directive never reached the model: it did nothing, and reports nothing. */
+    shelveUnannounced(state) {
+        state.plan = undefined;
+        state.mode = "none";
+        state.stepsPlanned = 0;
+        state.retired = true;
+        state.pinned.clear();
+        state.reported = true;
+        logDetail("replay.unannounced", {
+            scenario: state.scenarioId ?? undefined,
+            why: "the turn ended before the directive reached the model — never steered, never reported",
+        });
+    }
+    /**
+     * How `PreToolUse` should answer while carrying a call id for `serverName`,
+     * or undefined to carry none (the report then joins by fingerprint).
+     *
+     * THE RUNNER MUST NOT CHANGE WHAT THE USER IS ASKED. Answering `allow` skips
+     * the permission prompt for the call, so an id rides along — with `allow` —
+     * only where that changes nothing: a replay-pinned step (replay is its own
+     * consent, and its `updatedInput` must be applied), or a session in
+     * `bypassPermissions` mode, where nothing prompts anyway. Otherwise only an
+     * operator's explicit `BIR_CORRELATION_DECISION` (see
+     * {@link ControlServerOptions.correlation}). Never in `plan` mode, and never
+     * into a server with no live proxy to strip the id — an upstream reached
+     * directly would receive an argument it never declared.
+     */
+    injectionDecision(payload, pinned, serverName, session) {
+        if (this.opts.noCorrelation || isPlanMode(payload))
+            return undefined;
+        if (!this.hasLiveProxy(serverName))
+            return undefined;
+        // A registered proxy for this server is alive — but this session's calls
+        // to it went through something that never echoed an id (see
+        // `SessionState.noInjection`), so the id is not sent again.
+        if (session?.noInjection?.has(serverName))
+            return undefined;
+        if (pinned || payload.permission_mode === "bypassPermissions")
+            return "allow";
+        const policy = this.correlationPolicy();
+        return policy === "auto" ? undefined : policy;
+    }
+    /** See {@link ControlServerOptions.correlation}. */
+    correlationPolicy() {
+        if (this.opts.correlation)
+            return this.opts.correlation;
+        const env = (process.env.BIR_CORRELATION_DECISION ?? "").trim().toLowerCase();
+        if (env === "allow" || env === "ask" || env === "auto")
+            return env;
+        return this.opts.correlationDecision === "ask" ? "ask" : "auto";
+    }
+    /**
+     * Whether a proxy that registered for `serverName` is still running. Only a
+     * live proxy strips a call id before the upstream sees it; a server the user
+     * unwrapped while this recorder ran stays in {@link wrapped} forever, and
+     * must never receive one. Cached for a moment — this is on every wrapped call.
+     */
+    hasLiveProxy(serverName) {
+        const now = Date.now();
+        const cached = this.liveProxyCache.get(serverName);
+        if (cached && now - cached.at < LIVE_PROXY_CACHE_MS)
+            return cached.live;
+        const pids = this.proxyPids.get(serverName);
+        let live = false;
+        for (const pid of [...(pids ?? [])]) {
+            if (pidAlive(pid)) {
+                live = true;
+                break;
+            }
+            pids?.delete(pid);
+        }
+        this.liveProxyCache.set(serverName, { live, at: now });
+        return live;
+    }
+    /**
+     * Remember `pid` as a proxy serving `serverName` on this recorder — from its
+     * registration or its poll, the two requests that carry one. Only these make
+     * {@link hasLiveProxy} true: a proxy started under `bir off` is a pure pipe
+     * that sends neither, and must never be sent a call id it cannot strip.
+     */
+    noteProxyPid(serverName, pid) {
+        if (!serverName || !Number.isInteger(pid) || pid <= 0)
+            return;
+        const pids = this.proxyPids.get(serverName) ?? new Set();
+        if (pids.has(pid))
+            return;
+        pids.add(pid);
+        this.proxyPids.set(serverName, pids);
+        this.liveProxyCache.delete(serverName);
+    }
     /** A controller decision as a `PreToolUse` answer, or undefined to carry on. */
     preToolAnswer(action) {
         switch (action.kind) {
@@ -919,6 +2752,42 @@ export class ControlServer {
                 return undefined;
         }
     }
+    /**
+     * What `PreToolUse` answers when a steering plan is still working as the
+     * route's deadline passes.
+     *
+     * The one case that matters is a divergence: the plan retires, then runs
+     * its remaining steps for real inside this hook (§8), and a slow tool or a
+     * slow source-run fetch can take that past the host's timeout. Answering
+     * `{}` would let the model's own call run and leave it believing nothing
+     * happened, while the scenario's steps — writes included — keep landing
+     * behind its back, and it would then do them all again. So the call is
+     * answered with the truth instead: which steps are done, that the rest may
+     * still be running, and that the task is the model's from here.
+     *
+     * Before the divergence starts (the plan still armed) nothing has run, and
+     * `{}` is the honest answer.
+     */
+    replayOverran(state, toolName) {
+        if (!state.retired)
+            return {};
+        const done = [...state.stepResults.values()]
+            .filter((s) => s.status === "ok")
+            .map((s) => s.toolName || "a step");
+        logLine("replay.diverge_overran", {
+            scenario: state.scenarioId ?? undefined,
+            done: done.length,
+            why: "the recorded steps were still running at the hook's deadline — handed to the model",
+        });
+        const note = [
+            "A recorded run of this task was re-running its remaining steps for you and did not finish in time.",
+            done.length > 0
+                ? `Already done: ${done.join(", ")}.`
+                : "None of its steps had finished yet.",
+            "Some of the rest may still complete in the background, so check the current state before repeating any step, then carry on with the task yourself.",
+        ].join(" ");
+        return this.preToolAnswer(this.replay.deliverInstead(note, toolName)) ?? {};
+    }
     /**
      * Recordings this turn must not count a step hit against (segmented.md
      * R-HIT-7).
@@ -1003,6 +2872,14 @@ export class ControlServer {
      * builds an intent from the tool name and arguments, and a step the agent took
      * without narrating it is exactly as much a recurrence as one it explained.
      * Every failure is a miss.
+     *
+     * THE PROBE IS NOT WAITED ON unless it may arm ({@link intentArming}). Hit
+     * counting needs no answer at all, and waiting for one put a service round
+     * trip — 70-450 ms healthy, the whole 4 s budget on a hung service — in front
+     * of every Read, Grep, Edit and Bash of every signed-in user. When it may arm,
+     * the wait is {@link intentArmBudgetMs} at most, and none while the service is
+     * failing. Delivering a match on a *later* call instead is not an option: the
+     * matched call has run by then, and the plan's first step would repeat it.
      */
     async tryIntentMatch(session, run, toolName, intent, modelArgs) {
         const opts = this.replay.intentMatch;
@@ -1028,9 +2905,17 @@ export class ControlServer {
             .digest("hex");
         if (probeHash === run.intent.lastProbeHash)
             return undefined;
-        run.intent.lastProbeHash = probeHash;
         if (run.intent.requests >= opts.maxRequestsPerTurn)
             return undefined;
+        // A service in its cool-down is not asked at all. The probe would only add
+        // a socket to an outage, and the hits it counts are lost with it anyway.
+        // Neither the hash nor the cap is spent, so the same call probes again once
+        // the service answers.
+        if (!this.service.canWait()) {
+            logDetail("replay.intent_skipped", { run: run.runId, tool: toolName, why: "service unhealthy" });
+            return undefined;
+        }
+        run.intent.lastProbeHash = probeHash;
         run.intent.requests += 1;
         // Every scenario armed this turn, so a continuation cannot re-arm the plan
         // that just handed over.
@@ -1038,7 +2923,8 @@ export class ControlServer {
             .map((s) => s.scenarioId)
             .filter((id) => typeof id === "string");
         const startedAt = Date.now();
-        const answer = await this.withinBudget(this.recorder.matchIntent({
+        const probe = this.recorder
+            .matchIntent({
             text,
             source,
             // The same value twice: `currentToolName` is what today's server reads,
@@ -1053,49 +2939,33 @@ export class ControlServer {
             ranThrough: this.ranThroughFor(run),
             ...(this.replay.segmentArm ? { acceptSegments: true } : {}),
             supportsCalls: true,
-        }), opts.budgetMs);
-        if (!answer) {
-            logDetail("replay.intent_miss", { run: run.runId, tool: toolName });
+        }, 
+        // The probe's own budget (`BIR_INTENT_MATCH_BUDGET_MS`) ends the request
+        // itself — waited on or not — so an abandoned probe releases its socket
+        // rather than holding it for as long as the service takes to answer.
+        { timeoutMs: opts.budgetMs })
+            .catch(() => null);
+        if (!this.intentArming()) {
+            // Counted, never waited on: whatever the answer says is bookkeeping.
+            void probe.then((late) => {
+                if (late)
+                    this.noteProbe(run, toolName, source, late, startedAt, "not waited on — counting only");
+            });
             return undefined;
         }
-        if (answer.stepHit) {
-            run.intent.lastStepHit = { ...answer.stepHit, at: Date.now() };
-        }
-        // What *would* have armed, had segments been armed (segmented.md R-OUT-10).
-        // Logged at line level, not detail: this is the whole observe-only period,
-        // and the decision to turn arming on is made by reading these. The turn
-        // then carries on with whatever else the answer holds (R-OUT-15).
-        if (answer.segmentWouldArm) {
-            const w = answer.segmentWouldArm;
-            logLine("replay.segment_would_arm", {
-                scenario: w.scenarioId,
-                run: w.runId,
-                key: w.key,
-                similarity: w.similarity.toFixed(3),
-                band: w.band,
-                verified: w.verified
-                    ? w.verified.verdict === "skipped"
-                        ? `skipped:${w.verified.reason}`
-                        : `${w.verified.verdict}: ${w.verified.reason}`
-                    : undefined,
-                tool: w.tool ?? toolName,
-                firstTool: w.firstTool,
-                stepFrom: w.stepFrom,
-                stepTo: w.stepTo,
-                hitCount: w.hitCount,
+        const answer = await this.withinBudget(probe, this.intentArmBudgetMs());
+        if (!answer) {
+            logDetail("replay.intent_miss", { run: run.runId, tool: toolName });
+            // A miss, or too slow to arm here. A late answer's hit still counts
+            // where health shows it; a miss resolves null and notes nothing.
+            void probe.then((late) => {
+                if (late)
+                    this.noteProbe(run, toolName, source, late, startedAt, "answered after the call went ahead");
             });
+            return undefined;
         }
+        this.noteProbe(run, toolName, source, answer, startedAt);
         const match = answer.matched;
-        logDetail("replay.intent_probe", {
-            run: run.runId,
-            tool: toolName,
-            source,
-            stepHit: answer.stepHit ? `${answer.stepHit.runId}:${answer.stepHit.stepIndex}` : "none",
-            bestStepSimilarity: answer.bestStepSimilarity,
-            elapsedMs: Date.now() - startedAt,
-            matched: match?.scenarioId ?? "none",
-            kind: match?.kind,
-        });
         if (!match)
             return undefined;
         if (match.scenarioId && exclude.includes(match.scenarioId))
@@ -1108,16 +2978,43 @@ export class ControlServer {
             logLine("replay.intent_arm_capped", {
                 scenario: match.scenarioId ?? undefined,
                 kind: match.kind ?? "scenario",
-                similarity: match.similarity.toFixed(3),
+                similarity: score(match.similarity),
                 tool: toolName,
             });
             return undefined;
         }
-        const state = await this.replay.arm(match, text, this.wrapped, "intent", {
+        // Bounded like the probe: derivation for a scenario with a target can take
+        // seconds, and this call is waiting. A plan not armed in time is dropped
+        // unused — it was never announced, so it never steers — and its ticket is
+        // swept like any unredeemed one (R-OUT-12).
+        const arming = this.armOrLog(run, this.replay.arm(match, text, this.wrapped, "intent", {
             liveCall: { toolName, toolInput },
             recentResults: recentToolResults(session.transcriptPath, this.deriveRecentResults),
-        });
+        }));
+        const state = await this.withinBudget(arming, INTENT_ARM_DERIVE_MS);
+        if (state === undefined)
+            return undefined; // it threw, and said so
+        if (state === null) {
+            logLine("replay.decision", {
+                verdict: "no-steer",
+                code: "arm_timeout",
+                run: run.runId,
+                scenario: match.scenarioId ?? undefined,
+                kind: match.kind ?? "scenario",
+                ms: INTENT_ARM_DERIVE_MS,
+                why: "the plan was not ready before this call had to go ahead — never delivered, so never run",
+            });
+            void arming.then((late) => {
+                if (!late)
+                    return;
+                late.retired = true;
+                late.pinned.clear();
+                late.reported = true;
+            });
+            return undefined;
+        }
         state.sessionId = session.sessionId;
+        this.declineWithoutDeliveryTool(state);
         if (!state.plan) {
             // A declined intent hit reports nothing: the turn's cost is not a
             // measurement of that scenario's task, so it is no baseline sample either.
@@ -1146,18 +3043,129 @@ export class ControlServer {
         run.replay = state;
         run.intent.armed += 1;
         const directive = this.replay.directiveFor(state) ?? "";
+        // HOW THE DIRECTIVE REACHES THE MODEL. Mid-task, the call that matched is
+        // usually the model's own ordinary work — a `git status`, a file read —
+        // and denying it, or swapping its output for a directive, shows the user a
+        // blocked call and reads to the model like prompt injection. So the call
+        // runs untouched and the directive rides on its PostToolUse, the channel a
+        // hand-over note already uses; the plan starts at its first step after.
+        //
+        // The exception is a call that IS the plan's first step: letting it run
+        // would have the plan run it a second time — a duplicated write. That one
+        // is still answered in place. The same tool is not the same call, though:
+        // it is held to the pin guard's rule (control/pin-guard.ts), so a `git
+        // status` is never swapped for a deploy that happens to be a Bash step.
+        const inPlace = this.isFirstStep(state, toolName, modelArgs);
         logLine("replay.intent_armed", {
             run: run.runId,
             scenario: state.scenarioId ?? undefined,
-            similarity: match.similarity.toFixed(3),
+            similarity: score(match.similarity),
             mode: state.mode,
-            instead: toolName,
+            instead: inPlace ? toolName : undefined,
+            after: inPlace ? undefined : toolName,
             kind: match.kind ?? "scenario",
             key: match.key,
             verified: match.verified?.verdict,
             why: "the model's reasoning matched a calculated scenario's intent",
         });
-        return this.preToolAnswer(this.replay.deliverInstead(directive, toolName));
+        if (inPlace)
+            return this.preToolAnswer(this.replay.deliverInstead(directive, toolName));
+        run.pendingDirective = { state, text: directive };
+        return undefined;
+    }
+    /**
+     * Whether the model's call is plausibly `state`'s first step: its tool, and
+     * arguments the pin guard would pin to that step's input. The input is
+     * computed only for a step of the plan's own frame (a called segment's first
+     * step would build that segment's parameters here); anything that cannot be
+     * computed is "no" — the directive then rides on the call's PostToolUse.
+     */
+    isFirstStep(state, toolName, modelArgs) {
+        const plan = state.plan;
+        if (!plan || plan.expectedTool() !== toolName)
+            return false;
+        try {
+            const entry = plan.currentEntry();
+            if (!entry || entry.depth !== 0)
+                return false;
+            const first = plan.toolInputForCurrentStep();
+            return pinCompatible(toolName, modelArgs, first).ok;
+        }
+        catch (err) {
+            logDetail("replay.first_step_unknown", { tool: toolName, error: errText(err) });
+            return false;
+        }
+    }
+    /**
+     * Whether an intent probe may arm a plan in its own `PreToolUse` — and so
+     * whether that hook waits for it. See {@link ControlServerOptions.intentArm}.
+     */
+    intentArming() {
+        if (this.opts.intentArm !== undefined)
+            return this.opts.intentArm;
+        const env = process.env.BIR_INTENT_ARM;
+        if (env === "1")
+            return true;
+        if (env === "0")
+            return false;
+        return this.replay.segmentArm;
+    }
+    /** How long an arming probe is waited on: `BIR_INTENT_ARM_BUDGET_MS`, never past the probe's own budget. */
+    intentArmBudgetMs() {
+        return Math.min(this.replay.intentMatch.budgetMs, positiveEnv("BIR_INTENT_ARM_BUDGET_MS", INTENT_ARM_PROBE_MS));
+    }
+    /** The bookkeeping half of a probe's answer: what `/health` and the log show. */
+    noteProbe(run, toolName, source, answer, startedAt, late) {
+        // Bookkeeping only, and often run from a floating `.then` after the hook
+        // answered: a malformed answer is a log line, never an unhandled rejection
+        // (which crashes any embedder without a handler) or a failed route.
+        try {
+            this.noteProbeUnsafe(run, toolName, source, answer, startedAt, late);
+        }
+        catch (err) {
+            logDetail("replay.intent_note_failed", { run: run.runId, tool: toolName, error: errText(err) });
+        }
+    }
+    noteProbeUnsafe(run, toolName, source, answer, startedAt, late) {
+        if (answer.stepHit) {
+            run.intent.lastStepHit = { ...answer.stepHit, at: Date.now() };
+        }
+        // What *would* have armed, had segments been armed (segmented.md R-OUT-10).
+        // Logged at line level, not detail: this is the whole observe-only period,
+        // and the decision to turn arming on is made by reading these. The turn
+        // then carries on with whatever else the answer holds (R-OUT-15).
+        if (answer.segmentWouldArm) {
+            const w = answer.segmentWouldArm;
+            logLine("replay.segment_would_arm", {
+                scenario: w.scenarioId,
+                run: w.runId,
+                key: w.key,
+                similarity: score(w.similarity),
+                band: w.band,
+                verified: w.verified
+                    ? w.verified.verdict === "skipped"
+                        ? `skipped:${w.verified.reason}`
+                        : `${w.verified.verdict}: ${w.verified.reason}`
+                    : undefined,
+                tool: w.tool ?? toolName,
+                firstTool: w.firstTool,
+                stepFrom: w.stepFrom,
+                stepTo: w.stepTo,
+                hitCount: w.hitCount,
+            });
+        }
+        const match = answer.matched;
+        logDetail("replay.intent_probe", {
+            run: run.runId,
+            tool: toolName,
+            source,
+            stepHit: answer.stepHit ? `${answer.stepHit.runId}:${answer.stepHit.stepIndex}` : "none",
+            bestStepSimilarity: answer.bestStepSimilarity,
+            elapsedMs: Date.now() - startedAt,
+            matched: match?.scenarioId ?? "none",
+            kind: match?.kind,
+            late,
+        });
     }
     /**
      * Schedule a fragment once a matched turn's plan has handed over (fallbk.md
@@ -1179,6 +3187,11 @@ export class ControlServer {
      * The run id is swapped in place: steps allocated before belonged to a turn
      * the service never created a run for, and nothing of theirs may land in the
      * fragment — so pending correlations are latched and built-ins forgotten.
+     *
+     * Whether the service created the fragment decides only whether it is
+     * recorded, which the user never sees — so this call waits
+     * {@link FRAGMENT_CREATE_MS} for the answer at most, and not at all while the
+     * service is failing. A later answer is applied when it lands.
      */
     async openFragment(session, run, reasoning, toolName, args) {
         const f = run.fragment;
@@ -1205,29 +3218,40 @@ export class ControlServer {
             step: f.stepIndex,
             why: "recording the agent's own work after the scenario handed over",
         });
-        if (isRunCreationAware(this.recorder)) {
-            const created = await this.withinBudget(this.recorder.runCreated(id), this.replay.budgets.matchMs);
-            if (created && !created.created) {
-                run.recording = false;
-                f.state = "hit";
-                // Which run it hit matters from here on: this turn must not count step
-                // hits against the fragment it is a repeat of (segmented.md R-HIT-7).
-                f.hitRunId = created.fragmentOf?.runId;
-                logLine("run.fragment_hit", {
-                    run: id,
-                    scenario: f.scenarioId,
-                    step: f.stepIndex,
-                    of: created.fragmentOf?.runId,
-                    why: "a hand-over at this step was recorded before — counted as a hit, not recorded",
-                });
-            }
+        if (!isRunCreationAware(this.recorder))
+            return;
+        const pending = this.recorder.runCreated(id).catch(() => ({ created: true }));
+        const created = this.service.canWait() ? await this.withinBudget(pending, FRAGMENT_CREATE_MS) : null;
+        if (created) {
+            this.applyFragmentCreation(run, id, created);
+        }
+        else {
+            void pending.then((late) => this.applyFragmentCreation(run, id, late));
         }
     }
+    /** What the fragment's create call said: `created: false` is a hit, not a recording. */
+    applyFragmentCreation(run, id, created) {
+        const f = run.fragment;
+        if (created.created || !f || run.runId !== id)
+            return;
+        run.recording = false;
+        f.state = "hit";
+        // Which run it hit matters from here on: this turn must not count step
+        // hits against the fragment it is a repeat of (segmented.md R-HIT-7).
+        f.hitRunId = created.fragmentOf?.runId;
+        logLine("run.fragment_hit", {
+            run: id,
+            scenario: f.scenarioId,
+            step: f.stepIndex,
+            of: created.fragmentOf?.runId,
+            why: "a hand-over at this step was recorded before — counted as a hit, not recorded",
+        });
+    }
     /** Resolve with `p`, or null once `ms` passes or it rejects. */
     async withinBudget(p, ms) {
         let timer;
         const budget = new Promise((resolve) => {
-            timer = setTimeout(() => resolve(null), ms);
+            timer = setTimeout(() => resolve(null), Math.max(0, ms));
             timer.unref?.();
         });
         try {
@@ -1247,18 +3271,52 @@ export class ControlServer {
      */
     onToolPost(payload) {
         const out = this.toolPost(payload);
+        const context = [];
+        // What a cancelled direct run left this session to tell, whichever turn
+        // this post belongs to (see `SessionState.stashedNote`).
+        const stashed = this.claimStashedNote(payload.session_id);
+        if (stashed)
+            context.push(stashed);
         const run = this.sessions.get(payload.session_id ?? "unknown-session")?.run;
-        if (!run || run.finished)
-            return out;
-        this.noteHandover(run);
-        const note = this.replay.takeNote(run.replay);
-        if (!note)
+        if (run && !run.finished) {
+            this.noteHandover(run);
+            const note = this.replay.takeNote(run.replay);
+            if (note)
+                context.push(note);
+            if (run.handback) {
+                context.push(run.handback);
+                run.handback = undefined;
+            }
+            // A plan an intent match armed beside the model's own call: this is where
+            // the model hears of it (see `tryIntentMatch`), and from here it steers.
+            const pending = run.pendingDirective;
+            if (pending) {
+                run.pendingDirective = undefined;
+                if (pending.state.plan && !pending.state.retired && pending.text)
+                    context.push(pending.text);
+            }
+        }
+        if (context.length === 0)
             return out;
         return {
             ...out,
-            hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: note },
+            hookSpecificOutput: {
+                // The event that fired: this route serves PostToolUse and
+                // PostToolUseFailure, and the host rejects an answer naming the other.
+                hookEventName: payload.hook_event_name === "PostToolUseFailure" ? "PostToolUseFailure" : "PostToolUse",
+                additionalContext: context.join("\n\n"),
+            },
         };
     }
+    /** Whether `run` opened a step for (or deliberately skipped) this `tool_use_id`. */
+    knowsToolUse(run, toolUseId) {
+        if (run.builtIns.has(toolUseId) || run.housekeepingUses?.has(toolUseId))
+            return true;
+        for (const c of run.correlations.values())
+            if (c.toolUseId === toolUseId)
+                return true;
+        return false;
+    }
     /**
      * `PostToolUse` / `PostToolUseFailure`. For a built-in this closes the pair.
      * For a correlated MCP call it normally does nothing — the proxy owns that
@@ -1268,9 +3326,49 @@ export class ControlServer {
      */
     toolPost(payload) {
         const session = this.ensureSession(payload);
-        const run = this.ensureRun(session);
         const toolUseId = payload.tool_use_id ?? "";
         const toolName = payload.tool_name ?? "unknown";
+        if (toolName.startsWith(`mcp__${SCENARIO_SERVER_KEY}__`))
+            this.birToolSeen = true;
+        // Every completion, pinned or not, before anything below can return: it
+        // is what tells a plan's next call apart from one running beside a pin.
+        this.hostCompleted(session.run, toolUseId);
+        // A post for a call of a turn that has already ended — a background task
+        // finishing after Stop. It belongs to that turn, which is sealed; opening a
+        // new, prompt-less run for it would swallow the next prompt (see onPrompt).
+        if (toolUseId) {
+            const open = session.run && !session.run.finished ? session.run : undefined;
+            const sealed = [session.run, session.previous].find((r) => r !== undefined && r.finished && this.knowsToolUse(r, toolUseId));
+            if (sealed && !(open && this.knowsToolUse(open, toolUseId))) {
+                logDetail("tool.post.late", {
+                    run: sealed.runId,
+                    tool: toolName,
+                    why: "its turn had already ended — not recorded, and no new run is opened for it",
+                });
+                return {};
+            }
+        }
+        const failed = payload.hook_event_name === "PostToolUseFailure" || payload.error !== undefined;
+        if (this.replay.isDirectTool(toolName)) {
+            // `run_scenario` answered while its `PreToolUse` record is still waiting:
+            // its `/scenario/run` never arrived, because only that request consumes
+            // the record. The call was refused, cancelled, or failed on the way —
+            // and whether the host calls that a failure says nothing: bir-scenario
+            // answers every failure (no recorder, a stale token, a timeout) as an
+            // ordinary result, so it arrives as a plain `PostToolUse`. Either way
+            // the plan never ran, and it must not run later as a divergence the user
+            // never agreed to. Judged before anything below can return early.
+            const waiting = this.directCalls.find((c) => c.sessionId === session.sessionId && c.toolUseId === toolUseId);
+            if (waiting) {
+                this.directCalls = this.directCalls.filter((c) => c !== waiting);
+                if (!this.runningPlans.has(waiting.state)) {
+                    this.vetoPlan(waiting.run, waiting.state, failed
+                        ? "run_scenario failed before it reached the runner"
+                        : "run_scenario answered without ever reaching the runner");
+                }
+            }
+        }
+        const run = this.ensureRun(session);
         // `onToolPre` opened no step for these, so closing one here would record a
         // `tool_response` with no `tool_selected` before it. The id it remembered
         // decides first; the call itself is judged again only when no step was
@@ -1286,7 +3384,6 @@ export class ControlServer {
         // pre hook, so the test is whether that hook opened a step, not the plan.
         if (this.replay.isDirectTool(toolName) && !run.builtIns.has(toolUseId))
             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
@@ -1298,6 +3395,9 @@ export class ControlServer {
         const pinnedHere = replay && this.replay.isPinned(replay, toolUseId);
         const correlation = [...run.correlations.values()].find((c) => c.toolUseId && c.toolUseId === toolUseId);
         if (pinnedHere && replay) {
+            // The host's verdict, which outranks anything read from the output: a
+            // step that failed must never thread as if it worked (controller.ts).
+            const hostFailure = failed ? this.errorText(payload) : undefined;
             if (correlation && this.replay.threadsFromProxy(replay, toolUseId)) {
                 correlation.threadToolUseId = toolUseId;
                 correlation.threadFallback = setTimeout(() => {
@@ -1308,15 +3408,16 @@ export class ControlServer {
                         tool: toolName,
                         why: "no proxy report — threading the hook's view; shapes may differ",
                     });
-                    this.replay.postTool(replay, toolUseId, serializeCapped(payload.tool_response ?? {}));
+                    this.replay.postTool(replay, toolUseId, serializeCapped(payload.tool_response ?? {}), hostFailure);
                 }, PROXY_REPORT_GRACE_MS);
                 correlation.threadFallback.unref?.();
             }
             else {
-                this.replay.postTool(replay, toolUseId, serializeCapped(payload.tool_response ?? {}));
+                this.replay.postTool(replay, toolUseId, serializeCapped(payload.tool_response ?? {}), hostFailure);
             }
         }
         if (correlation) {
+            correlation.postSeen = true;
             if (correlation.settled) {
                 logDetail("tool.post.deduped", { run: run.runId, tool: toolName });
                 return { deduped: true };
@@ -1331,6 +3432,13 @@ export class ControlServer {
                     tool: correlation.qualifiedName,
                     why: "no proxy report — recording the hook's view instead",
                 });
+                if (correlation.injected) {
+                    // An id rode along and nothing echoed it: this session's calls to
+                    // the server may pass through a proxy that strips nothing (one
+                    // started under `bir off` is a pure pipe). No id goes there again
+                    // until a report proves otherwise.
+                    (session.noInjection ??= new Set()).add(correlation.serverName);
+                }
                 this.settle(run, correlation, {
                     args: correlation.hookArgs,
                     result: payload.tool_response,
@@ -1358,6 +3466,18 @@ export class ControlServer {
         logDetail("tool.post", { run: run.runId, tool: toolName, step: responseIndex, failed });
         return { stepIndex: responseIndex };
     }
+    /**
+     * Tell the replay controller the host finished `toolUseId` (`PostToolUse`
+     * or `PostToolUseFailure`). Bookkeeping for its pin waits; never throws.
+     */
+    hostCompleted(run, toolUseId) {
+        try {
+            this.replay.hostCompleted?.(run?.replay, toolUseId);
+        }
+        catch (err) {
+            logDetail("replay.host_completed_failed", { error: errText(err) });
+        }
+    }
     errorText(payload) {
         if (typeof payload.error === "string")
             return payload.error;
@@ -1398,15 +3518,28 @@ export class ControlServer {
         // 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);
+        // it did before. The drain that follows is background work: it is what
+        // lets the recorder forget the run once the service has it.
+        this.closeRun(session, { detach: false });
         return {};
     }
-    async onSessionEnd(payload) {
+    /**
+     * `SessionEnd` — `/clear`, exit, logout. Answered at once: the host is
+     * waiting on it to exit, and this process outlives the session, so the run
+     * is sealed here and reaches the service in the background.
+     */
+    onSessionEnd(payload) {
         const session = this.ensureSession(payload);
-        await this.finalizeRun(session);
         // Its proxies outlive it after a `/clear`, and serve the next session.
         this.replay.work.releaseSession(session.sessionId);
+        for (const [proxyId, sessionId] of this.proxySessions) {
+            if (sessionId === session.sessionId)
+                this.proxySessions.delete(proxyId);
+        }
+        this.closeRun(session, { detach: false, flushMs: FLUSH_MS.sessionEnd });
+        // Forgotten a little later by the reaper, not now: a late report or post
+        // for its last turn must still find that turn rather than open a new one.
+        session.endedAt = Date.now();
         return {};
     }
     // ── proxy routes ─────────────────────────────────────────────────────────
@@ -1416,12 +3549,18 @@ export class ControlServer {
             return { error: "serverName required" };
         this.wrapped.add(serverName);
         const proxyVersion = body.version === undefined ? undefined : String(body.version);
+        const pid = Number(body.pid ?? 0);
         this.registrations.set(serverName, {
-            pid: Number(body.pid ?? 0),
+            pid,
             cwd: String(body.cwd ?? ""),
             at: Date.now(),
             version: proxyVersion,
         });
+        // Every registered proxy of this server, not only the newest: any live one
+        // is a proxy that strips an injected id (see `hasLiveProxy`).
+        this.noteProxyPid(serverName, pid);
+        if (typeof body.proxyId === "string" && body.proxyId)
+            this.noteRegisteredProxy(body.proxyId);
         logLine("proxy.registered", {
             server: serverName,
             pid: body.pid,
@@ -1444,8 +3583,8 @@ export class ControlServer {
         }
         // 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;
+        // once one exists — the most recently active one, never merely the oldest.
+        const run = this.recentSessions().find((s) => this.isActive(s))?.run;
         return {
             ok: true,
             sessionId: this.sessionId,
@@ -1467,13 +3606,28 @@ export class ControlServer {
      */
     async onProxyPoll(body, signal) {
         const serverName = String(body.serverName ?? "");
+        const pid = Number(body.pid);
+        // A polling proxy is a bound one, and a bound proxy strips a call id: as
+        // good a sign of life as its registration (which a recorder that restarted
+        // under it may never have seen). A set lookup when already known.
+        this.noteProxyPid(serverName, pid);
+        // Replay off: say so, so the proxy slows its loop right down
+        // (proxy/session.ts) — and nothing is logged, since it asks again later.
+        // At once for a proxy that registered with this recorder. One that never
+        // did is from before it started, and a 0.2.12 proxy — which never
+        // registers again, and polls again 250 ms after any answer without work —
+        // would ask four times a second until its session ended: it is held
+        // first, as a poll with no work always was.
+        if (!this.replay.enabled) {
+            const proxyId = typeof body.proxyId === "string" ? body.proxyId : undefined;
+            if (!proxyId || !this.registeredProxies.has(proxyId))
+                await this.holdPoll(body, signal);
+            return { replay: false };
+        }
         if (!serverName)
             return { error: "serverName required" };
-        if (!this.replay.enabled)
-            return {};
         const hold = Number(body.holdMs);
         const startedAt = Number(body.startedAt);
-        const pid = Number(body.pid);
         const work = await this.replay.work.waitForWork(serverName, Number.isFinite(hold) && hold > 0 ? Math.min(hold, POLL_HOLD_MS) : POLL_HOLD_MS, signal, {
             proxyId: typeof body.proxyId === "string" ? body.proxyId : undefined,
             startedAt: Number.isFinite(startedAt) ? startedAt : undefined,
@@ -1481,6 +3635,46 @@ export class ControlServer {
         });
         return work ? { work } : {};
     }
+    /** Remember that `proxyId` registered with this recorder (see {@link registeredProxies}). */
+    noteRegisteredProxy(proxyId) {
+        this.registeredProxies.delete(proxyId);
+        this.registeredProxies.set(proxyId, Date.now());
+        while (this.registeredProxies.size > REGISTERED_PROXIES_MAX) {
+            const oldest = this.registeredProxies.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.registeredProxies.delete(oldest);
+        }
+    }
+    /**
+     * Park a poll for as long as it asked to be held (never past
+     * {@link POLL_HOLD_MS}), or until its caller goes away or this server closes.
+     */
+    holdPoll(body, signal) {
+        const asked = Number(body.holdMs);
+        const ms = Number.isFinite(asked) && asked > 0 ? Math.min(asked, POLL_HOLD_MS) : POLL_HOLD_MS;
+        logOnce("proxy.poll_held", "proxy.poll_held", {
+            why: "replay is off, and a proxy that never registered with this recorder is polling — held for its poll's hold, so an older proxy does not ask four times a second",
+        });
+        return new Promise((resolve) => {
+            if (signal?.aborted) {
+                resolve();
+                return;
+            }
+            let timer;
+            const release = () => {
+                if (timer)
+                    clearTimeout(timer);
+                signal?.removeEventListener("abort", release);
+                this.heldPolls.delete(release);
+                resolve();
+            };
+            timer = setTimeout(release, ms);
+            timer.unref?.();
+            signal?.addEventListener("abort", release, { once: true });
+            this.heldPolls.add(release);
+        });
+    }
     /** `POST /proxy/result` — the answer to one dispatched `tools/call`. */
     onProxyResult(body) {
         const workId = String(body.workId ?? "");
@@ -1499,23 +3693,139 @@ export class ControlServer {
      * 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).
+     *
+     * WHOSE PLAN. bir-scenario cannot say which session called it — a stdio MCP
+     * server is never told — and taking "the first armed plan" ran one session's
+     * plan, with its parameters, for another session's call, and returned its
+     * results there. The `PreToolUse` for `run_scenario` always reaches this
+     * recorder first, with its session, so the run takes the plan of the session
+     * that just asked (see {@link takeDirectCall}). No such pre, no run: a call
+     * the host never let through is not one to act on.
+     *
+     * ONE RUN PER PLAN. A second call while the plan is executing would run
+     * every step again beside the first — duplicated writes — and is told so.
+     *
+     * `signal` aborts when `bir-scenario`'s request goes away — the host
+     * cancelled the call (Esc) or its own timeout fired — so no further step is
+     * started for a caller that can no longer read the result.
      */
-    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)
+    async onScenarioRun(body, signal) {
+        const call = this.takeDirectCall(body);
+        if (!call) {
+            logDetail("replay.run_unbound", {
+                why: "no run_scenario PreToolUse is waiting for a run — nothing is run for this call",
+            });
             return { ok: false, why: "no_plan" };
-        const result = await this.replay.runArmed(run.replay);
-        return result;
+        }
+        const state = call.state;
+        if (this.runningPlans.has(state)) {
+            logLine("replay.run_refused", {
+                scenario: state.scenarioId ?? undefined,
+                sess: call.sessionId,
+                why: "this plan is already running — a second run would repeat every step",
+            });
+            return { ok: false, why: ALREADY_RUNNING };
+        }
+        this.runningPlans.add(state);
+        // The session is busy for as long as its plan runs, and sends no hook
+        // meanwhile: the host is waiting on this very call.
+        this.touchSession(call.sessionId);
+        // The user cancelling the call (Esc) cuts the turn short: what it cost is
+        // no measure of the scenario. Marked the moment it happens — the next
+        // prompt may seal the turn before the step in flight has finished.
+        const onCancel = () => {
+            this.cancelledPlans.add(state);
+        };
+        if (signal?.aborted)
+            onCancel();
+        else
+            signal?.addEventListener("abort", onCancel, { once: true });
+        try {
+            const result = await this.replay.runArmed(state, signal);
+            if (signal?.aborted)
+                this.stashCancelledNote(call.sessionId, state);
+            return result;
+        }
+        finally {
+            signal?.removeEventListener("abort", onCancel);
+            this.runningPlans.delete(state);
+            this.touchSession(call.sessionId);
+        }
+    }
+    /**
+     * A direct run whose caller went away (Esc, or bir-scenario's own timeout)
+     * stopped part-way, and the note that says which steps already ran — their
+     * side effects are in place — reached nobody. When the turn goes on, its
+     * next tool call carries it (the run's own path). When Esc ended the turn,
+     * the next prompt seals that run, so the note is kept on the session too,
+     * for its next `UserPromptSubmit`, `PostToolUse`, or `PreToolUse` of one of
+     * the plan's own tools (in that call's place): without it the model would
+     * run those steps a second time.
+     */
+    stashCancelledNote(sessionId, state) {
+        const h = state.handover;
+        if (!h || h.delivered)
+            return;
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        session.stashedNote = state;
+        logLine("replay.note_kept", {
+            sess: sessionId,
+            scenario: state.scenarioId ?? undefined,
+            why: "the run was cancelled part-way — which steps ran is told on this session's next prompt or tool result",
+        });
+    }
+    /** Mark a known session as heard from now (see {@link SessionState.lastSeenAt}). */
+    touchSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session)
+            session.lastSeenAt = Date.now();
+    }
+    /**
+     * The `run_scenario` pre this `/scenario/run` answers, removed from the
+     * waiting list — or undefined when there is none whose plan can still run.
+     *
+     * Exact when the caller names it (a `bir-scenario` that forwards the host's
+     * `tool_use_id` or session id). Otherwise only when every pre still waiting
+     * is one session's: the oldest of the fresh ones, and when none is fresh (a
+     * user who took a while to approve the call), the newest. Pres waiting in
+     * two sessions at once are never guessed between — see below.
+     */
+    takeDirectCall(body) {
+        const now = Date.now();
+        this.directCalls = this.directCalls.filter((c) => now - c.at < DIRECT_CALL_TTL_MS &&
+            !c.run.finished &&
+            c.state.plan !== undefined &&
+            !c.state.retired &&
+            c.run.replay === c.state);
+        const toolUseId = typeof body.toolUseId === "string" ? body.toolUseId : undefined;
+        const sessionId = typeof body.sessionId === "string" ? body.sessionId : undefined;
+        let pick;
+        if (toolUseId)
+            pick = this.directCalls.find((c) => c.toolUseId === toolUseId);
+        if (!pick && sessionId)
+            pick = this.directCalls.find((c) => c.sessionId === sessionId);
+        if (!pick && !toolUseId && !sessionId) {
+            // Unnamed, and more than one session waiting: which one is asking is a
+            // guess, and a wrong guess runs one session's plan, with its parameters,
+            // and hands the results to the other's model. Nothing runs instead; the
+            // record stays for its own PostToolUse, which retires the plan, and each
+            // model does its task itself — the safe way to be wrong.
+            const sessions = new Set(this.directCalls.map((c) => c.sessionId));
+            if (sessions.size > 1) {
+                logLine("replay.run_ambiguous", {
+                    sessions: sessions.size,
+                    why: "run_scenario is pending in more than one session and the request names neither — nothing is run",
+                });
+                return undefined;
+            }
+            const fresh = this.directCalls.filter((c) => now - c.at < DIRECT_CALL_FRESH_MS);
+            pick = fresh.length > 0 ? fresh[0] : this.directCalls[this.directCalls.length - 1];
+        }
+        if (pick)
+            this.directCalls = this.directCalls.filter((c) => c !== pick);
+        return pick;
     }
     /**
      * `POST /scenario/replay` — `bir replay`, i.e. a scenario nobody matched.
@@ -1535,54 +3845,64 @@ export class ControlServer {
         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.
+     * A proxy's `ProxyStepReport`. The step is joined to the call a hook saw,
+     * in whichever session made it — never simply "the first session with an
+     * open run", which put one window's MCP steps into another's recording:
+     *   1. the `callId` a hook injected (exact), looked up in every session;
+     *   2. the fingerprint `(server, tool, hash(args))` across every session's
+     *      current turn — lossy under identical concurrent calls, and documented
+     *      as such;
+     *   3. nothing — record it standalone, in the session this proxy is known to
+     *      serve, or else the most recently active one. That is what an SDK
+     *      session with no hooks produces, and a complete MCP step in its own
+     *      right.
      */
     onProxyStep(report) {
-        this.learnProxySession(report);
-        const session = this.sessionForProxyStep();
-        const run = this.ensureRun(session);
+        // `bir off` makes the runner inert. A proxy started before it keeps
+        // reporting (one started after is a pure pipe), and none of it is recorded
+        // until the runner is back on.
+        if (offSource(this.opts.cwd))
+            return { ok: true, off: true };
         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)));
-                this.noteHandover(run);
-            }
-            if (correlation.settled) {
-                logDetail("proxy.step.deduped", { run: run.runId, tool: report.qualifiedName });
-                return { deduped: true };
+        const owner = this.ownerOf(report);
+        // A session started with BIR_OFF=1 (K2) records nothing, whoever reports
+        // for it. Its own proxies are pure pipes; this is any other one.
+        const boundTo = report.proxyId ? this.proxySessions.get(report.proxyId) : undefined;
+        if (this.isSessionOff(owner?.session.sessionId ?? boundTo))
+            return { ok: true, off: true };
+        if (owner) {
+            const { session, run, correlation } = owner;
+            session.lastSeenAt = Date.now();
+            if (report.proxyId)
+                this.bindProxy(report.proxyId, session.sessionId);
+            if (run.finished && !correlation.settled && (run.finishQueued || !run.recording)) {
+                // Its turn ended, and its finish was sent, before the report arrived.
+                // Recording it now would land after that run's finish; opening a new
+                // run for it would swallow the next prompt. It stays with its turn,
+                // unrecorded, and says so. (Inside the seal's answer wait it is still
+                // recorded, below — ahead of the finish.)
+                correlation.settled = true;
+                correlation.reported = true;
+                logLine("proxy.step.late", {
+                    run: run.runId,
+                    tool: report.qualifiedName,
+                    why: "the report arrived after its turn was sealed — not recorded",
+                });
+                return { late: 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 };
+            return this.joinReport(run, correlation, report);
         }
         // Standalone: no hook ever saw this call.
+        const session = this.sessionForProxyStep(report);
+        if (this.isSessionOff(session.sessionId))
+            return { ok: true, off: true };
+        // A step is the session being heard from, exactly as a hook is. A host
+        // with no hooks (an SDK, a Tier-2 MCP client) sends nothing else: without
+        // this its busy run would read as idle on `/health` — an upgrade restart
+        // could land mid-work — and the reaper would seal it on every sweep once
+        // `idleSealMs` had passed, splitting its recording into a run a minute.
+        session.lastSeenAt = Date.now();
+        const run = this.ensureRun(session);
         const pair = run.ordering.allocatePair();
         this.record(run, pair, {
             toolName: report.qualifiedName || qualifyToolName(report.serverName, report.toolName),
@@ -1600,59 +3920,224 @@ export class ControlServer {
         });
         return { stepIndex: pair.selected, merged: false };
     }
+    /** Merge a report into the call a hook saw: thread it into a plan if pinned, record it once. */
+    joinReport(run, correlation, report) {
+        // 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)), 
+            // The proxy's verdict: a step that failed must never thread as if it
+            // worked (controller.ts `postTool`).
+            report.isError === true
+                ? typeof report.errorMessage === "string" && report.errorMessage
+                    ? report.errorMessage
+                    : "the tool reported an error"
+                : undefined);
+            this.noteHandover(run);
+        }
+        const duplicate = correlation.reported === true;
+        correlation.reported = true;
+        if (correlation.settled) {
+            logDetail("proxy.step.deduped", {
+                run: run.runId,
+                tool: report.qualifiedName,
+                why: duplicate ? "a second report for one call" : "already recorded from the hook's view",
+            });
+            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 };
+    }
     /**
-     * Tie the reporting proxy to the session whose hook minted the step's call id,
-     * so that session's replay steps run on this proxy's upstream and not on
-     * another session's (replay/executor.ts). Searches every session, not just the
-     * one {@link sessionForProxyStep} records into: with two sessions open, that
-     * guess is exactly what cannot be trusted.
+     * The session, run and call a report belongs to, or undefined when no hook
+     * saw it. An injected id is looked up everywhere first; then the
+     * fingerprint, across every session's current and just-sealed turn.
      */
-    learnProxySession(report) {
-        if (!report.proxyId || !report.callId)
-            return;
-        for (const session of this.sessions.values()) {
-            if (session.run?.correlations.has(report.callId)) {
-                this.replay.work.bindProxy(report.proxyId, session.sessionId);
-                return;
+    ownerOf(report) {
+        if (report.callId) {
+            for (const session of this.sessions.values()) {
+                for (const run of [session.run, session.previous]) {
+                    const correlation = run?.correlations.get(report.callId);
+                    if (run && correlation) {
+                        // An echoed id: this session's calls to the server do reach a
+                        // proxy that strips it.
+                        session.noInjection?.delete(correlation.serverName);
+                        return { session, run, correlation };
+                    }
+                }
             }
         }
+        return this.matchByFingerprint(report);
+    }
+    /**
+     * The fingerprint a report joins by, and whether it is over the raw
+     * arguments. A proxy that sends `argsFingerprint` hashed them before
+     * redaction and clipping, exactly as the hook side hashes `tool_input`; an
+     * older one did not, and its report's `args` are hashed as reported.
+     */
+    reportKey(report) {
+        const sent = report.argsFingerprint;
+        if (typeof sent === "string" && sent.length > 0)
+            return { key: sent, raw: true };
+        return { key: fingerprint(report.serverName, report.toolName, report.args), raw: false };
+    }
+    /**
+     * Tie a reporting proxy to the session whose call it just carried, so that
+     * session's replay steps run on this proxy's upstream and not on another
+     * session's (replay/executor.ts), and so its standalone reports are recorded
+     * there. A join is the only evidence of which session a proxy serves.
+     */
+    bindProxy(proxyId, sessionId) {
+        this.proxySessions.set(proxyId, sessionId);
+        this.replay.work.bindProxy(proxyId, sessionId);
+    }
+    /** Sessions, most recently heard from first. */
+    recentSessions() {
+        return [...this.sessions.values()].sort((a, b) => b.lastSeenAt - a.lastSeenAt);
     }
     /**
-     * Which session a proxy's step belongs to.
+     * Which session a standalone proxy 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*
+     * — so the control server decides: the session this proxy's earlier calls
+     * were joined to, else the most recently active session with a turn in
+     * progress, else the most recently heard session. 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];
+     * `SessionStart` and the first prompt from opening a second, parallel run.
+     */
+    sessionForProxyStep(report) {
+        const bound = report.proxyId ? this.proxySessions.get(report.proxyId) : undefined;
+        const known = bound ? this.sessions.get(bound) : undefined;
         if (known)
             return known;
+        const recent = this.recentSessions();
+        const active = recent.find((s) => this.isActive(s));
+        if (active)
+            return active;
+        if (recent[0])
+            return recent[0];
         // 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;
+    /**
+     * The call a report joins by fingerprint, across every session.
+     *
+     * Among the calls whose PostToolUse has arrived — they certainly ran — the
+     * oldest. Otherwise the newest call made before the proxy started this one:
+     * a call the user refused never runs and is never reported, and must not
+     * take the report of the identical call they approved after it; and a call
+     * made after the start is some other call. Only calls made within
+     * {@link CONSENT_WINDOW_MS} of the proxy starting the call qualify — the gap
+     * is the user reading a permission prompt — and one made up to
+     * {@link FINGERPRINT_SKEW_MS} after it only when nothing earlier does.
+     *
+     * A report for a call the hook's fallback already recorded (the report was
+     * slower than {@link PROXY_REPORT_GRACE_MS}) finds that call too, and is
+     * deduped rather than recorded a second time.
+     */
+    matchByFingerprint(report) {
+        const { key, raw } = this.reportKey(report);
+        const started = Number.isFinite(report.startedAt) && report.startedAt > 0 ? report.startedAt : Date.now();
+        const open = [];
+        const recorded = [];
+        for (const session of this.sessions.values()) {
+            for (const run of [session.run, session.previous]) {
+                if (!run)
+                    continue;
+                for (const correlation of run.correlations.values()) {
+                    const theirs = raw ? correlation.fingerprint : correlation.reportedFingerprint;
+                    if (theirs !== key || correlation.reported)
+                        continue;
+                    if (correlation.createdAt > started + FINGERPRINT_SKEW_MS)
+                        continue;
+                    if (started - correlation.createdAt > CONSENT_WINDOW_MS)
+                        continue;
+                    (correlation.settled ? recorded : open).push({ session, run, correlation });
+                }
+            }
+        }
+        const ran = open
+            .filter((h) => h.correlation.postSeen)
+            .sort((a, b) => a.correlation.createdAt - b.correlation.createdAt);
+        if (ran[0])
+            return ran[0];
+        open.sort((a, b) => b.correlation.createdAt - a.correlation.createdAt);
+        // Hook and proxy share this machine's clock, and the host sends a call
+        // only after its PreToolUse was answered: a PreToolUse made *after* the
+        // proxy started this call cannot be it. It may be the identical call of
+        // another session whose user is still reading the permission prompt —
+        // which, taken, would put this step in that session's recording and bind
+        // this proxy to it. The skew window is for clocks that disagree, so it is
+        // used only when no call made before the start qualifies.
+        const before = open.find((h) => h.correlation.createdAt <= started);
+        if (before)
+            return before;
+        if (open[0])
+            return open[0];
+        const settled = recorded.sort((a, b) => a.correlation.createdAt - b.correlation.createdAt)[0];
+        if (settled || raw)
+            return settled;
+        return this.soleCandidate(report, started);
+    }
+    /**
+     * A report with no `argsFingerprint` — from a proxy older than this
+     * recorder — whose arguments hash to no call: joined to the one call of the
+     * same server and tool that no report has claimed yet, when there is exactly
+     * one (UPG-8).
+     *
+     * Such a proxy redacted its copy of the arguments by its own, older rules,
+     * so a value those rules kept and today's redact (a DSN's password, a
+     * token in a URL, Basic auth) never hashes the same on the two sides.
+     * Recorded standalone, the call would be in the run twice: once from this
+     * report, once from its PostToolUse's fallback. Two candidates or more are
+     * never guessed between.
+     */
+    soleCandidate(report, started) {
+        let found;
+        for (const session of this.sessions.values()) {
+            for (const run of [session.run, session.previous]) {
+                if (!run)
+                    continue;
+                for (const correlation of run.correlations.values()) {
+                    if (correlation.reported)
+                        continue;
+                    if (correlation.serverName !== report.serverName || correlation.toolName !== report.toolName)
+                        continue;
+                    if (correlation.createdAt > started + FINGERPRINT_SKEW_MS)
+                        continue;
+                    if (started - correlation.createdAt > CONSENT_WINDOW_MS)
+                        continue;
+                    if (found)
+                        return undefined;
+                    found = { session, run, correlation };
+                }
+            }
+        }
+        if (found) {
+            logDetail("proxy.step.legacy_join", {
+                tool: report.qualifiedName,
+                why: "an older proxy's report matched no fingerprint — joined to the one open call of its tool",
+            });
         }
-        return best;
+        return found;
     }
     /** Record the merged pair for a correlation and latch it against re-entry. */
     settle(run, correlation, data) {