@basein/runner 0.2.12 → 0.3.0

package/docs/calculatedReplayGuide.md

@@ -1,1087 +1,1212 @@
-# Calculated Replay — instructions
-
-> The operator's half of [calculatedReplay.md](calculatedReplay.md). That document says *why*; this
-> one says *what to type*, in order, from an empty machine to a prompt that answers itself.
->
-> **Read this first.** Replay executes tool calls with arguments a scenario computed, and it does so
-> **without the permission prompts you would normally see** (design §13.2). `bir setup` (§1) turns it
-> on. Read §5 before you leave it on; `bir replay off` turns it off, and §2–§4 work either way.
-
----
-
-## 0. The shape of it, in thirty seconds
-
-```
-1. Record          you work normally; bir records the run
-2. Calculate       BaseIn analyses that run into a reusable scenario
-3. Match           next time you ask the same thing in different words,
-                   the server recognises it and hands the scenario back
-4. Replay          bir runs the scenario's tools instead of the model
-                   rediscovering the plan
-```
-
-All four are implemented — see §10 for the map from design phase to code, and for how to run the
-end-to-end smoke test.
-
----
-
-## 1. Prerequisites
-
-| # | You need | Check it with |
-|---|---|---|
-| 1 | A BaseIn service you can reach | `bir status` — its `BaseIn :` line is the address `bir setup` stored; `curl -fsS "<that address>/health"` proves it answers |
-| 2 | Anthropic configured **on the server** — calculation and derivation both need it | a `503 anthropic_not_configured` from `/calculate` means it is not |
-| 3 | `SIMILARITY_DETECTION_ENABLED=true` on the server (default) | otherwise no prompt ever matches |
-| 4 | BaseInstRunnerMCP built and installed in your project | `bir status` |
-| 5 | Tier 1 — the hooks wired and the recorder running | `bir doctor`; the SessionStart hook starts it |
-| 6 | *(replay only)* signed in, so the service can read what each request acts on | `bir doctor` — `derive=the service`; an `ANTHROPIC_API_KEY` here replaces it, see §5.3 |
-
-Tier 1 is not optional for replay. A match is a match on **the prompt**, and a standalone proxy never
-sees one (design §1.1). If `bir doctor` says `Recording tier : standalone (Tier 2)`, replay cannot
-arm, and that is the honest ceiling rather than a bug.
-
-One line, pasted into a terminal opened in the project you start Claude Code in. The console's *Set
-up the runner* page shows it with a one-time setup token filled in. Pasted in the home folder or a
-drive root it stops before downloading anything — `cd` to the project and paste the same line again:
-
-```powershell
-$env:BIR_SETUP_TOKEN="<token>"; irm https://api.bi2202.com/install.ps1 | iex      # Windows (PowerShell)
-```
-
-```bash
-curl -fsSL https://api.bi2202.com/install.sh | BIR_SETUP_TOKEN="<token>" sh       # macOS / Linux
-```
-
-From cmd.exe: `powershell -NoProfile -Command "$env:BIR_SETUP_TOKEN='<token>'; irm https://api.bi2202.com/install.ps1 | iex"`.
-
-It installs Node and Claude Code if they are missing, installs the package, and runs `bir setup`:
-sign-in, the service address stored in `~/.baseinstrunner/config.json`, the project's MCP servers
-wrapped, the hooks wired into `.claude/settings.local.json`, the scenario server added, the recorder
-started in the background. Nothing stays open: the SessionStart hook starts the recorder whenever
-it is missing, and its audit lines go to `~/.baseinstrunner/logs/<key>.log`. Re-running the line
-upgrades. With the package already installed, the same thing is:
-
-```bash
-bir setup --auth-url https://api.bi2202.com    # without a token it signs in through the browser
-```
-
----
-
-## 2. Record a run worth reusing
-
-Nothing special — work normally. Two server-side facts decide whether the run becomes reusable, and
-both bite quietly:
-
-**A run needs at least `RECORDING_MIN_ACTIONS` tool actions (default 4).** Below that it is not
-embedded, does not enter the similarity pool, does not appear in the list, and is eventually pruned.
-A two-tool run will never match anything, no matter how many times you repeat it.
-
-**The prompt is what gets embedded.** `findSimilarRun` embeds `run.input` — the text of your
-`UserPromptSubmit` — not the transcript, not the answer. So the prompt that *starts* the turn is the
-one future prompts are compared against. Write the first prompt of a reusable task as if someone else
-will have to phrase it again.
-
-Watch it land:
-
-```
-[bir] …  run.start   run=run_… sess=birsess_… tier=bound
-[bir] …  run.finish  run=run_… steps=14 durationMs=48210 lossy=false recorded=true
-```
-
-`recorded=false` means the service declined the run — usually because it matched something you
-already have. That is §4 working.
-
-List what you have:
-
-```bash
-bir scenario list                    # or: GET /recordings/runs
-```
-
-```
-run_5f3a…  Fleet risk sweep
-    iterations=3  steps=14  scenario=scn_9c1b… (ready)
-run_a812…  Rewrite the billing README
-    iterations=1  steps=9  scenario=none — run `bir scenario calc <runId>`
-run_c004…  Check open PRs for stale reviews
-    iterations=1  steps=6  scenario=scn_44d0… (calculating)
-```
-
-Ids are printed in full on their own line (shortened here), so they can be copied straight into
-`calc` and `replay`.
-
----
-
-## 3. Calculate the scenario
-
-A recorded run is a transcript. A **scenario** is what BaseIn derives from it: an intent, a parameter
-schema, and one JavaScript logic body per step that recomputes that step's tool arguments from new
-parameters. Until a run has one, a match can only stop recording — there is nothing to run.
-
-```bash
-bir scenario calc run_5f3a…            # POST /recordings/runs/:runId/calculate → 202
-bir scenario show run_5f3a…            # GET  /recordings/runs/:runId/scenario  (poll)
-```
-
-Raw, if you prefer — the service address lives in `~/.baseinstrunner/config.json` (`BIR_AUTH_URL`
-is normally unset after `bir setup`) and the token in `~/.baseinstrunner/credentials.json`:
-
-```bash
-BASEIN=$(node -p "require(require('os').homedir()+'/.baseinstrunner/config.json').authUrl")
-TOKEN=$(node -p "require(require('os').homedir()+'/.baseinstrunner/credentials.json').accessToken")
-curl -fsS -X POST "$BASEIN/recordings/runs/run_5f3a…/calculate" \
-     -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{}'
-```
-
-```powershell
-$b = (Get-Content "$HOME\.baseinstrunner\config.json" | ConvertFrom-Json).authUrl
-$t = (Get-Content "$HOME\.baseinstrunner\credentials.json" | ConvertFrom-Json).accessToken
-Invoke-RestMethod -Method Post -Uri "$b/recordings/runs/run_5f3a…/calculate" `
-  -Headers @{ authorization = "Bearer $t" } -ContentType 'application/json' -Body '{}'
-```
-
-Calculation is a background job. Poll `show` until `state` leaves `calculating`:
-
-| `state` | Meaning | Next |
-|---|---|---|
-| `calculating` | job running | poll again in a few seconds |
-| `ready` | usable | §4 |
-| `failed` | see the `error` field | fix and recalculate with `--force` |
-
-`409 scenario_exists` means this run already has one. Re-derive it in place — keeping the id and its
-replay history — with `bir scenario calc run_… --force`. A `run_` id reaches only the run's
-whole-run scenario. From the next version (not yet released), `bir scenario calc scn_… --force`
-does the same by the scenario's own id, a sub-task scenario included; it is the only way to
-recalculate a sub-task scenario from `bir`.
-
-To change one step instead, without recalculating, see §9.2. A plan with steps edited by hand is
-not rebuilt unless you add `--discard-edits`, which replaces those edits. They stay in
-`bir scenario edits`, marked replaced, and can no longer be undone.
-
-### 3.1 Check the scenario before you trust it
-
-**Dry replay is the cheapest thing you will do all day. Do it every time.** It derives parameters
-from a fresh prompt and runs the stored logic against the *original run's recorded outputs* — no real
-tools, no side effects, one Haiku call:
-
-```bash
-bir scenario replay scn_9c1b… --prompt "which devices in the fleet look risky right now?" --dry
-```
-
-```
-params      { "fleetId": "eu-west-1", "riskThreshold": 0.8 }
-step 0      mcp__chrome-devtools__navigate_page  { "url": "https://fleet.internal/eu-west-1" }
-step 1      mcp__chrome-devtools__take_snapshot  {}
-              → emitted: devices
-step 2      mcp__fleet-api__device_detail        { "id": "dev_88f1" }
-              → emitted: highestRiskDeviceId, riskScore
-response    { "fleet": "eu-west-1", "atRisk": 3, "worst": "dev_88f1" }
-cost        $0.0012
-```
-
-Read it for three things:
-
-1. **Did the parameters come out right** for a prompt phrased differently from the original?
-2. **Do the step inputs look computed**, or are they the original run's constants copied through? A
-   scenario whose inputs never vary with the parameters is a recording, not a scenario.
-3. **Is `emitted` non-empty** for steps that later steps depend on? `emitted` lists key names only;
-   `→ emitted: (nothing — toolOutputLogic derived no keys)` means every downstream input reading
-   that step will be wrong.
-
-A `↑ not named by the prompt:` line under `params` lists targets the dry run filled from the
-recording. A live turn finds those in an earlier step, or does not run — so a green trace with
-that line is not yet evidence that a session would steer.
-
-A dry replay is recorded as `outcome: 'dry'` and is excluded from savings by construction — it costs
-you a Haiku call and nothing else.
-
----
-
-## 4. Confirm the match fires
-
-Now ask the same thing in different words, in a new session.
-
-```
-you:  can you check the eu-west fleet and tell me which boxes are in trouble?
-```
-
-```
-[bir] …  run.matched  run=run_… matchedRun=run_5f3a… similarity=0.94
-         why="similar prompt — the service kept its own run; not recording this one"
-```
-
-That line is the whole feature working up to the point of replay. If it does not appear, the prompt
-did not clear the server's `SIMILARITY_THRESHOLD` (default 0.9) — see §8.
-
-**With replay off (`bir replay off`), this is where it stops.** The server keeps its canonical run, bumps
-its `iterations`, this turn is not recorded, and the model answers the ordinary way. Nothing is lost
-and nothing is skipped.
-
----
-
-## 5. Turn replay on
-
-> Read §5.1 before running anything in this section.
-
-### 5.1 What you are agreeing to
-
-A calculated scenario is, in effect, **a pre-approved list of tool calls with computed arguments.**
-When replay arms:
-
-- **Steered steps are auto-approved.** `PreToolUse` is answered `allow`, so a pinned `Bash` or `Edit`
-  runs without the prompt you would normally see.
-- **Direct steps are not visible to the permission system at all.** They are dispatched straight to a
-  `bir-proxy`, which calls the upstream on a connection it already holds. Claude Code never sees them.
-
-That is what makes replay fast, and it is the whole risk. Two things follow:
-
-1. Only enable it in a project whose scenarios you have dry-replayed and read (§3.1).
-2. Run `bir replay allow <servers>` (§5.3). An allowlist of the servers you are comfortable having
-   called unattended is cheap insurance, and it is the difference between "replay reads a dashboard"
-   and "replay can do anything any wrapped server can do".
-
-### 5.2 Enable it
-
-`bir setup` already did this: it installed the scenario server and pre-approved it, so Claude Code
-asks no question about it. By hand:
-
-```bash
-bir install --replay          # adds the `bir` MCP server (pre-approved)
-bir up --restart              # the recorder reads the change when it restarts
-```
-
-A flag-less `bir install` keeps the invocation the project was set up with — `bir setup` installs
-with `--global` from an installed package and `--local` from a checkout — so this downgrades
-nothing. `bir install --replay` does exactly two things beyond a normal install, and
-`bir uninstall --replay` takes the scenario server out again and leaves everything else as it is:
-
-- registers a first-party MCP server under the key **`bir`** in the project's `.mcp.json` (never
-  `~/.claude.json`), exposing `mcp__bir__run_scenario` — the channel a fully-wrapped scenario's
-  results come back through. It also offers three tools that only read a scenario
-  (`scenario_show`, `scenario_edits`, `investigate`) and, only after `bir scenario editing on`,
-  three for changing one (`scenario_check` tries a change, `scenario_edit` saves it,
-  `scenario_undo` takes it back). §9.2 lists them with their arguments; the editing it describes
-  is built but not yet released. From the next version, a call to any of them except
-  `run_scenario` is never recorded;
-- pre-approves that server in `.claude/settings.local.json` (`enabledMcpjsonServers`), because a
-  "No" to Claude Code's approval dialog leaves a direct replay with nowhere to deliver its results.
-
-The `UserPromptSubmit` hook's 15 s timeout, which the match round trip needs, is not one of them:
-every install writes it, replay or not.
-
-The `bir` tools are visible to the model in every session in this project. That is a real cost — a
-few more tools in the list, a little context per turn — and it is why replay is a separate flag
-rather than part of `bir install`. The tools that change a scenario are not among them until you
-run `bir scenario editing on` (§9.2).
-
-Confirm:
-
-```bash
-bir doctor
-```
-
-```
-Replay            : ON  servers=chrome-devtools,fleet-api  minSimilarity=0.92  source=sidecar
-                    derive=the service (no key needed here)
-Wrapped in config : chrome-devtools, fleet-api
-Registered proxies: chrome-devtools, fleet-api
-Control server    : http://127.0.0.1:53411
-BaseIn (shell)    : https://api.bi2202.com (answers /health)
-Recording tier    : bound (Tier 1)
-Recording         : yes
-
-  · recording to https://api.bi2202.com as you@example.com
-  · the recorder runs in the background (pid 41820); its audit log is ~/.baseinstrunner/logs/<key>.log
-  · recurring sub-tasks are observed only — nothing is replaced (BIR_SEGMENT_ARM unset)
-
-No problems found.
-```
-
-`BaseIn (shell)` is the address this terminal's `bir` commands would use — `BIR_AUTH_URL` if it
-is set, else the one `bir setup` stored — and `recording to` is the one the running recorder
-uses, with the account it is signed in as. The two normally agree.
-
-### 5.3 Environment
-
-The first three switches are stored per project, and that is where to set them:
-
-```bash
-bir replay allow chrome-devtools,fleet-api   # the servers direct execution may call; `allow all` clears it
-bir replay off                               # and back with `bir replay on`
-bir replay status                            # what is stored for this project
-bir up --restart                             # a running recorder reads them when it restarts
-```
-
-They are kept in `~/.baseinstrunner/installed.json`. A recorder started by the SessionStart hook has
-Claude Code's environment, not your terminal's, and reads them from there. The environment variables
-below override them wherever the recorder sees them; `bir doctor` says which is in effect
-(`source=sidecar` or `source=env`). The proxies need no replay configuration of their own — each one
-is told whether to open its work loop when it registers, so there is exactly one switch and it cannot
-get out of step with itself.
-
-| Variable | Default | What it does |
-|---|---|---|
-| `BIR_REPLAY` | *(on)* | `0` disables replay. Unset or any other value keeps it on; nothing below matters while it is `0` |
-| `BIR_REPLAY_ALLOW_SERVERS` | *(the stored list, else all wrapped)* | Comma-separated server keys eligible for **direct** execution. Overrides `bir replay allow` |
-| `BIR_MIN_STEER_SIMILARITY` | `0.92` | Below this a match is detected but not replayed (§8) |
-| `ANTHROPIC_API_KEY` | *(unset)* | **Not required.** Derivation — reading what this request acts on — is done by the service on its key for a signed-in runner. Set this to keep the reading on this machine instead: the prompt then never leaves it, and it is one round trip faster. Signed out *and* unset, only a scenario with nothing to work out replays |
-| `BIR_DERIVE_MODEL` | `claude-haiku-4-5-20251001` | The derivation model, when this machine does the reading |
-| `BIR_MATCH_BUDGET_MS` | `2500` | How long the prompt hook waits for a match before giving up |
-| `BIR_DERIVE_BUDGET_MS` | `8000` | How long the first `PreToolUse` waits for parameters |
-| `BIR_REPLAY_BUDGET_MS` | `120000` | Whole-plan ceiling for direct execution |
-| `BIR_STEP_TIMEOUT_MS` | `60000` | Per-step ceiling for one direct `tools/call` |
-| `BIR_VERBOSE` | *(unset)* | `1` adds per-step `replay.*` detail lines |
-
-**No API key is a supported configuration, not a broken one.** Signed in, the service reads the
-prompt on its own key and the replay is the same replay. Signed out *and* without a key, nothing
-can read the prompt: a *setting* takes the value it had in the recorded run, so a scenario whose
-parameters are all settings — a dashboard sweep, a fixed report — is still a complete, free replay;
-but a scenario with a *target* (the thing the task acts on: "check *eu-west*") is declined rather
-than run on last week's value, and the agent does the task normally. `bir doctor` names the state
-you are in: `derive=this machine (ANTHROPIC_API_KEY)`, `derive=the service (no key needed here)`,
-or `derive=recorded sample values — scenarios with a target will NOT run`.
-
----
-
-## 6. Run it, and read what happened
-
-Ask the matching question again, with replay on.
-
-### 6.1 A fully-wrapped scenario — direct
-
-```
-[bir] …  run.matched   run=run_… matchedRun=run_5f3a… similarity=0.94
-[bir] …  plan.armed    scenario=scn_9c1b… mode=direct steps=3
-         tools="mcp__chrome-devtools__navigate_page,mcp__chrome-devtools__take_snapshot,mcp__fleet-api__device_detail"
-[bir] …  replay.derived  scenario=scn_9c1b… params=2 costUsd=0.0011 source=the service
-[bir] …  replay.step     n=0 tool=navigate_page server=chrome-devtools ms=612 ok=true
-[bir] …  replay.step     n=1 tool=take_snapshot  server=chrome-devtools ms=1104 ok=true emitted=devices
-[bir] …  replay.step     n=2 tool=device_detail  server=fleet-api ms=210 ok=true emitted=highestRiskDeviceId,riskScore
-[bir] …  replay.done     scenario=scn_9c1b… mode=direct steps=3/3 outcome=steered_full ms=2766
-[bir] …  execution.reported  scenario=scn_9c1b… outcome=steered_full derive=0.0011 session=0.0083 fallback=0.0000 savedUsd=0.114
-```
-
-In the session you will see one tool call, `mcp__bir__run_scenario`, returning the composed results.
-The model reads them and answers. It never emitted the three underlying calls.
-
-### 6.2 A mixed scenario — steer
-
-The model emits each call itself; `bir` overrides the arguments. The per-step `replay.pin` and
-`replay.thread` lines are detail lines, printed only under `BIR_VERBOSE=1`; without it a steer run
-shows `plan.armed`, `replay.done`, and any `replay.thread_fallback` between them.
-
-```
-[bir] …  plan.armed    scenario=scn_44d0… mode=steer steps=4
-[bir] …  replay.pin    n=0 tool=mcp__github__list_pull_requests
-[bir] …  replay.thread n=0 via=proxy emitted=prNumbers done=false
-[bir] …  replay.pin    n=1 tool=Read
-[bir] …  replay.thread n=1 via=hook emitted=reviewers done=false
-[bir] …  replay.done   scenario=scn_44d0… mode=steer steps=4/4 outcome=steered_full
-```
-
-`via=proxy` versus `via=hook` matters: a wrapped MCP step's output is threaded from the **proxy's**
-report, because that is the shape the scenario's logic was written against (design §7.2). A
-`replay.thread_fallback run=… tool=… why="no proxy report — threading the hook's view; shapes may differ"`
-line — printed whether or not you are verbose — means the proxy did not report within its grace
-window and the hook's differently-shaped view was used instead. Expect derived values to be empty,
-and treat repeats as a bug.
-
-### 6.3 The model goes off-script
-
-```
-[bir] …  replay.diverge  scenario=scn_44d0… expected=Read called=Bash step=2/4
-[bir] …  replay.compose  scenario=scn_44d0… remaining=2 executed=1 recorded=1 skipped=0 bytes=8412 costUsd=0.00
-[bir] …  replay.done     scenario=scn_44d0… mode=steer steps=2/4 outcome=diverged
-```
-
-`costUsd=0.00` on the compose line is the point of the whole design: the remaining steps ran through
-proxies that were already connected, so recovering from a divergence cost no tokens at all.
-
-### 6.4 The audit vocabulary
-
-Everything replay decides is one line. `grep` for these:
-
-| Line | Means |
-|---|---|
-| `run.matched` | The server recognised the prompt |
-| `replay.decision … verdict=no-steer` | Matched, and declined. `why=` says which gate |
-| `plan.armed` | A plan exists. Carries mode, step count and the ordered tool names — **before** anything runs |
-| `replay.derived` / `replay.derive_failed` | Parameters resolved, or fell back to sample values |
-| `replay.pin` / `replay.thread` | One steered step's input pinned / output threaded — detail lines, only under `BIR_VERBOSE=1` |
-| `replay.thread_fallback` | A wrapped step's output was threaded from the hook's view because the proxy did not report in time |
-| `replay.step` | One direct step executed |
-| `replay.diverge` / `replay.compose` | Off-script, and the recovery |
-| `replay.done` | Final outcome, steps completed, elapsed |
-| `execution.reported` | The ticket was redeemed and the saving booked |
-
-A recorder started in the background — by the SessionStart hook, `bir up` or `bir setup` — keeps
-them in `~/.baseinstrunner/logs/<key>.log`; `bir status` names the file. One started in a terminal
-writes them to that terminal; keep them yourself: `bir-hooks 2>&1 | tee -a ~/.baseinstrunner/audit.log`.
-
----
-
-## 7. What each outcome means for your numbers
-
-Reported once per matched turn, to `POST /scenarios/:id/executions`, redeeming the match's
-`executionTicket`.
-
-| Outcome | When | Where it lands |
-|---|---|---|
-| `steered_full` | Every planned step ran under the scenario's control | savings ledger |
-| `diverged` | Off-script; the composed bundle answered | savings ledger |
-| `not_steered` | Matched, declined at a gate — the agent ran the task normally | **baseline sample** |
-| `failed` | Armed, then gave up — the agent ran the task normally | **baseline sample** |
-
-`not_steered` is not an error, and it is not wasted. A saving is `baseline − actual`, and the baseline
-is *what this task costs when the agent does it*. Every declined match is a fresh measurement of
-exactly that. A deployment that never declines has no baseline to measure against — which is a good
-reason to leave `BIR_MIN_STEER_SIMILARITY` where it is rather than driving it to zero.
-
-An **unredeemed** ticket books nothing at all. Silence loses a saving; it never invents one.
-
----
-
-## 8. Tuning
-
-Only one knob matters in practice.
-
-**`BIR_MIN_STEER_SIMILARITY` (default 0.92).** The server detects matches at 0.9 and uses that to
-decide *"don't record this again"* — cheap: the worst case is a lost recording. Steering makes a much
-stronger claim, *"don't think about this again"*, and a 0.90-similar prompt usually covers only part
-of the live task. Steering it produces a confident, thin, wrong answer.
-
-Tune it from evidence, not taste. Run for a week and read the declines:
-
-```bash
-grep 'replay.decision' audit.log | grep 'why="similarity below threshold"'
-```
-
-- Prompts you *would* have wanted replayed, sitting at 0.90–0.92 → lower it, in steps of 0.01.
-- Replays that answered the wrong question → raise it, and re-read the scenario's `intent`.
-
-If a specific pair of prompts *should* match and does not, the fix is usually upstream of the
-threshold: the two prompts genuinely mean different things to the embedding model. Re-record with a
-first prompt that states the task plainly.
-
----
-
-## 9. Troubleshooting
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| No `run.matched`, ever | Prompt below the server's `SIMILARITY_THRESHOLD` | Rephrase closer, or lower it server-side. Confirm the original run is in the list — a sub-`RECORDING_MIN_ACTIONS` run is never embedded |
-| `run.matched` but no `plan.armed` | A gate declined | Read the `replay.decision` line's `why=`. Ranked by frequency: `bir replay off` or `BIR_REPLAY=0` · scenario not `ready` · similarity below threshold · no step is executable |
-| `why="no step is executable"` | None of the scenario's tools is a wrapped MCP server and none is a built-in reachable in this session | Wrap the servers the scenario uses (`bir install --server …`) and recalculate |
-| `plan.armed mode=steer` where you expected `direct` | At least one step is a built-in, an unwrapped MCP server, or `claude-in-chrome` | `bir status` shows what is wrapped. `claude-in-chrome` is `scope: "dynamic"` and can never be wrapped |
-| Model ignores the directive and diverges every turn | Steering is advisory — the model chooses; `bir` only pins arguments | Expected occasionally. Persistent divergence usually means the scenario's tools do not fit the live task; check `intent` |
-| A `replay.thread` line with no `emitted=` (under `BIR_VERBOSE=1`) | `toolOutputLogic` derived nothing — usually the output shape changed since recording | Dry-replay (§3.1). If the dry run emits and the live run does not, the tool's output shape has drifted; recalculate |
-| `replay.thread_fallback` on a wrapped step | The proxy did not report within the grace window | Check that proxy is alive (`bir doctor`). Repeats mean a slow or dying upstream |
-| `run_scenario` returns "no scenario is armed" | The model called it on a turn with no plan | Harmless. It happens when the model remembers the tool from an earlier turn |
-| `recorder.send_failed … error="HTTP 409 … invalid_ticket"` | The execution report's ticket was already redeemed, or belongs to another scenario | Harmless if the body says `duplicate: true`. Otherwise a rollover raced `SessionEnd`; the server books once |
-| `savedUsd` looks impossible | Pricing drift between the runner's table and the server's | Compare `PRICING_VERSION` on both sides. Design §11.3 documents a known live drift between two existing copies |
-| The hand-over note says a step "did not run: its input needs a judgement" | The service marked the step non-deterministic when it calculated the plan: the generated logic could not compute its input from the prompt or from earlier outputs, so the recorded value was a copy (the service's plan-services design, D8 kind 3 — it lives in the BaseIn repository, not this one). `nondeterministicWhy: by_hand` means someone marked it with `bir scenario edit --freeze` | If the code only has a slip, fix the step yourself: `bir scenario show scn_… --step <n>`, write the input logic to a file, then `bir scenario edit scn_… --step <n> --input-logic <file>` — the service checks it against the recording before it saves it (§9.2, not yet released). Of the edits, only `--unfreeze` lifts a mark made by hand (`by_hand`); a code edit, even a forced one, leaves it in place. A real judgement — a choice with no fixed rule — cannot be written as code: the agent makes that choice and finishes the task; a model step for it is planned (W3.1). The journal's `plan.armed` line lists the step under `stops=` |
-| A parked step ran again after an hour, or a plan was recalculated by itself | The service's grace period (D8): a parked step is served with `stop: null` once an hour for a day and a success clears its count; if it keeps failing, or its tool is gone, the next repeat of the prompt is recorded in full and the plan is calculated again from it | Nothing: that is the repair. `bir investigate` says which it is — a step still being retried, a parked step whose repair is due, or a plan being calculated again. To repair now by hand: `bir scenario calc <runId> --force` for a whole-run plan; from the next version, `bir scenario calc <scnId> --force` works for any plan, a sub-task one included. A plan with steps edited by hand is not repaired by itself: the parked step stays parked, and `bir investigate` says the repair was skipped. Then fix the step (§9.2); or take the edits back with `bir scenario undo`, once per edit, and it is repaired as usual; or recalculate now and drop the edits: `bir scenario calc <scnId> --force --discard-edits` |
-| `sessionCostUsd` grows every prompt in a session | The per-run usage watermark is missing or not taken | Design §11.4. Reports without a mark must carry `measured: false` |
-| Everything works, nothing is saved | A replayed turn is deliberately not recorded (design §12) | Correct. The matched run stays canonical and its `iterations` is bumped |
-| `bir doctor`: the SessionStart hook points at a Node that is gone | The hook names Node by absolute path. That Node was uninstalled, moved, or was a version manager's per-shell copy; the hook then fails on every session, no recorder is started, and runs record Tier 2 | `bir setup` here again — it rewrites the hook to the Node that runs it |
-| `control.port_busy` in the log; the recorder is not running | Another program holds this project's port, or the system excludes it (on Windows, a range Hyper-V or WSL reserved). A background recorder with a recorded port does not fall back to another, because every hook but SessionStart names this one; only a `bir-hooks` you run by hand in a terminal still does | `bir setup --port <another>` in this directory — the fix the log line itself names. It rewrites the hook URLs and the scenario server's address together and restarts the recorder |
-| The recorder was started by the hook, and `bir doctor` says `servers=(all wrapped)` although you set `BIR_REPLAY_ALLOW_SERVERS` | The hook starts the recorder with Claude Code's environment, not your terminal's; a variable set in one terminal is not seen | `bir replay allow <a,b>` — stored for the project, read by every recorder — then `bir up --restart` |
-
----
-
-### 9.1 `bir investigate` — the table above, applied for you
-
-Every audit line that explains a turn is also kept in a **journal**, one JSON
-object per line, under `~/.baseinstrunner/control/journal/` (one file per
-directory, rotated at 4 MB). The recorder names it at start — the `journal=`
-field of its `control.listening` line, in the audit log for a background
-recorder. Ask the journal and the service together:
-
-```
-bir investigate                       # the newest turn in this directory
-bir investigate <run_|scn_|sexec_ id> # that run, scenario or execution
-bir investigate list [--limit n]      # recent turns and their verdicts
-bir investigate executions [--limit n] [--user <email|id>]   # the ledger
-```
-
-The output is the turn as the journal tells it (matched what, which gate
-declined and why, what mode armed with which coverage, what the execution
-reported), then **runner findings**, then the service's view (the recording,
-the scenario, the baseline and its sample count, the executions with their
-saved $ and %) and **service findings**. Every finding is *problem → cause →
-fix*. The three questions it answers:
-
-| Question | Where the answer comes from |
-|---|---|
-| Why did this turn not run its calculated scenario? | `replay.decision code=…` in the journal, mapped to the cause and the fix; and the service: is the run a recording, is it embedded, how many hits, is the scenario ready / failed / switched off, which step is parked |
-| Why did it save so little, or cost more? | the execution's cost breakdown (derive, session, fallback) against the baseline; steer mode with built-in steps is the usual answer, a single-sample baseline the second |
-| What happened, step by step? | the turn's lines in order, the per-step verdicts on the execution, and `replay.*_failed`, `replay.diverge`, `replay.handover` as incidents |
-
-You see your own data. An admin of the service sees everyone's and may pass
-`--user` to `executions`. `--json` on any form prints the raw merge.
-
-### 9.2 Fix a step — `bir scenario check`, `edit`, `edits`, `undo`
-
-> Built 2026-09-25, **not yet released**. It needs the next `@basein/runner` version *and* a
-> service deploy: the `/scenarios/:id/steps/…` routes and the sandbox the service runs step code
-> in. Version 0.2.11 on npm has an early form of these commands. It is not what this section
-> describes. The design is `editSteps.md` in the BaseIn repository.
->
-> The hiring-year outputs below were printed by the real `bir`, against the real service, on the
-> real recording. Only the ids are shortened, with `…`.
-
-`bir investigate` says *what* is wrong. This section is how you fix it. A calculated step is code:
-its **input logic** says what to send to the tool, and its **output logic** says what to keep from
-the answer. When that code is wrong, you do not have to recalculate and hope any more. You change
-the step, and the service checks your change against the recording before it saves it.
-
-**A change is saved only if it reproduces the recording and is not a copy — or on purpose, with
-`--force --note "why"`.**
-
-```
-bir scenario show  <runId|scnId> [--step <n>]
-bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze]
-bir scenario edit  <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
-                   [--freeze | --unfreeze] [--note "<why>"] [--force --note "<why>"] [--revision <n>]
-bir scenario edits <runId|scnId>
-bir scenario undo  <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "<why>"]
-bir scenario calc  <runId|scnId> [--force [--discard-edits]]
-bir scenario editing on|off|status
-```
-
-A `run_` id finds the run's whole-run scenario. A `scn_` id (what `bir investigate` prints) is used
-as it is. A sub-task scenario has only a `scn_` id. When a run has only sub-task scenarios, `bir`
-lists their `scn_` ids instead of guessing. `--step` is the `stepIndex` that `show` prints; it
-starts at 0. `--revision <n>` saves only if the plan is still at revision `n`: the `chainRevision`
-at the top of `show --step`. `--json` on `check`, `edit`, `edits` or `undo` prints the service's
-answer unchanged. Exit codes: `0` checked OK, saved or undone · `1` refused, not found, or a
-service error · `2` a wrong command line.
-
-#### What the code is
-
-Each logic is the *body* of a JavaScript function. It must end in `return { … }`.
-
-| Logic | Reads | Returns |
-|---|---|---|
-| input logic (`toolInputLogic`) | `parameters` — this request's values · `respParams` — what earlier steps kept · `intent` | the tool's input, as an object |
-| output logic (`toolOutputLogic`) | `toolOutput` — the tool's answer, as text · and the same three | the values to keep for later steps, as an object |
-
-The service runs your code in a sandbox (design §13.1). In the sandbox only JavaScript itself
-exists: `JSON`, `Math`, `Date`, `RegExp` and the like. There is no `require`, `process`, `fetch`,
-`Buffer` or timer. A few built-ins are taken away too: `ArrayBuffer`, the typed arrays such as
-`Uint8Array`, `Atomics`, `WebAssembly`, `FinalizationRegistry` and `Symbol.for`. Code that uses
-one of them with the recording's values throws in the check.
-
-**But the check only judges what your code returns for the recording's values.** A `fetch` behind
-a `typeof` guard (`if (typeof fetch === "function") …`), or on a branch the recording's values
-never take, is never reached in the check. A `fetch` inside a `try` fails in the check, but the
-`catch` hides the error. Either way the code passes. On your machine the runner runs the same
-code with `new Function`, where `fetch` and `process` do exist. So read every change before it is
-saved — yours and Claude's.
-
-**Only a step's code and its mark can be changed.** Not the parameters, not their sample values, not
-the logic that builds the final answer. Only tool steps: a sub-task call row belongs to the service.
-
-#### The fix, step by step
-
-On 2026-09-25 two SQL steps of the hiring-year scenario, 3 and 4, were marked *needs a judgement*.
-Step 4 is shown here; step 3 was fixed the same way. The calculation's code for step 4 wrote
-`schema + '.' + summary_table`, but the table name already carried its schema, so the code did not
-give the recorded call. The calculation then put a copy of the recorded call in its place, and
-marked the step.
-
-**1. Read the step.**
-
-```bash
-bir scenario show scn_4a17a126-… --step 4
-```
-
-You should see this (shortened: each `…` line stands for lines left out):
-
-```
-{
-  "scenarioId": "scn_4a17a126-…",
-  "chainRevision": 1,
-  "stepIndex": 4,
-  "kind": "tool",
-  "toolName": "mcp__postgres__execute_sql",
-  "toolInputLogic": "return {\"sql\":\"SELECT * FROM employees.hiring_year_summary ORDER BY hire_year;\"};",
-  …
-  "nondeterministic": true,
-  "nondeterministicWhy": "input_mismatch",
-  "editedAt": null,
-  "editForced": false,
-  "stop": {
-    "kind": "nondeterministic",
-    "why": "input_mismatch"
-  },
-  "sampleInput": "{\"sql\":\"SELECT * FROM employees.hiring_year_summary ORDER BY hire_year;\"}",
-  …
-}
-```
-
-`scenarioId` and `chainRevision` come first. They belong to the whole scenario, and
-`chainRevision` is the number `edit --revision` takes. The rest is the step. Its input logic is
-that copy: compare it with `sampleInput`. A copy does the old job, on the old table, whatever the
-new request says. That is why the step is marked (`nondeterministic: true`), and why runs hand over
-to the agent in front of it.
-
-**2. Write the new code to a file.**
-
-```bash
-cat step4.js
-```
-
-```
-return { sql: "SELECT * FROM " + parameters.summary_table + " ORDER BY hire_year;" };
-```
-
-Code always goes in from a file, or from stdin with `-`. Never on the command line: the shell's
-quoting breaks JavaScript.
-
-**3. Check it.** Nothing is saved.
-
-```bash
-bir scenario check scn_4a17a126-… --step 4 --input-logic step4.js
-```
-
-```
-Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
-  input    reproduces the recorded call
-  later    not affected: only the input logic changed
-  mark     needs a judgement (input_mismatch) → runs by itself
-Nothing saved. To save: bir scenario edit scn_4a17a126-… --step 4 --input-logic step4.js
-```
-
-- `input` — does the code give the recorded call?
-- `later` — do the steps after it still give theirs? Here only the input logic changed. Nothing a
-  later step reads has changed, so no later step was judged.
-- `mark` — what happens to the *needs a judgement* mark. `→ runs by itself` means the mark goes
-  when you save, and runs stop handing over in front of this step.
-
-**4. Save it.** `edit` runs the same check, and saves only what the check approved. Add a `--note`
-that says why; the history keeps it.
-
-```bash
-bir scenario edit scn_4a17a126-… --step 4 --input-logic step4.js --note "summary_table already carries its schema"
-```
-
-```
-Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
-  input    reproduces the recorded call
-  mark     needs a judgement (input_mismatch) → runs by itself
-Saved as sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda (revision 2). Undo: bir scenario undo scn_4a17a126-… --edit sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda
-```
-
-`edit` prints fewer lines than `check`. It always prints `input`, and the other lines only when
-something moved or broke. Step 3 was then saved the same way, as revision 3.
-
-**5. Try it without real tools.** A dry replay (§3.1) runs the new code over the recorded outputs:
-`bir scenario replay scn_4a17a126-… --prompt "…" --dry`. The next real prompt uses the new code.
-There is nothing to restart.
-
-#### How the check decides
-
-The service runs your code the way the recorded run would have run it: with the recording's
-parameter values, and with what the earlier steps kept from their recorded answers.
-
-| It asks | It refuses when |
-|---|---|
-| Does the code give the recorded call? Extra spaces inside strings, and the order of keys, do not count | it gives something else (`differs`), or it crashes (`throws`) |
-| Is it a copy? It changes one parameter, or one earlier output, at a time — only the ones the code reads | the call never moves: the code returns the recorded call whatever the request says |
-| Do the later steps still give their calls? Asked only when the **output** logic changed, and only of later steps that are not marked and can be checked | a later step that gave its recorded call before does not any more |
-| Does the final answer still get its values? Asked only when the **output** logic changed | it did before, and does not after |
-| Can the mark go? | you asked to unmark the step (`--unfreeze`), and its input does not reproduce |
-
-A recorded input of `{}` is never a copy. A recorded input that is plain text, not an object, is
-`not_checked`.
-
-**The check is kept small.** On the service it runs in a worker thread of its own, never in the
-thread that answers requests. By default it may use 5 seconds of sandbox time
-(`EDIT_CHECK_BUDGET_MS`, 5000 ms). Past that it stops, and the change is refused as *too costly to
-check*. The reason `bir` prints is the service's own sentence:
-
-```
-too costly to check: the check used up its 5000 ms of sandbox time (EDIT_CHECK_BUDGET_MS) before it finished.
-```
-
-One run of your code may take 1 second (`LOGIC_TIMEOUT_MS`) and 64 MB of memory
-(`LOGIC_MEMORY_MB`), by default. Code that ran out of time or memory, or stopped the sandbox twice,
-is held back for 10 minutes: every run of that same code fails at once, with the same message.
-
-A refused change says where it differs. Here `wrong.js` adds the schema a second time:
-
-```bash
-bir scenario check scn_4a17a126-… --step 4 --input-logic wrong.js
-```
-
-```
-Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
-  input    differs from the recorded call at character 32
-           computed  … FROM employees.employees.hiring_year_summary ORDER BY h…
-           recorded  … FROM employees.hiring_year_summary ORDER BY hire_year;"…
-  later    not affected: only the input logic changed
-  mark     needs a judgement (input_mismatch) → stays marked
-Nothing saved, and `bir scenario edit` would refuse it: the change does not reproduce the recording.
-  Fix the code and check again. If the recording itself was wrong, edit can save it on purpose: add --force --note "why".
-```
-
-`bir scenario edit` with the same file refuses it, and saves nothing:
-
-```
-Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
-  input    differs from the recorded call at character 32
-           computed  … FROM employees.employees.hiring_year_summary ORDER BY h…
-           recorded  … FROM employees.hiring_year_summary ORDER BY hire_year;"…
-Not saved: the change does not reproduce the recording.
-  Fix the code and try again, or save it on purpose: add --force --note "why".
-```
-
-A pasted value is refused as a copy. Here `pasted.js` returns the recorded SQL as fixed text:
-
-```bash
-bir scenario check scn_4a17a126-… --step 4 --input-logic pasted.js
-```
-
-```
-Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
-  input    is a copy: it returns the recorded call whatever the parameters say
-  later    not affected: only the input logic changed
-  mark     needs a judgement (input_mismatch) → stays marked
-Nothing saved, and `bir scenario edit` would refuse it: the input logic is a copy: it returns the recorded call whatever the parameters and earlier outputs say.
-  Fix the code and check again. If the recording itself was wrong, edit can save it on purpose: add --force --note "why".
-```
-
-Any other refusal prints the service's own reason, one line for each problem.
-
-Code and a mark the step already has change nothing. `check` then says
-`Nothing would change: the step already has this code and mark.` (exit 0), and `edit` refuses:
-
-```bash
-bir scenario edit scn_4a17a126-… --step 4 --input-logic step4.js
-```
-
-```
-Nothing to change: the step already has this code and this mark.
-```
-
-#### `--force --note`: save it on purpose
-
-**Use `--force` only when the recording itself was wrong** — for example, the recorded run sent a
-call with a mistake you do not want repeated. Then no correct code can reproduce it.
-
-- `--force` needs a `--note` that says why (500 characters at most). Without one, `bir` stops
-  before it sends anything (`note_required`).
-- **When the check found any problem, a forced save is recorded as forced.** `bir` says so under
-  the `Saved as …` line and repeats what the check said. `bir investigate` keeps reporting the step
-  as a `warn`.
-- A forced save removes a mark **the calculation** set, unless you also pass `--freeze`. A mark
-  made **by hand** (`--freeze`) stays. A save lifts it only with `--unfreeze`.
-- A step after a sub-task call row can only be saved with `--force`: the check cannot rebuild the
-  outputs that step reads.
-
-#### Mark or unmark a step by hand
-
-- `--freeze` marks the step *needs a judgement* (`nondeterministicWhy: by_hand`). Runs then hand
-  over to the agent in front of it. No check blocks this: a mark only makes replay more careful.
-- `--unfreeze` asks to remove a mark. The check decides: the step's input must reproduce. With
-  `--force --note "why"` the mark goes anyway, and the edit is recorded as forced.
-  `bir scenario check … --unfreeze` asks the same question without saving.
-- **A mark made by hand is lifted only when someone asks.** A code edit does not lift it, even one
-  that reproduces the recording, and neither does a forced save. What lifts it: `--unfreeze`,
-  undoing the edit that made it, or `bir scenario calc … --force --discard-edits`.
-
-#### The history, and undo
-
-After both steps were saved:
-
-```bash
-bir scenario edits scn_4a17a126-…
-```
-
-```
-sedit_02cb1210-1938-4902-9395-5a82b321276d  2026-09-25 11:10:59Z  step 3  edit    revision 2 → 3  "use the settings, not the recorded names"
-    input logic changed; needs a judgement (input_mismatch) → runs by itself
-sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda  2026-09-25 11:10:59Z  step 4  edit    revision 1 → 2  "summary_table already carries its schema"
-    input logic changed; needs a judgement (input_mismatch) → runs by itself
-```
-
-The newest entry is first. Each id is printed in full, because it is what `undo --edit` takes.
-
-Take back the newest edit:
-
-```bash
-bir scenario undo scn_4a17a126-…
-```
-
-```
-Step 3 (mcp__postgres__execute_sql) — checked against run_67afb010-…
-  input    back as it was before that edit
-  mark     runs by itself → needs a judgement (input_mismatch)
-Step 3 is back as it was before sedit_02cb1210-1938-4902-9395-5a82b321276d (revision 4). Redo: bir scenario undo scn_4a17a126-… --edit sedit_1bcba735-a526-4a1c-a890-261addf2d82b
-  One further back: bir scenario undo scn_4a17a126-…
-```
-
-The same command again goes one further back:
-
-```bash
-bir scenario undo scn_4a17a126-…
-```
-
-```
-Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
-  input    back as it was before that edit
-  mark     runs by itself → needs a judgement (input_mismatch)
-Step 4 is back as it was before sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda (revision 5). Redo: bir scenario undo scn_4a17a126-… --edit sedit_8d3da392-1d96-4b2e-8c5d-34f8ab668b53
-  One further back: bir scenario undo scn_4a17a126-…
-```
-
-Now the history shows the two undos, and both edits as undone:
-
-```bash
-bir scenario edits scn_4a17a126-…
-```
-
-```
-sedit_8d3da392-1d96-4b2e-8c5d-34f8ab668b53  2026-09-25 11:11:00Z  step 4  revert  revision 4 → 5
-    undoes sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda; input logic changed; runs by itself → needs a judgement (input_mismatch)
-sedit_1bcba735-a526-4a1c-a890-261addf2d82b  2026-09-25 11:11:00Z  step 3  revert  revision 3 → 4
-    undoes sedit_02cb1210-1938-4902-9395-5a82b321276d; input logic changed; runs by itself → needs a judgement (input_mismatch)
-sedit_02cb1210-1938-4902-9395-5a82b321276d  2026-09-25 11:10:59Z  step 3  edit    revision 2 → 3  "use the settings, not the recorded names"
-    input logic changed; needs a judgement (input_mismatch) → runs by itself; undone 2026-09-25 11:11:00Z
-sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda  2026-09-25 11:10:59Z  step 4  edit    revision 1 → 2  "summary_table already carries its schema"
-    input logic changed; needs a judgement (input_mismatch) → runs by itself; undone 2026-09-25 11:11:00Z
-```
-
-Step 4 is the calculation's code again: `bir scenario show scn_4a17a126-… --step 4` now prints
-`"chainRevision": 5`, `"editedAt": null` and the mark `"nondeterministicWhy": "input_mismatch"`.
-
-How undo works:
-
-- **Undo walks back.** `bir scenario undo <id>` takes back the newest edit that can be undone. Its
-  step goes back as it was before that edit: its code and its mark. Run it again to go one further
-  back. Keep going, and each step gets back to the calculation's code, unless an undo is refused
-  (below).
-- **`--step <n>` limits it to one step.** `bir scenario undo scn_… --step 4` takes back step 4's
-  newest edit, and nothing else.
-- `--edit <sedit_id>` takes back that one entry.
-- An undo is a new line in the history (`revert`). **To redo, undo the undo** by its id. The undo
-  prints that command after `Redo:`.
-- **An undo is checked too:** for the later steps and for the final answer, like a save (so only
-  when the undo changes the step's output logic). The step itself is not judged: it goes back
-  exactly as it was. If the undo would break a later step or the answer, it is refused
-  (`undo_refused`). `bir` prints `Not undone:` with the reason, then
-  `To undo it anyway, on purpose: add --force --note "why".` An undo forced past a refusal is
-  recorded as forced.
-- Once every hand edit of a plan is taken back, the service repairs and rebuilds it as usual again.
-  An undo forced past a refusal is the exception: it leaves its step counted as edited and
-  forced, so `bir investigate` keeps warning about it.
-
-#### What a save changes
-
-- **The next prompt uses the new code.** The service hands out the plan fresh on every prompt. A
-  turn that is already running keeps the old plan until it ends.
-- **The revision goes up by one, and the step's failure count is cleared.** Reports from turns that
-  started before the change do not count against the new code. An undo does the same.
-- **A saved step runs unattended, exactly like calculated code** (§5.1), on this machine, with
-  `new Function`. The service's sandbox does not protect this machine. Read your change as carefully
-  as you read a calculated plan, and dry-replay it (§3.1).
-- **Edits are protected.** A recalculation rebuilds every step from the recording, and would throw
-  your fix away. So `calc --force` refuses:
-
-```bash
-bir scenario calc run_67afb010-… --force
-```
-
-```
-Not recalculated: steps 3, 4 were edited by hand, and a recalculation rebuilds every step.
-  To recalculate anyway and discard the edits: bir scenario calc run_67afb010-… --force --discard-edits
-  (the edits stay in `bir scenario edits`, marked replaced)
-```
-
-A `run_` id reaches only the run's whole-run scenario. `bir scenario calc <scnId> --force`
-recalculates any scenario in place, by its own id, a sub-task scenario included. Add
-`--discard-edits` when it has hand edits. A `scn_` id without `--force` is refused before anything
-is sent: a scenario that exists can only be recalculated.
-
-The console's *Recalculate* button (on a sub-task's scenario) is refused too while a plan has hand
-edits; the console does not discard them. The service's own rebuilds — the repair of a parked step
-(§9) and the adoption of a sub-task — skip a plan with hand edits. `bir investigate` says that the
-service does not rebuild the plan on its own, and warns when it skipped a repair
-(`repair_skipped_edits`). After `--discard-edits` the old edits stay readable, but they cannot be
-undone (`edit_replaced`).
-
-#### What `bir investigate` says
-
-It reports every edited step, and names the command that takes it back. After both steps were
-saved, its service findings began like this:
-
-```
-Service findings
-  1. [info] Step 3 (mcp__postgres__execute_sql) was edited by hand on 2026-09-25; the chain is at revision 3.
-     why:  Its code or its mark was changed by hand rather than by the calculation, and the change was checked against the recording before it was saved. The service does not rebuild a plan with hand edits on its own.
-     fix:  To see it: `bir scenario edits scn_4a17a126-…`; to take it back: `bir scenario undo scn_4a17a126-… --step 3`. A recalculation will not replace it unless you pass --discard-edits.
-  2. [info] Step 4 (mcp__postgres__execute_sql) was edited by hand on 2026-09-25; the chain is at revision 3.
-     why:  Its code or its mark was changed by hand rather than by the calculation, and the change was checked against the recording before it was saved. The service does not rebuild a plan with hand edits on its own.
-     fix:  To see it: `bir scenario edits scn_4a17a126-…`; to take it back: `bir scenario undo scn_4a17a126-… --step 4`. A recalculation will not replace it unless you pass --discard-edits.
-```
-
-A forced edit is a `warn`, not an `info`. So is a repair the service skipped because of hand edits.
-
-#### Let Claude do it
-
-Claude Code can do all of this for you, in two ways. Both use the same service routes and the same
-check.
-
-1. **In its terminal.** Claude runs `bir scenario …` like any other command. You see each command,
-   and Claude Code asks you before it runs one, unless you allowed it. This works in every project.
-2. **As tools on the `bir` MCP server** — the server `bir setup` or `bir install --replay` adds
-   (§5.2). This is smoother for the model. **Reading is always offered. Changing is off until you
-   turn it on, per project:**
-
-```bash
-bir scenario editing on       # this project's `bir` server also offers the tools that change a scenario
-bir scenario editing off      # back to the tools that only read
-bir scenario editing status   # what is stored for this project
-```
-
-The tools, as the `bir` server defines them. **Bold** arguments are required.
-
-| Tool (`mcp__bir__…`) | Offered | Arguments | Runs |
-|---|---|---|---|
-| `run_scenario` | always | none | the plan armed for this turn (§6.1) |
-| `scenario_show` | always | **`target`**, `step` | `bir scenario show` |
-| `scenario_edits` | always | **`target`** | `bir scenario edits` |
-| `investigate` | always | `id` — a `run_`, `scn_` or `sexec_` id; without it, the newest turn here | `bir investigate` |
-| `scenario_check` | after `bir scenario editing on` | **`target`**, **`step`**, `inputLogic`, `outputLogic`, `unfreeze` | `bir scenario check` |
-| `scenario_edit` | after `bir scenario editing on` | **`target`**, **`step`**, `inputLogic`, `outputLogic`, `freeze`, `unfreeze`, `force`, `note`, `revision` | `bir scenario edit` |
-| `scenario_undo` | after `bir scenario editing on` | **`target`**, `edit` or `step` (not both), `force`, `note` | `bir scenario undo` |
-
-- `target` is a `scn_` id, or the `run_` id of a whole-run scenario. `step` is the `stepIndex`.
-- `inputLogic` and `outputLogic` are the code itself, as text. The server writes them to temporary
-  files for `bir`, and removes the files afterwards.
-- `revision` is the `chainRevision` at the top of `scenario_show` with `step`.
-- `force` needs `note`, as on the command line.
-- Each tool runs this package's own `bir` with `--json`. A refusal comes back as an error result
-  that carries the check's report, so the model can read why.
-- When the session ends, or you press Esc during a call, that call's `bir` is stopped and its
-  temporary files are removed. A request the service had already received may still finish there;
-  `bir scenario edits` shows it.
-
-Why changing is off by default: the `bir` server runs in every session of every project it is
-installed in, a fleet included. A plan must not change because some agent there decided to change
-it. The switch is kept in `~/.baseinstrunner/installed.json`, next to the replay switches. It only
-decides which tools the `bir` server offers; the `bir scenario` commands work everywhere. The server
-reads the switch when Claude Code lists its tools, and again on every call. **Restart the Claude
-Code session after you switch it** — a running session does not see the change.
-
-**`bir`'s own calls are never recorded.** A session that fixes a plan must not become a plan that
-edits plans when it is replayed. So these calls are never recorded as steps, and never count as the
-model leaving a plan: the `bir` server's tools other than `run_scenario`, and a `Bash` or
-`PowerShell` command made only of `bir` commands (a plain `cd` may come with them).
-`npm test && bir investigate` is still recorded: the `npm test` half is real work. So is writing
-the code file, which is an ordinary step. Under `BIR_VERBOSE=1` a skipped call shows as
-`tool.pre.skipped … why="host housekeeping"`.
-
-**Do this.** In the Claude Code session, in the project folder, paste:
-
-```
-Run `bir investigate` in this folder. If a step needs a judgement or its code
-is wrong, read it with `bir scenario show`, write the corrected code to a file,
-and test it with `bir scenario check`. Show me the check and explain it in plain
-words. Do not save anything until I say yes. Then save it with
-`bir scenario edit` and a --note that says why. Never use --force.
-```
-
-For the hiring-year case, Claude's report would be: *step 4's code is a copy of the recorded query,
-so it was marked; the new code builds the query from `summary_table`; the check says it reproduces
-the recording, and the step will run by itself.*
-
-#### When it does not work
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| `input differs from the recorded call at character N` | The code gives a different call from the recorded one | Read the `computed` and `recorded` lines, fix the code, check again |
-| `input is a copy` | The code returns the recorded call whatever the request says — usually a pasted value | Build the call from `parameters.…` or `respParams.…` |
-| `input throws` | The code crashed; the message is shown | Fix it. `require`, `process`, `fetch`, `Buffer`, timers, `ArrayBuffer`, the typed arrays and `Symbol.for` do not exist in the check |
-| `… did not finish in N ms`, `… ran out of memory (the limit is N MB)`, or `… stopped the logic sandbox before it finished` | The code went past the sandbox's time or memory limit (`LOGIC_TIMEOUT_MS`, `LOGIC_MEMORY_MB` on the service), or stopped the sandbox twice. That same code is then refused at once for 10 minutes | Fix the loop or the size. Changed code is new code, and is checked again |
-| A `later` step no longer reproduces | The change broke a step after it — usually output logic that stopped keeping a value a later step reads | Keep every key the later steps read |
-| `too costly to check` | The check used up its 5 seconds of sandbox time (`EDIT_CHECK_BUDGET_MS`). Usually code that reads or keeps a great many values, so the check has to run it very many times | Make the code cheaper to run, then check again |
-| `Nothing to change: the step already has this code and this mark.` | The code and the mark you gave are what the step already has (`nothing_to_change`) | Nothing to do. `check` says `Nothing would change` for the same case |
-| `not_a_tool_step` | The index is a sub-task call row, not a tool step | Call rows cannot be edited; the service writes them |
-| `note_required` | `--force` without `--note` | Add `--note "why"` |
-| `revision_changed` | The plan changed since you read it: another edit, or a recalculation | `show` it again, check again, save again |
-| `not_ready` or `scenario_calculating` | The scenario is not `ready`, or a recalculation is running | Wait for it to finish |
-| `undo_refused` | The undo would stop a later step from giving its recorded call, or leave the final answer without its values | Fix that later step first. Or undo it on purpose: `--force --note "why"` |
-| `not_latest_edit` | The step has changed since the edit you named: a newer entry changed it | `bir` prints two commands: undo the newer one first, then yours |
-| `already_undone` | That edit was undone already | To redo it, undo the undo. `bir` prints the command |
-| `edit_replaced` | A recalculation replaced the plan after that edit | Nothing to undo; the edit is history now |
-| `logic_sandbox_unavailable` | The service could not run step code just now (HTTP 503). Nothing was checked, saved or undone | Try again in a minute |
-| `invalid_input` | The service found the request invalid; `bir` prints its details. For example, a logic body longer than 20 000 characters, or a note longer than 500 | Shorten it |
-| `payload_too_large` | The whole request is larger than the service accepts (HTTP 413, over 256 kB) | A logic body may be at most 20 000 characters, and a note 500 |
-| `rate_limited` | More checks, edits and undos in a minute than the service allows (`SCENARIO_EDITS_PER_MINUTE`, 30 by default) | Wait a minute |
-| `not found` for a scenario you can see | It is not yours. **Only the owner can change a scenario** — an admin gets `not found` too | Ask the owner |
-| The `scenario_check`, `scenario_edit` and `scenario_undo` tools are missing | `bir scenario editing on` was not run in this project, or the session started before it | Run it here, then restart the session |
-
----
-
-## 10. What is built
-
-All of it. Phases R0–R7 of [calculatedReplay.md](calculatedReplay.md) §17 are implemented and
-tested; everything this guide describes is code you can run. §9.2 is built and tested too, but not
-yet released.
-
-| Phase | What landed | Where |
-|---|---|---|
-| **R0** | Plan, logic shims, coverage, bundle | [src/replay/](../src/replay/) — `plan.ts`, `logic.ts`, `coverage.ts`, `bundle.ts` |
-| **R1** | Derivation over raw `fetch`; pricing | [derive.ts](../src/replay/derive.ts), [pricing.ts](../src/replay/pricing.ts) |
-| **R2** | Gate ladder, mode choice, arming, directive | [controller.ts](../src/replay/controller.ts), [control/server.ts](../src/control/server.ts) |
-| **R3** | Pin, thread, retire | `onToolPre` / `onToolPost` / `onProxyStep` in [control/server.ts](../src/control/server.ts) |
-| **R4** | Long-poll work queue; direct execution | [executor.ts](../src/replay/executor.ts), [proxy/session.ts](../src/proxy/session.ts) |
-| **R5** | The `bir` MCP server, `/scenario/run`, `--replay` | [bin/bir-scenario.ts](../src/bin/bir-scenario.ts), [bin/bir.ts](../src/bin/bir.ts) |
-| **R6** | Divergence, source-run fallback, `bir replay` | `diverge()` in [controller.ts](../src/replay/controller.ts), [source-run.ts](../src/replay/source-run.ts) |
-| **R7** | Usage watermark, reporting, ticket, doctor | [control/transcript.ts](../src/control/transcript.ts), [remote-recorder.ts](../src/record/remote-recorder.ts) |
-| **§9.2** *(not yet released)* | `bir scenario show/check/edit/edits/undo/calc/editing`, the `bir` server's scenario tools, `bir` calls never recorded (`editSteps.md` D13) | [bin/scenario-edit.ts](../src/bin/scenario-edit.ts), [bin/bir-scenario.ts](../src/bin/bir-scenario.ts), [record/housekeeping.ts](../src/record/housekeeping.ts); tests: [scenario-edit.test.ts](../test/scenario-edit.test.ts), [bir-scenario.test.ts](../test/bir-scenario.test.ts), [housekeeping.test.ts](../test/housekeeping.test.ts), [replay-server.test.ts](../test/replay-server.test.ts) |
-
-```bash
-npm test                                                # ~450 tests, incl. test/replay.test.ts and test/replay-server.test.ts
-npm run build && npm run pretest && npm run test:smoke  # the smoke test needs the test build too
-```
-
-The smoke test is the one worth running after any change to the seams. It starts a stand-in BaseIn
-service, a real `bir-hooks`, a real `bir-proxy` wrapping a real MCP server, and a real `bir-scenario`,
-then drives a two-step scenario end to end through actual stdio — proving that a pinned argument
-reaches the real tool, that step 1's input was computed from step 0's real output, and that the turn
-books `steered_full` with `fallbackCostUsd: 0`.
-
-Three things the implementation settled that the design left open:
-
-- **`SerializedScenarioStep.recordedOutput` really is never sent.** Recorded outputs come from a lazy
-  `GET /recordings/runs/:runId` ([source-run.ts](../src/replay/source-run.ts)), as design §8.1 anticipated.
-- **The work queue must hold work for a proxy that is mid-round-trip.** Failing fast when no poller is
-  *parked* lost every step after the first in a multi-step direct plan, because the proxy is between
-  polls exactly then. It now fails fast only for a server no proxy has served in the last minute.
-- **The proxies need no replay configuration.** `/proxy/register` tells each one whether to open its
-  work loop, so `BIR_REPLAY` is a single switch on the control server.
-
----
-
-## 11. Turning it off
-
-Three levels, least to most.
-
-```bash
-bir replay off          # stop arming. Matches still detected; recording still stops on a match.
-                        # Stored for this project; `bir up --restart` applies it, `bir replay on` undoes it
-export BIR_REPLAY=0     # the same, wherever the recorder is started from (the SessionStart hook
-                        # gives it Claude Code's environment, not your terminal's)
-bir uninstall --replay  # remove the `bir` MCP server only; proxies, hooks and the prompt-hook timeout stay
-bir uninstall           # remove everything: proxies, hooks, the pre-approval
-```
-
-`bir uninstall` restores a file byte-for-byte when nothing else edited it since the install, and
-repairs it entry by entry otherwise. A file the install created — usually
-`.claude/settings.local.json` — stays behind with our entries removed, and the line that hid it in
-`.git/info/exclude` goes with them.
-
-With replay off the system is exactly v1 again: it recognises a repeated prompt, declines to
-record it a second time, and lets the model do the work.
+# Calculated Replay — instructions
+
+> The operator's half of [calculatedReplay.md](calculatedReplay.md). That document says *why*; this
+> one says *what to type*, in order, from an empty machine to a prompt that answers itself.
+>
+> **Read this first.** Replay executes tool calls with arguments a scenario computed, and it does so
+> **without the permission prompts you would normally see** (design §13.2). `bir setup` (§1) turns it
+> on. Read §5 before you leave it on; `bir replay off` turns it off, and §2–§4 work either way.
+
+---
+
+## 0. The shape of it, in thirty seconds
+
+```
+1. Record          you work normally; bir records the run
+2. Calculate       BaseIn analyses that run into a reusable scenario
+3. Match           next time you ask the same thing in different words,
+                   the server recognises it and hands the scenario back
+4. Replay          bir runs the scenario's tools instead of the model
+                   rediscovering the plan
+```
+
+All four are implemented — see §10 for the map from design phase to code, and for how to run the
+end-to-end smoke test.
+
+---
+
+## 1. Prerequisites
+
+| # | You need | Check it with |
+|---|---|---|
+| 1 | A BaseIn service you can reach | `bir status` — its `BaseIn :` line is the address `bir setup` stored; `curl -fsS "<that address>/health"` proves it answers |
+| 2 | Anthropic configured **on the server** — calculation and derivation both need it | a `503 anthropic_not_configured` from `/calculate` means it is not |
+| 3 | `SIMILARITY_DETECTION_ENABLED=true` on the server (default) | otherwise no prompt ever matches |
+| 4 | BaseInstRunnerMCP built and installed in your project | `bir status` |
+| 5 | Tier 1 — the hooks wired and the recorder running | `bir doctor`; the SessionStart hook starts it |
+| 6 | *(replay only)* signed in, so the service can read what each request acts on | `bir doctor` — `derive=the service`; a key of your own here (`BIR_DERIVE_API_KEY`) replaces it, see §5.3 |
+
+Tier 1 is not optional for replay. A match is a match on **the prompt**, and a standalone proxy never
+sees one (design §1.1). If `bir doctor` says `Recording tier : standalone (Tier 2)`, replay cannot
+arm, and that is the honest ceiling rather than a bug.
+
+One line, pasted into a terminal opened in the project you start Claude Code in. The console's *Set
+up the runner* page shows it with a one-time setup token filled in. Pasted in the home folder or a
+drive root it stops before downloading anything — `cd` to the project and paste the same line again:
+
+```powershell
+$env:BIR_SETUP_TOKEN="<token>"; irm https://api.bi2202.com/install.ps1 | iex      # Windows (PowerShell)
+```
+
+```bash
+curl -fsSL https://api.bi2202.com/install.sh | BIR_SETUP_TOKEN="<token>" sh       # macOS / Linux
+```
+
+From cmd.exe: `powershell -NoProfile -Command "$env:BIR_SETUP_TOKEN='<token>'; irm https://api.bi2202.com/install.ps1 | iex"`.
+
+It installs Node and Claude Code if they are missing, installs the package, and runs `bir setup`:
+sign-in, the service address stored in `~/.baseinstrunner/config.json`, the project's MCP servers
+wrapped (a `.mcp.json` server only once Claude Code has approved it — on a fresh clone, run
+`bir setup` again after the first session), the hooks wired into `.claude/settings.local.json`, the
+scenario server added and replay switched on, the recorder started in the background. Nothing stays
+open: the SessionStart hook starts the recorder whenever it is missing, and its audit lines go to
+`~/.baseinstrunner/logs/<key>.log`. Re-running the line upgrades. With the package already
+installed, the same thing is:
+
+```bash
+bir setup --auth-url https://api.bi2202.com    # without a token it signs in through the browser
+```
+
+---
+
+## 2. Record a run worth reusing
+
+Nothing special — work normally. Two server-side facts decide whether the run becomes reusable, and
+both bite quietly:
+
+**A run needs at least `RECORDING_MIN_ACTIONS` tool actions (default 4).** Below that it is not
+embedded, does not enter the similarity pool, does not appear in the list, and is eventually pruned.
+A two-tool run will never match anything, no matter how many times you repeat it.
+
+**The prompt is what gets embedded.** `findSimilarRun` embeds `run.input` — the text of your
+`UserPromptSubmit` — not the transcript, not the answer. So the prompt that *starts* the turn is the
+one future prompts are compared against. Write the first prompt of a reusable task as if someone else
+will have to phrase it again.
+
+Watch it land:
+
+```
+[bir] …  run.start   run=run_… sess=birsess_… tier=bound
+[bir] …  run.finish  run=run_… steps=14 durationMs=48210 lossy=false recorded=true
+```
+
+`recorded=false` means the service declined the run — usually because it matched something you
+already have. That is §4 working.
+
+List what you have:
+
+```bash
+bir scenario list                    # or: GET /recordings/runs
+```
+
+```
+run_5f3a…  Fleet risk sweep
+    iterations=3  steps=14  scenario=scn_9c1b… (ready)
+run_a812…  Rewrite the billing README
+    iterations=1  steps=9  scenario=none — run `bir scenario calc <runId>`
+run_c004…  Check open PRs for stale reviews
+    iterations=1  steps=6  scenario=scn_44d0… (calculating)
+```
+
+Ids are printed in full on their own line (shortened here), so they can be copied straight into
+`calc` and `replay`.
+
+---
+
+## 3. Calculate the scenario
+
+A recorded run is a transcript. A **scenario** is what BaseIn derives from it: an intent, a parameter
+schema, and one JavaScript logic body per step that recomputes that step's tool arguments from new
+parameters. Until a run has one, a match can only stop recording — there is nothing to run.
+
+```bash
+bir scenario calc run_5f3a…            # POST /recordings/runs/:runId/calculate → 202
+bir scenario show run_5f3a…            # GET  /recordings/runs/:runId/scenario  (poll)
+```
+
+Raw, if you prefer — the service address lives in `~/.baseinstrunner/config.json` (`BIR_AUTH_URL`
+is normally unset after `bir setup`) and the token in `~/.baseinstrunner/credentials.json`:
+
+```bash
+BASEIN=$(node -p "require(require('os').homedir()+'/.baseinstrunner/config.json').authUrl")
+TOKEN=$(node -p "require(require('os').homedir()+'/.baseinstrunner/credentials.json').accessToken")
+curl -fsS -X POST "$BASEIN/recordings/runs/run_5f3a…/calculate" \
+     -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{}'
+```
+
+```powershell
+$b = (Get-Content "$HOME\.baseinstrunner\config.json" | ConvertFrom-Json).authUrl
+$t = (Get-Content "$HOME\.baseinstrunner\credentials.json" | ConvertFrom-Json).accessToken
+Invoke-RestMethod -Method Post -Uri "$b/recordings/runs/run_5f3a…/calculate" `
+  -Headers @{ authorization = "Bearer $t" } -ContentType 'application/json' -Body '{}'
+```
+
+Calculation is a background job. Poll `show` until `state` leaves `calculating`:
+
+| `state` | Meaning | Next |
+|---|---|---|
+| `calculating` | job running | poll again in a few seconds |
+| `ready` | usable | §4 |
+| `failed` | see the `error` field | fix and recalculate with `--force` |
+
+`409 scenario_exists` means this run already has one. Re-derive it in place — keeping the id and its
+replay history — with `bir scenario calc run_… --force`. A `run_` id reaches only the run's
+whole-run scenario. From the next version (not yet released), `bir scenario calc scn_… --force`
+does the same by the scenario's own id, a sub-task scenario included; it is the only way to
+recalculate a sub-task scenario from `bir`.
+
+To change one step instead, without recalculating, see §9.2. A plan with steps edited by hand is
+not rebuilt unless you add `--discard-edits`, which replaces those edits. They stay in
+`bir scenario edits`, marked replaced, and can no longer be undone.
+
+### 3.1 Check the scenario before you trust it
+
+**Dry replay is the cheapest thing you will do all day. Do it every time.** It derives parameters
+from a fresh prompt and runs the stored logic against the *original run's recorded outputs* — no real
+tools, no side effects, one Haiku call:
+
+```bash
+bir scenario replay scn_9c1b… --prompt "which devices in the fleet look risky right now?" --dry
+```
+
+```
+params      { "fleetId": "eu-west-1", "riskThreshold": 0.8 }
+step 0      mcp__chrome-devtools__navigate_page  { "url": "https://fleet.internal/eu-west-1" }
+step 1      mcp__chrome-devtools__take_snapshot  {}
+              → emitted: devices
+step 2      mcp__fleet-api__device_detail        { "id": "dev_88f1" }
+              → emitted: highestRiskDeviceId, riskScore
+response    { "fleet": "eu-west-1", "atRisk": 3, "worst": "dev_88f1" }
+cost        $0.0012
+```
+
+Read it for three things:
+
+1. **Did the parameters come out right** for a prompt phrased differently from the original?
+2. **Do the step inputs look computed**, or are they the original run's constants copied through? A
+   scenario whose inputs never vary with the parameters is a recording, not a scenario.
+3. **Is `emitted` non-empty** for steps that later steps depend on? `emitted` lists key names only;
+   `→ emitted: (nothing — toolOutputLogic derived no keys)` means every downstream input reading
+   that step will be wrong.
+
+A `↑ not named by the prompt:` line under `params` lists targets the dry run filled from the
+recording. A live turn finds those in an earlier step, or does not run — so a green trace with
+that line is not yet evidence that a session would steer.
+
+A dry replay is recorded as `outcome: 'dry'` and is excluded from savings by construction — it costs
+you a Haiku call and nothing else.
+
+---
+
+## 4. Confirm the match fires
+
+Now ask the same thing in different words, in a new session.
+
+```
+you:  can you check the eu-west fleet and tell me which boxes are in trouble?
+```
+
+```
+[bir] …  run.matched  run=run_… matchedRun=run_5f3a… similarity=0.94
+         why="similar prompt — the service kept its own run; not recording this one"
+```
+
+That line is the whole feature working up to the point of replay. If it does not appear, the prompt
+did not clear the server's `SIMILARITY_THRESHOLD` (default 0.9) — see §8.
+
+**With replay off (`bir replay off`), this is where it stops.** The server keeps its canonical run, bumps
+its `iterations`, this turn is not recorded, and the model answers the ordinary way. Nothing is lost
+and nothing is skipped.
+
+---
+
+## 5. Turn replay on
+
+> Read §5.1 before running anything in this section.
+
+### 5.1 What you are agreeing to
+
+A calculated scenario is, in effect, **a pre-approved list of tool calls with computed arguments.**
+When replay arms:
+
+- **Steered steps are auto-approved.** `PreToolUse` is answered `allow` for a pinned call, so a
+  pinned `Bash` or `Edit` runs without the prompt you would normally see. A call is pinned only
+  when it plausibly *is* the step — the same command, the same file, an argument in common (design
+  §7) — and never in plan mode.
+- **Direct steps are not visible to the permission system at all.** They are dispatched straight to a
+  `bir-proxy`, which calls the upstream on a connection it already holds. Claude Code never sees them.
+  The `run_scenario` call that starts them is answered `allow` too, while the runner has announced a
+  direct plan; your own deny or ask rules for it still apply.
+
+That is what makes replay fast, and it is the whole risk. Two things follow:
+
+1. Only enable it in a project whose scenarios you have dry-replayed and read (§3.1).
+2. Run `bir replay allow <servers>` (§5.3). An allowlist of the servers you are comfortable having
+   called unattended is cheap insurance, and it is the difference between "replay reads a dashboard"
+   and "replay can do anything any wrapped server can do".
+
+Nothing else is approved on your behalf. Outside a matched scenario's own steps, a wrapped MCP call
+keeps its permission prompt, as it would without the runner (`bir doctor` says so in a note);
+`BIR_CORRELATION_DECISION=allow` where the recorder starts is the explicit opt-in to approve them
+all.
+
+### 5.2 Enable it
+
+`bir setup` already did this: it installed the scenario server in the local scope, which Claude
+Code never asks about, and switched replay on for the project. By hand:
+
+```bash
+bir install --replay          # adds the `bir` MCP server and switches replay on here
+bir up --restart              # the recorder reads the change when it restarts
+```
+
+A flag-less `bir install` keeps the invocation the project was set up with — `bir setup` installs
+with `--global` from an installed package and `--local` from a checkout — so this downgrades
+nothing. But a `bir install` **without** `--replay` leaves replay off in a project that never asked
+for it (one that already has the scenario server, or where you ran `bir replay on`, keeps what it
+had), and a later `bir install`, with or without `--replay`, never overrules `bir replay on|off`.
+`bir install --replay` does exactly two things beyond a normal install, and `bir uninstall --replay`
+undoes both, leaving everything else as it is:
+
+- registers a first-party MCP server under the key **`bir`** in the local scope — `~/.claude.json`,
+  under Claude Code's key for this project, never the `.mcp.json` a team commits (`--mcp-json` puts
+  it there instead, pre-approved in `.claude/settings.local.json`, the older shape). It exposes
+  `mcp__bir__run_scenario` — the channel a fully-wrapped scenario's results come back through — and
+  by default nothing else. Three tools that only read a scenario (`scenario_show`,
+  `scenario_edits`, `investigate`) are listed after `bir scenario editing on`, or with
+  `BIR_SCENARIO_TOOLS=read` in the server's environment, and three for changing one
+  (`scenario_check` tries a change, `scenario_edit` saves it, `scenario_undo` takes it back) only
+  after `bir scenario editing on`. §9.2 lists them with their arguments; the editing it describes
+  is built but not yet released. From the next version, a call to any of them except
+  `run_scenario` is never recorded. In a subdirectory or linked worktree of a git repository the
+  server is not added — in the local scope it would apply to the whole repository — and replay
+  steers without it;
+- switches replay on for the project (`bir uninstall --replay` switches it off, and restarts a
+  recorder no session is using so that applies at once).
+
+The hook timeouts, including `UserPromptSubmit`'s 10 s, are not among them: every install writes
+them, replay or not.
+
+`run_scenario` is visible to the model in every session in this project. That is a real cost — one
+more tool in the list, a little context per turn — and it is why replay is a separate flag rather
+than part of `bir install`. The other `bir` tools are not listed until you ask for them (§9.2).
+
+Confirm:
+
+```bash
+bir doctor
+```
+
+```
+Replay            : ON  servers=chrome-devtools,fleet-api  minSimilarity=0.92  source=sidecar
+                    derive=the service (no key needed here)
+Wrapped in config : chrome-devtools, fleet-api
+Registered proxies: chrome-devtools, fleet-api
+Control server    : http://127.0.0.1:53411
+BaseIn (shell)    : https://api.bi2202.com (answers /health)
+Recording tier    : bound (Tier 1)
+Recording         : yes
+
+  · recording to https://api.bi2202.com as you@example.com
+  · the recorder runs in the background (pid 41820); its audit log is ~/.baseinstrunner/logs/<key>.log
+  · the BaseIn service last answered the recorder 12 s ago
+  · wrapped MCP calls are not approved by the runner: Claude Code asks as it would without it. For headless runs (`claude -p`) allow them in permissions.allow or --allowedTools, or set BIR_CORRELATION_DECISION=allow where the recorder starts
+  · recurring sub-tasks are observed only — nothing is replaced (BIR_SEGMENT_ARM unset)
+
+No problems found.
+```
+
+`BaseIn (shell)` is the address this terminal's `bir` commands would use — `BIR_AUTH_URL` if it
+is set, else the one `bir setup` stored — and `recording to` is the one the running recorder
+uses, with the account it is signed in as. The two normally agree.
+
+### 5.3 Environment
+
+The first three switches are stored per project, and that is where to set them:
+
+```bash
+bir replay allow chrome-devtools,fleet-api   # the servers bir may call by itself; `allow all` clears it
+bir replay off                               # and back with `bir replay on`
+bir replay status                            # what is stored for this project
+bir up --restart                             # a running recorder reads them when it restarts
+```
+
+They are kept in `~/.baseinstrunner/installed.json`. A recorder started by the SessionStart hook has
+Claude Code's environment, not your terminal's, and reads them from there. The environment variables
+below override them wherever the recorder sees them; `bir doctor` says which is in effect
+(`source=sidecar` or `source=env`). The proxies need no replay configuration of their own — every
+bound proxy polls the recorder for work, and slows to one poll every 30 s while replay is off there,
+so there is exactly one switch and it cannot get out of step with itself.
+
+| Variable | Default | What it does |
+|---|---|---|
+| `BIR_REPLAY` | *(the stored switch)* | `0` disables replay and any other value turns it on, whatever `bir replay on` or `off` or the install stored. Unset, the stored switch decides: on after `bir setup` or `bir install --replay`, off after a plain `bir install`. Nothing below matters while replay is off |
+| `BIR_REPLAY_ALLOW_SERVERS` | *(the stored list, else all wrapped)* | Comma-separated server keys bir may call by itself: **direct** execution and divergence recovery. Overrides `bir replay allow` |
+| `BIR_MIN_STEER_SIMILARITY` | `0.92` | Below this a match is detected but not replayed (§8) |
+| `BIR_DERIVE_API_KEY` | *(unset)* | **Not required.** Derivation — reading what this request acts on — is done by the service on its key for a signed-in runner. Set this to keep the reading on this machine instead: the prompt then never leaves it, and it is one round trip faster. Signed out *and* unset, only a scenario with nothing to work out replays. A recorder running in the background (started by the SessionStart hook, `bir up` or `bir setup`) ignores `ANTHROPIC_API_KEY` (usually Claude Code's own, and billed) unless `BIR_USE_ANTHROPIC_API_KEY=1`; a `bir-hooks` you run in a terminal uses it |
+| `BIR_DERIVE_MODEL` | `claude-haiku-4-5-20251001` | The derivation model, when this machine does the reading |
+| `BIR_MATCH_BUDGET_MS` | `1500` | How long the prompt hook waits for a match before giving up. After a match slower than `BIR_MATCH_SLOW_MS` (`800`), prompts stop waiting for one for 5 minutes, doubling up to 30 while the service stays slow |
+| `BIR_DERIVE_BUDGET_MS` | `8000` | How long `run_scenario` waits for parameters |
+| `BIR_HOOK_DERIVE_BUDGET_MS` | `4000` | How long a hook waits for them: the prompt, for a scenario with a target, and the first `PreToolUse` (never longer than `BIR_DERIVE_BUDGET_MS`) |
+| `BIR_PRETOOL_REPLAY_BUDGET_MS` | `9000` | All replay work inside one `PreToolUse`, a divergence's steps included. At most 10 000 |
+| `BIR_REPLAY_PLAN_BUDGET_MS` | `100000` | Whole-plan ceiling for direct execution; `BIR_REPLAY_BUDGET_MS`, where set, overrides it. Past about 110 000 a long run may be moved to the background by Claude Code. Derivation plus plan is held under 270 s |
+| `BIR_STEP_TIMEOUT_MS` | `60000` | Per-step ceiling for one direct `tools/call`, clipped to what the plan has left |
+| `BIR_LOGIC_TIMEOUT_MS` | `1000` | How long one scenario logic body may run before it is stopped. At most 10 000 |
+| `BIR_REPLAY_RECORDED_OUTPUTS` | *(unset)* | `1` lets a step that could not be sent (a built-in, no proxy, a server off the allowlist) stand on its recorded output instead of stopping the plan. Never for a timeout or an upstream error |
+| `BIR_INTENT_ARM` | *(unset)* | `1` lets a match found mid-turn arm a plan in the calling tool's place, which means waiting for it (`BIR_INTENT_ARM_BUDGET_MS`, 500); `0` never waits; unset follows `BIR_SEGMENT_ARM` |
+| `BIR_VERBOSE` | *(unset)* | `1` adds per-step `replay.*` detail lines |
+
+The `bir` server reads its own, from the environment Claude Code starts it with:
+`BIR_SCENARIO_RUN_TIMEOUT_MS` (`290000`, how long `run_scenario` waits for its run),
+`BIR_SCENARIO_TOOLS=read` (list the reading tools, §9.2) and `BIR_SCENARIO_DEBUG=1` (raw reasons,
+§9). [production.md](../production.md) lists every variable.
+
+**No API key is a supported configuration, not a broken one.** Signed in, the service reads the
+prompt on its own key and the replay is the same replay. Signed out *and* without a key, nothing
+can read the prompt: a *setting* takes the value it had in the recorded run, so a scenario whose
+parameters are all settings — a dashboard sweep, a fixed report — is still a complete, free replay;
+but a scenario with a *target* (the thing the task acts on: "check *eu-west*") is declined rather
+than run on last week's value, and the agent does the task normally. `bir doctor` names the state
+you are in: `derive=this machine (a derivation key: BIR_DERIVE_API_KEY)`,
+`derive=the service (no key needed here)`, or
+`derive=recorded sample values — scenarios with a target will NOT run`. The recorder's own
+`replay.enabled` line at start names the variable.
+
+---
+
+## 6. Run it, and read what happened
+
+Ask the matching question again, with replay on.
+
+### 6.1 A fully-wrapped scenario — direct
+
+```
+[bir] …  run.matched   run=run_… matchedRun=run_5f3a… similarity=0.94
+[bir] …  plan.armed    scenario=scn_9c1b… mode=direct steps=3
+         tools="mcp__chrome-devtools__navigate_page,mcp__chrome-devtools__take_snapshot,mcp__fleet-api__device_detail"
+[bir] …  replay.derived  scenario=scn_9c1b… params=2 costUsd=0.0011 source=the service
+[bir] …  replay.step     n=0 tool=navigate_page server=chrome-devtools ms=612 ok=true
+[bir] …  replay.step     n=1 tool=take_snapshot  server=chrome-devtools ms=1104 ok=true emitted=devices
+[bir] …  replay.step     n=2 tool=device_detail  server=fleet-api ms=210 ok=true emitted=highestRiskDeviceId,riskScore
+[bir] …  replay.done     scenario=scn_9c1b… mode=direct steps=3/3 outcome=steered_full ms=2766
+[bir] …  execution.reported  scenario=scn_9c1b… outcome=steered_full derive=0.0011 session=0.0083 fallback=0.0000 savedUsd=0.114
+```
+
+In the session you will see one tool call, `mcp__bir__run_scenario`, with no permission prompt,
+returning the composed results. The model reads them and answers. It never emitted the three
+underlying calls.
+
+A direct plan runs only through that call. If the model's first call is anything else, the plan is
+retired without running a step (`replay.vetoed`), that call runs as written, and the model is told
+the scenario is not being run. A plan whose `run_scenario` is refused, or never reaches the
+recorder, is retired the same way. A direct plan is not even announced unless a running `bir`
+server has told the recorder it serves `run_scenario` (`replay.decision … code=no_delivery_tool`
+otherwise).
+
+### 6.2 A mixed scenario — steer
+
+The model emits each call itself; `bir` overrides the arguments. The per-step `replay.pin` and
+`replay.thread` lines are detail lines, printed only under `BIR_VERBOSE=1`; without it a steer run
+shows `plan.armed`, `replay.done`, and any `replay.thread_fallback` between them.
+
+```
+[bir] …  plan.armed    scenario=scn_44d0… mode=steer steps=4
+[bir] …  replay.pin    n=0 tool=mcp__github__list_pull_requests
+[bir] …  replay.thread n=0 via=proxy emitted=prNumbers done=false
+[bir] …  replay.pin    n=1 tool=Read
+[bir] …  replay.thread n=1 via=hook emitted=reviewers done=false
+[bir] …  replay.done   scenario=scn_44d0… mode=steer steps=4/4 outcome=steered_full
+```
+
+`via=proxy` versus `via=hook` matters: a wrapped MCP step's output is threaded from the **proxy's**
+report, because that is the shape the scenario's logic was written against (design §7.2). A
+`replay.thread_fallback run=… tool=… why="no proxy report — threading the hook's view; shapes may differ"`
+line — printed whether or not you are verbose — means the proxy did not report within its grace
+window and the hook's differently-shaped view was used instead. Expect derived values to be empty,
+and treat repeats as a bug.
+
+A pin needs the model's call to plausibly *be* the step: the same command, the same file, an
+argument in common (design §7). The directive shows each step's arguments where they are known, so
+the model can pass them as shown. A call to the expected tool that is not the step — `ls` where the
+step is `git push` — is not pinned: it runs as written, the plan stays armed, and
+`replay.pin_declined` says why. If the model then moves on to another tool, it did the step its own
+way: `replay.pin_abandoned` retires the plan without running anything, and the model is told the
+arguments are its own from then on. The plan runs one call at a time: a call made while a pinned
+step is still running hands the rest over (`replay.concurrent_call`).
+
+### 6.3 The model goes off-script
+
+```
+[bir] …  replay.diverge  scenario=scn_44d0… expected=mcp__github__get_pull_request called=Bash step=2/4
+[bir] …  replay.compose  scenario=scn_44d0… remaining=2 executed=2 recorded=0 skipped=0 bytes=8412 costUsd=0.00
+[bir] …  replay.done     scenario=scn_44d0… mode=steer steps=2/4 outcome=diverged
+```
+
+`costUsd=0.00` on the compose line is the point of the whole design: the remaining steps ran through
+proxies that were already connected, so recovering from a divergence cost no tokens at all.
+
+Only a wrapped server's step can run that way, and only one on the allowlist. A step that cannot —
+a built-in such as `Read`, a server off `BIR_REPLAY_ALLOW_SERVERS`, a proxy that does not answer —
+ends the bundle there: `replay.compose` shows `skipped=1 stopped=<n>:<reason>`, the bundle opens
+with a note that names the step and says what may be assumed about it, and the model carries on
+from that step. A recorded output stands in for it only with `BIR_REPLAY_RECORDED_OUTPUTS=1`. The
+recovery runs inside the diverging call's `PreToolUse`, so it starts no step after
+`BIR_PRETOOL_REPLAY_BUDGET_MS` (9 s). Direct plans never diverge (§6.1).
+
+### 6.4 The audit vocabulary
+
+Everything replay decides is one line. `grep` for these:
+
+| Line | Means |
+|---|---|
+| `run.matched` | The server recognised the prompt |
+| `replay.decision … verdict=no-steer` | Matched, and declined. `why=` says which gate, `code=` names it: `match_timeout`, `service_unhealthy`, `arm_timeout`, `arm_unannounced`, `no_delivery_tool`, `missing_target`, … |
+| `replay.match_gate` | Prompts stopped waiting on a slow match (`state=holding`), or started again (`state=open`) |
+| `plan.armed` | A plan exists. Carries mode, step count and the ordered tool names — **before** anything runs |
+| `replay.derived` / `replay.derive_failed` / `replay.derive_timeout` | Parameters resolved, fell back to sample values, or ran out of time |
+| `replay.unsafe_param` | A derived value failed the safety check for a command-like step; the plan is declined before it arms, or hands over |
+| `replay.pin` / `replay.thread` | One steered step's input pinned / output threaded — detail lines, only under `BIR_VERBOSE=1` |
+| `replay.pin_declined` / `replay.pin_abandoned` | A call to the expected tool was not the step and ran as written / the model moved on, and the plan was retired |
+| `replay.concurrent_call` | A call ran beside a pinned step; the plan handed over |
+| `replay.thread_fallback` | A wrapped step's output was threaded from the hook's view because the proxy did not report in time |
+| `replay.step` | One direct step executed |
+| `replay.diverge` / `replay.compose` | Off-script, and the recovery |
+| `replay.handover` | The plan stopped and handed the rest of the task to the model; `kind=` and `step=` say where |
+| `replay.vetoed` | A direct plan retired without running anything: `run_scenario` was not the first call, or never arrived |
+| `replay.run_ambiguous` | Two sessions had `run_scenario` pending and the request named neither; nothing ran |
+| `replay.cancelled` / `replay.note_kept` | A direct run's caller went away (Esc); no further step started, and the note is kept for the model's next call |
+| `replay.pin_overran` / `replay.diverge_overran` | `PreToolUse` reached its deadline while replay was still working |
+| `replay.budget_clamped` | A budget set past its ceiling was brought back under it, at start |
+| `replay.delivery_tool` | A `bir` server said it can, or cannot, deliver a direct plan |
+| `control.hook_deadline` | A hook route answered `{}` at its deadline |
+| `replay.done` | Final outcome, steps completed, elapsed |
+| `execution.reported` | The ticket was redeemed and the saving booked |
+
+`scenario.answered` is the `bir` server's own line, on its stderr (Claude Code's log for that MCP
+server): what `run_scenario` answered, and the real reason when the model was told only that the
+results are not available.
+
+A recorder started in the background — by the SessionStart hook, `bir up` or `bir setup` — keeps
+them in `~/.baseinstrunner/logs/<key>.log`; `bir status` names the file. One started in a terminal
+writes them to that terminal; keep them yourself: `bir-hooks 2>&1 | tee -a ~/.baseinstrunner/audit.log`.
+
+---
+
+## 7. What each outcome means for your numbers
+
+Reported once per matched turn, to `POST /scenarios/:id/executions`, redeeming the match's
+`executionTicket`.
+
+| Outcome | When | Where it lands |
+|---|---|---|
+| `steered_full` | Every planned step ran under the scenario's control | savings ledger |
+| `diverged` | Off-script, and some steps ran under the plan; the composed bundle answered | savings ledger |
+| `fell_back` | Some steps did their work, then the plan handed the rest of the task to the model | savings ledger, measured against the whole turn (it can be negative) |
+| `not_steered` | Matched, declined at a gate — or a direct plan retired before it ran anything — and the agent ran the task normally | **baseline sample** |
+| `failed` | Armed, then gave up before any step did its work — the agent ran the task normally | **baseline sample** |
+
+A recorded output that stood in for a step (`BIR_REPLAY_RECORDED_OUTPUTS=1`) is never counted as
+work done. A direct run you cancel (Esc) is booked `fell_back` or `failed` with `measured: false`:
+a turn cut short says nothing about what the task costs.
+
+`not_steered` is not an error, and it is not wasted. A saving is `baseline − actual`, and the baseline
+is *what this task costs when the agent does it*. Every declined match is a fresh measurement of
+exactly that. A deployment that never declines has no baseline to measure against — which is a good
+reason to leave `BIR_MIN_STEER_SIMILARITY` where it is rather than driving it to zero.
+
+An **unredeemed** ticket books nothing at all. Silence loses a saving; it never invents one.
+
+---
+
+## 8. Tuning
+
+Only one knob matters in practice.
+
+**`BIR_MIN_STEER_SIMILARITY` (default 0.92).** The server detects matches at 0.9 and uses that to
+decide *"don't record this again"* — cheap: the worst case is a lost recording. Steering makes a much
+stronger claim, *"don't think about this again"*, and a 0.90-similar prompt usually covers only part
+of the live task. Steering it produces a confident, thin, wrong answer.
+
+Tune it from evidence, not taste. Run for a week and read the declines:
+
+```bash
+grep 'replay.decision' audit.log | grep 'why="similarity below threshold"'
+```
+
+- Prompts you *would* have wanted replayed, sitting at 0.90–0.92 → lower it, in steps of 0.01.
+- Replays that answered the wrong question → raise it, and re-read the scenario's `intent`.
+
+If a specific pair of prompts *should* match and does not, the fix is usually upstream of the
+threshold: the two prompts genuinely mean different things to the embedding model. Re-record with a
+first prompt that states the task plainly.
+
+---
+
+## 9. Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| No `run.matched`, ever | Prompt below the server's `SIMILARITY_THRESHOLD` | Rephrase closer, or lower it server-side. Confirm the original run is in the list — a sub-`RECORDING_MIN_ACTIONS` run is never embedded |
+| `run.matched` but no `plan.armed` | A gate declined | Read the `replay.decision` line's `why=`. Ranked by frequency: replay off — `bir replay off`, `BIR_REPLAY=0`, or never switched on here (a `bir install` without `--replay`; `bir replay status` says which) · scenario not `ready` · similarity below threshold · no step is executable |
+| `replay.decision … code=match_timeout` or `code=service_unhealthy` on many prompts | The service answered the match slower than `BIR_MATCH_BUDGET_MS` (1.5 s), or is failing and in its cool-down | Nothing breaks: those turns run normally, and after a slow match prompts stop waiting on it for a while by themselves (`replay.match_gate`). `bir doctor` shows the service's state. Raise `BIR_MATCH_BUDGET_MS` only if the service is reliably just over it — every prompt pays it |
+| `replay.decision … code=no_delivery_tool` | A direct plan, and no running `bir` server has told the recorder it serves `run_scenario`: the server is missing, disabled or failed in `/mcp`, was not added (a subdirectory or worktree of a repository), or the session was started with `BIR_OFF=1` | `/mcp` shows whether `bir` is connected. `bir install --replay` adds it, in the project's own directory; then start a new session |
+| `replay.vetoed … the model's first call was …, not run_scenario` | A direct plan, and the model reached for another tool first — usually because it has no `run_scenario` | As for `no_delivery_tool`. Nothing ran; the model did the task |
+| `replay.pin_declined` on most steered turns | The model's calls to the expected tool are not the step — another command, another file — so nothing is pinned; if it then moves on, `replay.pin_abandoned` retires the plan | Harmless for those calls, which ran as the model wrote them. Persistent declines on one step usually mean its arguments cannot be shown in the directive (they depend on an earlier step's output, or the command runs to several lines), and the model writes its own |
+| `why="no step is executable"` | None of the scenario's tools is a wrapped MCP server and none is a built-in reachable in this session | Wrap the servers the scenario uses (`bir install --server …`) and recalculate |
+| `plan.armed mode=steer` where you expected `direct` | At least one step is a built-in, an unwrapped MCP server, or `claude-in-chrome` | `bir status` shows what is wrapped. `claude-in-chrome` is `scope: "dynamic"` and can never be wrapped |
+| Model ignores the directive and diverges every turn | Steering is advisory — the model chooses; `bir` only pins arguments | Expected occasionally. Persistent divergence usually means the scenario's tools do not fit the live task; check `intent` |
+| A `replay.thread` line with no `emitted=` (under `BIR_VERBOSE=1`) | `toolOutputLogic` derived nothing — usually the output shape changed since recording | Dry-replay (§3.1). If the dry run emits and the live run does not, the tool's output shape has drifted; recalculate |
+| `replay.thread_fallback` on a wrapped step | The proxy did not report within the grace window | Check that proxy is alive (`bir doctor`). Repeats mean a slow or dying upstream |
+| `run_scenario` answers "Nothing to run for this request; continue normally." | The model called it on a turn with no plan, the runner is off, or no recorder is running for this directory | Harmless, and not an error. It happens when the model remembers the tool from an earlier turn |
+| `run_scenario` answers "The prepared results are not available for this request. Do the task normally with your tools." | The plan could not be delivered — a recorder that does not answer, a timeout, an HTTP error — and the model does the task itself | The `scenario.answered` line on the `bir` server's stderr has the real reason. `BIR_SCENARIO_DEBUG=1` in that server's environment hands the raw reason to the model as an error, for debugging |
+| A hand-over note says a step "was sent but did not answer … may or may not have completed" | The step timed out, or its upstream went away mid-call; nothing after it ran | Check whether its work happened before running it again — the model is told the same. Repeats: look at that upstream, or raise `BIR_STEP_TIMEOUT_MS` |
+| A hand-over note says "a step never runs on another session's upstream" | Two Claude Code sessions are open in the project, and this one has not yet made a call of its own to that server, so bir cannot tell its proxy from the other session's | Expected: the model calls the tool itself. Once the session's own call to the server has gone through, later replays use its proxy |
+| `recorder.send_failed … error="HTTP 409 … invalid_ticket"` | The execution report's ticket was already redeemed, or belongs to another scenario | Harmless if the body says `duplicate: true`. Otherwise a rollover raced `SessionEnd`; the server books once |
+| `savedUsd` looks impossible | Pricing drift between the runner's table and the server's | Compare `PRICING_VERSION` on both sides. Design §11.3 documents a known live drift between two existing copies |
+| The hand-over note says a step "did not run: its input needs a judgement" | The service marked the step non-deterministic when it calculated the plan: the generated logic could not compute its input from the prompt or from earlier outputs, so the recorded value was a copy (the service's plan-services design, D8 kind 3 — it lives in the BaseIn repository, not this one). `nondeterministicWhy: by_hand` means someone marked it with `bir scenario edit --freeze` | If the code only has a slip, fix the step yourself: `bir scenario show scn_… --step <n>`, write the input logic to a file, then `bir scenario edit scn_… --step <n> --input-logic <file>` — the service checks it against the recording before it saves it (§9.2, not yet released). Of the edits, only `--unfreeze` lifts a mark made by hand (`by_hand`); a code edit, even a forced one, leaves it in place. A real judgement — a choice with no fixed rule — cannot be written as code: the agent makes that choice and finishes the task; a model step for it is planned (W3.1). The journal's `plan.armed` line lists the step under `stops=` |
+| A parked step ran again after an hour, or a plan was recalculated by itself | The service's grace period (D8): a parked step is served with `stop: null` once an hour for a day and a success clears its count; if it keeps failing, or its tool is gone, the next repeat of the prompt is recorded in full and the plan is calculated again from it | Nothing: that is the repair. `bir investigate` says which it is — a step still being retried, a parked step whose repair is due, or a plan being calculated again. To repair now by hand: `bir scenario calc <runId> --force` for a whole-run plan; from the next version, `bir scenario calc <scnId> --force` works for any plan, a sub-task one included. A plan with steps edited by hand is not repaired by itself: the parked step stays parked, and `bir investigate` says the repair was skipped. Then fix the step (§9.2); or take the edits back with `bir scenario undo`, once per edit, and it is repaired as usual; or recalculate now and drop the edits: `bir scenario calc <scnId> --force --discard-edits` |
+| `sessionCostUsd` grows every prompt in a session | The per-run usage watermark is missing or not taken | Design §11.4. Reports without a mark must carry `measured: false` |
+| Everything works, nothing is saved | A replayed turn is deliberately not recorded (design §12) | Correct. The matched run stays canonical and its `iterations` is bumped |
+| `bir doctor`: the SessionStart hook points at a Node that is gone | The hook names Node by absolute path. That Node was uninstalled, moved, or was a version manager's per-shell copy; the hook then fails on every session, no recorder is started, and runs record Tier 2 | `bir setup` here again — it rewrites the hook to the Node that runs it |
+| `control.port_busy` in the log; the recorder is not running | Another program holds this project's port, or the system excludes it (on Windows, a range Hyper-V or WSL reserved). A background recorder with a recorded port does not fall back to another, because every hook but SessionStart names this one; only a `bir-hooks` you run by hand in a terminal still does | `bir setup --port <another>` in this directory — the fix the log line itself names. It rewrites the hook URLs and the scenario server's address together and restarts the recorder |
+| The recorder was started by the hook, and `bir doctor` says `servers=(all wrapped)` although you set `BIR_REPLAY_ALLOW_SERVERS` | The hook starts the recorder with Claude Code's environment, not your terminal's; a variable set in one terminal is not seen | `bir replay allow <a,b>` — stored for the project, read by every recorder — then `bir up --restart` |
+| A session misbehaves, and you want to rule the runner out now | — | `bir off --here` (or `bir off` for every project): hooks answer with nothing within about a second, open sessions included, the `bir` server lists no tools, and nothing is recorded or replayed; wrapped servers run as plain pipes from their next start. Nothing is uninstalled. `bir on --here` (or `bir on`) undoes it (§11) |
+
+---
+
+### 9.1 `bir investigate` — the table above, applied for you
+
+Every audit line that explains a turn is also kept in a **journal**, one JSON
+object per line, under `~/.baseinstrunner/control/journal/` (one file per
+directory, rotated at 4 MB). The recorder names it at start — the `journal=`
+field of its `control.listening` line, in the audit log for a background
+recorder. Ask the journal and the service together:
+
+```
+bir investigate                       # the newest turn in this directory
+bir investigate <run_|scn_|sexec_ id> # that run, scenario or execution
+bir investigate list [--limit n]      # recent turns and their verdicts
+bir investigate executions [--limit n] [--user <email|id>]   # the ledger
+```
+
+The output is the turn as the journal tells it (matched what, which gate
+declined and why, what mode armed with which coverage, what the execution
+reported), then **runner findings**, then the service's view (the recording,
+the scenario, the baseline and its sample count, the executions with their
+saved $ and %) and **service findings**. Every finding is *problem → cause →
+fix*. The three questions it answers:
+
+| Question | Where the answer comes from |
+|---|---|
+| Why did this turn not run its calculated scenario? | `replay.decision code=…` in the journal, mapped to the cause and the fix; and the service: is the run a recording, is it embedded, how many hits, is the scenario ready / failed / switched off, which step is parked |
+| Why did it save so little, or cost more? | the execution's cost breakdown (derive, session, fallback) against the baseline; steer mode with built-in steps is the usual answer, a single-sample baseline the second |
+| What happened, step by step? | the turn's lines in order, the per-step verdicts on the execution, and `replay.*_failed`, `replay.diverge`, `replay.handover` as incidents |
+
+You see your own data. An admin of the service sees everyone's and may pass
+`--user` to `executions`. `--json` on any form prints the raw merge.
+
+### 9.2 Fix a step — `bir scenario check`, `edit`, `edits`, `undo`
+
+> Built 2026-09-25, **not yet released**. It needs the next `@basein/runner` version *and* a
+> service deploy: the `/scenarios/:id/steps/…` routes and the sandbox the service runs step code
+> in. Version 0.2.11 on npm has an early form of these commands. It is not what this section
+> describes. The design is `editSteps.md` in the BaseIn repository.
+>
+> The hiring-year outputs below were printed by the real `bir`, against the real service, on the
+> real recording. Only the ids are shortened, with `…`.
+
+`bir investigate` says *what* is wrong. This section is how you fix it. A calculated step is code:
+its **input logic** says what to send to the tool, and its **output logic** says what to keep from
+the answer. When that code is wrong, you do not have to recalculate and hope any more. You change
+the step, and the service checks your change against the recording before it saves it.
+
+**A change is saved only if it reproduces the recording and is not a copy — or on purpose, with
+`--force --note "why"`.**
+
+```
+bir scenario show  <runId|scnId> [--step <n>]
+bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze]
+bir scenario edit  <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
+                   [--freeze | --unfreeze] [--note "<why>"] [--force --note "<why>"] [--revision <n>]
+bir scenario edits <runId|scnId>
+bir scenario undo  <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "<why>"]
+bir scenario calc  <runId|scnId> [--force [--discard-edits]]
+bir scenario editing on|off|status
+```
+
+A `run_` id finds the run's whole-run scenario. A `scn_` id (what `bir investigate` prints) is used
+as it is. A sub-task scenario has only a `scn_` id. When a run has only sub-task scenarios, `bir`
+lists their `scn_` ids instead of guessing. `--step` is the `stepIndex` that `show` prints; it
+starts at 0. `--revision <n>` saves only if the plan is still at revision `n`: the `chainRevision`
+at the top of `show --step`. `--json` on `check`, `edit`, `edits` or `undo` prints the service's
+answer unchanged. Exit codes: `0` checked OK, saved or undone · `1` refused, not found, or a
+service error · `2` a wrong command line.
+
+#### What the code is
+
+Each logic is the *body* of a JavaScript function. It must end in `return { … }`.
+
+| Logic | Reads | Returns |
+|---|---|---|
+| input logic (`toolInputLogic`) | `parameters` — this request's values · `respParams` — what earlier steps kept · `intent` | the tool's input, as an object |
+| output logic (`toolOutputLogic`) | `toolOutput` — the tool's answer, as text · and the same three | the values to keep for later steps, as an object |
+
+The service runs your code in a sandbox (design §13.1). In the sandbox only JavaScript itself
+exists: `JSON`, `Math`, `Date`, `RegExp` and the like. There is no `require`, `process`, `fetch`,
+`Buffer` or timer. A few built-ins are taken away too: `ArrayBuffer`, the typed arrays such as
+`Uint8Array`, `Atomics`, `WebAssembly`, `FinalizationRegistry` and `Symbol.for`. Code that uses
+one of them with the recording's values throws in the check.
+
+**But the check only judges what your code returns for the recording's values.** A `fetch` behind
+a `typeof` guard (`if (typeof fetch === "function") …`), or on a branch the recording's values
+never take, is never reached in the check. A `fetch` inside a `try` fails in the check, but the
+`catch` hides the error. Either way the code passes. On your machine the runner runs the same
+code in its own process, with the global scope and only a time limit, where `fetch` and `process`
+do exist. So read every change before it is saved — yours and Claude's.
+
+**Only a step's code and its mark can be changed.** Not the parameters, not their sample values, not
+the logic that builds the final answer. Only tool steps: a sub-task call row belongs to the service.
+
+#### The fix, step by step
+
+On 2026-09-25 two SQL steps of the hiring-year scenario, 3 and 4, were marked *needs a judgement*.
+Step 4 is shown here; step 3 was fixed the same way. The calculation's code for step 4 wrote
+`schema + '.' + summary_table`, but the table name already carried its schema, so the code did not
+give the recorded call. The calculation then put a copy of the recorded call in its place, and
+marked the step.
+
+**1. Read the step.**
+
+```bash
+bir scenario show scn_4a17a126-… --step 4
+```
+
+You should see this (shortened: each `…` line stands for lines left out):
+
+```
+{
+  "scenarioId": "scn_4a17a126-…",
+  "chainRevision": 1,
+  "stepIndex": 4,
+  "kind": "tool",
+  "toolName": "mcp__postgres__execute_sql",
+  "toolInputLogic": "return {\"sql\":\"SELECT * FROM employees.hiring_year_summary ORDER BY hire_year;\"};",
+  …
+  "nondeterministic": true,
+  "nondeterministicWhy": "input_mismatch",
+  "editedAt": null,
+  "editForced": false,
+  "stop": {
+    "kind": "nondeterministic",
+    "why": "input_mismatch"
+  },
+  "sampleInput": "{\"sql\":\"SELECT * FROM employees.hiring_year_summary ORDER BY hire_year;\"}",
+  …
+}
+```
+
+`scenarioId` and `chainRevision` come first. They belong to the whole scenario, and
+`chainRevision` is the number `edit --revision` takes. The rest is the step. Its input logic is
+that copy: compare it with `sampleInput`. A copy does the old job, on the old table, whatever the
+new request says. That is why the step is marked (`nondeterministic: true`), and why runs hand over
+to the agent in front of it.
+
+**2. Write the new code to a file.**
+
+```bash
+cat step4.js
+```
+
+```
+return { sql: "SELECT * FROM " + parameters.summary_table + " ORDER BY hire_year;" };
+```
+
+Code always goes in from a file, or from stdin with `-`. Never on the command line: the shell's
+quoting breaks JavaScript.
+
+**3. Check it.** Nothing is saved.
+
+```bash
+bir scenario check scn_4a17a126-… --step 4 --input-logic step4.js
+```
+
+```
+Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
+  input    reproduces the recorded call
+  later    not affected: only the input logic changed
+  mark     needs a judgement (input_mismatch) → runs by itself
+Nothing saved. To save: bir scenario edit scn_4a17a126-… --step 4 --input-logic step4.js
+```
+
+- `input` — does the code give the recorded call?
+- `later` — do the steps after it still give theirs? Here only the input logic changed. Nothing a
+  later step reads has changed, so no later step was judged.
+- `mark` — what happens to the *needs a judgement* mark. `→ runs by itself` means the mark goes
+  when you save, and runs stop handing over in front of this step.
+
+**4. Save it.** `edit` runs the same check, and saves only what the check approved. Add a `--note`
+that says why; the history keeps it.
+
+```bash
+bir scenario edit scn_4a17a126-… --step 4 --input-logic step4.js --note "summary_table already carries its schema"
+```
+
+```
+Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
+  input    reproduces the recorded call
+  mark     needs a judgement (input_mismatch) → runs by itself
+Saved as sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda (revision 2). Undo: bir scenario undo scn_4a17a126-… --edit sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda
+```
+
+`edit` prints fewer lines than `check`. It always prints `input`, and the other lines only when
+something moved or broke. Step 3 was then saved the same way, as revision 3.
+
+**5. Try it without real tools.** A dry replay (§3.1) runs the new code over the recorded outputs:
+`bir scenario replay scn_4a17a126-… --prompt "…" --dry`. The next real prompt uses the new code.
+There is nothing to restart.
+
+#### How the check decides
+
+The service runs your code the way the recorded run would have run it: with the recording's
+parameter values, and with what the earlier steps kept from their recorded answers.
+
+| It asks | It refuses when |
+|---|---|
+| Does the code give the recorded call? Extra spaces inside strings, and the order of keys, do not count | it gives something else (`differs`), or it crashes (`throws`) |
+| Is it a copy? It changes one parameter, or one earlier output, at a time — only the ones the code reads | the call never moves: the code returns the recorded call whatever the request says |
+| Do the later steps still give their calls? Asked only when the **output** logic changed, and only of later steps that are not marked and can be checked | a later step that gave its recorded call before does not any more |
+| Does the final answer still get its values? Asked only when the **output** logic changed | it did before, and does not after |
+| Can the mark go? | you asked to unmark the step (`--unfreeze`), and its input does not reproduce |
+
+A recorded input of `{}` is never a copy. A recorded input that is plain text, not an object, is
+`not_checked`.
+
+**The check is kept small.** On the service it runs in a worker thread of its own, never in the
+thread that answers requests. By default it may use 5 seconds of sandbox time
+(`EDIT_CHECK_BUDGET_MS`, 5000 ms). Past that it stops, and the change is refused as *too costly to
+check*. The reason `bir` prints is the service's own sentence:
+
+```
+too costly to check: the check used up its 5000 ms of sandbox time (EDIT_CHECK_BUDGET_MS) before it finished.
+```
+
+One run of your code may take 1 second (`LOGIC_TIMEOUT_MS`) and 64 MB of memory
+(`LOGIC_MEMORY_MB`), by default. Code that ran out of time or memory, or stopped the sandbox twice,
+is held back for 10 minutes: every run of that same code fails at once, with the same message.
+
+A refused change says where it differs. Here `wrong.js` adds the schema a second time:
+
+```bash
+bir scenario check scn_4a17a126-… --step 4 --input-logic wrong.js
+```
+
+```
+Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
+  input    differs from the recorded call at character 32
+           computed  … FROM employees.employees.hiring_year_summary ORDER BY h…
+           recorded  … FROM employees.hiring_year_summary ORDER BY hire_year;"…
+  later    not affected: only the input logic changed
+  mark     needs a judgement (input_mismatch) → stays marked
+Nothing saved, and `bir scenario edit` would refuse it: the change does not reproduce the recording.
+  Fix the code and check again. If the recording itself was wrong, edit can save it on purpose: add --force --note "why".
+```
+
+`bir scenario edit` with the same file refuses it, and saves nothing:
+
+```
+Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
+  input    differs from the recorded call at character 32
+           computed  … FROM employees.employees.hiring_year_summary ORDER BY h…
+           recorded  … FROM employees.hiring_year_summary ORDER BY hire_year;"…
+Not saved: the change does not reproduce the recording.
+  Fix the code and try again, or save it on purpose: add --force --note "why".
+```
+
+A pasted value is refused as a copy. Here `pasted.js` returns the recorded SQL as fixed text:
+
+```bash
+bir scenario check scn_4a17a126-… --step 4 --input-logic pasted.js
+```
+
+```
+Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
+  input    is a copy: it returns the recorded call whatever the parameters say
+  later    not affected: only the input logic changed
+  mark     needs a judgement (input_mismatch) → stays marked
+Nothing saved, and `bir scenario edit` would refuse it: the input logic is a copy: it returns the recorded call whatever the parameters and earlier outputs say.
+  Fix the code and check again. If the recording itself was wrong, edit can save it on purpose: add --force --note "why".
+```
+
+Any other refusal prints the service's own reason, one line for each problem.
+
+Code and a mark the step already has change nothing. `check` then says
+`Nothing would change: the step already has this code and mark.` (exit 0), and `edit` refuses:
+
+```bash
+bir scenario edit scn_4a17a126-… --step 4 --input-logic step4.js
+```
+
+```
+Nothing to change: the step already has this code and this mark.
+```
+
+#### `--force --note`: save it on purpose
+
+**Use `--force` only when the recording itself was wrong** — for example, the recorded run sent a
+call with a mistake you do not want repeated. Then no correct code can reproduce it.
+
+- `--force` needs a `--note` that says why (500 characters at most). Without one, `bir` stops
+  before it sends anything (`note_required`).
+- **When the check found any problem, a forced save is recorded as forced.** `bir` says so under
+  the `Saved as …` line and repeats what the check said. `bir investigate` keeps reporting the step
+  as a `warn`.
+- A forced save removes a mark **the calculation** set, unless you also pass `--freeze`. A mark
+  made **by hand** (`--freeze`) stays. A save lifts it only with `--unfreeze`.
+- A step after a sub-task call row can only be saved with `--force`: the check cannot rebuild the
+  outputs that step reads.
+
+#### Mark or unmark a step by hand
+
+- `--freeze` marks the step *needs a judgement* (`nondeterministicWhy: by_hand`). Runs then hand
+  over to the agent in front of it. No check blocks this: a mark only makes replay more careful.
+- `--unfreeze` asks to remove a mark. The check decides: the step's input must reproduce. With
+  `--force --note "why"` the mark goes anyway, and the edit is recorded as forced.
+  `bir scenario check … --unfreeze` asks the same question without saving.
+- **A mark made by hand is lifted only when someone asks.** A code edit does not lift it, even one
+  that reproduces the recording, and neither does a forced save. What lifts it: `--unfreeze`,
+  undoing the edit that made it, or `bir scenario calc … --force --discard-edits`.
+
+#### The history, and undo
+
+After both steps were saved:
+
+```bash
+bir scenario edits scn_4a17a126-…
+```
+
+```
+sedit_02cb1210-1938-4902-9395-5a82b321276d  2026-09-25 11:10:59Z  step 3  edit    revision 2 → 3  "use the settings, not the recorded names"
+    input logic changed; needs a judgement (input_mismatch) → runs by itself
+sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda  2026-09-25 11:10:59Z  step 4  edit    revision 1 → 2  "summary_table already carries its schema"
+    input logic changed; needs a judgement (input_mismatch) → runs by itself
+```
+
+The newest entry is first. Each id is printed in full, because it is what `undo --edit` takes.
+
+Take back the newest edit:
+
+```bash
+bir scenario undo scn_4a17a126-…
+```
+
+```
+Step 3 (mcp__postgres__execute_sql) — checked against run_67afb010-…
+  input    back as it was before that edit
+  mark     runs by itself → needs a judgement (input_mismatch)
+Step 3 is back as it was before sedit_02cb1210-1938-4902-9395-5a82b321276d (revision 4). Redo: bir scenario undo scn_4a17a126-… --edit sedit_1bcba735-a526-4a1c-a890-261addf2d82b
+  One further back: bir scenario undo scn_4a17a126-…
+```
+
+The same command again goes one further back:
+
+```bash
+bir scenario undo scn_4a17a126-…
+```
+
+```
+Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
+  input    back as it was before that edit
+  mark     runs by itself → needs a judgement (input_mismatch)
+Step 4 is back as it was before sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda (revision 5). Redo: bir scenario undo scn_4a17a126-… --edit sedit_8d3da392-1d96-4b2e-8c5d-34f8ab668b53
+  One further back: bir scenario undo scn_4a17a126-…
+```
+
+Now the history shows the two undos, and both edits as undone:
+
+```bash
+bir scenario edits scn_4a17a126-…
+```
+
+```
+sedit_8d3da392-1d96-4b2e-8c5d-34f8ab668b53  2026-09-25 11:11:00Z  step 4  revert  revision 4 → 5
+    undoes sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda; input logic changed; runs by itself → needs a judgement (input_mismatch)
+sedit_1bcba735-a526-4a1c-a890-261addf2d82b  2026-09-25 11:11:00Z  step 3  revert  revision 3 → 4
+    undoes sedit_02cb1210-1938-4902-9395-5a82b321276d; input logic changed; runs by itself → needs a judgement (input_mismatch)
+sedit_02cb1210-1938-4902-9395-5a82b321276d  2026-09-25 11:10:59Z  step 3  edit    revision 2 → 3  "use the settings, not the recorded names"
+    input logic changed; needs a judgement (input_mismatch) → runs by itself; undone 2026-09-25 11:11:00Z
+sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda  2026-09-25 11:10:59Z  step 4  edit    revision 1 → 2  "summary_table already carries its schema"
+    input logic changed; needs a judgement (input_mismatch) → runs by itself; undone 2026-09-25 11:11:00Z
+```
+
+Step 4 is the calculation's code again: `bir scenario show scn_4a17a126-… --step 4` now prints
+`"chainRevision": 5`, `"editedAt": null` and the mark `"nondeterministicWhy": "input_mismatch"`.
+
+How undo works:
+
+- **Undo walks back.** `bir scenario undo <id>` takes back the newest edit that can be undone. Its
+  step goes back as it was before that edit: its code and its mark. Run it again to go one further
+  back. Keep going, and each step gets back to the calculation's code, unless an undo is refused
+  (below).
+- **`--step <n>` limits it to one step.** `bir scenario undo scn_… --step 4` takes back step 4's
+  newest edit, and nothing else.
+- `--edit <sedit_id>` takes back that one entry.
+- An undo is a new line in the history (`revert`). **To redo, undo the undo** by its id. The undo
+  prints that command after `Redo:`.
+- **An undo is checked too:** for the later steps and for the final answer, like a save (so only
+  when the undo changes the step's output logic). The step itself is not judged: it goes back
+  exactly as it was. If the undo would break a later step or the answer, it is refused
+  (`undo_refused`). `bir` prints `Not undone:` with the reason, then
+  `To undo it anyway, on purpose: add --force --note "why".` An undo forced past a refusal is
+  recorded as forced.
+- Once every hand edit of a plan is taken back, the service repairs and rebuilds it as usual again.
+  An undo forced past a refusal is the exception: it leaves its step counted as edited and
+  forced, so `bir investigate` keeps warning about it.
+
+#### What a save changes
+
+- **The next prompt uses the new code.** The service hands out the plan fresh on every prompt. A
+  turn that is already running keeps the old plan until it ends.
+- **The revision goes up by one, and the step's failure count is cleared.** Reports from turns that
+  started before the change do not count against the new code. An undo does the same.
+- **A saved step runs unattended, exactly like calculated code** (§5.1), on this machine, in the
+  recorder's own process with a time limit and no sandbox. The service's sandbox does not protect
+  this machine. Read your change as carefully as you read a calculated plan, and dry-replay it
+  (§3.1).
+- **Edits are protected.** A recalculation rebuilds every step from the recording, and would throw
+  your fix away. So `calc --force` refuses:
+
+```bash
+bir scenario calc run_67afb010-… --force
+```
+
+```
+Not recalculated: steps 3, 4 were edited by hand, and a recalculation rebuilds every step.
+  To recalculate anyway and discard the edits: bir scenario calc run_67afb010-… --force --discard-edits
+  (the edits stay in `bir scenario edits`, marked replaced)
+```
+
+A `run_` id reaches only the run's whole-run scenario. `bir scenario calc <scnId> --force`
+recalculates any scenario in place, by its own id, a sub-task scenario included. Add
+`--discard-edits` when it has hand edits. A `scn_` id without `--force` is refused before anything
+is sent: a scenario that exists can only be recalculated.
+
+The console's *Recalculate* button (on a sub-task's scenario) is refused too while a plan has hand
+edits; the console does not discard them. The service's own rebuilds — the repair of a parked step
+(§9) and the adoption of a sub-task — skip a plan with hand edits. `bir investigate` says that the
+service does not rebuild the plan on its own, and warns when it skipped a repair
+(`repair_skipped_edits`). After `--discard-edits` the old edits stay readable, but they cannot be
+undone (`edit_replaced`).
+
+#### What `bir investigate` says
+
+It reports every edited step, and names the command that takes it back. After both steps were
+saved, its service findings began like this:
+
+```
+Service findings
+  1. [info] Step 3 (mcp__postgres__execute_sql) was edited by hand on 2026-09-25; the chain is at revision 3.
+     why:  Its code or its mark was changed by hand rather than by the calculation, and the change was checked against the recording before it was saved. The service does not rebuild a plan with hand edits on its own.
+     fix:  To see it: `bir scenario edits scn_4a17a126-…`; to take it back: `bir scenario undo scn_4a17a126-… --step 3`. A recalculation will not replace it unless you pass --discard-edits.
+  2. [info] Step 4 (mcp__postgres__execute_sql) was edited by hand on 2026-09-25; the chain is at revision 3.
+     why:  Its code or its mark was changed by hand rather than by the calculation, and the change was checked against the recording before it was saved. The service does not rebuild a plan with hand edits on its own.
+     fix:  To see it: `bir scenario edits scn_4a17a126-…`; to take it back: `bir scenario undo scn_4a17a126-… --step 4`. A recalculation will not replace it unless you pass --discard-edits.
+```
+
+A forced edit is a `warn`, not an `info`. So is a repair the service skipped because of hand edits.
+
+#### Let Claude do it
+
+Claude Code can do all of this for you, in two ways. Both use the same service routes and the same
+check.
+
+1. **In its terminal.** Claude runs `bir scenario …` like any other command. You see each command,
+   and Claude Code asks you before it runs one, unless you allowed it. This works in every project.
+2. **As tools on the `bir` MCP server** — the server `bir setup` or `bir install --replay` adds
+   (§5.2). This is smoother for the model. **By default the server lists only `run_scenario`:
+   every tool definition rides along with every request of every session. The tools that read and
+   change a scenario come when you turn editing on, per project:**
+
+```bash
+bir scenario editing on       # this project's `bir` server also offers the tools that read and change a scenario
+bir scenario editing off      # back to run_scenario alone
+bir scenario editing status   # what is stored for this project
+```
+
+`BIR_SCENARIO_TOOLS=read` in the `bir` server's environment (its entry's `env`, or the shell that
+starts `claude`) lists the reading tools without turning editing on. A reading tool answers when it
+is called unlisted, too.
+
+The tools, as the `bir` server defines them. **Bold** arguments are required.
+
+| Tool (`mcp__bir__…`) | Offered | Arguments | Runs |
+|---|---|---|---|
+| `run_scenario` | always, unless the runner is off | none | the plan armed for this turn (§6.1) |
+| `scenario_show` | after `bir scenario editing on`, or with `BIR_SCENARIO_TOOLS=read` | **`target`**, `step` | `bir scenario show` |
+| `scenario_edits` | after `bir scenario editing on`, or with `BIR_SCENARIO_TOOLS=read` | **`target`** | `bir scenario edits` |
+| `investigate` | after `bir scenario editing on`, or with `BIR_SCENARIO_TOOLS=read` | `id` — a `run_`, `scn_` or `sexec_` id; without it, the newest turn here | `bir investigate` |
+| `scenario_check` | after `bir scenario editing on` | **`target`**, **`step`**, `inputLogic`, `outputLogic`, `unfreeze` | `bir scenario check` |
+| `scenario_edit` | after `bir scenario editing on` | **`target`**, **`step`**, `inputLogic`, `outputLogic`, `freeze`, `unfreeze`, `force`, `note`, `revision` | `bir scenario edit` |
+| `scenario_undo` | after `bir scenario editing on` | **`target`**, `edit` or `step` (not both), `force`, `note` | `bir scenario undo` |
+
+- `target` is a `scn_` id, or the `run_` id of a whole-run scenario. `step` is the `stepIndex`.
+- `inputLogic` and `outputLogic` are the code itself, as text. The server writes them to temporary
+  files for `bir`, and removes the files afterwards.
+- `revision` is the `chainRevision` at the top of `scenario_show` with `step`.
+- `force` needs `note`, as on the command line.
+- Each tool runs this package's own `bir` with `--json`. A refusal comes back as an error result
+  that carries the check's report, so the model can read why.
+- A reading tool's answer is cut at 24 000 characters (`BIR_SCENARIO_MAX_OUTPUT_CHARS`), with a
+  hint to ask for one step at a time, and it gives up after `BIR_READ_TIMEOUT_MS` (15 s) plus 10 s.
+  A tool that changes a scenario gets 120 s.
+- When the session ends, or you press Esc during a call, that call's `bir` is stopped and its
+  temporary files are removed. A request the service had already received may still finish there;
+  `bir scenario edits` shows it.
+- While the runner is off (`bir off`), the server lists no tools; a reading tool called anyway says
+  there is nothing to read, and a changing one is refused.
+
+Why changing is off by default: the `bir` server runs in every session of every project it is
+installed in, a fleet included. A plan must not change because some agent there decided to change
+it. The switch is kept in `~/.baseinstrunner/installed.json`, next to the replay switches. It only
+decides which tools the `bir` server offers; the `bir scenario` commands work everywhere. The server
+reads the switch when Claude Code lists its tools, and again on every call. **Restart the Claude
+Code session after you switch it** — a running session does not see the change.
+
+**`bir`'s own calls are never recorded.** A session that fixes a plan must not become a plan that
+edits plans when it is replayed. So these calls are never recorded as steps, and never count as the
+model leaving a plan: the `bir` server's tools other than `run_scenario`, and a `Bash` or
+`PowerShell` command made only of `bir` commands (a plain `cd` may come with them).
+`npm test && bir investigate` is still recorded: the `npm test` half is real work. So is writing
+the code file, which is an ordinary step. Under `BIR_VERBOSE=1` a skipped call shows as
+`tool.pre.skipped … why="host housekeeping"`.
+
+**Do this.** In the Claude Code session, in the project folder, paste:
+
+```
+Run `bir investigate` in this folder. If a step needs a judgement or its code
+is wrong, read it with `bir scenario show`, write the corrected code to a file,
+and test it with `bir scenario check`. Show me the check and explain it in plain
+words. Do not save anything until I say yes. Then save it with
+`bir scenario edit` and a --note that says why. Never use --force.
+```
+
+For the hiring-year case, Claude's report would be: *step 4's code is a copy of the recorded query,
+so it was marked; the new code builds the query from `summary_table`; the check says it reproduces
+the recording, and the step will run by itself.*
+
+#### When it does not work
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `input differs from the recorded call at character N` | The code gives a different call from the recorded one | Read the `computed` and `recorded` lines, fix the code, check again |
+| `input is a copy` | The code returns the recorded call whatever the request says — usually a pasted value | Build the call from `parameters.…` or `respParams.…` |
+| `input throws` | The code crashed; the message is shown | Fix it. `require`, `process`, `fetch`, `Buffer`, timers, `ArrayBuffer`, the typed arrays and `Symbol.for` do not exist in the check |
+| `… did not finish in N ms`, `… ran out of memory (the limit is N MB)`, or `… stopped the logic sandbox before it finished` | The code went past the sandbox's time or memory limit (`LOGIC_TIMEOUT_MS`, `LOGIC_MEMORY_MB` on the service), or stopped the sandbox twice. That same code is then refused at once for 10 minutes | Fix the loop or the size. Changed code is new code, and is checked again |
+| A `later` step no longer reproduces | The change broke a step after it — usually output logic that stopped keeping a value a later step reads | Keep every key the later steps read |
+| `too costly to check` | The check used up its 5 seconds of sandbox time (`EDIT_CHECK_BUDGET_MS`). Usually code that reads or keeps a great many values, so the check has to run it very many times | Make the code cheaper to run, then check again |
+| `Nothing to change: the step already has this code and this mark.` | The code and the mark you gave are what the step already has (`nothing_to_change`) | Nothing to do. `check` says `Nothing would change` for the same case |
+| `not_a_tool_step` | The index is a sub-task call row, not a tool step | Call rows cannot be edited; the service writes them |
+| `note_required` | `--force` without `--note` | Add `--note "why"` |
+| `revision_changed` | The plan changed since you read it: another edit, or a recalculation | `show` it again, check again, save again |
+| `not_ready` or `scenario_calculating` | The scenario is not `ready`, or a recalculation is running | Wait for it to finish |
+| `undo_refused` | The undo would stop a later step from giving its recorded call, or leave the final answer without its values | Fix that later step first. Or undo it on purpose: `--force --note "why"` |
+| `not_latest_edit` | The step has changed since the edit you named: a newer entry changed it | `bir` prints two commands: undo the newer one first, then yours |
+| `already_undone` | That edit was undone already | To redo it, undo the undo. `bir` prints the command |
+| `edit_replaced` | A recalculation replaced the plan after that edit | Nothing to undo; the edit is history now |
+| `logic_sandbox_unavailable` | The service could not run step code just now (HTTP 503). Nothing was checked, saved or undone | Try again in a minute |
+| `invalid_input` | The service found the request invalid; `bir` prints its details. For example, a logic body longer than 20 000 characters, or a note longer than 500 | Shorten it |
+| `payload_too_large` | The whole request is larger than the service accepts (HTTP 413, over 256 kB) | A logic body may be at most 20 000 characters, and a note 500 |
+| `rate_limited` | More checks, edits and undos in a minute than the service allows (`SCENARIO_EDITS_PER_MINUTE`, 30 by default) | Wait a minute |
+| `not found` for a scenario you can see | It is not yours. **Only the owner can change a scenario** — an admin gets `not found` too | Ask the owner |
+| The `scenario_check`, `scenario_edit` and `scenario_undo` tools are missing | `bir scenario editing on` was not run in this project, or the session started before it | Run it here, then restart the session |
+| Only `run_scenario` is listed; `scenario_show`, `scenario_edits` and `investigate` are missing | That is the default: the reading tools come with `bir scenario editing on`, or with `BIR_SCENARIO_TOOLS=read` in the server's environment | Either one, then restart the session. Or run the `bir scenario …` commands in the terminal |
+| The `bir` server lists no tools at all | The runner is off here (`bir off`, `bir off --here`, or `BIR_OFF=1` where Claude Code started) | `bir on` (or `bir on --here`), and the server tells the open session its list changed. For `BIR_OFF=1`, start Claude Code without it |
+
+---
+
+## 10. What is built
+
+All of it. Phases R0–R7 of [calculatedReplay.md](calculatedReplay.md) §17 are implemented and
+tested; everything this guide describes is code you can run. §9.2 is built and tested too, but not
+yet released.
+
+| Phase | What landed | Where |
+|---|---|---|
+| **R0** | Plan, logic shims, coverage, bundle | [src/replay/](../src/replay/) — `plan.ts`, `logic.ts`, `coverage.ts`, `bundle.ts` |
+| **R1** | Derivation over raw `fetch`; pricing | [derive.ts](../src/replay/derive.ts), [pricing.ts](../src/replay/pricing.ts) |
+| **R2** | Gate ladder, mode choice, arming, directive | [controller.ts](../src/replay/controller.ts), [control/server.ts](../src/control/server.ts) |
+| **R3** | Pin, thread, retire | `onToolPre` / `onToolPost` / `onProxyStep` in [control/server.ts](../src/control/server.ts) |
+| **R4** | Long-poll work queue; direct execution | [executor.ts](../src/replay/executor.ts), [proxy/session.ts](../src/proxy/session.ts) |
+| **R5** | The `bir` MCP server, `/scenario/run`, `--replay` | [bin/bir-scenario.ts](../src/bin/bir-scenario.ts), [bin/bir.ts](../src/bin/bir.ts) |
+| **R6** | Divergence, source-run fallback, `bir replay` | `diverge()` in [controller.ts](../src/replay/controller.ts), [source-run.ts](../src/replay/source-run.ts) |
+| **R7** | Usage watermark, reporting, ticket, doctor | [control/transcript.ts](../src/control/transcript.ts), [remote-recorder.ts](../src/record/remote-recorder.ts) |
+| **§9.2** *(not yet released)* | `bir scenario show/check/edit/edits/undo/calc/editing`, the `bir` server's scenario tools, `bir` calls never recorded (`editSteps.md` D13) | [bin/scenario-edit.ts](../src/bin/scenario-edit.ts), [bin/bir-scenario.ts](../src/bin/bir-scenario.ts), [record/housekeeping.ts](../src/record/housekeeping.ts); tests: [scenario-edit.test.ts](../test/scenario-edit.test.ts), [bir-scenario.test.ts](../test/bir-scenario.test.ts), [housekeeping.test.ts](../test/housekeeping.test.ts), [replay-server.test.ts](../test/replay-server.test.ts) |
+
+```bash
+npm test                                                # ~1,000 tests, incl. test/replay.test.ts and test/replay-server.test.ts
+npm run build && npm run pretest && npm run test:smoke  # the smoke test needs the test build too
+```
+
+The smoke test is the one worth running after any change to the seams. It starts a stand-in BaseIn
+service, a real `bir-hooks`, a real `bir-proxy` wrapping a real MCP server, and a real `bir-scenario`,
+then drives a two-step scenario end to end through actual stdio — proving that a pinned argument
+reaches the real tool, that step 1's input was computed from step 0's real output, and that the turn
+books `steered_full` with `fallbackCostUsd: 0`.
+
+Three things the implementation settled that the design left open:
+
+- **`SerializedScenarioStep.recordedOutput` really is never sent.** Recorded outputs come from a lazy
+  `GET /recordings/runs/:runId` ([source-run.ts](../src/replay/source-run.ts)), as design §8.1
+  anticipated — fetched only when `BIR_REPLAY_RECORDED_OUTPUTS=1` lets one stand in, or in
+  `bir replay`. By default a step with no result stops the plan and hands over.
+- **The work queue must hold work for a proxy that is mid-round-trip.** Failing fast when no poller is
+  *parked* lost every step after the first in a multi-step direct plan, because the proxy is between
+  polls exactly then. It now fails fast only for a server no proxy has served in the last minute —
+  and, with two sessions open, never runs a step on a proxy that may be the other session's.
+- **The proxies need no replay configuration.** Every bound proxy runs its work loop; while replay
+  is off the control server answers `{ replay: false }` and the proxy polls every 30 s. So
+  `BIR_REPLAY` is a single switch on the control server, and replay turned on with
+  `bir up --restart` reaches open sessions within about 30 s.
+
+---
+
+## 11. Turning it off
+
+From least to most.
+
+```bash
+bir replay off          # stop arming. Matches still detected; recording still stops on a match.
+                        # Stored for this project; `bir up --restart` applies it, `bir replay on` undoes it
+export BIR_REPLAY=0     # the same, wherever the recorder is started from (the SessionStart hook
+                        # gives it Claude Code's environment, not your terminal's)
+bir off --here          # the whole runner, this project, at once: hooks answer nothing, the `bir`
+                        # server lists no tools, nothing is recorded or replayed. `bir off` does it
+                        # for every project. Nothing is uninstalled; `bir on [--here]` undoes it
+bir uninstall --replay  # remove the `bir` MCP server and switch replay off; proxies and hooks stay
+bir uninstall           # remove everything here: wrapped servers, hooks, the `bir` server; stop the recorder
+bir uninstall --all     # the same in every project on this machine
+```
+
+`bir uninstall` restores a project file (`.mcp.json`, `.claude/settings.local.json`) byte-for-byte
+when nothing else edited it since the install, and repairs it entry by entry otherwise.
+`~/.claude.json`, where the wrapped servers and the `bir` server live, is always repaired entry by
+entry. A file the install created — usually `.claude/settings.local.json` — stays behind with our
+entries removed, and the line that hid it in `.git/info/exclude` goes with them. A recorder that an
+open session is still using is left running, switched off for this project: restart that session,
+then `bir down` (`--keep-recorder` leaves the recorder alone). When something here still runs
+through the runner, `bir uninstall` says *Not everything could be undone*, lists it, and exits 1.
+
+Before you remove the package (`npm rm -g @basein/runner`, or deleting `~/.baseinstrunner`), run
+`bir uninstall --all`. The install line does the same, and nothing else, with `BIR_UNINSTALL=1`:
+
+```bash
+curl -fsSL https://api.bi2202.com/install.sh | BIR_UNINSTALL=1 sh                   # macOS / Linux
+```
+
+```powershell
+$env:BIR_UNINSTALL="1"; irm https://api.bi2202.com/install.ps1 | iex                # Windows (PowerShell)
+```
+
+Otherwise every other project's wrapped servers and hooks name files that are gone.
+
+With replay off the system is exactly v1 again: it recognises a repeated prompt, declines to
+record it a second time, and lets the model do the work.