@basein/runner 0.2.12 → 0.3.0

package/docs/calculatedReplay.md

@@ -1,1304 +1,1625 @@
-# Calculated Replay — running a scenario on a similar-meaning match
-
-> Design doc for BaseInstRunnerMCP **v2** ([BaseInstRunner.md](BaseInstRunner.md) §12), the
-> milestone the v1 design deferred: *"Serve recorded results; port RRepeat's divergence handling."*
->
-> **What it adds.** When the user's prompt means the same thing as a prompt they have run before,
-> the BaseIn service says so and hands back the *calculated scenario* derived from that earlier run.
-> This document specifies what BaseInstRunnerMCP does with it: derive the new prompt's parameters,
-> run the scenario's tool sequence against live data, and let the model answer from genuine results —
-> instead of rediscovering the same plan token by token.
->
-> **Status:** implemented. Phases R0–R7 (§17) are in `src/replay/`, wired through the control server
-> and the proxies, covered by `test/replay.test.ts` and `test/replay-server.test.ts`, and proved end
-> to end with real processes by `test/smoke-replay.mjs`. Three notes below are marked **[built]**
-> where the implementation settled something this design left open.
-> **Reference implementation:** RRepeat's [`docs/replay.md`](../../../BasInstRunner/RRepeat/docs/replay.md)
-> §3, §12, §13 and [`docs/savingCalcRunner.md`](../../../BasInstRunner/RRepeat/docs/savingCalcRunner.md).
-> **Server contract:** BaseIn `src/recordings/routes.ts`, `src/scenarios/{routes,repo,replay,logic}.ts`.
-
----
-
-## 0. The one fact that makes this different from RRepeat
-
-RRepeat and BaseInstRunnerMCP are solving the same problem from opposite sides of the tool call.
-
-RRepeat **observes** a Claude Code session through hooks. It has no execution path of its own, so
-when a replay diverges it must spawn a *second* Claude Agent SDK session to run the remaining tools
-for real (`sdk-tool-session.ts`, `replay.md` §13). Its own savings doc names the consequence:
-
-> *"the **dominant** cost of today's calculated run is a full second agent session, and it is the one
-> cost nobody counts."* — `savingCalcRunner.md` §4
-
-BaseInstRunnerMCP **is** the execution path for MCP. Every wrapped server is reached through a
-`bir-proxy` process that already holds an initialized, live `UpstreamClient` to it
-([`src/upstream/client.ts`](../src/upstream/client.ts)). Issuing a `tools/call` on that connection
-costs **zero tokens** and requires no second agent, no subprocess, and no model in the loop.
-
-Everything below follows from that. Where RRepeat has one replay mode and an expensive fallback,
-this design has a ladder whose cheapest rung is free — and the more of a stack sits behind
-`bir-proxy`, the further down the ladder a scenario lands.
-
-| | RRepeat | BaseInstRunnerMCP |
-|---|---|---|
-| Runs MCP tools itself | No (`replay.md` §12: *"rrepeat never executes tools — not even MCP"*) | **Yes**, on the connection it already owns |
-| Divergence fallback | A second Agent SDK session — the dominant cost | Direct `tools/call` through the proxies — **$0** |
-| Reaches built-ins (`Bash`, `Read`) | Only by steering the live session | Same — only by steering the live session |
-| Needs `@anthropic-ai/*` at runtime | Yes | No (§16.3) |
-
----
-
-## 1. Decisions locked
-
-Continuing v1's D1–D8.
-
-| # | Decision | Choice | Consequence |
-|---|---|---|---|
-| **D9** | What a match buys | **Execute the scenario**, do not merely stop recording | v1's `watchForMatch` already detects the hit and stops; this replaces the no-op with work |
-| **D10** | Who decides the mode | **Tool coverage**, computed per scenario at arm time (§5) | A fully-wrapped scenario replays for free; a mixed one steers the live session |
-| **D11** | Execution ownership for MCP steps | **The proxy that owns the upstream** | No second connection, no double-spawned browser, no Agent SDK dependency |
-| **D12** | Control → proxy channel | **Long-poll**, proxy dials out | No new listeners, no new ports, no new tokens (§13.3, §19.2) |
-| **D13** | Result delivery in direct mode | A **first-party MCP server** (`bir`), one tool | The model reads a genuine `tool_result`, never a `deny` reason it distrusts (§19.1) |
-| **D14** | Default state | **On** once `bir install --replay` has run; `BIR_REPLAY=0` turns it off | Replay bypasses permission prompts (§13.2); the install flag is the opt-in, the env var is the kill switch |
-| **D15** | Parameter derivation | One Haiku call over raw `fetch`; **no API key ⇒ recorded sample values** | Preserves v1's zero-runtime-dependency property, and degrades to a free replay |
-| **D16** | Savings reporting | Every armed match reports to `POST /scenarios/:id/executions`, including declines | A decline is a *baseline sample*, not silence — it is what keeps the ledger honest |
-
-### 1.1 Non-goals
-
-- **Replay in Tier 2.** A match is a match *on the prompt*, and a standalone proxy never sees one
-  (§0.1 of the v1 design). Tier 2 gets the manual `bir replay` command (§12.1) and nothing automatic.
-- **Chaining scenarios.** RRepeat's `next`/`getScenarioChain` has no counterpart in BaseIn's
-  `serializeScenario` payload, which serializes exactly one scenario. Out of scope.
-- **Editing tool descriptions to steer selection.** Still a non-goal, unchanged. §6's `bir` server
-  adds one *first-party* tool and touches no upstream schema — and it costs context in every session,
-  which is why D14 makes it opt-in.
-- **Recording the replayed turn.** The service created no run for it, by design. §12.
-
----
-
-## 2. The match, and where it already works
-
-Nothing in this section is new. It is already implemented and already runs on every prompt.
-
-```
-UserPromptSubmit
-   └─ ControlServer.onPrompt          src/control/server.ts
-       └─ ensureRun → recorder.startRun(input, metadata)
-           └─ RemoteRecorder.startRun     POST /recordings/runs { id, framework, input, metadata }
-               └─ BaseIn recordings/routes.ts:
-                    findSimilarRun(userId, input)         ← embed + cosine over the user's runs
-                    ├─ miss → 201 { id, matched: null }
-                    └─ hit  → 200 { id: null, matched: {...} }   ← no run is created
-```
-
-On a hit the server answers with the whole thing — there is no follow-up fetch:
-
-```jsonc
-{
-  "id": null,
-  "matched": {
-    "runId": "run_…",              // the canonical earlier run
-    "scenarioId": "scn_…",         // its calculated scenario, when one is ready
-    "similarity": 0.94,            // cosine, ≥ SIMILARITY_THRESHOLD (server default 0.9)
-    "executionTicket": "tkt_…",    // redeem exactly once at POST /scenarios/:id/executions
-    "scenario": { /* serializeScenario(): intent, paramsObject, paramsLogic,
-                     responseParamsLogic, steps[{ stepIndex, toolName,
-                     toolInputLogic, toolOutputLogic, reasoning }] */ }
-  }
-}
-```
-
-[`RemoteRecorder.getMatch(runId)`](../src/record/remote-recorder.ts) already exposes it, and
-[`ControlServer.watchForMatch`](../src/control/server.ts) already consumes it — to do exactly one
-thing:
-
-```ts
-run.recording = false;
-logLine("run.matched", { …, why: "similar prompt — the service kept its own run; not recording this one" });
-```
-
-**That is the whole of v1's replay support: a correct stop.** This design replaces the stop with a
-plan, and keeps the stop.
-
-### 2.1 What "similar meaning" means, precisely
-
-Server-side, and worth stating because the threshold in §4 is a judgement about it:
-
-- The embedding is of the run's **`input`** — the user's prompt — computed by
-  `Xenova/all-MiniLM-L6-v2` (`EMBEDDING_MODEL`), mean-pooled and normalized
-  (`recordings/embeddings.ts`).
-- Candidates are **the caller's own canonical runs only** (`listUserRunEmbeddings(userId)`);
-  duplicates and sub-threshold runs are excluded from the pool at record time.
-- The match is the single best cosine ≥ `SIMILARITY_THRESHOLD` (default **0.9**).
-- A matched run only carries a `scenarioId` when its scenario exists **and** is `state: 'ready'`.
-
-So "similar meaning" is: *the same user asked for something that embeds within 0.1 cosine of this,
-and we finished calculating a reusable plan for it.* It is not "the same words", and it is not
-cross-tenant.
-
----
-
-## 3. Architecture
-
-```mermaid
-graph TB
-  subgraph host["Claude Code session"]
-    M[model loop]
-    H[hooks]
-  end
-
-  subgraph bir["BaseInstRunnerMCP"]
-    C["bir-hooks — control server<br/>ScenarioReplayPlan lives here"]
-    S["bir-scenario<br/>MCP server: run_scenario"]
-    P1["bir-proxy — chrome-devtools"]
-    P2["bir-proxy — github"]
-  end
-
-  U1[chrome-devtools-mcp]
-  U2[github mcp]
-  R[("BaseIn /recordings/* /scenarios/*")]
-
-  H -->|"UserPromptSubmit → directive"| C
-  H -->|"PreToolUse → pinned updatedInput"| C
-  H -->|"PostToolUse → real output"| C
-  M -->|"mcp__bir__run_scenario"| S
-  S -->|"POST /scenario/run"| C
-  C -.->|"work: tools/call"| P1
-  C -.->|"work: tools/call"| P2
-  P1 -->|"bir: id request"| U1
-  P2 -->|"bir: id request"| U2
-  C -->|"match + execution report"| R
-```
-
-Three additions to the v1 topology, and nothing else moves:
-
-| Component | New? | Role in replay |
-|---|---|---|
-| `bir-hooks` control server | extended | Holds the `ScenarioReplayPlan` on `RunState`. Arms it, pins inputs, threads outputs, dispatches direct steps, redeems the ticket |
-| `bir-proxy` | extended | Long-polls for work; executes a `tools/call` on the upstream it already owns |
-| `bir-scenario` | **new**, ~120 lines | A stdio MCP server exposing one tool, `run_scenario`. The delivery channel for direct mode (§6). It later gained the scenario tools of §16.5 |
-
----
-
-## 4. The gate ladder
-
-Ported from RRepeat's `applyMatch`, with one gate this repo needs and RRepeat cannot have.
-Every gate that declines logs **one** `replay.decision` line carrying the reason — because
-*"a scenario existed and was not used"* is a fact an auditor needs as much as *"a scenario ran"*.
-
-| # | Gate | Declines when | Outcome floor |
-|---|---|---|---|
-| 1 | **A match arrived** | `getMatch()` resolved `null`, or the budget expired (§10) | (no report — nothing matched) |
-| 2 | **Replay enabled** | `BIR_REPLAY === "0"` | `not_steered` |
-| 3 | **Scenario ready** | `scenario == null`, `state !== "ready"`, or `steps.length === 0` | `not_steered` |
-| 4 | **Similarity** | `similarity < BIR_MIN_STEER_SIMILARITY` (default **0.92**) | `not_steered` |
-| 5 | **Tool coverage** | No step is executable anywhere (§5 → `mode: "none"`) | `not_steered` |
-
-Gate 4 deserves its own note. The server's own detection threshold is 0.9, and it uses it to decide
-*"do not record this again"* — a cheap claim: the worst case is a lost recording. Steering makes a
-much stronger claim: *"do not think about this again."* A prompt that is 0.90-similar usually covers
-only part of the live task, and steering it produces a confident, thin, wrong answer. So the steer
-threshold sits **above** the detection threshold by default, and `BIR_MIN_STEER_SIMILARITY` is the
-single knob an operator turns after watching `replay.decision` lines for a week.
-
-`not_steered` as the floor is not a failure code. It is the **control group**: the prompt matched,
-the agent ran the task the ordinary way, and the cost of doing so is a fresh measurement of what this
-task costs — which is exactly what a baseline is made of. BaseIn's
-`POST /scenarios/:id/executions` routes `not_steered` to `addBaselineSample` rather than the
-savings ledger, on purpose (`scenarios/routes.ts`). §11.
-
----
-
-## 5. Tool coverage decides the mode
-
-The classification is a pure function of the scenario's steps and the set of server keys registered
-with this control server (`ControlServer.wrapped`, grown by `/proxy/register`).
-
-```ts
-// src/replay/coverage.ts
-export type StepReach = "direct" | "live";
-export type ReplayMode = "direct" | "steer" | "none";
-
-export function reachOf(toolName: string, wrapped: ReadonlySet<string>): StepReach {
-  const mcp = parseQualifiedName(toolName);          // src/control/correlation.ts
-  return mcp && wrapped.has(mcp.serverName) ? "direct" : "live";
-}
-
-export function modeFor(steps: SerializedScenarioStep[], wrapped: ReadonlySet<string>): ReplayMode {
-  if (steps.length === 0) return "none";
-  return steps.every((s) => reachOf(s.toolName, wrapped) === "direct") ? "direct" : "steer";
-}
-```
-
-| Every step | Mode | Where the tools run | Model spend |
-|---|---|---|---|
-| a wrapped MCP tool | **`direct`** (§6) | The proxies, on connections already open | one Haiku derivation + one turn that reads the results |
-| anything else, or mixed | **`steer`** (§7) | The live session, inputs pinned | one Haiku derivation + the live turn |
-| — | `none` | nowhere | declines at gate 5 |
-
-`live` covers three genuinely different cases and treats them identically, correctly: a built-in
-(`Bash`, `Read`, `Edit`, `Grep`, `Task`, `WebFetch`), an MCP server the user chose not to wrap, and
-`claude-in-chrome` — which is `scope: "dynamic"`, appears in no config file, and therefore can never
-be wrapped (v1 design §1). None of them can be reached except through the session.
-
-A **mixed** scenario in `steer` mode still gets direct execution for its wrapped steps once it
-diverges (§8), so coverage is not all-or-nothing at the divergence boundary — only at the arm-time
-mode choice.
-
----
-
-## 6. Mode A — direct execution
-
-The cheap rung. Every step is a wrapped MCP tool, so the model never has to emit a single tool call.
-
-### 6.1 Sequence
-
-```mermaid
-sequenceDiagram
-    participant CC as Claude Code (model)
-    participant CS as bir-hooks (control server)
-    participant SC as bir-scenario (MCP)
-    participant PX as bir-proxy
-    participant UP as upstream MCP server
-
-    CC->>CS: UserPromptSubmit
-    CS->>CS: gates pass, mode=direct → arm plan; start derivation (not awaited)
-    CS-->>CC: additionalContext: "call mcp__bir__run_scenario once"
-    CC->>SC: tools/call run_scenario {}
-    SC->>CS: POST /scenario/run
-    CS->>CS: await plan.ready()  (derivation lands)
-    loop each step
-        CS->>CS: toolInputForCurrentStep()
-        CS-->>PX: work { workId, toolName, arguments }   (answers an open long-poll)
-        PX->>UP: tools/call  (bir: id, on the open connection)
-        UP-->>PX: CallToolResult
-        PX->>CS: POST /proxy/result { workId, result }
-        CS->>CS: applyOutput(JSON.stringify(result)) → respParams
-    end
-    CS->>CS: responseParamsLogic → response model; assembleBundle()
-    CS-->>SC: { text, responseModel, steps }
-    SC-->>CC: tool_result (genuine)
-    CC->>CC: answers from the results
-    CC->>CS: Stop → seal, report execution (ticket)
-```
-
-### 6.2 Why a first-party MCP server, and not `additionalContext`
-
-Executing inside `UserPromptSubmit` and returning the results as `additionalContext` is the obvious
-shortcut, and it is wrong for three separate reasons:
-
-1. **Budget.** `UserPromptSubmit` has a hook timeout (§10). N live MCP round trips do not fit inside
-   one, and if it expires Claude Code proceeds *without* the context — so the work is burned and the
-   user waits for nothing.
-2. **Trust.** RRepeat learned this expensively. Its `deny`-with-a-reason delivery is *"inherently
-   read as a denial by the model"* (`hook-server.ts`), which is why it grew a Bash-rewrite path and
-   then a whole MCP bridge (`mcp-bridge.ts`) to hand the same bytes back as a genuine `tool_result`.
-   A first-party MCP tool is that bridge, without the shadowing.
-3. **Truth.** A `tool_result` in the transcript is a real record of a real call. `additionalContext`
-   asserting that tools ran is a claim the transcript cannot corroborate.
-
-The cost is honest and worth naming: one extra tool in the model's tool list, in **every** session
-where `bir install --replay` ran. That is why it is a separate install flag and why `bir status`
-prints it.
-
-### 6.3 `run_scenario`
-
-```jsonc
-// tools/list, from bir-scenario
-{
-  "name": "run_scenario",
-  "description":
-    "Run the pre-calculated tool sequence BaseInstRunner has armed for the current request, and return its results. Call once, with no arguments, when instructed to.",
-  "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false }
-}
-```
-
-No arguments **by design**: the armed plan is server-side state keyed by the control server's open
-run, so there is nothing for the model to get wrong and nothing it can point at a different scenario.
-When no plan is armed the tool returns `isError: true` with `"no scenario is armed for this turn"`,
-which is a tool failure the model reacts to normally.
-
-`bir-scenario` is a client of the control server, discovered the same way a proxy discovers it —
-`~/.baseinstrunner/control/<key>.json`, mode `0600`, bearer token
-([`src/control/discovery.ts`](../src/control/discovery.ts)). It holds no state, no credentials and
-no upstream connections.
-
-### 6.4 The steering directive (direct)
-
-```
-[BaseInstRunner] A known-good tool sequence was recorded for this request
-(intent: <scenario.intent>). Call mcp__bir__run_scenario once, with no
-arguments, before any other tool. It runs the sequence and returns the
-results. Answer the user from those results.
-```
-
-If the model calls something else first, the turn falls to §8 — the plan is still armed and the
-divergence path still executes it.
-
----
-
-## 7. Mode B — model-steered live replay
-
-The mixed rung. Ported from RRepeat's `replay.md` §3/§12, which is the right design and is already
-proven: the model chooses *which* tool and *when*; the control server overrides the *arguments* and
-threads state between steps. The session never leaves the model's hands, so every
-`tool_use`/`tool_result` in the transcript is genuine and continuation is automatic.
-
-**Arm** at `UserPromptSubmit` — plan on `run.plan`, `run.planToolUse = new Set()`, directive via
-`additionalContext`, **no `decision`** so the prompt still reaches the model:
-
-```
-[BaseInstRunner calculated replay] A known-good tool sequence was previously
-recorded for this request. Call exactly these tools, in order, one at a time:
-
-  1. mcp__chrome-devtools__navigate_page — open the fleet dashboard
-  2. mcp__chrome-devtools__take_snapshot — read the device table
-  3. Read — load the alert thresholds
-
-The system supplies the exact arguments for each call — you do not need to
-compute them. Do not call any other tools until this sequence is complete,
-then answer the user's request from the tool results.
-```
-
-**Pin** at `PreToolUse`, while a plan is active and the call is not `mcp__bir__run_scenario`:
-
-```ts
-if (toolName === plan.expectedTool()) {
-  const input = plan.toolInputForCurrentStep();          // may throw → §8
-  run.planToolUse.add(toolUseId);
-  return { hookSpecificOutput: { hookEventName: "PreToolUse",
-                                 permissionDecision: "allow",
-                                 updatedInput: withCallId(input) } };   // §7.1
-}
-return divergence(…);                                                   // §8
-```
-
-**Thread** at `PostToolUse`, for a `tool_use_id ∈ run.planToolUse` — but *from the right source*
-(§7.2). When `plan.isDone()`, retire the plan; the model then writes its answer from the real tool
-history.
-
-### 7.1 Steering and correlation both write `updatedInput` — they must merge
-
-This collision does not exist in RRepeat and is easy to miss here.
-
-`onToolPre` already returns an `updatedInput` for every **wrapped MCP** call: it is how the
-correlation id rides along to the proxy ([`src/control/correlation.ts`](../src/control/correlation.ts)).
-A pinned step whose tool is a wrapped MCP tool therefore needs *both* payloads in one object, and the
-order is not arbitrary:
-
-```ts
-/** Pinned arguments plus, for a wrapped MCP tool, the correlation id. */
-function withCallId(pinned: Record<string, unknown>): Record<string, unknown> {
-  const mcp = parseQualifiedName(toolName);
-  if (!mcp || !this.wrapped.has(mcp.serverName) || this.opts.noCorrelation) return pinned;
-  const correlation = mintCorrelation(run, mcp, pinned, context);   // hookArgs = the PINNED args
-  return { ...pinned, [BIR_CALL_ID]: correlation.callId };
-}
-```
-
-Three consequences, all load-bearing:
-
-- **The correlation's `hookArgs` must be the pinned arguments, not the model's.** `settle()` records
-  `correlation.hookArgs ?? report.args`; recording the arguments the model *proposed* rather than the
-  ones that *ran* would put a lie in the corpus. (In a replayed turn nothing is recorded — §12 — but
-  the same code path serves recorded turns, and the invariant must hold there.)
-- **Schema relaxation must already be active**, or the host may reject the extra key. It is, whenever
-  Tier 1 correlation is on (`ProxySession.correlationActive`). Under `--no-correlation`, `withCallId`
-  is a no-op and pinning still works — only the *result* join degrades to fingerprints.
-- **`permissionDecision: "allow"` auto-approves.** Already true for every correlated call today
-  (`BIR_CORRELATION_DECISION`), and now true for pinned built-ins too. §13.2.
-
-### 7.2 Thread from the same source that recorded
-
-`toolOutputLogic` was authored by BaseIn's `analyzeRun` against the exact bytes stored in that step's
-`tool_output`. Feeding it a differently-shaped rendering of the same result does not fail loudly — it
-silently derives nothing, and every later step reading `respParams` produces a wrong input.
-
-In this repo those bytes have **two different origins**:
-
-| Step's tool | What was recorded | Therefore thread from |
-|---|---|---|
-| Wrapped MCP | `serializeCapped(redact(report.result))` — the proxy's whole `CallToolResult`, via `settle()` → `record()` | the **proxy's `/proxy/step` report** |
-| Built-in / unwrapped MCP | `serializeCapped(redact(payload.tool_response))` — Claude Code's rendering, via `onToolPost` | the **hook's `tool_response`** |
-
-So `/tool/post` must not thread unconditionally. It threads for a `live` step, and for a `direct`
-step it does what it already does for a correlated call: **arm the existing
-`PROXY_REPORT_GRACE_MS` fallback**, and let `onProxyStep` thread when the report lands.
-
-```ts
-// onToolPost, for a pinned step
-if (reachOf(step.toolName, this.wrapped) === "live") {
-  plan.applyOutput(serializeCapped(payload.tool_response ?? {}));
-} else {
-  correlation.threadOnReport = true;         // onProxyStep calls plan.applyOutput(report.result)
-  correlation.fallback = setTimeout(() => {  // …unless the proxy never reports
-    logLine("replay.thread_fallback", { why: "no proxy report — threading the hook's view; shapes may differ" });
-    plan.applyOutput(serializeCapped(payload.tool_response ?? {}));
-  }, PROXY_REPORT_GRACE_MS);
-}
-```
-
-This reuses machinery that exists and is already correct. It also means the §7.3 ordering constraint
-binds a little harder: the proxy report must land before the next `PreToolUse`, and
-`PROXY_REPORT_GRACE_MS` (1500 ms) is the bound on how long that can take before we degrade.
-
-### 7.3 Synchronous `PostToolUse` is a requirement, not a preference
-
-Step *N*'s `/tool/post` must finish updating `respParams` before step *N+1*'s `/tool/pre` reads it.
-In [`HOOK_ROUTES`](../src/config/adapters/claude-code.ts) neither `PreToolUse` nor `PostToolUse`
-carries `async: true`, so this already holds — **and must never be relaxed**. Add it to the comment
-block there, next to the `SessionEnd` note that records the same class of lesson.
-
----
-
-## 8. Divergence
-
-The model called a tool the plan did not expect, or `toolInputLogic` threw, or the tool had no
-`tool_use_id`. Three tiers, tried in order. Here is where the §0 asymmetry pays.
-
-**Tier 1 — direct-execute the remainder (new; the common case).**
-Take every not-yet-run step, execute it, and hand the composed result back. Steps with
-`reach === "direct"` run through their proxy. Steps with `reach === "live"` cannot run here at all —
-a hook process is not the session — and fall back to the step's **recorded output** (§8.1), or are
-skipped with a logged warning. RRepeat's rule, and its reasoning holds verbatim: a *skipped* step
-also stops threading `respParams`, so every later step reading from it fails too, and a five-step
-scenario degrades to nothing. A recorded result is marked as such in the bundle, so the model is
-never told a stale result is fresh.
-
-Delivery, best channel first:
-
-1. **The `bir` tool** — if the divergent call *is* `mcp__bir__run_scenario`, or the model can be
-   nudged to it. Genuine `tool_result`.
-2. **Bash-clean** — if the divergent call is `Bash`, rewrite the command to `cat` a heredoc of the
-   bundle. The model sees ordinary command output. (RRepeat's `bashCleanPath`; neutralize the
-   delimiter first.)
-3. **Deny-inject** — `permissionDecision: "deny"`, bundle as `permissionDecisionReason`, capped at
-   `MAX_REPLAY_REASON` (60 000 chars) with the same fair-share truncation
-   (`assembleBundle`/`truncate`, portable verbatim from `payload-executor.ts`). Works for any tool,
-   and is read as adversarial — hence last.
-
-**Tier 2 — abort.** Composition itself threw. Retire the plan, return `{}`, continue as an ordinary
-turn. Outcome `failed`.
-
-**The cost line.** RRepeat's Tier 1 is an Agent SDK session, and its own doc calls that the dominant
-cost of a calculated run. Here Tier 1 is N `tools/call`s on connections that are already open:
-**`fallbackCostUsd` is 0.00 by construction**, for every step the proxies can reach.
-
-> **Do not port the unconditional-divergence line.** RRepeat's `steerPreTool` ends with a deliberate
-> `return await injectBundle(...)` that bypasses the pin branch on *every* armed plan
-> (`savingCalcRunner.md` §4 documents the consequence: `stepsPinned` is 0 on every row). That was a
-> choice made when the bundle was the only path that ran real tools. It is not this design's choice:
-> pinning is tried first, always, and divergence is what its name says.
-
-### 8.1 Where a recorded output actually comes from
-
-RRepeat reads it from `SerializedScenarioStep.recordedOutput`, whose own comment says the field is
-optional because *"it is the server's payload that decides whether to send it, and older payloads do
-not."* Verify this before relying on it: **no payload does.** BaseIn's `scenario_steps` table has
-columns `tool_input_logic`, `tool_output_logic`, `reasoning`, `reasoning_vector` — and no
-`recorded_output`; `serializeScenario` emits no such field. RRepeat's fallback is unreachable in
-production today.
-
-There is a path that needs no server change, and the match payload already carries its key:
-
-```
-GET /recordings/runs/:runId        →  { run, steps }   // steps carry tool_name + tool_output
-                    ↑ matched.runId — the canonical source run this scenario was calculated from
-```
-
-So: fetch the source run **lazily**, on the first `live` step of the first divergence, and index its
-`tool_response` steps by tool name into the same FIFO queue BaseIn's own `dryReplay` builds
-(`recordedOutputsByTool` in `scenarios/replay.ts` — a `Map<toolName, string[]>` drawn in order, with
-a per-tool cursor). One authenticated GET, cached for the turn, and the queue semantics match the
-server's dry replay exactly — which matters, because a scenario that behaves one way under
-`bir scenario replay --dry` and another way here would be untestable.
-
-Adding `recorded_output` to `scenario_steps` would make this a field read instead of a fetch, and is
-a reasonable server-side follow-up. It is not a prerequisite.
-
-> **[built]** [`src/replay/source-run.ts`](../src/replay/source-run.ts). The type still carries the
-> optional `recordedOutput` field and prefers it when present, so a server that starts sending it
-> needs no change here — but nothing depends on it.
-
----
-
-## 9. The plan, and state threading across hook calls
-
-`ScenarioReplayPlan` ports from RRepeat's [`payload-executor.ts`](../../../BasInstRunner/RRepeat/src/server/payload-executor.ts)
-with three changes.
-
-```ts
-// src/replay/plan.ts
-export class ScenarioReplayPlan {
-  readonly scenarioId: string;
-  readonly mode: ReplayMode;
-  readonly stepCount: number;
-
-  /** Resolves when derivation has landed and paramsLogic has been applied. */
-  ready(): Promise<void>;
-
-  currentStepIndex: number;
-  expectedTool(): string | undefined;
-  isDone(): boolean;
-
-  /** Pinned input for the current step. Throws → divergence. */
-  toolInputForCurrentStep(): Record<string, unknown>;
-  /** Thread a real output into respParams and advance. Throws → abort. */
-  applyOutput(realOutput: string): void;
-
-  steeringDirective(): string;
-  /** Execute every remaining step through `execute`, and lay the results out under `maxChars`. */
-  composeBundle(maxChars: number, execute: ExecuteStep): Promise<BundleResult>;
-  /** responseParamsLogic over the accumulated respParams. */
-  responseModel(): Record<string, unknown>;
-}
-```
-
-**Change 1 — lifetime is a run, not a session.** The plan hangs off `RunState`, not `SessionState`.
-In this codebase a run *is* a turn (`UserPromptSubmit → Stop`, `server.ts` §onPrompt), which is
-exactly the plan's lifetime. `sealRun` retires it; a second prompt in the same session cannot inherit
-a stale plan, which in RRepeat requires care.
-
-**Change 2 — `params` are a promise.** The constructor takes `Promise<Record<string, unknown>>`, not
-a value, so arming does not wait for the Haiku call (§10). `paramsLogic` is applied once, inside
-`ready()`, the first time it resolves.
-
-**Change 3 — `execute` is a step, not a tool name.** `composeBundle` takes
-`(step, input) => Promise<string>` rather than `(toolName, input)`, because the executor must know
-the step's `reach` to decide between the proxy, the recorded output, and skipping.
-
-The four `new Function` shims (`evalParamsLogic`, `evalToolInputLogic`, `evalToolOutputLogic`,
-`evalResponseParamsLogic`) go in `src/replay/logic.ts`, ported from BaseIn's
-[`src/scenarios/logic.ts`](../../../BaseIntSever/BaseIn/src/scenarios/logic.ts) — which is the same
-code with better comments and an `assertPlainObject` guard the other copies lack. **Port BaseIn's
-version**, not RRepeat's: it is the one the server evaluates against, so a divergence between them is
-a divergence between what a scenario does in a dry replay and what it does here.
-
-### 9.1 What flows between steps
-
-- **`params`** — computed once (derivation → `paramsLogic`), read by every `toolInputLogic`.
-- **`respParams`** — starts `{}`; each step's `toolOutputLogic` merges keys in
-  (`respParams = { ...respParams, ...derived }`); later steps' `toolInputLogic` read the accumulation.
-  This is how step 1's `highestRiskDeviceId` reaches step 2's input.
-
-In direct mode both live inside one `for` loop. In steer mode they are split across *separate HTTP
-requests* — which is what §7.3's ordering rule protects.
-
----
-
-## 10. Timing: what may block, and for how long
-
-The hook is on the user's critical path. Every await here is a stall the user watches.
-
-| Moment | Route | Hook timeout | What may be awaited | Budget |
-|---|---|---|---|---|
-| `UserPromptSubmit` | `/session/prompt` | **5 s → raise to 15 s** | `getMatch()` only | `BIR_MATCH_BUDGET_MS` = **2500** |
-| `PreToolUse` | `/tool/pre` | 30 s (unchanged) | `plan.ready()` (derivation) | `BIR_DERIVE_BUDGET_MS` = **8000** |
-| `run_scenario` | `/scenario/run` | MCP client's own | `ready()` + N steps | `BIR_REPLAY_BUDGET_MS` = **120000**, `BIR_STEP_TIMEOUT_MS` = **60000** |
-| `Stop` | `/session/stop` | 10 s | nothing (report is queued) | — |
-
-**Derivation is deliberately not awaited at the prompt.** The steering directive needs only the
-scenario's ordered tool names and reasonings — it does not need parameter values. So the prompt hook
-returns the directive the moment the match lands, and the Haiku call runs un-awaited; the *first*
-`PreToolUse` awaits it, inside a 30-second budget instead of a 15-second one. On a mode-`direct` turn
-the wait lands inside `run_scenario` instead, where there is no hook timeout at all.
-
-**Budget expiry is never an error.** Match budget expired → no plan, ordinary turn, one
-`replay.decision` line. Derivation budget expired → fall back to the scenario's recorded
-`sampleValue`s (D15) and keep going; a replay with stale parameters is worth more than no replay, and
-the audit line says which happened.
-
-**The one hook-config change** is `UserPromptSubmit`'s timeout, `5` → `15`, in
-[`HOOK_ROUTES`](../src/config/adapters/claude-code.ts). It must stay non-`async`: an async hook is
-fire-and-forget and cannot return `additionalContext` at all.
-
----
-
-## 11. Reporting: outcome, ticket, cost
-
-This is the half that makes replay *provable* rather than merely fast, and v1 does none of it.
-
-### 11.1 The outcome ladder
-
-```ts
-// Upgrade-only. `not_steered` is the floor and the safe answer if the turn dies mid-flight.
-const OUTCOME_RANK = { not_steered: 0, failed: 1, diverged: 2, steered_full: 3 } as const;
-```
-
-| Outcome | Means | Server-side effect |
-|---|---|---|
-| `not_steered` | Matched, declined at a gate; the agent ran the task | **baseline sample** (`addBaselineSample`) |
-| `failed` | Armed, then the machinery gave up; the agent ran the task | **baseline sample** |
-| `diverged` | The model went off-script; the bundle answered | ledger row, `saved_usd` computed |
-| `steered_full` | Every planned step ran with scenario-derived inputs | ledger row, `saved_usd` computed |
-
-Direct mode reports `steered_full`. BaseIn's zod enum
-(`['steered_full','diverged','not_steered','failed']`) has no `direct` member, and `steered_full`
-means exactly what happened: every planned step executed under the scenario's control and the
-response model was produced. A `direct` discriminator would be a *server* change and is §20's
-question 2, not a blocker.
-
-### 11.2 The ticket
-
-`matched.executionTicket` is the server's claim token, and **it is the execution row's id** — which
-is what makes a doubled report book once (`scenarios/routes.ts`: a `claimed` ticket returns
-`200 { duplicate: true }`, not an error). Redeem it exactly once, in `sealRun`, pushed onto
-`pendingSeals` alongside the answer resolution so `Stop` never blocks on the network:
-
-```
-POST /scenarios/:scenarioId/executions
-  { ticket, outcome, deriveCostUsd, sessionCostUsd, fallbackCostUsd,
-    durationMs, stepsPlanned, stepsPinned, measured, pricingVersion, prompt,
-    steps, error, errorStage, errorStepIndex, errorToolName }
-```
-
-An **unredeemed** ticket leaves no execution row at all. That asymmetry is intentional and worth
-preserving: silence loses a saving; it never invents one.
-
-### 11.2a What each step did (the service's errorshandling.md)
-
-The last five fields are the diagnosis, and none of the money depends on them. The service's
-recording page draws the scenario's chain step by step; without these, a scenario whose step 2
-throws on every replay renders as four healthy-looking steps beside a saving that never grows. The
-error exists — in a log line, on the operator's machine. The person who owns the scenario is looking
-at a web page.
-
-```ts
-steps: Array<{
-  stepIndex: number;          // the scenario's own index, not a position in this array
-  toolName: string;
-  status: "ok" | "recorded" | "skipped" | "failed";
-  stage?: ExecutionStage;     // where in the step, for `failed` / `skipped`
-  error?: string;             // message only — this is rendered in a web page
-  durationMs?: number;
-}>
-```
-
-`ok` and `recorded` are passes (`recorded` with an asterisk: the values came from the source run).
-`skipped` did not run. **`failed` is the only one that means the scenario is broken** rather than
-the environment — it is the scenario's own logic throwing, and it is what `Recalculate` fixes.
-
-Three rules this must keep:
-
-1. **A step the turn never reached is absent**, not `skipped`. The page shows those as "not run",
-   and a turn that dies at step 2 of 5 must not paint steps 3-5 red.
-2. **Every field is optional on the wire.** An older service ignores them; the costs still book.
-3. **The headline and the steps are one statement.** `error*` is lifted from the first `failed`
-   step (`blameStep`), never assembled independently, so the page's card cannot contradict the step
-   list underneath it.
-
-The verdicts come from `plan.ts`'s `onStep`, which has always known them — with one addition: a
-logic failure is announced *before* the throw propagates (`reportingStage`), because after it
-nothing knows which step the stack trace belonged to. In steer mode there is no loop to observe, so
-the controller records the verdict at both hooks: `PreToolUse` for an input-logic throw, `PostToolUse`
-for the pass or the output-logic throw. `ReplayState.stepResults` is keyed by step index so the
-second word on a step replaces the first.
-
-One consequence for the rule that a costless decline is not worth sending (`buildReport`, and the
-service's matching `202 { recorded: false }`): it now *is* worth sending when a step broke. No cost
-**and** no error remains nothing to report.
-
-### 11.3 Cost, and a live pricing hazard
-
-| Component | Source | Notes |
-|---|---|---|
-| `deriveCostUsd` | our own Haiku call's `usage`, priced locally | the only tokens replay itself spends |
-| `sessionCostUsd` | transcript usage **delta** for this run (§11.4) | the live turn: prompt, tool calls, answer |
-| `fallbackCostUsd` | **0.00** | direct execution spends no tokens (§8) |
-
-> ### ⚠ Verify the pricing table before copying it
->
-> A saving is `baseline − actual`, where the baseline is priced by BaseIn's
-> [`src/scenarios/cost.ts`](../../../BaseIntSever/BaseIn/src/scenarios/cost.ts) and the actual by the
-> runner's copy. Both currently declare `PRICING_VERSION = '2026-08-30'`, and **the two tables
-> already disagree**: RRepeat prices `claude-opus-4-6` at `3.0 / 15.0`, BaseIn at `5.0 / 25.0`. Equal
-> versions are supposed to mean *"these are comparable"*. Right now, for that row, they are not.
->
-> So: **copy BaseIn's table, not RRepeat's** — the server owns the baseline, and the baseline is the
-> number a saving is measured *against*. Copy `PRICING_VERSION` with it. Treat any price change as a
-> three-repository change, and file the drift above against RRepeat rather than reproducing it.
->
-> Practical exposure here is small — derivation runs on `claude-haiku-4-5-20251001`, which both
-> tables price identically at `1.0 / 5.0` — but the invariant is what matters, not today's blast
-> radius.
-
-### 11.4 The per-run usage watermark
-
-`savingCalcRunner.md` §3 documents this trap in RRepeat, and **BaseInstRunnerMCP has it too**, for
-the same structural reason: Claude Code writes one transcript per *session*, and `onPrompt` rolls a
-new run on every prompt. Summing the whole file gives run 3 the cost of runs 1+2+3.
-
-Every one of those numbers is a **baseline** on the server. Do not ship the whole-file version.
-
-```ts
-// src/control/transcript.ts — two new exports beside contextForToolUse / settledLastAssistantText
-/** Per-model cumulative usage, captured when a run starts. */
-export function markTranscriptUsage(path: string | undefined): UsageMark;
-/** Per-model delta since `mark`, clamped at 0 per field. */
-export function usageSince(path: string | undefined, mark: UsageMark): ModelUsage[];
-```
-
-Take the mark in `ensureRun`, beside `startedAtMs`, so the cost window and the duration window are
-the same window. Clamp per field, so a compacted or rotated transcript degrades to *"no usage"*
-rather than to a negative cost. A run with **no mark** (one opened lazily by a proxy step before any
-prompt) reports `measured: false` — better to say "unmeasured" than to hand the ledger an inflated
-baseline.
-
-`measured` is `true` only when a mark existed **and** `pricingVersion` matches the server's. The
-server enforces the second half itself and stores a mismatched report as unmeasured rather than
-trusting it.
-
----
-
-## 12. What the replayed turn records
-
-**Nothing, and that is correct.** The service answered `{ id: null }`; no run exists; every step post
-would 404. `run.recording = false` already handles it — `record()` early-returns and `sealRun` skips
-both the final answer and `finishRun`.
-
-Three consequences to keep straight:
-
-1. **Step indices are still allocated.** `ordering` runs regardless, correlations are still minted
-   and settled, and `bir doctor` still shows a live step count. Only the *sending* stops.
-2. **The matched run is the canonical one.** The server bumped its `iterations` at match time. The
-   corpus does not grow on a replay, by design — that is what stops one popular task from flooding
-   the similarity pool with near-duplicates.
-3. **Direct-mode calls bypass the recorder entirely.** They are issued via `UpstreamClient.request`,
-   which allocates a `bir:` id and consumes its own response in `accept()` before the relay's
-   handlers ever see it ([`src/upstream/client.ts`](../src/upstream/client.ts)). So
-   `RecordingInterceptor` never observes them and cannot double-record. That interface comment says
-   `request()` is *"Never used by the relay"* — it was built for `bir doctor` and tests, and this is
-   its second, load-bearing user.
-
-### 12.1 `bir replay` — the Tier 2 and debugging path
-
-```bash
-bir replay --scenario scn_… --prompt "check the fleet for high-risk devices"   # run it
-bir replay --scenario scn_… --prompt "…" --dry                                # derive + plan only
-```
-
-Runs the same plan through the same executor, against the same live proxies, printing the per-step
-input/output and the response model. It is how you test a scenario without a session, how a Tier 2
-or non-Claude-Code client gets any replay at all, and the first thing to reach for when a steered
-turn behaves oddly.
-
----
-
-## 13. Security
-
-v1 §9 holds unchanged. Replay adds two exposures, and neither is small.
-
-### 13.1 The scenario payload is executable code
-
-`toolInputLogic`, `toolOutputLogic`, `paramsLogic` and `responseParamsLogic` are JavaScript function
-*bodies*, compiled with `new Function` and run **in the control server process** — a process holding
-the user's BaseIn credentials and, through the proxies, live authenticated access to every wrapped
-MCP server.
-
-BaseIn's own `logic.ts` argues the eval is safe because *"these run only over data the owner already
-produced… so the dynamic eval is scoped to first-party content."* That argument holds here too, and
-the blast radius does not: BaseIn evaluates them against a database row, we evaluate them next to a
-browser and a GitHub token.
-
-What actually constrains it:
-
-- The payload arrives **only** in the response to an authenticated `POST /recordings/runs` against
-  the configured `BIR_AUTH_URL`, over the user's own token, describing the user's own runs. It is not
-  attacker-supplied in any ordinary threat model.
-- A `new Function` body gets its declared arguments **and the global scope**. `require` and `import`
-  are not reachable (ESM, no CommonJS wrapper), but `fetch`, `process` and `globalThis` are. Say this
-  plainly rather than implying a sandbox: **there is no sandbox.**
-- `BIR_REPLAY` is opt-in (D14), so a compromised or misconfigured `BIR_AUTH_URL` cannot start
-  executing logic on a machine whose operator never asked for replay.
-
-If that is not enough for a deployment, the mitigation is a real one and is out of scope here:
-evaluate the logic in a `node:vm` context with a frozen, minimal global. Filed as §20 question 3.
-
-**A hand-edited step is the same code, and runs the same way.** Since 2026-09-25 (the service's
-`editSteps.md`; built, not yet released) the owner — or Claude working for them — can change a step's
-logic with `bir scenario edit`. The service checks the change against the recording before it saves
-it, but that check is about *what the code computes*. Once saved, the step arrives in the same
-payload and runs here unattended, with `new Function`, next to the same credentials, exactly like
-calculated code. The provenance argument still holds: only the owner can edit, over their own token,
-and anyone else — an admin included — gets `404`. What changes is that *"the model wrote it"* is no
-longer always true.
-
-The service sandboxes its own evaluation of every logic body (built with the same service change;
-not yet released). It had to: there, one account's code runs next to every account's data and the
-service's secrets. How it is built:
-
-- **A fresh `node:vm` context for each evaluation**, with a time limit (`LOGIC_TIMEOUT_MS`). Only
-  JavaScript's own built-ins are in it, less `ArrayBuffer`, `SharedArrayBuffer`, `DataView`, the
-  typed arrays, `Atomics`, `WebAssembly` and `FinalizationRegistry`; `Symbol.for` and
-  `Symbol.keyFor` are removed too. No `require`, `process`, `fetch`, `Buffer` or timers. Values go
-  in and come out as JSON text only.
-- **That context lives in a separate evaluator process**, not in the service: an empty
-  environment, `--permission` (no files, no child processes), `--disallow-code-generation-from-strings`,
-  `--frozen-intrinsics`, and a heap of `LOGIC_MEMORY_MB`.
-- **A relay worker thread of the service drives that process.** No logic runs in the relay. It
-  kills the evaluator when a body runs too long, and the next job starts a new one; a body that
-  runs out of memory takes down only the evaluator, and is run once more on a fresh one before it
-  is blamed. The relay also replaces the evaluator when its heap stays above half of
-  `LOGIC_MEMORY_MB` after a job, and after 2,000 jobs. A body that overran its time or memory, or
-  took the evaluator down twice, is refused at once, with the same message, for the next 10
-  minutes.
-- **The hand-edit check runs in a check worker thread of its own**, with its own relay and
-  evaluator process, under a sandbox-time budget
-  (`EDIT_CHECK_BUDGET_MS`, 5000 ms by default; past it, *too costly to check*), so a slow check
-  never holds up the service's other requests.
-
-**The runner still does not sandbox.** Here the code runs on the owner's machine, for the owner's
-account, with `new Function`. One consequence to know: **the service's check only judges what a
-body returns for the recording's values.** Code that calls `fetch`, `process` or a timer on that
-path, and does not catch the error, throws in the check, so it cannot be saved without `--force`.
-But a call behind a `typeof` guard (`if (typeof fetch === "function") …`), or on a branch the
-recording's values never take, is never reached in the check; one inside a `try` fails there
-quietly. Such code passes, it is saved like any other change, and here it runs with `fetch`,
-`process` and timers all present. The service's sandbox protects the service; it proves
-nothing about what a body does on the runner. Read every hand edit before it is saved.
-
-### 13.2 Replay bypasses permission prompts
-
-This is the sharpest edge in the whole design, and it must not be buried.
-
-- **Steer mode** answers `PreToolUse` with `permissionDecision: "allow"`, so a pinned call is
-  auto-approved. The `BIR_CORRELATION_DECISION` note in `bir-hooks.ts` already documents this for
-  correlated MCP calls; steering extends it to **built-ins** — including `Bash` and `Edit`.
-- **Direct mode** never reaches `PreToolUse` at all. A `tools/call` dispatched to a proxy is not
-  visible to Claude Code's permission system in any form.
-
-So a scenario is, in effect, a **pre-approved list of tool calls with computed arguments**. That is
-precisely what makes it valuable, and precisely what makes it dangerous. Four mitigations, all
-required:
-
-1. `bir install --replay` a distinct, non-default flag; `BIR_REPLAY=0` a one-line kill switch once installed.
-2. `BIR_REPLAY_ALLOW_SERVERS` — a comma-separated allowlist of server keys eligible for **direct**
-   execution. Unset means *all wrapped servers*; the guide (§4 of `calculatedReplayGuide.md`)
-   recommends setting it.
-3. `bir doctor` prints `replay: on` and the effective allowlist, loudly, at the top. A capability this
-   sharp must never be discoverable only by reading a log.
-4. Every armed plan logs `plan.armed` with the scenario id, mode, step count and the ordered tool
-   names **before** the first call runs. The audit line precedes the action.
-
-### 13.3 The control plane
-
-`/scenario/run`, `/proxy/poll` and `/proxy/result` are ordinary control-server routes: loopback only,
-bearer token from the `0600` discovery file, same as `/proxy/step`. `/proxy/poll` holds a connection
-open for up to 25 s — a long-lived authenticated request, not a new trust boundary.
-
----
-
-## 14. Degradation matrix
-
-The governing rule is unchanged and outranks every optimisation here: **the host session must never
-fail because of BaseInstRunner.**
-
-| Failure | Behaviour |
-|---|---|
-| `getMatch()` slower than the match budget | No plan. Ordinary turn. One `replay.decision` line |
-| No `ANTHROPIC_API_KEY` | The service derives instead (segmented.md R-PARAM-5). Signed out as well: settings take their recorded `sampleValue`s, a scenario with a target declines `no_derive_key`, `deriveCostUsd: 0` |
-| The service declines, is slow, or cannot be reached | The same, with its reason carried into the `replay.derived` and `replay.decision` lines. Never a throw |
-| Derivation call fails or times out | Same as above, plus a `replay.derive_failed` line |
-| `toolInputLogic` throws | Divergence (§8) — never a crash |
-| `toolOutputLogic` throws | Retire the plan, abort to an ordinary turn, outcome `failed` |
-| Model calls an unexpected tool | Divergence (§8) |
-| A proxy has no open long-poll (dead, or `BIR_REPLAY` unset in its env) | That step falls back to `recordedOutput`, else is skipped with a warning |
-| A direct step exceeds `BIR_STEP_TIMEOUT_MS` | Same as above; the work item is abandoned server-side |
-| Whole plan exceeds `BIR_REPLAY_BUDGET_MS` | Return what completed, marked partial; outcome `diverged` |
-| `bir-scenario` cannot find the control server | `run_scenario` returns `isError: true`; the model proceeds normally |
-| Ticket redemption fails (offline, 409) | Logged; the turn is unaffected. An unredeemed ticket books nothing |
-| Two reports for one ticket (retry, `Stop` racing `SessionEnd`) | Server books once, answers `200 { duplicate: true }` |
-| `BIR_REPLAY` unset | Exactly v1: stop recording on a match, do nothing else |
-
----
-
-## 15. Solution layout
-
-```
-src/
-├─ replay/                       ← new
-│  ├─ plan.ts                    # ScenarioReplayPlan (§9)
-│  ├─ logic.ts                   # the four new Function shims — port BaseIn's (§9)
-│  ├─ derive.ts                  # Haiku parameter derivation over raw fetch (§16.3)
-│  ├─ pricing.ts                 # MODEL_PRICING + PRICING_VERSION — copy BaseIn's (§11.3)
-│  ├─ coverage.ts                # reachOf / modeFor (§5)
-│  ├─ bundle.ts                  # assembleBundle / truncate — port verbatim
-│  ├─ executor.ts                # direct step dispatch + the work queue (§16.2)
-│  ├─ source-run.ts              # lazy GET /recordings/runs/:id → recorded outputs by tool (§8.1)
-│  └─ types.ts                   # SerializedScenario, SerializedScenarioStep
-├─ bin/
-│  ├─ bir-scenario.ts            ← new: the `bir` MCP server — `run_scenario` (§6.3), later the scenario tools (§16.5)
-│  └─ bir.ts                     # + `--replay`, `bir scenario …`, `bir replay` (§16.5)
-├─ control/
-│  ├─ server.ts                  # + arm / pin / thread / dispatch / report
-│  └─ transcript.ts              # + markTranscriptUsage / usageSince (§11.4)
-├─ proxy/
-│  └─ session.ts                 # + the long-poll work loop (§16.2)
-├─ record/
-│  ├─ recorder.ts                # + reportExecution() on the Recorder surface
-│  └─ remote-recorder.ts         # + POST /scenarios/:id/executions
-└─ config/adapters/claude-code.ts # UserPromptSubmit timeout 5 → 15; the `bir` MCP entry
-```
-
-`package.json` gains one bin: `"bir-scenario": "dist/bin/bir-scenario.js"`. Runtime dependencies stay
-at **zero** (§16.3).
-
----
-
-## 16. Contracts
-
-### 16.1 Control-plane routes (new)
-
-```ts
-// bir-scenario → control server
-POST /scenario/run    {}
-  → 200 { ok: true, text: string, responseModel: object, steps: number, partial?: boolean }
-  → 200 { ok: false, why: "no_plan" | "not_ready" | "budget_exceeded" }
-
-// proxy → control server (long-poll; holds up to 25 s, then answers empty)
-POST /proxy/poll      { serverName: string }
-  → 200 {} | 200 { work: { workId: string; toolName: string; arguments: unknown; timeoutMs: number } }
-
-// proxy → control server
-POST /proxy/result    { workId: string, result?: unknown, error?: string }
-  → 200 { ok: true }
-```
-
-### 16.2 The direct executor
-
-```ts
-// src/replay/executor.ts
-export type ExecuteStep = (step: SerializedScenarioStep, input: Record<string, unknown>) => Promise<string>;
-
-/** Hands work to the proxy that owns `serverName` and awaits its result. */
-export class ProxyWorkQueue {
-  /** Called by POST /proxy/poll. Resolves with work, or with undefined at the poll deadline. */
-  waitForWork(serverName: string, pollDeadlineMs: number): Promise<Work | undefined>;
-  /** Called by POST /proxy/result. */
-  complete(workId: string, result?: unknown, error?: string): void;
-  /** Dispatch and await one call. Rejects on timeout or on no registered proxy. */
-  call(serverName: string, toolName: string, args: unknown, timeoutMs: number): Promise<unknown>;
-}
-```
-
-> **[built] "No poller parked" is not the same as "no proxy".** The first implementation rejected
-> `call` immediately whenever no poller was waiting, on the reasoning that queued work could stall a
-> turn past its budget. That reasoning holds for a server no proxy serves — and is wrong for the case
-> that actually dominates: a proxy is *between* polls precisely while it is POSTing one step's result
-> and re-polling, which is exactly the gap between two steps of a multi-step plan. The end-to-end test
-> caught it as "step 2 of 2 never ran".
->
-> So the queue tracks `lastSeen` per server. Work dispatched while a recently-seen proxy is
-> mid-round-trip is **held** for its next poll; the per-call timeout still bounds the wait, and a
-> server nothing has served for a minute still fails fast into the recorded-output fallback.
-
-Proxy side, in `ProxySession` — started after a successful `register()`, only when `BIR_REPLAY=1`:
-
-```ts
-while (!closed) {
-  const work = await control.poll(this.serverName);          // 25 s long-poll
-  if (!work) continue;
-  try {
-    // The reserved `bir:` id space, built for exactly this and never used by the relay.
-    const result = await this.upstream.request("tools/call",
-      { name: work.toolName, arguments: work.arguments },
-      AbortSignal.timeout(work.timeoutMs));
-    await control.result(work.workId, result);
-  } catch (err) {
-    await control.result(work.workId, undefined, errText(err));
-  }
-}
-```
-
-Note `work.toolName` is the **upstream-local** name (`navigate_page`), not the qualified one —
-`parseQualifiedName` splits it at dispatch. Storing both parts is what v1 §5 bought.
-
-> **[built] The proxy needs no replay configuration of its own.** `/proxy/register` answers
-> `{ replay: boolean, pollHoldMs }`, and the loop opens only if that says so. `BIR_REPLAY` is
-> therefore a single switch on the control server, with no second copy in each wrapped entry's `env`
-> to drift out of step with it.
-
-### 16.3 Derivation without a dependency
-
-```ts
-// src/replay/derive.ts — no SDK; ~50 lines of fetch.
-export async function deriveParameters(opts: {
-  prompt: string;
-  intent: string;
-  paramsObject: Record<string, { sampleValue: unknown; description: string }> | null;
-  apiKey?: string;                       // ANTHROPIC_API_KEY — an override
-  service?: { baseUrl: string; token: string; scenarioId: string };  // the default path
-  model?: string;                        // default claude-haiku-4-5-20251001
-  signal?: AbortSignal;
-}): Promise<{ params: Record<string, unknown>; costUsd: number; derived: boolean }>;
-```
-
-Behaviour, matching RRepeat's `deriveParametersFromScenarioPayload` exactly so the two produce the
-same parameters from the same prompt:
-
-- No `paramsObject` keys → `{}`, `costUsd: 0`.
-- **No `apiKey` but a `service` → `POST {baseUrl}/scenarios/{id}/derive`** with the turn (prompt,
-  live call, recent results) and a bearer token, `derived` as the service answered. This is the
-  ordinary path: nearly every session runs inside Claude Code on a subscription and has no key of
-  its own (segmented.md R-PARAM-5). The answer is re-normalised here against this runner's own copy
-  of the schema, so the gate reads a `missing` computed from what will actually run.
-- **Neither → return every key's recorded `sampleValue`**, `costUsd: 0`, `derived: false`. Settings
-  stand on their samples; a scenario with a target declines rather than run on a stale one.
-- With an `apiKey`, `POST https://api.anthropic.com/v1/messages` with the same extraction prompt,
-  tolerant JSON extraction (first balanced `{…}`, `undefined` → `null`), and any `null`/missing
-  **setting** filled from its `sampleValue` — a `null` target is named in `missing` instead.
-
-Keeping this dependency-free is not purity. `bir-proxy` is spawned inside the host's process tree for
-*every* wrapped server; an npm install that pulls a model SDK into that path is a startup-latency and
-supply-chain cost paid N times per session, for a feature most sessions never arm.
-
-### 16.4 `Recorder` gains one method
-
-```ts
-export interface ScenarioReporter {
-  reportExecution(r: {
-    scenarioId: string; ticket?: string;
-    outcome: "steered_full" | "diverged" | "not_steered" | "failed";
-    deriveCostUsd: number; sessionCostUsd: number; fallbackCostUsd: number;
-    durationMs: number; stepsPlanned: number; stepsPinned: number;
-    measured: boolean; pricingVersion: string; prompt?: string;
-  }): void;
-}
-export function isScenarioReporter(r: Recorder): r is Recorder & ScenarioReporter;
-```
-
-Optional capability, discovered the same way `isMatchAware` is — so `NullRecorder` needs no change
-and a session with no BaseIn credentials still replays (it just books nothing).
-
-### 16.5 CLI surface
-
-`bir` gains one flag and one command group. Everything here is a thin client over service
-endpoints, except `bir replay`, which drives §16.2's executor directly.
-
-```
-bir install --replay          register the `bir` MCP server; raise the prompt-hook timeout to 15 s
-bir uninstall --replay        reverse exactly that, leaving the rest of the install alone
-
-bir scenario list             GET  /recordings/runs               runs, iterations, scenario state
-bir scenario show <runId>     GET  /recordings/runs/:id/scenario  intent, params, steps, logic
-bir scenario show <scnId>     GET  /scenarios/:id                 the same, by scenario id (segments too)
-                                   [--step <n>: one step, with scenarioId and chainRevision first]
-bir scenario calc <runId>     POST /recordings/runs/:id/calculate     [--force to re-derive in place]
-                                   [--force --discard-edits: re-derive a plan with hand edits]
-bir scenario calc <scnId> --force
-                              POST /scenarios/:id/recalculate    recalculate in place (segments too)
-                                   [--discard-edits: sends {discardEdits: true}]
-bir scenario replay <scnId> --prompt "…" [--dry]
-
-bir scenario check <id> --step <n>    POST  /scenarios/:id/steps/:n/check        try a change; writes nothing
-bir scenario edit  <id> --step <n>    PATCH /scenarios/:id/steps/:n              the same check, then save
-bir scenario edits <id>               GET   /scenarios/:id/edits                 the history, newest first
-bir scenario undo  <id> [--edit <e> | --step <n>]
-                                      POST  /scenarios/:id/edits/:e/revert       take back the newest edit (of step n)
-bir scenario editing on|off|status    (no route) ~/.baseinstrunner/installed.json  which `bir` MCP tools are offered
-
-bir replay --scenario <scnId> --prompt "…" [--dry]     alias; the Tier 2 / debugging path (§12.1)
-```
-
-The second group, and `show <scnId>`, `--step`, `calc <scnId>` and `--discard-edits`, were added
-on 2026-09-25 by the service's `editSteps.md`. They are built and tested, and not yet released in
-the form described here (version 0.2.11 on npm has an early form): they need the next
-`@basein/runner` version and a service deploy, because their routes are new on the service. They
-are where `bir` changes a scenario by hand, so the rules are strict:
-
-- **Owner only.** Anyone else, an admin included, gets `404`, never `403`.
-- **A change is saved only if it reproduces the recording and is not a copy**, or on purpose with
-  `--force --note "<why>"`. `check` and `edit` run the same check; `check` never writes. When the
-  check had any problem, a forced save is recorded as forced, and `bir investigate` keeps saying so.
-- `<id>` is a `run_` id, resolved to its whole-run scenario with `GET /recordings/runs/:id/scenario`,
-  or a `scn_` id, used as it is. A sub-task scenario has only its `scn_` id; for a run with only
-  sub-task scenarios, `bir` lists their `scn_` ids. Logic goes in with `--input-logic` /
-  `--output-logic` from a file, or `-` for stdin — never inline, because shell quoting mangles
-  JavaScript. `edit` also takes `--freeze`, `--unfreeze`, `--note` and `--revision <n>` (the
-  `expectedRevision` of the body).
-- `show --step <n>` prints the step object with `scenarioId` and `chainRevision` first. The revision
-  is the scenario's, and is what `--revision` takes.
-- **`undo` walks back.** Without `--edit` it takes back the newest edit (never an undo entry) that
-  can be undone; with `--step <n>`, the newest edit of step `n`. Run again, it goes one further
-  back. `--edit` and `--step` cannot be given together. To redo, undo the undo entry by its
-  `sedit_` id; the undo prints that command. The service checks an undo like a save, for the later
-  steps and the final answer (so only when it changes output logic), and answers
-  `422 undo_refused` when it would break them, unless `--force --note "<why>"` is given. Every
-  save and every undo bumps the scenario's `chainRevision`.
-- A save lifts a mark made by hand (`--freeze`, `by_hand`) only with `--unfreeze`; undoing the
-  freeze, or `calc --force --discard-edits`, also removes it. A forced save lifts only a mark the
-  calculation set.
-- `calc --force` answers `409 scenario_has_edits` on a plan with hand edits, unless
-  `--discard-edits` is given. `calc <scnId>` without `--force` is a usage error: nothing is sent.
-- Answers `bir` puts in words: `400 nothing_to_change` (the code and mark asked for are the step's
-  already), `413 payload_too_large`, `503 logic_sandbox_unavailable` (nothing was checked, saved or
-  undone), and a check report with `noChange: true` (`check` then says nothing would change, and
-  exits `0`).
-- Exit codes: `0` checked OK, saved or undone; `1` refused, not found, or a service error; `2`
-  usage. `--json` prints the service's body unchanged.
-
-The same commands are tools on the `bir` MCP server. `scenario_show` (`target`, `step`),
-`scenario_edits` (`target`) and `investigate` (`id`) only read, and are always offered.
-`scenario_check` (`target`, `step`, `inputLogic`, `outputLogic`, `unfreeze`), `scenario_edit` (the
-same, plus `freeze`, `force`, `note`, `revision`) and `scenario_undo` (`target`, `edit` or `step`,
-`force`, `note`) are offered only in a project where `bir scenario editing on` was run, because that
-server runs in every session of every installed project. Each tool runs this package's own
-`bir … --json`, with logic bodies passed through temporary files; a refusal comes back as an MCP
-error result carrying the report. A call the host cancels, or leaves behind when it exits, has its
-`bir` stopped and its files removed.
-
-**`bir`'s own calls are never recorded** (the service's `editSteps.md` D13; not yet released). The
-`bir` server's tools other than `run_scenario`, and a `Bash` or `PowerShell` command made only of
-`bir` invocations (and a plain `cd`), are host housekeeping, like `ToolSearch`
-([housekeeping.ts](../src/record/housekeeping.ts)). They are never recorded as steps, and never
-count as divergence from a plan. A session that fixes a plan must not become a plan that edits
-plans when it is replayed. The operator's walk-through is
-[calculatedReplayGuide.md](calculatedReplayGuide.md) §9.2.
-
-`--dry` maps to BaseIn's `POST /scenarios/:id/replay`, which evaluates the stored logic against the
-source run's *recorded* outputs — no real tools, no side effects, one Haiku call. Without `--dry`,
-`bir replay` runs the same plan through the same executor against the live proxies. `bir doctor`
-gains a `replay` block: on/off, the effective `BIR_REPLAY_ALLOW_SERVERS` allowlist,
-`BIR_MIN_STEER_SIMILARITY`, and who derives — this machine, the service, or nobody, which is the
-state in which a scenario with a target never runs (§13.2, mitigation 3).
-
----
-
-## 17. Implementation phases
-
-Each phase ends in something runnable. Do not start a phase before its predecessor's acceptance test
-passes.
-
-### Phase R0 — Plan, logic, coverage (no wiring)
-Port `logic.ts` from BaseIn, `bundle.ts` and `ScenarioReplayPlan` from RRepeat, write `coverage.ts`.
-Pure, dependency-free, no I/O.
-**Acceptance:** unit tests replay a fixture `SerializedScenario` end to end against a stub executor
-and reproduce the recorded outputs byte for byte.
-
-### Phase R1 — Derivation and pricing
-`derive.ts` + `pricing.ts`. Both fully testable against a fake `fetch`.
-**Acceptance:** with no key, derivation returns sample values at zero cost; with a stubbed key, it
-parses fenced JSON, bare JSON and prose-wrapped JSON, and prices a known `usage` to the same cent as
-BaseIn's `cost.ts`.
-
-### Phase R2 — Arming and the decision log
-`onPrompt` awaits `getMatch()` under budget, runs the gate ladder, computes the mode, arms the plan,
-returns the directive. **No execution yet.**
-**Acceptance:** a fake recorder returns a match; assert exactly one `plan.armed` or one
-`replay.decision` line per prompt, the right mode, and that the prompt hook returns inside the
-budget when `getMatch` never resolves.
-
-### Phase R3 — Steer mode
-`/tool/pre` pinning (with the §7.1 `updatedInput` merge), `/tool/post` threading (with the §7.2
-source split), retire on done.
-**Acceptance:** a scripted hook sequence drives a 3-step plan to `steered_full`; a wrapped-MCP step
-threads from `/proxy/step` and not from the hook; reordering the model's calls produces exactly one
-divergence and no crash.
-
-### Phase R4 — The work queue and direct execution
-`ProxyWorkQueue`, `/proxy/poll`, `/proxy/result`, the proxy-side loop.
-**Acceptance:** against `test/fake-upstream.ts`, a 3-step direct plan executes with `respParams`
-threaded between steps; killing the proxy mid-plan degrades to `recordedOutput`/skip and the session
-survives.
-
-### Phase R5 — `bir-scenario` and direct delivery
-The MCP server, `/scenario/run`, `bir install --replay`.
-**Acceptance:** a real Claude Code session on a fully-wrapped scenario answers from one
-`run_scenario` call, and the transcript shows a genuine `tool_result`.
-
-### Phase R6 — Divergence
-Direct-execute the remainder; the lazy source-run fetch for `live` steps (§8.1); Bash-clean,
-`bir`-tool and deny delivery; the fair-share bundle cap.
-**Acceptance:** forcing an off-script call produces a bundle under `MAX_REPLAY_REASON` containing
-every remaining step; a `live` step is served its recorded output, marked `(recorded)`, and threads
-`respParams` for the steps after it; a `live` step with no recorded output is skipped with a warning
-and later steps still resolve.
-
-### Phase R7 — Reporting
-The usage watermark, `reportExecution`, ticket redemption in `sealRun`, `bir doctor` fields.
-**Acceptance:** three prompts in one session produce three *non-cumulative* `sessionCostUsd` values;
-a declined match books a baseline sample; a doubled report books once.
-
----
-
-## 18. Testing
-
-Extends v1 §11; same `node:test` harness, same `test/fake-upstream.ts`.
-
-1. **Plan semantics** — `respParams` threading, `paramsLogic` applied once, `isDone` after the last
-   step, throw-propagation for each of the four logic hooks.
-2. **Coverage** — every combination of wrapped/unwrapped MCP and built-in maps to the right mode,
-   including the empty-steps and all-live cases.
-3. **The `updatedInput` merge (§7.1)** — a pinned wrapped-MCP call carries both the pinned arguments
-   and `__bir_call_id__`; the correlation's `hookArgs` are the *pinned* ones; `--no-correlation`
-   still pins.
-4. **The threading source (§7.2)** — a wrapped step threads the proxy's `result`, not the hook's
-   `tool_response`, and threads the hook's view only after the grace window, with the warning.
-5. **Budgets** — a `getMatch` that never resolves still returns the prompt hook inside its budget;
-   a derivation that never resolves still pins, using sample values.
-6. **Direct execution** — end to end through `fake-upstream`, including a step timeout, a dead proxy
-   and a `tools/call` that returns `isError: true` (which is a *result*, not a failure — it must
-   thread).
-7. **Divergence** — each of the three delivery channels; delimiter neutralisation in the Bash path;
-   the fair-share cap with one enormous response and four small ones.
-8. **Reporting** — the watermark across three prompts; each outcome's server-side effect against a
-   fake BaseIn; ticket idempotence.
-9. **Integration** — a real Claude Code session against `fake-upstream` with a hand-written scenario,
-   asserting a `steered_full` report. The only test that catches host-behaviour drift.
-
----
-
-## 19. Rejected alternatives
-
-**19.1 Deliver direct-mode results as `additionalContext`.** No extra MCP server, no extra tool in the
-list. Rejected: it must execute inside `UserPromptSubmit`'s timeout (§10), and it asserts to the model
-that tools ran without a transcript record that they did. §6.2.
-
-**19.2 A callback URL per proxy instead of long-polling.** Faster dispatch, no idle connection.
-Rejected: N new loopback listeners, N new tokens, N new things `bir doctor` must verify — for a
-latency saving of milliseconds on a path already dominated by the upstream's own round trip. Dialling
-out is also the posture v1 §9 already chose everywhere else. D12.
-
-**19.3 Give `bir-scenario` its own upstream connections.** Then no work queue at all. Rejected
-outright: it double-spawns every upstream. Two `chrome-devtools-mcp` processes means two browsers,
-two profiles, and a scenario that navigates one and screenshots the other.
-
-**19.4 Port RRepeat's Agent-SDK divergence fallback.** Rejected: it is the dominant cost of RRepeat's
-calculated run (`savingCalcRunner.md` §4), it adds `@anthropic-ai/claude-agent-sdk` to a
-zero-dependency package, it needs anti-recursion guards, and here it buys nothing the proxies do not
-already buy for free. §8.
-
-**19.5 Block the prompt and answer from the scenario alone.** The original RRepeat design, superseded
-there (`replay.md` §1, §10). Rejected for the same reasons plus one of ours: it forfeits the live
-session's built-in tools entirely, which is exactly the half of a mixed scenario the proxy cannot
-reach.
-
-**19.6 Match on the whole conversation rather than the prompt.** Arguably better "similar meaning".
-Rejected as a *server* concern: `findSimilarRun` embeds `run.input`, and changing what is embedded
-changes the corpus, the threshold and every stored vector. §20 question 1.
-
----
-
-## 20. Open questions
-
-1. **Should the match embed more than the first prompt?** A turn's meaning often lives in the
-   preceding turn. Changing it is a BaseIn-side decision with a corpus migration attached, and it
-   would let `bir` match mid-conversation rather than only at a turn boundary.
-2. **Does BaseIn want a `direct` outcome?** Today direct mode reports `steered_full`, which is
-   accurate but hides that the run cost no session tokens at all. A fifth enum member would let the
-   ledger separate "the model was steered cheaply" from "the model did not run the task."
-3. **`node:vm` for the logic bodies?** §13.1 states plainly that there is no sandbox. A frozen,
-   minimal context would cost little and close the gap between "first-party by provenance" and
-   "first-party by construction."
-4. **Should a declined match still arm a *dry* plan?** Deriving parameters and computing the first
-   step's input without executing anything would make `bir doctor` able to say *"this scenario would
-   have run these three calls"* — excellent for tuning `BIR_MIN_STEER_SIMILARITY`, at the price of a
-   Haiku call on turns that replay nothing.
-5. **Should `scenario_steps` carry `recorded_output`?** §8.1 works around its absence with one lazy
-   `GET /recordings/runs/:runId`. A column would make it a field read, would let a scenario outlive
-   the deletion of its source run, and would finally make RRepeat's `recordedOutput` field mean
-   something. Cost: the scenario row grows by the size of every step's output.
-6. **Cwd fit.** A scenario recorded in project A may pin paths that do not exist in project B, and
-   nothing currently checks. A cheap sixth gate — compare `run.metadata.cwd` — would catch the common
-   case; the general case (relative paths, monorepos) is harder and probably belongs in
-   `toolInputLogic` generation server-side.
+# Calculated Replay — running a scenario on a similar-meaning match
+
+> Design doc for BaseInstRunnerMCP **v2** ([BaseInstRunner.md](BaseInstRunner.md) §12), the
+> milestone the v1 design deferred: *"Serve recorded results; port RRepeat's divergence handling."*
+>
+> **What it adds.** When the user's prompt means the same thing as a prompt they have run before,
+> the BaseIn service says so and hands back the *calculated scenario* derived from that earlier run.
+> This document specifies what BaseInstRunnerMCP does with it: derive the new prompt's parameters,
+> run the scenario's tool sequence against live data, and let the model answer from genuine results —
+> instead of rediscovering the same plan token by token.
+>
+> **Status:** implemented. Phases R0–R7 (§17) are in `src/replay/`, wired through the control server
+> and the proxies, covered by `test/replay.test.ts` and `test/replay-server.test.ts`, and proved end
+> to end with real processes by `test/smoke-replay.mjs`. Notes marked **[built]** are where the
+> implementation settled something this design left open, and notes marked **[changed]** are where
+> the production-readiness work later changed what a phase built. [production.md](../production.md)
+> holds the production contract: budgets, environment variables, and what fails how.
+> **Reference implementation:** RRepeat's [`docs/replay.md`](../../../BasInstRunner/RRepeat/docs/replay.md)
+> §3, §12, §13 and [`docs/savingCalcRunner.md`](../../../BasInstRunner/RRepeat/docs/savingCalcRunner.md).
+> **Server contract:** BaseIn `src/recordings/routes.ts`, `src/scenarios/{routes,repo,replay,logic}.ts`.
+
+---
+
+## 0. The one fact that makes this different from RRepeat
+
+RRepeat and BaseInstRunnerMCP are solving the same problem from opposite sides of the tool call.
+
+RRepeat **observes** a Claude Code session through hooks. It has no execution path of its own, so
+when a replay diverges it must spawn a *second* Claude Agent SDK session to run the remaining tools
+for real (`sdk-tool-session.ts`, `replay.md` §13). Its own savings doc names the consequence:
+
+> *"the **dominant** cost of today's calculated run is a full second agent session, and it is the one
+> cost nobody counts."* — `savingCalcRunner.md` §4
+
+BaseInstRunnerMCP **is** the execution path for MCP. Every wrapped server is reached through a
+`bir-proxy` process that already holds an initialized, live `UpstreamClient` to it
+([`src/upstream/client.ts`](../src/upstream/client.ts)). Issuing a `tools/call` on that connection
+costs **zero tokens** and requires no second agent, no subprocess, and no model in the loop.
+
+Everything below follows from that. Where RRepeat has one replay mode and an expensive fallback,
+this design has a ladder whose cheapest rung is free — and the more of a stack sits behind
+`bir-proxy`, the further down the ladder a scenario lands.
+
+| | RRepeat | BaseInstRunnerMCP |
+|---|---|---|
+| Runs MCP tools itself | No (`replay.md` §12: *"rrepeat never executes tools — not even MCP"*) | **Yes**, on the connection it already owns |
+| Divergence fallback | A second Agent SDK session — the dominant cost | Direct `tools/call` through the proxies — **$0** |
+| Reaches built-ins (`Bash`, `Read`) | Only by steering the live session | Same — only by steering the live session |
+| Needs `@anthropic-ai/*` at runtime | Yes | No (§16.3) |
+
+---
+
+## 1. Decisions locked
+
+Continuing v1's D1–D8.
+
+| # | Decision | Choice | Consequence |
+|---|---|---|---|
+| **D9** | What a match buys | **Execute the scenario**, do not merely stop recording | v1's `watchForMatch` already detects the hit and stops; this replaces the no-op with work |
+| **D10** | Who decides the mode | **Tool coverage**, computed per scenario at arm time (§5) | A fully-wrapped scenario replays for free; a mixed one steers the live session |
+| **D11** | Execution ownership for MCP steps | **The proxy that owns the upstream** | No second connection, no double-spawned browser, no Agent SDK dependency |
+| **D12** | Control → proxy channel | **Long-poll**, proxy dials out | No new listeners, no new ports, no new tokens (§13.3, §19.2) |
+| **D13** | Result delivery in direct mode | A **first-party MCP server** (`bir`), one tool | The model reads a genuine `tool_result`, never a `deny` reason it distrusts (§19.1) |
+| **D14** | Default state | **On** once `bir install --replay` has run; `BIR_REPLAY=0` turns it off | Replay bypasses permission prompts (§13.2); the install flag is the opt-in, the env var is the kill switch |
+| **D15** | Parameter derivation | One Haiku call over raw `fetch`; **no API key ⇒ recorded sample values** | Preserves v1's zero-runtime-dependency property, and degrades to a free replay |
+| **D16** | Savings reporting | Every armed match reports to `POST /scenarios/:id/executions`, including declines | A decline is a *baseline sample*, not silence — it is what keeps the ledger honest |
+
+### 1.1 Non-goals
+
+- **Replay in Tier 2.** A match is a match *on the prompt*, and a standalone proxy never sees one
+  (§0.1 of the v1 design). Tier 2 gets the manual `bir replay` command (§12.1) and nothing automatic.
+- **Chaining scenarios.** RRepeat's `next`/`getScenarioChain` has no counterpart in BaseIn's
+  `serializeScenario` payload, which serializes exactly one scenario. Out of scope.
+- **Editing tool descriptions to steer selection.** Still a non-goal, unchanged. §6's `bir` server
+  adds one *first-party* tool and touches no upstream schema — and it costs context in every session,
+  which is why D14 makes it opt-in.
+- **Recording the replayed turn.** The service created no run for it, by design. §12.
+
+---
+
+## 2. The match, and where it already works
+
+Nothing in this section is new. It is already implemented and already runs on every prompt.
+
+```
+UserPromptSubmit
+   └─ ControlServer.onPrompt          src/control/server.ts
+       └─ ensureRun → recorder.startRun(input, metadata)
+           └─ RemoteRecorder.startRun     POST /recordings/runs { id, framework, input, metadata }
+               └─ BaseIn recordings/routes.ts:
+                    findSimilarRun(userId, input)         ← embed + cosine over the user's runs
+                    ├─ miss → 201 { id, matched: null }
+                    └─ hit  → 200 { id: null, matched: {...} }   ← no run is created
+```
+
+On a hit the server answers with the whole thing — there is no follow-up fetch:
+
+```jsonc
+{
+  "id": null,
+  "matched": {
+    "runId": "run_…",              // the canonical earlier run
+    "scenarioId": "scn_…",         // its calculated scenario, when one is ready
+    "similarity": 0.94,            // cosine, ≥ SIMILARITY_THRESHOLD (server default 0.9)
+    "executionTicket": "tkt_…",    // redeem exactly once at POST /scenarios/:id/executions
+    "scenario": { /* serializeScenario(): intent, paramsObject, paramsLogic,
+                     responseParamsLogic, steps[{ stepIndex, toolName,
+                     toolInputLogic, toolOutputLogic, reasoning }] */ }
+  }
+}
+```
+
+[`RemoteRecorder.getMatch(runId)`](../src/record/remote-recorder.ts) already exposes it, and
+[`ControlServer.watchForMatch`](../src/control/server.ts) already consumes it — to do exactly one
+thing:
+
+```ts
+run.recording = false;
+logLine("run.matched", { …, why: "similar prompt — the service kept its own run; not recording this one" });
+```
+
+**That is the whole of v1's replay support: a correct stop.** This design replaces the stop with a
+plan, and keeps the stop.
+
+### 2.1 What "similar meaning" means, precisely
+
+Server-side, and worth stating because the threshold in §4 is a judgement about it:
+
+- The embedding is of the run's **`input`** — the user's prompt — computed by
+  `Xenova/all-MiniLM-L6-v2` (`EMBEDDING_MODEL`), mean-pooled and normalized
+  (`recordings/embeddings.ts`).
+- Candidates are **the caller's own canonical runs only** (`listUserRunEmbeddings(userId)`);
+  duplicates and sub-threshold runs are excluded from the pool at record time.
+- The match is the single best cosine ≥ `SIMILARITY_THRESHOLD` (default **0.9**).
+- A matched run only carries a `scenarioId` when its scenario exists **and** is `state: 'ready'`.
+
+So "similar meaning" is: *the same user asked for something that embeds within 0.1 cosine of this,
+and we finished calculating a reusable plan for it.* It is not "the same words", and it is not
+cross-tenant.
+
+---
+
+## 3. Architecture
+
+```mermaid
+graph TB
+  subgraph host["Claude Code session"]
+    M[model loop]
+    H[hooks]
+  end
+
+  subgraph bir["BaseInstRunnerMCP"]
+    C["bir-hooks — control server<br/>ScenarioReplayPlan lives here"]
+    S["bir-scenario<br/>MCP server: run_scenario"]
+    P1["bir-proxy — chrome-devtools"]
+    P2["bir-proxy — github"]
+  end
+
+  U1[chrome-devtools-mcp]
+  U2[github mcp]
+  R[("BaseIn /recordings/* /scenarios/*")]
+
+  H -->|"UserPromptSubmit → directive"| C
+  H -->|"PreToolUse → pinned updatedInput"| C
+  H -->|"PostToolUse → real output"| C
+  M -->|"mcp__bir__run_scenario"| S
+  S -->|"POST /scenario/run"| C
+  C -.->|"work: tools/call"| P1
+  C -.->|"work: tools/call"| P2
+  P1 -->|"bir: id request"| U1
+  P2 -->|"bir: id request"| U2
+  C -->|"match + execution report"| R
+```
+
+Three additions to the v1 topology, and nothing else moves:
+
+| Component | New? | Role in replay |
+|---|---|---|
+| `bir-hooks` control server | extended | Holds the `ScenarioReplayPlan` on `RunState`. Arms it, pins inputs, threads outputs, dispatches direct steps, redeems the ticket |
+| `bir-proxy` | extended | Long-polls for work; executes a `tools/call` on the upstream it already owns |
+| `bir-scenario` | **new**, ~120 lines | A stdio MCP server exposing one tool, `run_scenario`. The delivery channel for direct mode (§6). It later gained the scenario tools of §16.5 |
+
+---
+
+## 4. The gate ladder
+
+Ported from RRepeat's `applyMatch`, with one gate this repo needs and RRepeat cannot have.
+Every gate that declines logs **one** `replay.decision` line carrying the reason — because
+*"a scenario existed and was not used"* is a fact an auditor needs as much as *"a scenario ran"*.
+
+| # | Gate | Declines when | Outcome floor |
+|---|---|---|---|
+| 1 | **A match arrived** | `getMatch()` resolved `null`, or the budget expired (§10) | (no report — nothing matched) |
+| 2 | **Replay enabled** | `BIR_REPLAY === "0"`, or, with it unset, the project's stored switch is off (`bir replay off`, or a `bir install` without `--replay`) | `not_steered` |
+| 3 | **Scenario ready** | `scenario == null`, `state !== "ready"`, or `steps.length === 0` | `not_steered` |
+| 4 | **Similarity** | `similarity < BIR_MIN_STEER_SIMILARITY` (default **0.92**) | `not_steered` |
+| 5 | **Tool coverage** | No step is executable anywhere (§5 → `mode: "none"`) | `not_steered` |
+
+Past the table, a plan can still be refused before the model hears of it, each refusal with its own
+`replay.decision` code. The match is not waited on at all while the service is cooling down after a
+failure (`service_unhealthy`), or while prompts are holding off a service that answered matches
+slowly (`match_slow`, the match gate, §10). A match or a plan that is not ready
+inside the prompt's budget (§10) is dropped (`match_timeout`, `arm_timeout`), and one that lands
+after the prompt was answered is retired unannounced (`match_late`, `arm_unannounced`). A `direct`
+plan is declined when no running `bir-scenario` has said it serves `run_scenario`
+(`no_delivery_tool`, §6.3). In plan mode (`permission_mode: "plan"`) nothing is announced at all.
+
+Gate 4 deserves its own note. The server's own detection threshold is 0.9, and it uses it to decide
+*"do not record this again"* — a cheap claim: the worst case is a lost recording. Steering makes a
+much stronger claim: *"do not think about this again."* A prompt that is 0.90-similar usually covers
+only part of the live task, and steering it produces a confident, thin, wrong answer. So the steer
+threshold sits **above** the detection threshold by default, and `BIR_MIN_STEER_SIMILARITY` is the
+single knob an operator turns after watching `replay.decision` lines for a week.
+
+`not_steered` as the floor is not a failure code. It is the **control group**: the prompt matched,
+the agent ran the task the ordinary way, and the cost of doing so is a fresh measurement of what this
+task costs — which is exactly what a baseline is made of. BaseIn's
+`POST /scenarios/:id/executions` routes `not_steered` to `addBaselineSample` rather than the
+savings ledger, on purpose (`scenarios/routes.ts`). §11.
+
+---
+
+## 5. Tool coverage decides the mode
+
+The classification is a pure function of the scenario's steps and the set of server keys registered
+with this control server (`ControlServer.wrapped`, grown by `/proxy/register`).
+
+```ts
+// src/replay/coverage.ts
+export type StepReach = "direct" | "live";
+export type ReplayMode = "direct" | "steer" | "none";
+
+export function reachOf(toolName: string, wrapped: ReadonlySet<string>): StepReach {
+  const mcp = parseQualifiedName(toolName);          // src/control/correlation.ts
+  return mcp && wrapped.has(mcp.serverName) ? "direct" : "live";
+}
+
+export function modeFor(steps: SerializedScenarioStep[], wrapped: ReadonlySet<string>): ReplayMode {
+  if (steps.length === 0) return "none";
+  return steps.every((s) => reachOf(s.toolName, wrapped) === "direct") ? "direct" : "steer";
+}
+```
+
+| Every step | Mode | Where the tools run | Model spend |
+|---|---|---|---|
+| a wrapped MCP tool | **`direct`** (§6) | The proxies, on connections already open | one Haiku derivation + one turn that reads the results |
+| anything else, or mixed | **`steer`** (§7) | The live session, inputs pinned | one Haiku derivation + the live turn |
+| — | `none` | nowhere | declines at gate 5 |
+
+`live` covers three genuinely different cases and treats them identically, correctly: a built-in
+(`Bash`, `Read`, `Edit`, `Grep`, `Task`, `WebFetch`), an MCP server the user chose not to wrap, and
+`claude-in-chrome` — which is `scope: "dynamic"`, appears in no config file, and therefore can never
+be wrapped (v1 design §1). None of them can be reached except through the session.
+
+A **mixed** scenario in `steer` mode still gets direct execution for its wrapped steps once it
+diverges (§8), so coverage is not all-or-nothing at the divergence boundary — only at the arm-time
+mode choice.
+
+---
+
+## 6. Mode A — direct execution
+
+The cheap rung. Every step is a wrapped MCP tool, so the model never has to emit a single tool call.
+
+### 6.1 Sequence
+
+```mermaid
+sequenceDiagram
+    participant CC as Claude Code (model)
+    participant CS as bir-hooks (control server)
+    participant SC as bir-scenario (MCP)
+    participant PX as bir-proxy
+    participant UP as upstream MCP server
+
+    CC->>CS: UserPromptSubmit
+    CS->>CS: gates pass, mode=direct → arm plan; start derivation (not awaited)
+    CS-->>CC: additionalContext: "call mcp__bir__run_scenario once"
+    CC->>CS: PreToolUse run_scenario → allow (binds the call to this session)
+    CC->>SC: tools/call run_scenario {}
+    SC->>CS: POST /scenario/run { toolUseId }
+    CS->>CS: await plan.ready()  (derivation lands)
+    loop each step
+        CS->>CS: toolInputForCurrentStep()
+        CS-->>PX: work { workId, toolName, arguments }   (answers an open long-poll)
+        PX->>UP: tools/call  (bir: id, on the open connection)
+        UP-->>PX: CallToolResult
+        PX->>CS: POST /proxy/result { workId, result }
+        CS->>CS: applyOutput(JSON.stringify(result)) → respParams
+    end
+    CS->>CS: responseParamsLogic → response model; assembleBundle()
+    CS-->>SC: { text, responseModel, steps }
+    SC-->>CC: tool_result (genuine)
+    CC->>CC: answers from the results
+    CC->>CS: Stop → seal, report execution (ticket)
+```
+
+### 6.2 Why a first-party MCP server, and not `additionalContext`
+
+Executing inside `UserPromptSubmit` and returning the results as `additionalContext` is the obvious
+shortcut, and it is wrong for three separate reasons:
+
+1. **Budget.** `UserPromptSubmit` has a hook timeout (§10). N live MCP round trips do not fit inside
+   one, and if it expires Claude Code proceeds *without* the context — so the work is burned and the
+   user waits for nothing.
+2. **Trust.** RRepeat learned this expensively. Its `deny`-with-a-reason delivery is *"inherently
+   read as a denial by the model"* (`hook-server.ts`), which is why it grew a Bash-rewrite path and
+   then a whole MCP bridge (`mcp-bridge.ts`) to hand the same bytes back as a genuine `tool_result`.
+   A first-party MCP tool is that bridge, without the shadowing.
+3. **Truth.** A `tool_result` in the transcript is a real record of a real call. `additionalContext`
+   asserting that tools ran is a claim the transcript cannot corroborate.
+
+The cost is honest and worth naming: one extra tool in the model's tool list, in **every** session
+where `bir install --replay` ran. That is why it is a separate install flag and why `bir status`
+prints it.
+
+### 6.3 `run_scenario`
+
+```jsonc
+// tools/list, from bir-scenario
+{
+  "name": "run_scenario",
+  "description":
+    "Returns the results BaseInstRunner prepared for the current request. Call it only when a BaseInstRunner note in this turn (text beginning \"[BaseInstRunner calculated replay]\", in a system note or a tool result) tells you to; never otherwise.",
+  "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false }
+}
+```
+
+No arguments **by design**: the armed plan is server-side state keyed by the control server's open
+run, so there is nothing for the model to get wrong and nothing it can point at a different scenario.
+Which session's plan runs is the control server's call. The `PreToolUse` for `run_scenario` records
+the session and its `tool_use_id` (and answers `allow` for an announced direct plan, §13.2), and
+`bir-scenario` forwards the host's id for the call, Claude Code's
+`params._meta["claudecode/toolUseId"]`, as `toolUseId`. With no `PreToolUse` waiting, nothing runs.
+
+`run_scenario` never answers with an error (`isError: false`), because a model sometimes calls it
+unasked, and a red error under a tool the user never asked about helps nobody:
+
+| Situation | What the model reads |
+|---|---|
+| No plan for this call, or no control server running for this directory | `Nothing to run for this request; continue normally.` |
+| The plan stopped part-way | the controller's hand-over note (§8), which begins `[BaseInstRunner calculated replay]` and says which steps ran, then the results of those steps |
+| The plan ran nothing live | the hand-over note alone |
+| A second call while the plan is still running | `The prepared results for this request are already being produced for an earlier run_scenario call, and they come back there. Do not call run_scenario again, and do not repeat its steps.` |
+| Anything else: a control server that does not answer, a timeout, an HTTP error | `The prepared results are not available for this request. Do the task normally with your tools.` |
+
+A bundle the plan's time budget cut short ends with `(partial: the scenario stopped before all of its
+steps ran)`. The real reason is in the `scenario.answered` line on the server's stderr;
+`BIR_SCENARIO_DEBUG=1` in its environment brings back the raw reasons as `isError` results. The
+request waits at most 290 s (`BIR_SCENARIO_RUN_TIMEOUT_MS`), below Claude Code's 5-minute idle
+timeout for an MCP call. Esc (`notifications/cancelled`) aborts it, and the control server starts
+no further step.
+
+By default the server lists only `run_scenario`; §16.5 has the others. While the runner is off
+(`bir off`, `BIR_OFF=1`) it lists no tools, and it tells Claude Code when that changes
+(`notifications/tools/list_changed`).
+
+`bir-scenario` is a client of the control server, discovered the same way a proxy discovers it —
+`~/.baseinstrunner/control/<key>.json`, mode `0600`, bearer token
+([`src/control/discovery.ts`](../src/control/discovery.ts)). It holds no state, no credentials and
+no upstream connections.
+
+**It says it is there.** A configured `bir` server is not a connected one: a stale node path, a
+crash, the server disabled in `/mcp` or a session started with `BIR_OFF=1` all leave the model
+without the tool. So `bir-scenario` sends `POST /scenario/hello` (pid, version, how many tools, off
+or not) on `initialize`, on `tools/list`, when the off switch flips, whenever its recorder changes
+(it looks every 2 s) and every 5 minutes, bounded at 1 s and never awaited. The control server
+announces a direct plan only while a live `bir-scenario` pid has said hello within the last 30
+minutes, with at least one tool and not off; otherwise the plan is declined (`no_delivery_tool`)
+and the agent does the task. When the recorder's pid is dead and its port refuses connections,
+`bir-scenario` also starts `bir-hooks revive` for an installed project (detached and rate-limited,
+never for a missing discovery file, so never after `bir down`), and logs `scenario.recorder_revive`.
+
+### 6.4 The steering directive (direct)
+
+```
+[BaseInstRunner calculated replay] A known-good tool sequence was recorded
+for this request (intent: <scenario.intent>).
+
+It runs these tools, in order, and returns their results:
+
+  1. mcp__chrome-devtools__navigate_page — open the fleet dashboard
+  2. mcp__chrome-devtools__take_snapshot — read the device table
+
+Call mcp__bir__run_scenario once, with no arguments, before any other tool.
+Then answer the user's request from the results it returns.
+```
+
+**A direct plan never diverges.** If the model's first call (host housekeeping such as `ToolSearch`
+aside) is anything but `run_scenario`, the likeliest reason is that it has no such tool, and
+executing every step unattended inside that call's hook is the wrong answer to a broken delivery
+tool. The plan is retired without running anything (`replay.vetoed`, booked `not_steered`), the
+call runs as the model wrote it, and its `PostToolUse` tells the model that the scenario is not
+being run. A plan whose `run_scenario` was called but whose `/scenario/run` never arrived — the
+user refused the call, a rule denied it, or it failed on the way — is retired the same way, at that
+call's `PostToolUse` or the next call, so a refusal is never overridden by running the same steps
+another way. Divergence (§8) is for steer plans only.
+
+---
+
+## 7. Mode B — model-steered live replay
+
+The mixed rung. Ported from RRepeat's `replay.md` §3/§12, which is the right design and is already
+proven: the model chooses *which* tool and *when*; the control server overrides the *arguments* and
+threads state between steps. The session never leaves the model's hands, so every
+`tool_use`/`tool_result` in the transcript is genuine and continuation is automatic.
+
+**Arm** at `UserPromptSubmit` — plan on `run.plan`, `run.planToolUse = new Set()`, directive via
+`additionalContext`, **no `decision`** so the prompt still reaches the model:
+
+```
+[BaseInstRunner calculated replay] A known-good tool sequence was previously
+recorded for this request. Call exactly these tools, in order, one at a time:
+
+  1. mcp__chrome-devtools__navigate_page — open the fleet dashboard
+     arguments: {"url":"https://fleet.internal/eu-west-1"}
+  2. mcp__chrome-devtools__take_snapshot — read the device table
+     arguments: {}
+  3. Read — load the alert thresholds
+
+Context: <scenario.intent>
+
+The system supplies the exact arguments for each call. Where a step shows
+its arguments above, they are the ones it runs with: pass them as shown.
+Do not call any other tools until this sequence is complete,
+then answer the user's request from the tool results.
+```
+
+Where a step's arguments are known when the plan arms, they are shown under it: `command: …` for
+`Bash` and `PowerShell`, `arguments: {…}` for anything else, redacted and at most 240 characters.
+A step whose input reads an earlier step's output (step 3 above) or runs a multi-line command shows
+none, and a plan holding a value the safety check (§13.2) would refuse shows no arguments at all.
+With no arguments shown at all, the closing lines
+are the older *"The system supplies the exact arguments for each call — you do not need to compute
+them."* The arguments matter because of the pin guard below: told only that the system supplies
+them, a model writes a placeholder call that the guard rightly declines. A steer plan with a shell
+or file-write step gets up to 1.2 s of the prompt's budget for its parameters to settle, so that its
+directive can show them.
+
+**Pin** at `PreToolUse`, while a plan is active and the call is not `mcp__bir__run_scenario`:
+
+```ts
+if (toolName === plan.expectedTool()) {
+  const input = plan.toolInputForCurrentStep();          // may throw → hand over (§8)
+  if (!pinCompatible(toolName, modelArgs, input).ok)     // control/pin-guard.ts
+    return asWritten();                                  // no pin; the plan stays armed
+  run.planToolUse.add(toolUseId);
+  return { hookSpecificOutput: { hookEventName: "PreToolUse",
+                                 permissionDecision: "allow",
+                                 updatedInput: withCallId(input) } };   // §7.1
+}
+return divergence(…);                                                   // §8
+```
+
+**The same tool is not the same call.** A pin swaps the model's arguments for the step's and
+answers `allow`, so it is kept only for a call that plausibly *is* the step
+([`pin-guard.ts`](../src/control/pin-guard.ts)):
+
+- `Bash` / `PowerShell`: the same commands, chained the same way (`&&`, `||`, `;`, `|`, `&`, a new
+  line), each with the same head — the program plus its subcommand (`git push`, `npm test`), or
+  plus what it runs (`npm run lint`, `npx eslint`, `python deploy.py`, `python -m pytest`,
+  `uv run pytest`; `bash -c 'git push'` counts as `git push`). A step with a command substitution
+  (`$(…)`, backticks) pins only to an exact copy.
+- Tools that write a file: the same file. Read-only file tools (`Read`, `Grep`, `Glob`, …) may be
+  steered to the step's path.
+- MCP tools whose input is run — a query, a statement, a shell command: every statement the step
+  runs, supplied with the same verb (`SELECT` for `SELECT`, never for `DELETE`), or no arguments at
+  all. An empty statement argument of the step need not be supplied, but a call that runs something
+  there is not the step.
+- Everything else: at least one argument in common, and no argument naming *where* the call acts
+  (a path, a URL) pointing somewhere else. A call with no arguments at all is pinned.
+
+A call the guard declines runs exactly as the model wrote it, and the plan stays armed for the call
+that is the step (`replay.pin_declined`). If the model then calls a *different* tool, it did the
+step its own way and moved on: the plan is retired without running anything (`replay.pin_abandoned`),
+that call runs as written, and its `PostToolUse` tells the model the arguments are its own from now
+on.
+
+**One call at a time.** A pin moves the plan's cursor only when its output threads. A call that
+arrives while the previous pin has not threaded first waits for it inside `PreToolUse`: up to 1.75 s
+after the host reported the pinned call finished, 200 ms while it has not, and not at all when the
+plan's last step is the one in flight. A call still running beside a pin after that hands the plan
+over (`replay.concurrent_call`), booked `fell_back` or `failed`, and carries the note in its place.
+A pinned step the host reports as failed (`PostToolUseFailure`), or whose proxy report is an error,
+hands over as well; nothing after it is pinned or approved.
+
+**Thread** at `PostToolUse`, for a `tool_use_id ∈ run.planToolUse` — but *from the right source*
+(§7.2). When `plan.isDone()`, retire the plan; the model then writes its answer from the real tool
+history.
+
+### 7.1 Steering and correlation both write `updatedInput` — they must merge
+
+This collision does not exist in RRepeat and is easy to miss here.
+
+`onToolPre` can return an `updatedInput` for a **wrapped MCP** call of its own: it is how the
+correlation id rides along to the proxy ([`src/control/correlation.ts`](../src/control/correlation.ts)).
+By default it does so only where answering `allow` changes nothing the user is asked — a
+replay-pinned step, or a session in `bypassPermissions` mode — or where the operator opted in with
+`BIR_CORRELATION_DECISION=allow|ask`; never in plan mode, and never into a server with no live
+proxy to strip the id. Every other wrapped call gets no decision at all and joins its proxy report
+by fingerprint. A pinned step whose tool is a wrapped MCP tool therefore needs *both* payloads in
+one object, and the order is not arbitrary:
+
+```ts
+/** Pinned arguments plus, for a wrapped MCP tool, the correlation id. */
+function withCallId(pinned: Record<string, unknown>): Record<string, unknown> {
+  const mcp = parseQualifiedName(toolName);
+  if (!mcp || !this.wrapped.has(mcp.serverName) || this.opts.noCorrelation) return pinned;
+  if (!liveProxy(mcp.serverName)) return pinned;                     // allow + pinned input, no id
+  const correlation = mintCorrelation(run, mcp, pinned, context);   // hookArgs = the PINNED args
+  return { ...pinned, [BIR_CALL_ID]: correlation.callId };
+}
+```
+
+Three consequences, all load-bearing:
+
+- **The correlation's `hookArgs` must be the pinned arguments, not the model's.** `settle()` records
+  `correlation.hookArgs ?? report.args`; recording the arguments the model *proposed* rather than the
+  ones that *ran* would put a lie in the corpus. (In a replayed turn nothing is recorded — §12 — but
+  the same code path serves recorded turns, and the invariant must hold there.)
+- **The key must already be declared**, or the host may reject it. It is: while a control server
+  may inject call ids, the proxy's `tools/list` declares `__bir_call_id__` as a string property
+  (*"Reserved. Leave unset."*) and leaves `additionalProperties` as the upstream had it
+  (`ProxySession.declaresCallId`). Under `--no-correlation`, `withCallId` is a no-op and pinning
+  still works — only the *result* join degrades to fingerprints.
+- **`permissionDecision: "allow"` auto-approves.** A pinned step is answered `allow` — built-ins
+  and wrapped MCP tools alike — because replay is its own consent and the host may drop an
+  `updatedInput` it did not approve. An ordinary wrapped call is not auto-approved unless the
+  operator set `BIR_CORRELATION_DECISION=allow`. §13.2.
+
+### 7.2 Thread from the same source that recorded
+
+`toolOutputLogic` was authored by BaseIn's `analyzeRun` against the exact bytes stored in that step's
+`tool_output`. Feeding it a differently-shaped rendering of the same result does not fail loudly — it
+silently derives nothing, and every later step reading `respParams` produces a wrong input.
+
+In this repo those bytes have **two different origins**:
+
+| Step's tool | What was recorded | Therefore thread from |
+|---|---|---|
+| Wrapped MCP | `serializeCapped(redact(report.result))` — the proxy's whole `CallToolResult`, via `settle()` → `record()` | the **proxy's `/proxy/step` report** |
+| Built-in / unwrapped MCP | `serializeCapped(redact(payload.tool_response))` — Claude Code's rendering, via `onToolPost` | the **hook's `tool_response`** |
+
+So `/tool/post` must not thread unconditionally. It threads for a `live` step, and for a `direct`
+step it does what it already does for a correlated call: **arm the existing
+`PROXY_REPORT_GRACE_MS` fallback**, and let `onProxyStep` thread when the report lands.
+
+```ts
+// onToolPost, for a pinned step
+if (reachOf(step.toolName, this.wrapped) === "live") {
+  plan.applyOutput(serializeCapped(payload.tool_response ?? {}));
+} else {
+  correlation.threadOnReport = true;         // onProxyStep calls plan.applyOutput(report.result)
+  correlation.fallback = setTimeout(() => {  // …unless the proxy never reports
+    logLine("replay.thread_fallback", { why: "no proxy report — threading the hook's view; shapes may differ" });
+    plan.applyOutput(serializeCapped(payload.tool_response ?? {}));
+  }, PROXY_REPORT_GRACE_MS);
+}
+```
+
+This reuses machinery that exists and is already correct. It also means the §7.3 ordering constraint
+binds a little harder: the proxy report must land before the next `PreToolUse`, and
+`PROXY_REPORT_GRACE_MS` (1500 ms) is the bound on how long that can take before we degrade.
+
+### 7.3 Synchronous `PostToolUse` is a requirement, not a preference
+
+Step *N*'s `/tool/post` must finish updating `respParams` before step *N+1*'s `/tool/pre` reads it.
+In [`HOOK_ROUTES`](../src/config/adapters/claude-code.ts) neither `PreToolUse` nor `PostToolUse`
+carries `async: true`, so this already holds — **and must never be relaxed**. Add it to the comment
+block there, next to the `SessionEnd` note that records the same class of lesson.
+
+---
+
+## 8. Divergence
+
+In a steer plan, the model called a tool the plan did not expect, or the call had no `tool_use_id`.
+(A direct plan never diverges, §6.4. A `toolInputLogic` that throws is not a divergence either:
+re-executing would start at that same step and throw again, so the step is recorded as failed and
+the task is handed to the model, with a note in place of the call.) Three tiers, tried in order.
+Here is where the §0 asymmetry pays.
+
+**Tier 1 — direct-execute the remainder (new; the common case).**
+Take every not-yet-run step, execute it, and hand the composed result back. This happens inside the
+diverging call's `PreToolUse`, so it is bounded by `BIR_PRETOOL_REPLAY_BUDGET_MS` (§10): no step
+starts after that budget, or after the hook has had to answer without it. Steps with
+`reach === "direct"` run through their proxy, and only on servers `BIR_REPLAY_ALLOW_SERVERS`
+allows. Steps with `reach === "live"` cannot run here at all — a hook process is not the session.
+
+**A step that produced no result ends the bundle there**: a `live` step, a server off the
+allowlist, no proxy to take the call, a timeout, an upstream refusal, a tool error or a logic
+failure. Nothing after it runs. This is RRepeat's rule about skipped steps taken to its end: every
+later step reading `respParams` would compute on a result that does not exist. The bundle then opens
+with a hand-over note that names the step and says what may be assumed about it — a call that was
+sent and never answered *"may or may not have completed"*, a step whose tool ran but whose output
+logic failed is *"Do not run it again"* — and the model carries on from there. If nothing ran here
+at all, no bundle is sent: the model's own call goes ahead, unless a step was sent and never
+answered, in which case the note alone takes the call's place.
+
+Every hand-over note ([`handover.ts`](../src/replay/handover.ts)) — here, in a direct run's answer,
+or in place of a call — opens with *"[BaseInstRunner calculated replay] The calculated scenario for
+this request stopped before finishing. Continue the task yourself from here, calling tools as
+needed."* It says which steps ran (*"Steps 1–k of N ran under the scenario … Do not repeat them."*,
+split between the tool calls above and the results below when both exist; or *"No step of the
+scenario ran; the whole task is yours."*), then names the stopped step and what may be assumed
+about it:
+
+- not sent: *"Step k of N (tool) did not run: … Nothing of it happened; do it yourself."*
+- sent, and never answered: *"… was sent but did not answer (…). It may or may not have completed:
+  check whether its work happened before you run it again."* When nothing else ran, the note says
+  *"No step of the scenario is known to have finished; the task is yours."* instead of *"No step …
+  ran"*.
+- its tool ran, its output logic failed: *"… ran — its result is real and its side effects are in
+  place — but the scenario could not read its output (…), so it stops there. Do not run it again."*
+- out of time, or cancelled: *"… did not run: the scenario's time budget ran out before it."* /
+  *"… the scenario run was cancelled before it."*
+- beside a pin still in flight: *"… was not run by the scenario: another of its calls was still in
+  flight, and a scenario runs one call at a time."*, and the pin itself *"was started and has not
+  reported back"*.
+
+It ends with the remaining planned steps and the parameters derived for this request, within 4 000
+characters.
+
+With `BIR_REPLAY_RECORDED_OUTPUTS=1`, a step that could not be *sent* (a built-in, no proxy, off the
+allowlist) is served its **recorded output** instead (§8.1), marked `(recorded)` in the bundle so the
+model is never told a stale result is fresh. A timeout or an upstream error never is.
+
+Delivery, best channel first. (A direct plan's own results go through `run_scenario`, §6.)
+
+1. **Bash-clean** — if the divergent call is `Bash`, rewrite the command to `cat` the bundle. The
+   model sees ordinary command output. (RRepeat's `bashCleanPath`.) Up to 6 000 characters ride
+   inline as a heredoc, delimiter neutralised; a longer text is written to a `0600` file under
+   `<BIR_HOME or ~/.baseinstrunner>/tmp` that is removed after an hour, and the command reads it.
+   The text is capped at `BASH_CHANNEL_MAX` (25 000 chars), because the host cuts long command
+   output too. If the file cannot be written, deny-inject carries the text.
+2. **Deny-inject** — `permissionDecision: "deny"`, bundle as `permissionDecisionReason`, capped at
+   `MAX_REPLAY_REASON` (60 000 chars) with the same fair-share truncation
+   (`assembleBundle`/`truncate`, portable verbatim from `payload-executor.ts`). Works for any tool,
+   and is read as adversarial — hence last.
+
+**Tier 2 — abort.** Composition itself threw (`replay.compose_failed`). Retire the plan, return
+`{}`, continue as an ordinary turn. Outcome `failed`.
+
+**The cost line.** RRepeat's Tier 1 is an Agent SDK session, and its own doc calls that the dominant
+cost of a calculated run. Here Tier 1 is N `tools/call`s on connections that are already open:
+**`fallbackCostUsd` is 0.00 by construction**, for every step the proxies can reach.
+
+> **Do not port the unconditional-divergence line.** RRepeat's `steerPreTool` ends with a deliberate
+> `return await injectBundle(...)` that bypasses the pin branch on *every* armed plan
+> (`savingCalcRunner.md` §4 documents the consequence: `stepsPinned` is 0 on every row). That was a
+> choice made when the bundle was the only path that ran real tools. It is not this design's choice:
+> pinning is tried first, always, and divergence is what its name says.
+
+### 8.1 Where a recorded output actually comes from
+
+RRepeat reads it from `SerializedScenarioStep.recordedOutput`, whose own comment says the field is
+optional because *"it is the server's payload that decides whether to send it, and older payloads do
+not."* Verify this before relying on it: **no payload does.** BaseIn's `scenario_steps` table has
+columns `tool_input_logic`, `tool_output_logic`, `reasoning`, `reasoning_vector` — and no
+`recorded_output`; `serializeScenario` emits no such field. RRepeat's fallback is unreachable in
+production today.
+
+There is a path that needs no server change, and the match payload already carries its key:
+
+```
+GET /recordings/runs/:runId        →  { run, steps }   // steps carry tool_name + tool_output
+                    ↑ matched.runId — the canonical source run this scenario was calculated from
+```
+
+So: fetch the source run **lazily**, on the first `live` step of the first divergence, and index its
+`tool_response` steps by tool name into the same FIFO queue BaseIn's own `dryReplay` builds
+(`recordedOutputsByTool` in `scenarios/replay.ts` — a `Map<toolName, string[]>` drawn in order, with
+a per-tool cursor). One authenticated GET, cached for the turn, and the queue semantics match the
+server's dry replay exactly — which matters, because a scenario that behaves one way under
+`bir scenario replay --dry` and another way here would be untestable.
+
+Adding `recorded_output` to `scenario_steps` would make this a field read instead of a fetch, and is
+a reasonable server-side follow-up. It is not a prerequisite.
+
+> **[built]** [`src/replay/source-run.ts`](../src/replay/source-run.ts). The type still carries the
+> optional `recordedOutput` field and prefers it when present, so a server that starts sending it
+> needs no change here — but nothing depends on it.
+>
+> **[changed]** Recorded outputs no longer stand in by default: a step with no result stops the
+> plan (§8). The source run is fetched only when `BIR_REPLAY_RECORDED_OUTPUTS=1` (or
+> `ReplayOptions.recordedFallback`) allows a stand-in, and in `bir replay`, which keeps it. The
+> lookup is bounded by the hook's or the plan's deadline and skipped when less than 250 ms remain.
+> A recorded stand-in never counts as work done under the plan (§11.1).
+
+---
+
+## 9. The plan, and state threading across hook calls
+
+`ScenarioReplayPlan` ports from RRepeat's [`payload-executor.ts`](../../../BasInstRunner/RRepeat/src/server/payload-executor.ts)
+with three changes.
+
+```ts
+// src/replay/plan.ts
+export class ScenarioReplayPlan {
+  readonly scenarioId: string;
+  readonly mode: ReplayMode;
+  readonly stepCount: number;
+
+  /** Resolves when derivation has landed and paramsLogic has been applied. */
+  ready(): Promise<void>;
+
+  currentStepIndex: number;
+  expectedTool(): string | undefined;
+  isDone(): boolean;
+
+  /** Pinned input for the current step. Throws → the plan hands over (§8). */
+  toolInputForCurrentStep(): Record<string, unknown>;
+  /** Thread a real output into respParams and advance. Throws → the plan hands over (§8). */
+  applyOutput(realOutput: string): void;
+
+  steeringDirective(): string;
+  /** Execute every remaining step through `execute`, and lay the results out under `maxChars`. */
+  composeBundle(maxChars: number, execute: ExecuteStep): Promise<BundleResult>;
+  /** responseParamsLogic over the accumulated respParams. */
+  responseModel(): Record<string, unknown>;
+}
+```
+
+**Change 1 — lifetime is a run, not a session.** The plan hangs off `RunState`, not `SessionState`.
+In this codebase a run *is* a turn (`UserPromptSubmit → Stop`, `server.ts` §onPrompt), which is
+exactly the plan's lifetime. `sealRun` retires it; a second prompt in the same session cannot inherit
+a stale plan, which in RRepeat requires care.
+
+**Change 2 — `params` are a promise.** The constructor takes `Promise<Record<string, unknown>>`, not
+a value, so arming does not wait for the Haiku call (§10). `paramsLogic` is applied once, inside
+`ready()`, the first time it resolves.
+
+**Change 3 — `execute` is a step, not a tool name.** `composeBundle` takes
+`(step, input) => Promise<string>` rather than `(toolName, input)`, because the executor must know
+the step's `reach` to decide between the proxy, the recorded output (only when opted in, §8.1), and
+stopping the plan.
+
+The four `new Function` shims (`evalParamsLogic`, `evalToolInputLogic`, `evalToolOutputLogic`,
+`evalResponseParamsLogic`) go in `src/replay/logic.ts`, ported from BaseIn's
+[`src/scenarios/logic.ts`](../../../BaseIntSever/BaseIn/src/scenarios/logic.ts) — which is the same
+code with better comments and an `assertPlainObject` guard the other copies lack. **Port BaseIn's
+version**, not RRepeat's: it is the one the server evaluates against, so a divergence between them is
+a divergence between what a scenario does in a dry replay and what it does here. (Each body is
+still parsed as a `new Function` body, but now runs through `vm.Script#runInThisContext` under a
+time limit, §13.1; argument order and the plain-object guard still match the service.)
+
+### 9.1 What flows between steps
+
+- **`params`** — computed once (derivation → `paramsLogic`), read by every `toolInputLogic`.
+- **`respParams`** — starts `{}`; each step's `toolOutputLogic` merges keys in
+  (`respParams = { ...respParams, ...derived }`); later steps' `toolInputLogic` read the accumulation.
+  This is how step 1's `highestRiskDeviceId` reaches step 2's input.
+
+In direct mode both live inside one `for` loop. In steer mode they are split across *separate HTTP
+requests* — which is what §7.3's ordering rule protects.
+
+---
+
+## 10. Timing: what may block, and for how long
+
+The hook is on the user's critical path. Every await here is a stall the user watches.
+
+| Moment | Route | Hook timeout | Answered by | What may be awaited | Budget |
+|---|---|---|---|---|---|
+| `UserPromptSubmit` | `/session/prompt` | 10 s | 7 s | the match; for a scenario with a target, its derivation; a steer plan's argument preview | match `BIR_MATCH_BUDGET_MS` = **1500**; match and arming together ≤ **6 s**; derivation ≤ `BIR_HOOK_DERIVE_BUDGET_MS` = **4000** |
+| `PreToolUse` | `/tool/pre` | 15 s | 12 s | `plan.ready()` (derivation); on a divergence, the remaining steps | derivation ≤ min(`BIR_DERIVE_BUDGET_MS`, `BIR_HOOK_DERIVE_BUDGET_MS`) = **4000**; all replay work ≤ `BIR_PRETOOL_REPLAY_BUDGET_MS` = **9000** (held at ≤ 10 000) |
+| `run_scenario` | `/scenario/run` | `bir-scenario`'s own, **290 s** (`BIR_SCENARIO_RUN_TIMEOUT_MS`) | — | `ready()` + N steps | derivation `BIR_DERIVE_BUDGET_MS` = **8000**; plan `BIR_REPLAY_PLAN_BUDGET_MS` = **100000** (`BIR_REPLAY_BUDGET_MS` overrides it where set); per step `BIR_STEP_TIMEOUT_MS` = **60000**, clipped to what the plan has left |
+| `PostToolUse` | `/tool/post` | 5 s | 2 s | nothing | — |
+| `Stop` | `/session/stop` | 5 s | 2 s | nothing (report is queued) | — |
+
+"Hook timeout" is what `bir install` writes into
+[`HOOK_ROUTES`](../src/config/adapters/claude-code.ts): the user's worst case if the control server
+hung. "Answered by" is the control server's own deadline for the route, well inside it: past it the
+route answers `{}` (at `/tool/pre`, a divergence's hand-over note if one was under way) and logs
+`control.hook_deadline`. Every scenario logic body is stopped after `BIR_LOGIC_TIMEOUT_MS`
+(**1000**, at most 10 000). Values set past a ceiling are brought back under it and logged as
+`replay.budget_clamped`. [production.md](../production.md) has the full budget and environment
+reference.
+
+**Derivation is awaited at the prompt only when it must be.** The steering directive needs only the
+scenario's ordered tool names and reasonings — it does not need parameter values. So for a scenario
+whose parameters are all settings the prompt hook returns the directive the moment the match lands,
+and the Haiku call runs un-awaited; the *first* `PreToolUse` awaits it, within its own hook budget.
+A scenario with a *target* derives before its directive goes out, inside the prompt's budget, so a
+plan that cannot find what it is to act on is never announced (gate 7, `segmented.md` R-PARAM-4). A
+steer plan with a shell or file-write step may spend up to 1.2 s of that budget letting its
+parameters settle, so that its directive can show them (§7). On a mode-`direct` turn the wait lands
+inside `run_scenario` instead, which waits the full `BIR_DERIVE_BUDGET_MS`.
+
+**A direct run is held under 270 s**, so it answers before `bir-scenario` stops waiting: derivation
+plus plan plus 12 s of slack at the default logic limit (one last step's 1 s minimum, six logic
+bodies at their limit, a 5 s margin); past the ceiling the derivation wait is cut to 60 s first,
+then the plan. The defaults come to 120 s, or 140 s with `BIR_REPLAY_BUDGET_MS=120000`. A plan budget
+much past 100 s also risks Claude Code moving a long `run_scenario` call to the background after 2
+minutes, while its steps keep starting. `bir replay` is not held to the ceiling.
+
+**Budget expiry is never an error.** Match budget expired → no plan, ordinary turn, one
+`replay.decision` line (`match_timeout`). **The match gate:** a match that answered slower than
+`BIR_MATCH_SLOW_MS` (**800**), or not at all, also makes prompts stop waiting on the match for 5
+minutes, doubling up to 30 while the service stays slow; a fast match ends the hold
+(`replay.match_gate`). A healthy service answers in 300–450 ms, so past 800 ms waiting would add
+that much to every prompt. The match is still asked meanwhile, so a hit still stops the recording. Derivation budget expired →
+settings take their recorded `sampleValue`s and targets stay `null`, never `{}`; a plan that needs a
+missing target, or whose `paramsLogic` throws, hands over instead of running (in steer mode the
+note replaces the call, in direct mode `run_scenario` answers with it). The derivation request
+itself times out after max(`BIR_SERVICE_TIMEOUT_MS`, `BIR_DERIVE_BUDGET_MS`). None of these waits
+happens while the service is cooling down after a failure: the turn simply runs normally.
+
+**Intent arming mid-turn is opt-in.** An intent probe is sent from `PreToolUse` for hit counting and
+is never waited on, unless `BIR_INTENT_ARM=1` or `BIR_SEGMENT_ARM=1` lets it arm a plan in that
+call's place; then it waits at most `BIR_INTENT_ARM_BUDGET_MS` (**500**) for the probe and 1.5 s for
+arming. `BIR_INTENT_ARM=0` never waits.
+
+`UserPromptSubmit` must stay non-`async`: an async hook is fire-and-forget and cannot return
+`additionalContext` at all.
+
+---
+
+## 11. Reporting: outcome, ticket, cost
+
+This is the half that makes replay *provable* rather than merely fast, and v1 does none of it.
+
+### 11.1 The outcome ladder
+
+```ts
+// Upgrade-only. `not_steered` is the floor and the safe answer if the turn dies mid-flight.
+const OUTCOME_RANK = { not_steered: 0, failed: 1, fell_back: 2, diverged: 3, steered_full: 4 } as const;
+```
+
+| Outcome | Means | Server-side effect |
+|---|---|---|
+| `not_steered` | Matched, declined at a gate, or retired before it ran anything (a direct plan whose `run_scenario` never came, §6.4); the agent ran the task | **baseline sample** (`addBaselineSample`) |
+| `failed` | Armed, then the machinery gave up before any step did its work; the agent ran the task | **baseline sample** |
+| `fell_back` | Some steps did their work under the plan, then it handed the rest of the task to the model | ledger row, measured against the whole turn (may be negative) |
+| `diverged` | The model went off-script and the bundle answered; or a direct run's budget ran out after some steps | ledger row, `saved_usd` computed |
+| `steered_full` | Every planned step ran with scenario-derived inputs | ledger row, `saved_usd` computed |
+
+`diverged` is booked only when something ran under the plan — a step executed now, or a pin that
+threaded before the divergence. A divergence that ran nothing books `failed`, and so does one that
+stopped at a step that broke (a logic failure, a tool error, a call sent and never answered). A
+recorded stand-in (`BIR_REPLAY_RECORDED_OUTPUTS=1`) is never work done: it counts toward neither
+`stepsPinned` nor the upgrade, and a direct run that used one is `diverged` at best. A call that ran
+beside a pinned one hands over as `fell_back` or `failed` (§7). A direct run cancelled by its caller
+(Esc, or `bir-scenario`'s own timeout) books `fell_back` or `failed` with `measured: false`, never
+`diverged`: that turn's cost says nothing about what the task costs.
+
+Direct mode reports `steered_full`. BaseIn's zod enum
+(mirrored in [`replay/types.ts`](../src/replay/types.ts)) has no `direct` member, and `steered_full`
+means exactly what happened: every planned step executed under the scenario's control and the
+response model was produced. A `direct` discriminator would be a *server* change and is §20's
+question 2, not a blocker.
+
+### 11.2 The ticket
+
+`matched.executionTicket` is the server's claim token, and **it is the execution row's id** — which
+is what makes a doubled report book once (`scenarios/routes.ts`: a `claimed` ticket returns
+`200 { duplicate: true }`, not an error). Redeem it exactly once, in `sealRun`, which queues the
+report and returns; the run's drain — its own `sealing` promise (the answer resolution), then a
+bounded flush — runs in the background, so `Stop` never blocks on the network:
+
+```
+POST /scenarios/:scenarioId/executions
+  { ticket, outcome, deriveCostUsd, sessionCostUsd, fallbackCostUsd,
+    durationMs, stepsPlanned, stepsPinned, measured, pricingVersion, prompt,
+    steps, error, errorStage, errorStepIndex, errorToolName }
+```
+
+An **unredeemed** ticket leaves no execution row at all. That asymmetry is intentional and worth
+preserving: silence loses a saving; it never invents one.
+
+### 11.2a What each step did (the service's errorshandling.md)
+
+The last five fields are the diagnosis, and none of the money depends on them. The service's
+recording page draws the scenario's chain step by step; without these, a scenario whose step 2
+throws on every replay renders as four healthy-looking steps beside a saving that never grows. The
+error exists — in a log line, on the operator's machine. The person who owns the scenario is looking
+at a web page.
+
+```ts
+steps: Array<{
+  stepIndex: number;          // the scenario's own index, not a position in this array
+  toolName: string;
+  status: "ok" | "recorded" | "skipped" | "failed";
+  stage?: ExecutionStage;     // where in the step, for `failed` / `skipped`
+  error?: string;             // message only — this is rendered in a web page
+  durationMs?: number;
+}>
+```
+
+`ok` and `recorded` are passes (`recorded` with an asterisk: the values came from the source run,
+which happens only with `BIR_REPLAY_RECORDED_OUTPUTS=1` and in `bir replay`). `skipped` produced no
+result here: its call could not be sent (a built-in outside the session, no proxy for its server,
+only another open session's proxy), or it was sent and timed out or was refused. The plan stops at
+a `skipped` step. **`failed` is the only one that means the scenario is broken** rather than
+the environment — it is the scenario's own logic throwing, and it is what `Recalculate` fixes.
+
+Three rules this must keep:
+
+1. **A step the turn never reached is absent**, not `skipped`. The page shows those as "not run",
+   and a turn that dies at step 2 of 5 must not paint steps 3-5 red.
+2. **Every field is optional on the wire.** An older service ignores them; the costs still book.
+3. **The headline and the steps are one statement.** `error*` is lifted from the first `failed`
+   step (`blameStep`), never assembled independently, so the page's card cannot contradict the step
+   list underneath it.
+
+The verdicts come from `plan.ts`'s `onStep`, which has always known them — with one addition: a
+logic failure is announced *before* the throw propagates (`reportingStage`), because after it
+nothing knows which step the stack trace belonged to. In steer mode there is no loop to observe, so
+the controller records the verdict at both hooks: `PreToolUse` for an input-logic throw, `PostToolUse`
+for the pass or the output-logic throw. `ReplayState.stepResults` is keyed by step index so the
+second word on a step replaces the first.
+
+One consequence for the rule that a costless decline is not worth sending (`buildReport`, and the
+service's matching `202 { recorded: false }`): it now *is* worth sending when a step broke. No cost
+**and** no error remains nothing to report.
+
+### 11.3 Cost, and a live pricing hazard
+
+| Component | Source | Notes |
+|---|---|---|
+| `deriveCostUsd` | our own Haiku call's `usage`, priced locally | the only tokens replay itself spends |
+| `sessionCostUsd` | transcript usage **delta** for this run (§11.4) | the live turn: prompt, tool calls, answer |
+| `fallbackCostUsd` | **0.00** | direct execution spends no tokens (§8) |
+
+> ### ⚠ Verify the pricing table before copying it
+>
+> A saving is `baseline − actual`, where the baseline is priced by BaseIn's
+> [`src/scenarios/cost.ts`](../../../BaseIntSever/BaseIn/src/scenarios/cost.ts) and the actual by the
+> runner's copy. Both currently declare `PRICING_VERSION = '2026-08-30'`, and **the two tables
+> already disagree**: RRepeat prices `claude-opus-4-6` at `3.0 / 15.0`, BaseIn at `5.0 / 25.0`. Equal
+> versions are supposed to mean *"these are comparable"*. Right now, for that row, they are not.
+>
+> So: **copy BaseIn's table, not RRepeat's** — the server owns the baseline, and the baseline is the
+> number a saving is measured *against*. Copy `PRICING_VERSION` with it. Treat any price change as a
+> three-repository change, and file the drift above against RRepeat rather than reproducing it.
+>
+> Practical exposure here is small — derivation runs on `claude-haiku-4-5-20251001`, which both
+> tables price identically at `1.0 / 5.0` — but the invariant is what matters, not today's blast
+> radius.
+
+### 11.4 The per-run usage watermark
+
+`savingCalcRunner.md` §3 documents this trap in RRepeat, and **BaseInstRunnerMCP has it too**, for
+the same structural reason: Claude Code writes one transcript per *session*, and `onPrompt` rolls a
+new run on every prompt. Summing the whole file gives run 3 the cost of runs 1+2+3.
+
+Every one of those numbers is a **baseline** on the server. Do not ship the whole-file version.
+
+```ts
+// src/control/transcript.ts — two new exports beside contextForToolUse / settledLastAssistantText
+/** Per-model cumulative usage, captured when a run starts. */
+export function markTranscriptUsage(path: string | undefined): UsageMark;
+/** Per-model delta since `mark`, clamped at 0 per field. */
+export function usageSince(path: string | undefined, mark: UsageMark): ModelUsage[];
+```
+
+Take the mark in `ensureRun`, beside `startedAtMs`, so the cost window and the duration window are
+the same window. Clamp per field, so a compacted or rotated transcript degrades to *"no usage"*
+rather than to a negative cost. A run with **no mark** (one opened lazily by a proxy step before any
+prompt) reports `measured: false` — better to say "unmeasured" than to hand the ledger an inflated
+baseline.
+
+`measured` is `true` only when a mark existed **and** `pricingVersion` matches the server's. The
+server enforces the second half itself and stores a mismatched report as unmeasured rather than
+trusting it.
+
+---
+
+## 12. What the replayed turn records
+
+**Nothing, and that is correct.** The service answered `{ id: null }`; no run exists; every step post
+would 404. `run.recording = false` already handles it — `record()` early-returns and `sealRun` skips
+both the final answer and `finishRun`.
+
+Three consequences to keep straight:
+
+1. **Step indices are still allocated.** `ordering` runs regardless, correlations are still minted
+   and settled, and `bir doctor` still shows a live step count. Only the *sending* stops.
+2. **The matched run is the canonical one.** The server bumped its `iterations` at match time. The
+   corpus does not grow on a replay, by design — that is what stops one popular task from flooding
+   the similarity pool with near-duplicates.
+3. **Direct-mode calls bypass the recorder entirely.** They are issued via `UpstreamClient.request`,
+   which allocates a `bir:` id and consumes its own response in `accept()` before the relay's
+   handlers ever see it ([`src/upstream/client.ts`](../src/upstream/client.ts)). So
+   `RecordingInterceptor` never observes them and cannot double-record. That interface comment says
+   `request()` is *"Never used by the relay"* — it was built for `bir doctor` and tests, and this is
+   its second, load-bearing user.
+
+### 12.1 `bir replay` — the Tier 2 and debugging path
+
+```bash
+bir replay --scenario scn_… --prompt "check the fleet for high-risk devices"   # run it
+bir replay --scenario scn_… --prompt "…" --dry                                # derive + plan only
+```
+
+Runs the same plan through the same executor, against the same live proxies, printing the per-step
+input/output and the response model. It is how you test a scenario without a session, how a Tier 2
+or non-Claude-Code client gets any replay at all, and the first thing to reach for when a steered
+turn behaves oddly. The operator named the scenario, so it keeps its own contract: a step it cannot
+send stands on its recorded output, the allowlist does not gate it, and it is not held to the 270 s
+direct-run ceiling (§10).
+
+---
+
+## 13. Security
+
+v1 §9 holds unchanged. Replay adds two exposures, and neither is small.
+
+### 13.1 The scenario payload is executable code
+
+`toolInputLogic`, `toolOutputLogic`, `paramsLogic` and `responseParamsLogic` are JavaScript function
+*bodies*, compiled as function bodies and run **in the control server process**, in that process's
+own context (`vm.Script#runInThisContext`) — a process holding the user's BaseIn credentials and,
+through the proxies, live authenticated access to every wrapped MCP server.
+
+BaseIn's own `logic.ts` argues the eval is safe because *"these run only over data the owner already
+produced… so the dynamic eval is scoped to first-party content."* That argument holds here too, and
+the blast radius does not: BaseIn evaluates them against a database row, we evaluate them next to a
+browser and a GitHub token.
+
+What actually constrains it:
+
+- The payload arrives **only** in the response to an authenticated `POST /recordings/runs` against
+  the configured `BIR_AUTH_URL`, over the user's own token, describing the user's own runs. It is not
+  attacker-supplied in any ordinary threat model.
+- A body gets its declared arguments **and the global scope**. `require` and `import` are not
+  reachable (ESM, no CommonJS wrapper), but `fetch`, `process` and `globalThis` are. Say this
+  plainly rather than implying a sandbox: **there is no sandbox.**
+- **A time limit, and nothing more.** Each body is stopped after `BIR_LOGIC_TIMEOUT_MS` (default
+  1000 ms, at most 10 000). A regex that backtracks on a larger output than the recording's, or a
+  loop saved with `--force`, then fails as a logic error and the plan hands over at that step,
+  instead of freezing every hook of the project. The limit covers synchronous work only:
+  continuations a body queues (promises, `queueMicrotask`, timers) run afterwards and are not
+  bounded, and a body that returns a promise or any thenable is refused. There is no memory limit.
+- Replay is opt-in per project (D14): `bir install --replay`, which `bir setup` passes, turns it on,
+  and a `bir install` without it stores replay off in a project that never asked for it. A
+  compromised or misconfigured `BIR_AUTH_URL` therefore cannot start executing logic on a machine
+  whose operator never asked for replay.
+
+If that is not enough for a deployment, the mitigation is a real one and is out of scope here:
+evaluate the logic in a separate `node:vm` context with a frozen, minimal global. Filed as §20 question 3.
+
+**A hand-edited step is the same code, and runs the same way.** Since 2026-09-25 (the service's
+`editSteps.md`; built, not yet released) the owner — or Claude working for them — can change a step's
+logic with `bir scenario edit`. The service checks the change against the recording before it saves
+it, but that check is about *what the code computes*. Once saved, the step arrives in the same
+payload and runs here unattended, in the same process, next to the same credentials, exactly like
+calculated code. The provenance argument still holds: only the owner can edit, over their own token,
+and anyone else — an admin included — gets `404`. What changes is that *"the model wrote it"* is no
+longer always true.
+
+The service sandboxes its own evaluation of every logic body (built with the same service change;
+not yet released). It had to: there, one account's code runs next to every account's data and the
+service's secrets. How it is built:
+
+- **A fresh `node:vm` context for each evaluation**, with a time limit (`LOGIC_TIMEOUT_MS`). Only
+  JavaScript's own built-ins are in it, less `ArrayBuffer`, `SharedArrayBuffer`, `DataView`, the
+  typed arrays, `Atomics`, `WebAssembly` and `FinalizationRegistry`; `Symbol.for` and
+  `Symbol.keyFor` are removed too. No `require`, `process`, `fetch`, `Buffer` or timers. Values go
+  in and come out as JSON text only.
+- **That context lives in a separate evaluator process**, not in the service: an empty
+  environment, `--permission` (no files, no child processes), `--disallow-code-generation-from-strings`,
+  `--frozen-intrinsics`, and a heap of `LOGIC_MEMORY_MB`.
+- **A relay worker thread of the service drives that process.** No logic runs in the relay. It
+  kills the evaluator when a body runs too long, and the next job starts a new one; a body that
+  runs out of memory takes down only the evaluator, and is run once more on a fresh one before it
+  is blamed. The relay also replaces the evaluator when its heap stays above half of
+  `LOGIC_MEMORY_MB` after a job, and after 2,000 jobs. A body that overran its time or memory, or
+  took the evaluator down twice, is refused at once, with the same message, for the next 10
+  minutes.
+- **The hand-edit check runs in a check worker thread of its own**, with its own relay and
+  evaluator process, under a sandbox-time budget
+  (`EDIT_CHECK_BUDGET_MS`, 5000 ms by default; past it, *too costly to check*), so a slow check
+  never holds up the service's other requests.
+
+**The runner still does not sandbox.** Here the code runs on the owner's machine, for the owner's
+account, in the control server's own context with a time limit and nothing else. One consequence
+to know: **the service's check only judges what a
+body returns for the recording's values.** Code that calls `fetch`, `process` or a timer on that
+path, and does not catch the error, throws in the check, so it cannot be saved without `--force`.
+But a call behind a `typeof` guard (`if (typeof fetch === "function") …`), or on a branch the
+recording's values never take, is never reached in the check; one inside a `try` fails there
+quietly. Such code passes, it is saved like any other change, and here it runs with `fetch`,
+`process` and timers all present. The service's sandbox protects the service; it proves
+nothing about what a body does on the runner. Read every hand edit before it is saved.
+
+### 13.2 Replay bypasses permission prompts
+
+This is the sharpest edge in the whole design, and it must not be buried.
+
+- **Steer mode** answers `PreToolUse` with `permissionDecision: "allow"` for a pinned call — one
+  the pin guard (§7) accepts as the step — so it is auto-approved, **built-ins** included (`Bash`,
+  `Edit`). Nothing else is: an ordinary wrapped MCP call gets no decision from the runner, and
+  Claude Code asks about it as it would without the runner, unless the operator set
+  `BIR_CORRELATION_DECISION=allow` where the recorder starts (see `bir-hooks.ts`).
+- **Direct mode** never reaches `PreToolUse` at all. A `tools/call` dispatched to a proxy is not
+  visible to Claude Code's permission system in any form. The `run_scenario` call that starts it is
+  answered `allow` while the runner has announced a direct plan, so it brings no surprise prompt
+  (and no denial under `claude -p`); the user's own deny or ask rules for it still apply.
+- **Plan mode** (`permission_mode: "plan"`) gets none of it: no directive, no pin, no `allow`.
+
+So a scenario is, in effect, a **pre-approved list of tool calls with computed arguments**. That is
+precisely what makes it valuable, and precisely what makes it dangerous. Six mitigations, all
+required:
+
+1. `--replay` is a distinct flag: `bir setup` passes it, and a `bir install` without it leaves
+   replay off in a project that never asked for it. `bir replay off` or `BIR_REPLAY=0` turns it off
+   once installed, and `bir off` takes the whole runner out of the way.
+2. `BIR_REPLAY_ALLOW_SERVERS` — a comma-separated allowlist of the server keys bir may call by
+   itself: **direct** runs and divergence recovery (§8), though not `bir replay`, which an operator
+   runs by hand. Unset means *all wrapped servers*; the guide (§5 of `calculatedReplayGuide.md`)
+   recommends setting it.
+3. `bir doctor` prints `replay: on` and the effective allowlist, loudly, at the top. A capability this
+   sharp must never be discoverable only by reading a log.
+4. Every armed plan logs `plan.armed` with the scenario id, mode, step count and the ordered tool
+   names **before** the first call runs. The audit line precedes the action.
+5. The pin guard (§7): a pin replaces the arguments of a call only when that call plausibly is the
+   step, so a model's `Bash ls` is never turned into a step's `git push`.
+6. The injection guard ([`safety.ts`](../src/replay/safety.ts)). In a plan with a step whose input
+   is run — `Bash`, `PowerShell`, or an MCP tool or server named for SQL, queries, `exec` or a shell,
+   in any naming convention — a value derived for this turn that differs from its recorded sample
+   must be free of shell and SQL metacharacters and keep the sample's shape (a number stays a
+   number, nothing starts with `-`, no whitespace, glob, brace or parenthesis the sample did not
+   have), or the plan hands over; found at arm time, it declines as `missing_target`. A plan whose
+   only such steps write files (`Edit`, `MultiEdit`, `Write`, `NotebookEdit`) rejects only line
+   breaks and NUL. Plans with a step whose input is run do not send recent tool results to
+   derivation, and the derivation prompt is redacted before it leaves the machine.
+
+### 13.3 The control plane
+
+`/scenario/run`, `/scenario/hello`, `/proxy/poll` and `/proxy/result` are ordinary control-server
+routes: loopback only, bearer token from the `0600` discovery file, same as `/proxy/step`.
+`/proxy/poll` holds a connection open for up to 25 s — a long-lived authenticated request, not a
+new trust boundary.
+
+---
+
+## 14. Degradation matrix
+
+The governing rule is unchanged and outranks every optimisation here: **the host session must never
+fail because of BaseInstRunner.**
+
+| Failure | Behaviour |
+|---|---|
+| `getMatch()` slower than the match budget | No plan. Ordinary turn. One `replay.decision` line (`match_timeout`); a match that lands later is `match_late` and never steers. A slow match also makes prompts stop waiting on it for a while (`replay.match_gate`, §10) |
+| The service is cooling down after a failure | Nothing waits on it: no match wait (`service_unhealthy`), no derivation wait, no intent probe. Ordinary turn |
+| No derivation key here (`BIR_DERIVE_API_KEY`; the background recorder ignores `ANTHROPIC_API_KEY` unless `BIR_USE_ANTHROPIC_API_KEY=1`) | The service derives instead (segmented.md R-PARAM-5). Signed out as well: settings take their recorded `sampleValue`s, a scenario with a target declines `no_derive_key`, `deriveCostUsd: 0` |
+| The service declines, is slow, or cannot be reached | The same, with its reason carried into the `replay.derived` and `replay.decision` lines. Never a throw |
+| Derivation call fails or times out | Settings take their samples and targets stay `null`, never `{}`; a plan that needs a missing target hands over instead of running. Plus a `replay.derive_failed` or `replay.derive_timeout` line |
+| `paramsLogic` or `toolInputLogic` throws | The step is recorded as failed and the plan hands over: the note replaces the call (steer), or is `run_scenario`'s answer (direct). Never a crash |
+| `toolOutputLogic` throws | The step's tool ran, so the plan hands over with a note that says so (*"Do not run it again"*); outcome `fell_back` |
+| A logic body runs past `BIR_LOGIC_TIMEOUT_MS` | Stopped (*"… ran longer than N ms and was stopped"*), and handled as that logic throwing |
+| Model calls an unexpected tool (steer plan) | Divergence (§8) |
+| A direct plan's first call is not `run_scenario`, or its `run_scenario` never reaches the runner | Retired without running anything (`replay.vetoed`), `not_steered`; the call runs as written (§6.4) |
+| The expected tool, but not plausibly the step | No pin: it runs as written and the plan stays armed (`replay.pin_declined`). A call to another tool next retires the plan (`replay.pin_abandoned`) |
+| A call arrives while a pinned step is still running | It waits briefly for the pin to thread; still beside it, the plan hands over (`replay.concurrent_call`), `fell_back` or `failed` |
+| A pinned step fails (`PostToolUseFailure`, an error report from its proxy) | The plan hands over; nothing after it is pinned or approved |
+| A step cannot be sent: a built-in reached by a divergence, no proxy polling for its server, a server off `BIR_REPLAY_ALLOW_SERVERS` | Nothing is sent. The plan stops at that step and hands over (*"did not run … Nothing of it happened"*). With `BIR_REPLAY_RECORDED_OUTPUTS=1` its recorded output stands in instead |
+| Two sessions are open, and none of the server's proxies is known to be this session's | Nothing is sent: the step is not run, the plan hands over, and the model calls the tool on its own upstream. A lone session uses its unbound proxy as before |
+| A direct step exceeds `BIR_STEP_TIMEOUT_MS` | The proxy cancels the call upstream (`notifications/cancelled`) just before the control server gives up; the plan stops and hands over (*"was sent but did not answer … may or may not have completed"*). No recorded output stands in |
+| Whole plan exceeds its budget (`BIR_REPLAY_PLAN_BUDGET_MS`) | Return what completed behind a hand-over note, marked partial; outcome `diverged` (`failed` when no step had run) |
+| `run_scenario` cancelled (Esc) or `bir-scenario`'s 290 s timeout | No further step starts. The note saying which steps ran reaches the model on its next prompt or tool call; `fell_back` or `failed`, `measured: false` |
+| A `PreToolUse`'s replay work reaches its budget or deadline | No divergence step starts past `BIR_PRETOOL_REPLAY_BUDGET_MS`. At the 12 s route deadline the hook answers anyway: `{}` with a plan still getting ready retired (`replay.pin_overran`), or a divergence's note (`replay.diverge_overran`) |
+| Any hook route passes its deadline | It answers `{}` and logs `control.hook_deadline`; the work finishes in the background |
+| No running `bir` server has said hello | A direct plan is declined (`no_delivery_tool`); the agent does the task |
+| `bir-scenario` cannot find the control server | `run_scenario` answers *"Nothing to run for this request; continue normally."* (`isError: false`); the model proceeds normally |
+| A second `run_scenario` while the plan is running | Refused; the model is told the results come back on the first call |
+| `run_scenario` pending in two sessions and the request names neither | Nothing runs (`replay.run_ambiguous`); each model does its own task |
+| The runner is off (`bir off`, or `BIR_OFF=1` for a session) | Hooks answer `{}` and nothing arms; the `bir` server lists no tools |
+| Plan mode | Nothing is announced, pinned or approved |
+| Ticket redemption fails (offline, 409) | Logged; the turn is unaffected. An unredeemed ticket books nothing |
+| Two reports for one ticket (retry, `Stop` racing `SessionEnd`) | Server books once, answers `200 { duplicate: true }` |
+| Replay off (`BIR_REPLAY=0`, `bir replay off`, or never installed with `--replay`) | Exactly v1: stop recording on a match, do nothing else, and no prompt waits for the match |
+
+---
+
+## 15. Solution layout
+
+```
+src/
+├─ replay/                       ← new
+│  ├─ plan.ts                    # ScenarioReplayPlan (§9)
+│  ├─ logic.ts                   # the four logic evaluators, under a time limit — port BaseIn's (§9, §13.1)
+│  ├─ safety.ts                  # the injection guard for derived values (§13.2)
+│  ├─ derive.ts                  # Haiku parameter derivation over raw fetch (§16.3)
+│  ├─ pricing.ts                 # MODEL_PRICING + PRICING_VERSION — copy BaseIn's (§11.3)
+│  ├─ coverage.ts                # reachOf / modeFor (§5)
+│  ├─ bundle.ts                  # assembleBundle / truncate — port verbatim
+│  ├─ executor.ts                # direct step dispatch + the work queue (§16.2)
+│  ├─ source-run.ts              # lazy GET /recordings/runs/:id → recorded outputs by tool (§8.1)
+│  └─ types.ts                   # SerializedScenario, SerializedScenarioStep
+├─ bin/
+│  ├─ bir-scenario.ts            ← new: the `bir` MCP server — `run_scenario` (§6.3), later the scenario tools (§16.5)
+│  └─ bir.ts                     # + `--replay`, `bir scenario …`, `bir replay` (§16.5)
+├─ control/
+│  ├─ server.ts                  # + arm / pin / thread / dispatch / report
+│  ├─ pin-guard.ts               # whether a call is plausibly the step before it is pinned (§7)
+│  └─ transcript.ts              # + markTranscriptUsage / usageSince (§11.4)
+├─ proxy/
+│  └─ session.ts                 # + the long-poll work loop (§16.2)
+├─ record/
+│  ├─ recorder.ts                # + reportExecution() on the Recorder surface
+│  └─ remote-recorder.ts         # + POST /scenarios/:id/executions
+└─ config/adapters/claude-code.ts # the hook timeouts (§10); the `bir` MCP entry
+```
+
+`package.json` gains one bin: `"bir-scenario": "dist/bin/bir-scenario.js"`. Runtime dependencies stay
+at **zero** (§16.3).
+
+---
+
+## 16. Contracts
+
+### 16.1 Control-plane routes (new)
+
+```ts
+// bir-scenario → control server. toolUseId is Claude Code's params._meta["claudecode/toolUseId"];
+// only the plan of the session whose run_scenario PreToolUse is waiting runs (§6.3).
+POST /scenario/run    { toolUseId?: string, sessionId?: string }
+  → 200 { ok: true, text: string, responseModel: object, steps: number, partial?: boolean }
+  → 200 { ok: false, why: "no_plan" }                                    // no run_scenario pre waiting for it
+  → 200 { ok: false, why: "[BaseInstRunner calculated replay] …", note: true }  // hand-over: nothing ran live
+  → 200 { ok: false, why: "this scenario is already running for this turn — …" } // a second call
+  → 200 { ok: false, why: "not_ready" | "the scenario could not be run" }  // the run itself threw
+
+// bir-scenario → control server (never awaited; bounded at 1 s). Proof the delivery tool is live.
+POST /scenario/hello  { pid: number, version: string, tools: number, off: boolean }
+  → 200 { ok: true }
+
+// proxy → control server (long-poll; holds up to 25 s, then answers empty)
+POST /proxy/poll      { serverName: string, proxyId?: string, startedAt?: number, pid?: number, holdMs?: number }
+  → 200 {} | 200 { work: { workId: string; toolName: string; arguments: unknown; timeoutMs: number } }
+  → 200 { replay: false }                                                // replay is off: poll slowly
+
+// proxy → control server
+POST /proxy/result    { workId: string, result?: unknown, error?: string }
+  → 200 { ok: true }
+```
+
+### 16.2 The direct executor
+
+```ts
+// src/replay/executor.ts
+export type ExecuteStep = (step: SerializedScenarioStep, input: Record<string, unknown>) => Promise<string>;
+
+/** Hands work to the proxy that owns `serverName` and awaits its result. */
+export class ProxyWorkQueue {
+  /** Called by POST /proxy/poll. Resolves with work, or with undefined at the poll deadline. */
+  waitForWork(serverName: string, pollDeadlineMs: number): Promise<Work | undefined>;
+  /** Called by POST /proxy/result. */
+  complete(workId: string, result?: unknown, error?: string): void;
+  /**
+   * Dispatch and await one call. Rejects on timeout, on no polling proxy, and with
+   * NoSessionProxyError when no polling proxy can be shown to be `route.sessionId`'s.
+   */
+  call(serverName: string, toolName: string, args: unknown, timeoutMs: number,
+       route?: { sessionId?: string }): Promise<unknown>;
+}
+```
+
+> **[built] "No poller parked" is not the same as "no proxy".** The first implementation rejected
+> `call` immediately whenever no poller was waiting, on the reasoning that queued work could stall a
+> turn past its budget. That reasoning holds for a server no proxy serves — and is wrong for the case
+> that actually dominates: a proxy is *between* polls precisely while it is POSTing one step's result
+> and re-polling, which is exactly the gap between two steps of a multi-step plan. The end-to-end test
+> caught it as "step 2 of 2 never ran".
+>
+> So the queue tracks `lastSeen` per server. Work dispatched while a recently-seen proxy is
+> mid-round-trip is **held** for its next poll; the per-call timeout still bounds the wait, and a
+> server nothing has served for a minute still fails fast: the step is not sent, and the plan stops
+> there (§8) unless `BIR_REPLAY_RECORDED_OUTPUTS=1` lets its recorded output stand in.
+>
+> **[built] Which proxy.** Every Claude Code session starts its own proxies, and they are not
+> interchangeable: each holds its own upstream (another browser page, another database session). A
+> step goes to a proxy bound to the step's session — learned from a correlated call it reported, or
+> an earlier step of the session it ran — and otherwise to an unbound proxy **only while no other
+> session is live**. With two sessions open, a session with no bound proxy for the server gets none:
+> the call rejects with `NoSessionProxyError`, nothing is sent, the step is recorded as `skipped`,
+> and the plan hands over so the model calls the tool on its own upstream. `bir replay` has no
+> session and takes the newest proxy.
+
+Proxy side, in `ProxySession` — started as soon as the proxy is bound, whether replay is on or not:
+
+```ts
+while (!closed && !upstream.dead) {
+  const { work, ...answer } = await control.pollWork(this.serverName, holdMs);  // 25 s long-poll
+  if (!work) { pace(answer); continue; }                                       // see below
+  try {
+    // The reserved `bir:` id space, built for exactly this and never used by the relay.
+    // A little under the server's own budget, so a timeout's notifications/cancelled
+    // reaches the upstream before the control server gives up on the step.
+    const budget = work.timeoutMs - Math.min(1_000, work.timeoutMs / 10);
+    const result = await this.upstream.request("tools/call",
+      { name: work.toolName, arguments: work.arguments },
+      AbortSignal.timeout(budget));
+    await control.result(work.workId, result);
+  } catch (err) {
+    await control.result(work.workId, undefined, errText(err));
+  }
+}
+```
+
+The pace: a held poll re-polls at once; a control server that answers `{ replay: false }`, or
+answers at once, is polled every 30 s; one that cannot be reached (a recorder restarting) is retried
+with a backoff of at most 5 s, and the proxy registers again when it answers. The loop never stops
+on its own, so replay turned on with `bir up --restart` reaches open sessions within about 30 s.
+An aborted `bir:` request sends `notifications/cancelled` upstream. A proxy report or
+`/proxy/result` with no result at all is a call that was sent and may or may not have run — never
+a success.
+
+Note `work.toolName` is the **upstream-local** name (`navigate_page`), not the qualified one —
+`parseQualifiedName` splits it at dispatch. Storing both parts is what v1 §5 bought.
+
+> **[built] The proxy needs no replay configuration of its own.** `/proxy/register` answers
+> `{ replay: boolean, pollHoldMs }`, and `/proxy/poll` answers `{ replay: false }` while replay is
+> off, which only slows the loop down. `BIR_REPLAY` is therefore a single switch on the control
+> server, with no second copy in each wrapped entry's `env` to drift out of step with it.
+
+### 16.3 Derivation without a dependency
+
+```ts
+// src/replay/derive.ts — no SDK; ~50 lines of fetch.
+export async function deriveParameters(opts: {
+  prompt: string;
+  intent: string;
+  paramsObject: Record<string, { sampleValue: unknown; description: string }> | null;
+  apiKey?: string;                       // BIR_DERIVE_API_KEY — an override (see below)
+  service?: { baseUrl: string; token: string; scenarioId: string };  // the default path
+  model?: string;                        // default claude-haiku-4-5-20251001
+  signal?: AbortSignal;                  // default: times out after BIR_SERVICE_TIMEOUT_MS
+}): Promise<{ params: Record<string, unknown>; costUsd: number; derived: boolean }>;
+```
+
+Behaviour, matching RRepeat's `deriveParametersFromScenarioPayload` exactly so the two produce the
+same parameters from the same prompt:
+
+- No `paramsObject` keys → `{}`, `costUsd: 0`.
+- **No `apiKey` but a `service` → `POST {baseUrl}/scenarios/{id}/derive`** with the turn (prompt,
+  live call, recent results) and a bearer token, `derived` as the service answered. This is the
+  ordinary path: nearly every session runs inside Claude Code on a subscription and has no key of
+  its own (segmented.md R-PARAM-5). The answer is re-normalised here against this runner's own copy
+  of the schema, so the gate reads a `missing` computed from what will actually run.
+- **Neither → return every key's recorded `sampleValue`**, `costUsd: 0`, `derived: false`. Settings
+  stand on their samples; a scenario with a target declines rather than run on a stale one.
+- With an `apiKey`, `POST https://api.anthropic.com/v1/messages` with the same extraction prompt,
+  tolerant JSON extraction (first balanced `{…}`, `undefined` → `null`), and any `null`/missing
+  **setting** filled from its `sampleValue` — a `null` target is named in `missing` instead.
+
+The key comes from a variable set for this purpose alone, `BIR_DERIVE_API_KEY`. The background
+recorder has Claude Code's environment, and an API-billed Claude Code carries its
+`ANTHROPIC_API_KEY` there, so the recorder ignores that variable (logging `derive.api_key_ignored`)
+unless `BIR_USE_ANTHROPIC_API_KEY=1`; a `bir-hooks` run by hand in a terminal still uses it. The
+prompt (or an intent arm's reasoning) and any live call or recent results are redacted before they
+leave the machine, either way. The controller gives the request max(`BIR_SERVICE_TIMEOUT_MS`,
+`BIR_DERIVE_BUDGET_MS`) before it aborts it, and does not wait on the service at all while it is
+cooling down after a failure.
+
+Keeping this dependency-free is not purity. `bir-proxy` is spawned inside the host's process tree for
+*every* wrapped server; an npm install that pulls a model SDK into that path is a startup-latency and
+supply-chain cost paid N times per session, for a feature most sessions never arm.
+
+### 16.4 `Recorder` gains one method
+
+```ts
+export interface ScenarioReporter {
+  reportExecution(r: {
+    scenarioId: string; ticket?: string;
+    outcome: "steered_full" | "diverged" | "not_steered" | "failed" | "fell_back";
+    deriveCostUsd: number; sessionCostUsd: number; fallbackCostUsd: number;
+    durationMs: number; stepsPlanned: number; stepsPinned: number;
+    measured: boolean; pricingVersion: string; prompt?: string;
+  }): void;
+}
+export function isScenarioReporter(r: Recorder): r is Recorder & ScenarioReporter;
+```
+
+Optional capability, discovered the same way `isMatchAware` is — so `NullRecorder` needs no change
+and a session with no BaseIn credentials still replays (it just books nothing).
+
+### 16.5 CLI surface
+
+`bir` gains one flag and one command group. Everything here is a thin client over service
+endpoints, except `bir replay`, which drives §16.2's executor directly.
+
+```
+bir install --replay          register the `bir` MCP server (local scope) and switch replay on here
+bir uninstall --replay        take the `bir` server out and switch replay off; the rest of the install stays
+bir replay status|on|off|allow <a,b>|allow all
+                              this project's replay switches, kept in ~/.baseinstrunner/installed.json
+
+bir scenario list             GET  /recordings/runs               runs, iterations, scenario state
+bir scenario show <runId>     GET  /recordings/runs/:id/scenario  intent, params, steps, logic
+bir scenario show <scnId>     GET  /scenarios/:id                 the same, by scenario id (segments too)
+                                   [--step <n>: one step, with scenarioId and chainRevision first]
+bir scenario calc <runId>     POST /recordings/runs/:id/calculate     [--force to re-derive in place]
+                                   [--force --discard-edits: re-derive a plan with hand edits]
+bir scenario calc <scnId> --force
+                              POST /scenarios/:id/recalculate    recalculate in place (segments too)
+                                   [--discard-edits: sends {discardEdits: true}]
+bir scenario replay <scnId> --prompt "…" [--dry]
+
+bir scenario check <id> --step <n>    POST  /scenarios/:id/steps/:n/check        try a change; writes nothing
+bir scenario edit  <id> --step <n>    PATCH /scenarios/:id/steps/:n              the same check, then save
+bir scenario edits <id>               GET   /scenarios/:id/edits                 the history, newest first
+bir scenario undo  <id> [--edit <e> | --step <n>]
+                                      POST  /scenarios/:id/edits/:e/revert       take back the newest edit (of step n)
+bir scenario editing on|off|status    (no route) ~/.baseinstrunner/installed.json  which `bir` MCP tools are offered
+
+bir replay --scenario <scnId> --prompt "…" [--dry]     alias; the Tier 2 / debugging path (§12.1)
+```
+
+The second group, and `show <scnId>`, `--step`, `calc <scnId>` and `--discard-edits`, were added
+on 2026-09-25 by the service's `editSteps.md`. They are built and tested, and not yet released in
+the form described here (version 0.2.11 on npm has an early form): they need the next
+`@basein/runner` version and a service deploy, because their routes are new on the service. They
+are where `bir` changes a scenario by hand, so the rules are strict:
+
+- **Owner only.** Anyone else, an admin included, gets `404`, never `403`.
+- **A change is saved only if it reproduces the recording and is not a copy**, or on purpose with
+  `--force --note "<why>"`. `check` and `edit` run the same check; `check` never writes. When the
+  check had any problem, a forced save is recorded as forced, and `bir investigate` keeps saying so.
+- `<id>` is a `run_` id, resolved to its whole-run scenario with `GET /recordings/runs/:id/scenario`,
+  or a `scn_` id, used as it is. A sub-task scenario has only its `scn_` id; for a run with only
+  sub-task scenarios, `bir` lists their `scn_` ids. Logic goes in with `--input-logic` /
+  `--output-logic` from a file, or `-` for stdin — never inline, because shell quoting mangles
+  JavaScript. `edit` also takes `--freeze`, `--unfreeze`, `--note` and `--revision <n>` (the
+  `expectedRevision` of the body).
+- `show --step <n>` prints the step object with `scenarioId` and `chainRevision` first. The revision
+  is the scenario's, and is what `--revision` takes.
+- **`undo` walks back.** Without `--edit` it takes back the newest edit (never an undo entry) that
+  can be undone; with `--step <n>`, the newest edit of step `n`. Run again, it goes one further
+  back. `--edit` and `--step` cannot be given together. To redo, undo the undo entry by its
+  `sedit_` id; the undo prints that command. The service checks an undo like a save, for the later
+  steps and the final answer (so only when it changes output logic), and answers
+  `422 undo_refused` when it would break them, unless `--force --note "<why>"` is given. Every
+  save and every undo bumps the scenario's `chainRevision`.
+- A save lifts a mark made by hand (`--freeze`, `by_hand`) only with `--unfreeze`; undoing the
+  freeze, or `calc --force --discard-edits`, also removes it. A forced save lifts only a mark the
+  calculation set.
+- `calc --force` answers `409 scenario_has_edits` on a plan with hand edits, unless
+  `--discard-edits` is given. `calc <scnId>` without `--force` is a usage error: nothing is sent.
+- Answers `bir` puts in words: `400 nothing_to_change` (the code and mark asked for are the step's
+  already), `413 payload_too_large`, `503 logic_sandbox_unavailable` (nothing was checked, saved or
+  undone), and a check report with `noChange: true` (`check` then says nothing would change, and
+  exits `0`).
+- Exit codes: `0` checked OK, saved or undone; `1` refused, not found, or a service error; `2`
+  usage. `--json` prints the service's body unchanged.
+
+The same commands are tools on the `bir` MCP server, which by default lists only `run_scenario`:
+every tool definition rides along with every request of every session. `scenario_show` (`target`,
+`step`), `scenario_edits` (`target`) and `investigate` (`id`) only read; they are listed in a project
+where `bir scenario editing on` was run, or with `BIR_SCENARIO_TOOLS=read` in the `bir` server's
+environment, and answer a host that calls them unlisted all the same. `scenario_check` (`target`,
+`step`, `inputLogic`, `outputLogic`, `unfreeze`), `scenario_edit` (the same, plus `freeze`, `force`,
+`note`, `revision`) and `scenario_undo` (`target`, `edit` or `step`, `force`, `note`) are offered
+only in a project where `bir scenario editing on` was run, because that server runs in every session
+of every installed project. Each tool runs this package's own `bir … --json`, with logic bodies
+passed through temporary files; a refusal comes back as an MCP error result carrying the report. A
+reading tool's answer is capped at 24 000 characters (`BIR_SCENARIO_MAX_OUTPUT_CHARS`) and gives up
+after `BIR_READ_TIMEOUT_MS` (15 s) plus 10 s; a changing tool gets 120 s. A call the host cancels, or
+leaves behind when it exits, has its `bir` stopped and its files removed. While the runner is off,
+the server lists nothing; a reading tool answers that there is nothing to read, and a changing tool
+is refused.
+
+**`bir`'s own calls are never recorded** (the service's `editSteps.md` D13; not yet released). The
+`bir` server's tools other than `run_scenario`, and a `Bash` or `PowerShell` command made only of
+`bir` invocations (and a plain `cd`), are host housekeeping, like `ToolSearch`
+([housekeeping.ts](../src/record/housekeeping.ts)). They are never recorded as steps, and never
+count as divergence from a plan. A session that fixes a plan must not become a plan that edits
+plans when it is replayed. The operator's walk-through is
+[calculatedReplayGuide.md](calculatedReplayGuide.md) §9.2.
+
+`--dry` maps to BaseIn's `POST /scenarios/:id/replay`, which evaluates the stored logic against the
+source run's *recorded* outputs — no real tools, no side effects, one Haiku call. Without `--dry`,
+`bir replay` runs the same plan through the same executor against the live proxies. `bir doctor`
+gains a `replay` block: on/off, the effective `BIR_REPLAY_ALLOW_SERVERS` allowlist,
+`BIR_MIN_STEER_SIMILARITY`, and who derives — this machine, the service, or nobody, which is the
+state in which a scenario with a target never runs (§13.2, mitigation 3).
+
+---
+
+## 17. Implementation phases
+
+Each phase ends in something runnable. Do not start a phase before its predecessor's acceptance test
+passes.
+
+### Phase R0 — Plan, logic, coverage (no wiring)
+Port `logic.ts` from BaseIn, `bundle.ts` and `ScenarioReplayPlan` from RRepeat, write `coverage.ts`.
+Pure, dependency-free, no I/O.
+**Acceptance:** unit tests replay a fixture `SerializedScenario` end to end against a stub executor
+and reproduce the recorded outputs byte for byte.
+
+### Phase R1 — Derivation and pricing
+`derive.ts` + `pricing.ts`. Both fully testable against a fake `fetch`.
+**Acceptance:** with no key, derivation returns sample values at zero cost; with a stubbed key, it
+parses fenced JSON, bare JSON and prose-wrapped JSON, and prices a known `usage` to the same cent as
+BaseIn's `cost.ts`.
+
+### Phase R2 — Arming and the decision log
+`onPrompt` awaits `getMatch()` under budget, runs the gate ladder, computes the mode, arms the plan,
+returns the directive. **No execution yet.**
+**Acceptance:** a fake recorder returns a match; assert exactly one `plan.armed` or one
+`replay.decision` line per prompt, the right mode, and that the prompt hook returns inside the
+budget when `getMatch` never resolves.
+
+### Phase R3 — Steer mode
+`/tool/pre` pinning (with the §7.1 `updatedInput` merge), `/tool/post` threading (with the §7.2
+source split), retire on done.
+**Acceptance:** a scripted hook sequence drives a 3-step plan to `steered_full`; a wrapped-MCP step
+threads from `/proxy/step` and not from the hook; reordering the model's calls produces exactly one
+divergence and no crash.
+
+### Phase R4 — The work queue and direct execution
+`ProxyWorkQueue`, `/proxy/poll`, `/proxy/result`, the proxy-side loop.
+**Acceptance:** against `test/fake-upstream.ts`, a 3-step direct plan executes with `respParams`
+threaded between steps; killing the proxy mid-plan degrades to `recordedOutput`/skip and the session
+survives. **[changed]** The plan now stops at that step and hands over (§8); a recorded output stands
+in only with `BIR_REPLAY_RECORDED_OUTPUTS=1`.
+
+### Phase R5 — `bir-scenario` and direct delivery
+The MCP server, `/scenario/run`, `bir install --replay`.
+**Acceptance:** a real Claude Code session on a fully-wrapped scenario answers from one
+`run_scenario` call, and the transcript shows a genuine `tool_result`.
+
+### Phase R6 — Divergence
+Direct-execute the remainder; the lazy source-run fetch for `live` steps (§8.1); Bash-clean,
+`bir`-tool and deny delivery; the fair-share bundle cap.
+**Acceptance:** forcing an off-script call produces a bundle under `MAX_REPLAY_REASON` containing
+every remaining step; a `live` step is served its recorded output, marked `(recorded)`, and threads
+`respParams` for the steps after it; a `live` step with no recorded output is skipped with a warning
+and later steps still resolve. **[changed]** Recorded outputs stand in only with
+`BIR_REPLAY_RECORDED_OUTPUTS=1`, and a step with no result ends the bundle there: later steps do
+not run on nothing, and the bundle opens with a hand-over note.
+
+### Phase R7 — Reporting
+The usage watermark, `reportExecution`, ticket redemption in `sealRun`, `bir doctor` fields.
+**Acceptance:** three prompts in one session produce three *non-cumulative* `sessionCostUsd` values;
+a declined match books a baseline sample; a doubled report books once.
+
+---
+
+## 18. Testing
+
+Extends v1 §11; same `node:test` harness, same `test/fake-upstream.ts`.
+
+1. **Plan semantics** — `respParams` threading, `paramsLogic` applied once, `isDone` after the last
+   step, throw-propagation for each of the four logic hooks.
+2. **Coverage** — every combination of wrapped/unwrapped MCP and built-in maps to the right mode,
+   including the empty-steps and all-live cases.
+3. **The `updatedInput` merge (§7.1)** — a pinned wrapped-MCP call carries both the pinned arguments
+   and `__bir_call_id__`; the correlation's `hookArgs` are the *pinned* ones; `--no-correlation`
+   still pins.
+4. **The threading source (§7.2)** — a wrapped step threads the proxy's `result`, not the hook's
+   `tool_response`, and threads the hook's view only after the grace window, with the warning.
+5. **Budgets** — a `getMatch` that never resolves still returns the prompt hook inside its budget;
+   a derivation that never resolves still pins a scenario of settings, using sample values, and
+   hands over one that needs a target it was not given; the direct-run worst case stays under the
+   270 s ceiling.
+6. **Direct execution** — end to end through `fake-upstream`, including a step timeout, a dead proxy
+   and a `tools/call` that returns `isError: true` (a *result*, not a transport failure: it is read,
+   and the plan stops and hands over rather than threading on it).
+7. **Divergence** — both delivery channels; delimiter neutralisation in the Bash path, and the
+   file route past 6 000 characters; the fair-share cap with one enormous response and four small
+   ones; the bundle ending at a step with no result.
+8. **Reporting** — the watermark across three prompts; each outcome's server-side effect against a
+   fake BaseIn; ticket idempotence.
+9. **Integration** — a real Claude Code session against `fake-upstream` with a hand-written scenario,
+   asserting a `steered_full` report. The only test that catches host-behaviour drift.
+
+---
+
+## 19. Rejected alternatives
+
+**19.1 Deliver direct-mode results as `additionalContext`.** No extra MCP server, no extra tool in the
+list. Rejected: it must execute inside `UserPromptSubmit`'s timeout (§10), and it asserts to the model
+that tools ran without a transcript record that they did. §6.2.
+
+**19.2 A callback URL per proxy instead of long-polling.** Faster dispatch, no idle connection.
+Rejected: N new loopback listeners, N new tokens, N new things `bir doctor` must verify — for a
+latency saving of milliseconds on a path already dominated by the upstream's own round trip. Dialling
+out is also the posture v1 §9 already chose everywhere else. D12.
+
+**19.3 Give `bir-scenario` its own upstream connections.** Then no work queue at all. Rejected
+outright: it double-spawns every upstream. Two `chrome-devtools-mcp` processes means two browsers,
+two profiles, and a scenario that navigates one and screenshots the other.
+
+**19.4 Port RRepeat's Agent-SDK divergence fallback.** Rejected: it is the dominant cost of RRepeat's
+calculated run (`savingCalcRunner.md` §4), it adds `@anthropic-ai/claude-agent-sdk` to a
+zero-dependency package, it needs anti-recursion guards, and here it buys nothing the proxies do not
+already buy for free. §8.
+
+**19.5 Block the prompt and answer from the scenario alone.** The original RRepeat design, superseded
+there (`replay.md` §1, §10). Rejected for the same reasons plus one of ours: it forfeits the live
+session's built-in tools entirely, which is exactly the half of a mixed scenario the proxy cannot
+reach.
+
+**19.6 Match on the whole conversation rather than the prompt.** Arguably better "similar meaning".
+Rejected as a *server* concern: `findSimilarRun` embeds `run.input`, and changing what is embedded
+changes the corpus, the threshold and every stored vector. §20 question 1.
+
+---
+
+## 20. Open questions
+
+1. **Should the match embed more than the first prompt?** A turn's meaning often lives in the
+   preceding turn. Changing it is a BaseIn-side decision with a corpus migration attached, and it
+   would let `bir` match mid-conversation rather than only at a turn boundary.
+2. **Does BaseIn want a `direct` outcome?** Today direct mode reports `steered_full`, which is
+   accurate but hides that the run cost no session tokens at all. A sixth enum member would let the
+   ledger separate "the model was steered cheaply" from "the model did not run the task."
+3. **A separate `node:vm` context for the logic bodies?** §13.1 states plainly that there is no
+   sandbox. The bodies already run through `node:vm`, but in this process's own context, which buys
+   a time limit and nothing more. A frozen, minimal context would close the gap between
+   "first-party by provenance" and "first-party by construction", at the price of the shared realm
+   and argument objects the bodies rely on today.
+4. **Should a declined match still arm a *dry* plan?** Deriving parameters and computing the first
+   step's input without executing anything would make `bir doctor` able to say *"this scenario would
+   have run these three calls"* — excellent for tuning `BIR_MIN_STEER_SIMILARITY`, at the price of a
+   Haiku call on turns that replay nothing.
+5. **Should `scenario_steps` carry `recorded_output`?** §8.1 works around its absence with one lazy
+   `GET /recordings/runs/:runId`. A column would make it a field read, would let a scenario outlive
+   the deletion of its source run, and would finally make RRepeat's `recordedOutput` field mean
+   something. Cost: the scenario row grows by the size of every step's output.
+6. **Cwd fit.** A scenario recorded in project A may pin paths that do not exist in project B, and
+   nothing currently checks. A cheap sixth gate — compare `run.metadata.cwd` — would catch the common
+   case; the general case (relative paths, monorepos) is harder and probably belongs in
+   `toolInputLogic` generation server-side.