@basein/runner 0.1.0

package/docs/calculatedReplay.md

@@ -0,0 +1,1185 @@
+# 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 | **Off.** `BIR_REPLAY=1` plus `bir install --replay` | Replay bypasses permission prompts (§13.2); opt-in is the only defensible default |
+| **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) |
+
+---
+
+## 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 !== "1"` | `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.
+
+### 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_REPLAY` off by default; `bir install --replay` a distinct, non-default flag.
+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` | Derivation skipped; the scenario's recorded `sampleValue`s are used. `deriveCostUsd: 0` |
+| 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 one-tool MCP server (§6.3)
+│  └─ 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
+  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` → return every key's recorded `sampleValue`**, `costUsd: 0`, `derived: false`. A plain
+  replay of the recorded parameters, free, and the documented default for anyone without a key.
+- Otherwise `POST https://api.anthropic.com/v1/messages` with the same extraction prompt, tolerant
+  JSON extraction (first balanced `{…}`, `undefined` → `null`), and any `null`/missing key filled
+  from its `sampleValue`.
+
+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 endpoints that
+already exist server-side, 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 calc <runId>     POST /recordings/runs/:id/calculate     [--force to re-derive in place]
+bir scenario replay <scnId> --prompt "…" [--dry]
+
+bir replay --scenario <scnId> --prompt "…" [--dry]     alias; the Tier 2 / debugging path (§12.1)
+```
+
+`--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 whether an `ANTHROPIC_API_KEY` was found (§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.