@basein/runner 0.2.12 → 0.3.0

package/dist/control/server.d.ts

@@ -26,6 +26,38 @@
 import { type IntentSource } from "./transcript.js";
 import { type Recorder } from "../record/recorder.js";
 import { type ReplayOptions } from "../replay/controller.js";
+import { type ServiceHealth } from "../util/service-health.js";
+/**
+ * The prompt match gate (see {@link ControlServer.armFromMatch}). A match that
+ * answered slower than `slowMs` (`BIR_MATCH_SLOW_MS`), or not inside its
+ * budget, is not waited for again for `holdMs`; the hold doubles while the
+ * service stays slow, up to `maxHoldMs`, and a fast answer ends it.
+ */
+export interface MatchGateTimings {
+    slowMs: number;
+    holdMs: number;
+    maxHoldMs: number;
+}
+/**
+ * Session bookkeeping (see {@link ControlServer.reap}). A long-lived recorder
+ * sees every session its project ever has — every `/clear`, every `claude -p`
+ * — and must forget them, and a turn that ended without `Stop` (Esc, then the
+ * window closed) must stop counting as one in progress.
+ */
+export interface SessionTimings {
+    /** A session unheard from for longer is not "mid-turn" on `/health`. */
+    activeMs: number;
+    /** An open run unheard from for longer is sealed: the turn was abandoned. */
+    idleSealMs: number;
+    /** A session with no open run, unheard from for longer, is forgotten. */
+    forgetMs: number;
+    /** A session this long after its `SessionEnd`, and silent since, is forgotten. */
+    endedForgetMs: number;
+    /** Past this many, the least recently heard sessions without an open run go first. */
+    maxSessions: number;
+    /** How often the reaper runs. */
+    reapEveryMs: number;
+}
 /** The subset of the Claude Code hook payload we consume (all optional, all defensive). */
 export interface HookPayload {
     session_id?: string;
@@ -39,6 +71,18 @@ export interface HookPayload {
     tool_use_id?: string;
     error?: unknown;
     agent_id?: string;
+    /**
+     * The host's permission mode for this event (`default`, `plan`,
+     * `acceptEdits`, `bypassPermissions`, …). Decides whether answering `allow`
+     * would change anything the user is asked — see `injectionDecision`.
+     */
+    permission_mode?: string;
+    /**
+     * Added by the SessionStart ensure hook (never by the host) when the
+     * session was started with `BIR_OFF=1`: the runner is off for this session
+     * only. See {@link ControlServer.offSessions}.
+     */
+    bir_off?: unknown;
 }
 export interface ControlServerOptions {
     recorder: Recorder;
@@ -71,15 +115,56 @@ export interface ControlServerOptions {
         version?: string;
     };
     /**
-     * What `PreToolUse` answers when it injects a correlation id.
+     * Legacy twin of {@link correlation}, as `bir-hooks` up to 0.2.12 passes it.
      *
-     * `"allow"` is what §6/Phase 6 specifies, and what makes injection reliable —
-     * but it also **auto-approves the call**, skipping a permission prompt the user
-     * might otherwise have seen. `"ask"` keeps the prompt at the cost of some hosts
-     * ignoring `updatedInput` on a non-allow decision (correlation then degrades to
-     * the fingerprint path). Set with `BIR_CORRELATION_DECISION`.
+     * Those versions passed `"allow"` whenever `BIR_CORRELATION_DECISION` was
+     * unset — the old default, not a choice anybody made — so only `"ask"` is
+     * read from here. `BIR_CORRELATION_DECISION=allow` in the recorder's
+     * environment is the explicit opt-in, and is read directly.
      */
     correlationDecision?: "allow" | "ask";
+    /**
+     * How `PreToolUse` joins an ordinary (not replay-pinned) wrapped MCP call to
+     * its proxy's report. Overrides `BIR_CORRELATION_DECISION`.
+     *
+     *  - `"auto"` (default): carry a correlation id only where answering `allow`
+     *    changes nothing the user is asked — the session is in
+     *    `bypassPermissions` mode. Everywhere else the hook answers with no
+     *    decision at all and the report joins by fingerprint, so the user's
+     *    permission prompts for their MCP tools are exactly what they were
+     *    without the runner.
+     *  - `"allow"`: always inject and answer `allow` — the behaviour of 0.2.12 and earlier,
+     *    which **auto-approves every wrapped call**. Opt-in only.
+     *  - `"ask"`: always inject and answer `ask`, which prompts even for tools
+     *    the user allow-listed, and shows the injected id in the prompt.
+     *
+     * Never `allow` in `plan` mode, and never an id into a server with no live
+     * proxy to strip it (see `hasLiveProxy`).
+     */
+    correlation?: "auto" | "allow" | "ask";
+    /**
+     * Whether this project has the `bir` MCP server, through which a `direct`
+     * plan is delivered (`mcp__bir__run_scenario`). A plan that names a tool
+     * the model does not have is never armed: the model would look for it, fail,
+     * reach for its own tools — and a divergence would then run the scenario
+     * unattended in a project that never installed replay's delivery tool.
+     *
+     * A boolean is the caller vouching either way (tests, an embedder that
+     * delivers direct plans itself). Omitted — every recorder `bir` starts — a
+     * direct plan needs **live** evidence: a `/scenario/hello` from a
+     * `bir-scenario` that still runs, lists at least one tool and is not off,
+     * within {@link DELIVERY_HELLO_TTL_MS}. Configured is not connected: the
+     * server may have failed to start, been disabled in `/mcp`, or run under
+     * `BIR_OFF=1` with no tools. The background recorder (`BIR_DAEMON=1`) also
+     * reads the project's MCP configuration, off the hook path, and a project
+     * with no `bir` entry there has none. A function answers the configuration
+     * half; live evidence is still required.
+     */
+    deliveryTool?: boolean | (() => boolean | undefined);
+    /** The prompt match gate's thresholds (tests). See {@link MatchGateTimings}. */
+    matchGate?: Partial<MatchGateTimings>;
+    /** Session bookkeeping thresholds (tests). See {@link SessionTimings}. */
+    sessionTimings?: Partial<SessionTimings>;
     /** Disable id injection; use `(server, tool, hash(args))` matching instead. */
     noCorrelation?: boolean;
     /**
@@ -118,6 +203,30 @@ export interface ControlServerOptions {
      * killed, which on Windows is the only other option.
      */
     onStopRequested?: () => void;
+    /**
+     * Whether an intent probe may arm a plan inside the `PreToolUse` that sent it
+     * (fallbk.md §Runner 4).
+     *
+     * Arming there means *waiting* there, on every unsteered tool call, for a
+     * service round trip — so by default the probe is sent without waiting, for
+     * hit counting only, and nothing arms mid-turn. It waits (at most
+     * `BIR_INTENT_ARM_BUDGET_MS`, 500 ms, and never while the service is failing)
+     * when segment arming is on (`BIR_SEGMENT_ARM=1`), or when `BIR_INTENT_ARM=1`
+     * asks for whole-scenario intent arming as before. `BIR_INTENT_ARM=0` never
+     * waits.
+     */
+    intentArm?: boolean;
+    /**
+     * The verdict hot paths consult before they wait on the service. Defaults to
+     * the process-wide one every service call reports to; tests pass their own.
+     */
+    serviceHealth?: ServiceHealth;
+    /**
+     * Shorter per-route hook deadlines, in ms, keyed by route (tests). A value
+     * above the built-in deadline is ignored: those are what keep every hook
+     * inside the timeout `bir install` writes.
+     */
+    hookDeadlinesMs?: Readonly<Record<string, number>>;
 }
 export interface ControlServerAddress {
     url: string;
@@ -136,11 +245,102 @@ export declare class ControlServer {
     private readonly wrapped;
     /** serverName → registration facts, for `bir doctor`. */
     private readonly registrations;
+    /**
+     * 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.
+     */
+    private readonly proxyPids;
+    /** serverName → the last answer of {@link hasLiveProxy}, briefly. */
+    private readonly liveProxyCache;
+    /**
+     * proxyId → the session its calls were joined to. Where a report no hook
+     * minted an id for is recorded — never "whichever session is first".
+     */
+    private readonly proxySessions;
+    /** `run_scenario` pres not yet consumed by a `/scenario/run`, oldest first. */
+    private directCalls;
+    /** Plans a `/scenario/run` is executing right now: one run per plan. */
+    private readonly runningPlans;
+    /**
+     * 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}.
+     */
+    private readonly declinedPins;
+    /** Whether this project's `bir` server exists, from its MCP config (see {@link ControlServerOptions.deliveryTool}). */
+    private deliveryFromConfig?;
+    private deliveryConfigStamp?;
+    private 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.
+     */
+    private birToolSeen;
+    /**
+     * `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}).
+     */
+    private readonly scenarioHellos;
+    /**
+     * 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.
+     */
+    private readonly offSessions;
+    /**
+     * 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.
+     */
+    private readonly registeredProxies;
+    /** Releases for polls held with replay off (see {@link onProxyPoll}), for `close()`. */
+    private readonly heldPolls;
+    /**
+     * 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.
+     */
+    private readonly cancelledPlans;
+    /** See {@link MatchGateTimings}. */
+    private readonly 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).
+     */
+    private matchGate;
+    private readonly timings;
+    private reaper?;
     private server?;
     private address?;
     private lossy;
-    /** Seals whose answer text is still being waited for. Awaited before any flush. */
-    private readonly pendingSeals;
+    /**
+     * The project's current token as the install sidecar last said, and the
+     * file stamp it was read at (see {@link currentProjectToken}).
+     */
+    private 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.
+     */
+    private readonly drains;
+    /** Whether the service may be waited on right now (service-health.ts). */
+    private readonly 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.
+     */
+    private readonly hookStats;
     /** Calculated replay. Inert unless `opts.replay.enabled`. */
     private readonly replay;
     /**
@@ -160,16 +360,147 @@ export declare class ControlServer {
     close(): Promise<void>;
     /** Facts for `bir doctor` / `GET /health`. */
     health(): Record<string, unknown>;
+    /**
+     * 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(): {
+        openRuns: number;
+        knownSessions: number;
+        liveProxyPids: number;
+    };
+    /**
+     * 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.
+     */
+    private recorderBacklog;
+    /**
+     * 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.
+     */
+    private authorized;
+    /**
+     * 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".
+     */
+    private currentProjectToken;
     private handle;
+    /**
+     * 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.
+     */
+    private handleHook;
+    /**
+     * `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.
+     */
+    private forEvent;
+    /**
+     * 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.
+     */
+    private sessionOff;
+    /** Mark `sessionId` off (see {@link sessionOff}), sealing whatever it had open. */
+    private markSessionOff;
+    /** Whether `sessionId` is a session started with `BIR_OFF=1`. */
+    private isSessionOff;
+    /** The route's hook deadline, or undefined when `route` is not a hook this recorder serves. */
+    private deadlineFor;
+    /** What the prompt hook may spend on the match and arming: a second inside its deadline. */
+    private promptWaitMs;
+    private dispatchHook;
+    /**
+     * `body` with `text` put in front of whatever `additionalContext` it
+     * already carries, under `event` — the event that fired.
+     */
+    private withContext;
+    /**
+     * 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}).
+     */
+    private claimStashedNote;
     private send;
+    /**
+     * 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.
+     */
     private readJson;
     private ensureSession;
+    /**
+     * Whether `session` is mid-turn: an open run, heard from recently enough to
+     * be working rather than abandoned (see {@link SessionTimings.activeMs}).
+     */
+    private isActive;
+    /** Start the reaper and, for the background recorder, the delivery-tool refresh. Both unref'd. */
+    private startHousekeeping;
+    /**
+     * 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?: number): void;
+    /** Drop a session and everything keyed on it. Its last run was sealed and drained already. */
+    private forgetSession;
     /** Open a run for `session`, or return the open one. */
     private ensureRun;
     private runMetadata;
     /**
      * 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
@@ -179,6 +510,100 @@ export declare class ControlServer {
      * Resolves with the steering directive to inject, or undefined.
      */
     private watchForMatch;
+    /**
+     * 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).
+     */
+    private armFromMatch;
+    /**
+     * 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).
+     */
+    private noteMatchLatency;
+    /**
+     * {@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.
+     */
+    private noteDisabledMatch;
+    /**
+     * 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.
+     */
+    private declineWithoutDeliveryTool;
+    /**
+     * 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.
+     */
+    private deliveryToolAvailable;
+    /**
+     * 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.
+     */
+    private deliveryConfigured;
+    /**
+     * 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.
+     */
+    private liveHellos;
+    /**
+     * `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.
+     */
+    private onScenarioHello;
+    /**
+     * 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.
+     */
+    private refreshDeliveryTool;
+    /** `arming`, never rejecting: a broken arm is logged and is no plan at all. */
+    private armOrLog;
+    /**
+     * 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.
+     */
+    private retireUnannounced;
+    /**
+     * 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.
+     */
+    private shelve;
     /**
      * Close the run's books, without waiting for the network.
      *
@@ -218,23 +643,131 @@ export declare class ControlServer {
     /** Transcript cost since `mark`; unmeasured (and zero) without one. */
     private costSince;
     private reportExecution;
-    /** Seal the run *and* wait for everything queued to reach the service. */
-    private finalizeRun;
+    /**
+     * 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.
+     */
+    private closeRun;
+    /**
+     * 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.
+     */
+    private drainInBackground;
+    /**
+     * 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.
+     */
+    private drainRun;
     private onSessionStart;
     private onPrompt;
     /**
      * `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}.
      */
     private onToolPre;
+    /** This run's plan, when it is armed, still live, and announced to the model. */
+    private livePlan;
+    /** Whether a `run_scenario` pre for `state` is still waiting for its `/scenario/run`. */
+    private hasDirectCall;
+    /**
+     * 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.
+     */
+    private vetoPlan;
+    /**
+     * 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.
+     */
+    private abandonAfterDeclinedPin;
+    /** An intent plan whose directive never reached the model: it did nothing, and reports nothing. */
+    private shelveUnannounced;
+    /**
+     * 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.
+     */
+    private injectionDecision;
+    /** See {@link ControlServerOptions.correlation}. */
+    private correlationPolicy;
+    /**
+     * 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.
+     */
+    private hasLiveProxy;
+    /**
+     * 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.
+     */
+    private noteProxyPid;
     /** A controller decision as a `PreToolUse` answer, or undefined to carry on. */
     private preToolAnswer;
+    /**
+     * 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.
+     */
+    private replayOverran;
     /**
      * Recordings this turn must not count a step hit against (segmented.md
      * R-HIT-7).
@@ -271,8 +804,34 @@ export declare 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.
      */
     private tryIntentMatch;
+    /**
+     * 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.
+     */
+    private isFirstStep;
+    /**
+     * Whether an intent probe may arm a plan in its own `PreToolUse` — and so
+     * whether that hook waits for it. See {@link ControlServerOptions.intentArm}.
+     */
+    private intentArming;
+    /** How long an arming probe is waited on: `BIR_INTENT_ARM_BUDGET_MS`, never past the probe's own budget. */
+    private intentArmBudgetMs;
+    /** The bookkeeping half of a probe's answer: what `/health` and the log show. */
+    private noteProbe;
+    private noteProbeUnsafe;
     /**
      * Schedule a fragment once a matched turn's plan has handed over (fallbk.md
      * D7). Only a turn that is not already recording needs one: an unmatched turn
@@ -285,8 +844,15 @@ export declare 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.
      */
     private openFragment;
+    /** What the fragment's create call said: `created: false` is a hit, not a recording. */
+    private applyFragmentCreation;
     /** Resolve with `p`, or null once `ms` passes or it rejects. */
     private withinBudget;
     /**
@@ -294,6 +860,8 @@ export declare class ControlServer {
      * output reaches the model at once, as `additionalContext` (fallbk.md D4).
      */
     private onToolPost;
+    /** Whether `run` opened a step for (or deliberately skipped) this `tool_use_id`. */
+    private knowsToolUse;
     /**
      * `PostToolUse` / `PostToolUseFailure`. For a built-in this closes the pair.
      * For a correlated MCP call it normally does nothing — the proxy owns that
@@ -302,6 +870,11 @@ export declare class ControlServer {
      * {@link PROXY_REPORT_GRACE_MS} rather than the step being lost entirely.
      */
     private toolPost;
+    /**
+     * Tell the replay controller the host finished `toolUseId` (`PostToolUse`
+     * or `PostToolUseFailure`). Bookkeeping for its pin waits; never throws.
+     */
+    private hostCompleted;
     private errorText;
     /**
      * `SubagentStart` / `SubagentStop`. These carry `agent_id`, which is the only
@@ -315,6 +888,11 @@ export declare class ControlServer {
      */
     private onAgent;
     private onStop;
+    /**
+     * `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.
+     */
     private onSessionEnd;
     private onProxyRegister;
     /**
@@ -326,6 +904,13 @@ export declare class ControlServer {
      * would be invisible next to the upstream's own round trip (D12).
      */
     private onProxyPoll;
+    /** Remember that `proxyId` registered with this recorder (see {@link registeredProxies}). */
+    private noteRegisteredProxy;
+    /**
+     * 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.
+     */
+    private holdPoll;
     /** `POST /proxy/result` — the answer to one dispatched `tools/call`. */
     private onProxyResult;
     /**
@@ -335,8 +920,47 @@ export declare 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.
      */
     private onScenarioRun;
+    /**
+     * 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.
+     */
+    private stashCancelledNote;
+    /** Mark a known session as heard from now (see {@link SessionState.lastSeenAt}). */
+    private touchSession;
+    /**
+     * 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.
+     */
+    private takeDirectCall;
     /**
      * `POST /scenario/replay` — `bir replay`, i.e. a scenario nobody matched.
      *
@@ -348,33 +972,85 @@ export declare class ControlServer {
      */
     private onScenarioReplay;
     /**
-     * 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.
      */
     private onProxyStep;
+    /** Merge a report into the call a hook saw: thread it into a plan if pinned, record it once. */
+    private joinReport;
+    /**
+     * 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.
+     */
+    private ownerOf;
+    /**
+     * 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.
+     */
+    private reportKey;
     /**
-     * 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.
+     * 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.
      */
-    private learnProxySession;
+    private bindProxy;
+    /** Sessions, most recently heard from first. */
+    private recentSessions;
     /**
-     * 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.
+     * `SessionStart` and the first prompt from opening a second, parallel run.
      */
     private sessionForProxyStep;
+    /**
+     * 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.
+     */
     private matchByFingerprint;
+    /**
+     * 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.
+     */
+    private soleCandidate;
     /** Record the merged pair for a correlation and latch it against re-entry. */
     private settle;
     /** The one place a tool step pair is written. Redaction and caps live here. */