@basein/runner 0.2.8 → 0.2.11

package/docs/calculatedReplayGuide.md

@@ -4,8 +4,8 @@
 > 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). It is off by default and
-> it should stay off until you have read §5. Nothing in §1–§4 changes any behaviour.
+> **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.
 
 ---
 
@@ -29,23 +29,40 @@ end-to-end smoke test.
 
 | # | You need | Check it with |
 |---|---|---|
-| 1 | A BaseIn service you can reach | `curl -fsS "$BIR_AUTH_URL/health"` |
+| 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 `bir-hooks` running | `bir doctor` |
+| 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 `tier: standalone`, replay cannot arm, and that is the
-honest ceiling rather than a bug.
+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
-export BIR_AUTH_URL=https://your-basein-service
-npm install && npm run build
-node dist/bin/bir.js install        # or `bir install` once linked/published
-bir login                           # prints a link and a code; approve in the browser
-bir-hooks                           # leave running in its own terminal
+bir setup --auth-url https://api.bi2202.com    # without a token it signs in through the browser
 ```
 
 ---
@@ -81,12 +98,17 @@ bir scenario list                    # or: GET /recordings/runs
 ```
 
 ```
-RUN            ITER  STEPS  SCENARIO   STATE       TITLE
-run_5f3a…         3     14  scn_9c1b…  ready       Fleet risk sweep
-run_a812…         1      9  —          —           Rewrite the billing README
-run_c004…         1      6  scn_44d0…  calculating Check open PRs for stale reviews
+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
@@ -100,17 +122,20 @@ bir scenario calc run_5f3a…            # POST /recordings/runs/:runId/calculat
 bir scenario show run_5f3a…            # GET  /recordings/runs/:runId/scenario  (poll)
 ```
 
-Raw, if you prefer — the token lives in `~/.baseinstrunner/credentials.json`:
+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 "$BIR_AUTH_URL/recordings/runs/run_5f3a…/calculate" \
+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 "$env:BIR_AUTH_URL/recordings/runs/run_5f3a…/calculate" `
+Invoke-RestMethod -Method Post -Uri "$b/recordings/runs/run_5f3a…/calculate" `
   -Headers @{ authorization = "Bearer $t" } -ContentType 'application/json' -Body '{}'
 ```
 
@@ -123,7 +148,9 @@ Calculation is a background job. Poll `show` until `state` leaves `calculating`:
 | `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`.
+replay history — with `bir scenario calc run_… --force`. To change one step instead, without
+recalculating, see §9.2; a plan with steps edited by hand needs `--force --discard-edits` to be
+rebuilt.
 
 ### 3.1 Check the scenario before you trust it
 
@@ -139,7 +166,7 @@ bir scenario replay scn_9c1b… --prompt "which devices in the fleet look risky
 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[24]
+              → 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" }
@@ -151,8 +178,13 @@ 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? An empty `emitted` means
-   `toolOutputLogic` derived nothing, and every downstream input reading it will be wrong.
+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.
@@ -175,7 +207,7 @@ you:  can you check the eu-west fleet and tell me which boxes are in trouble?
 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 (the default), this is where it stops.** The server keeps its canonical run, bumps
+**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.
 
@@ -198,28 +230,39 @@ When replay arms:
 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. Set `BIR_REPLAY_ALLOW_SERVERS` (§5.3). An allowlist of the servers you are comfortable having
+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; raises the prompt-hook timeout
-unset BIR_REPLAY              # on by default; only BIR_REPLAY=0 turns it off
-bir-hooks                     # restart it
+bir install --replay          # adds the `bir` MCP server (pre-approved)
+bir up --restart              # the recorder reads the change when it restarts
 ```
 
-`bir install --replay` does exactly two things beyond a normal install, and `bir uninstall` reverses
-both:
+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 — and three tools that only read a scenario (`scenario_show`,
+  `scenario_edits`, `investigate`; §9.2, not yet released);
+- 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.
 
-- registers a first-party MCP server under the key **`bir`**, exposing one tool,
-  `mcp__bir__run_scenario` — the channel a fully-wrapped scenario's results come back through;
-- raises `UserPromptSubmit`'s hook timeout from 5 s to 15 s, so the match round trip fits.
+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` tool 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 `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:
 
@@ -228,23 +271,48 @@ bir doctor
 ```
 
 ```
-replay          ON      servers=chrome-devtools,fleet-api   minSimilarity=0.92
-                derive=the service (no key needed here)
-control         http://127.0.0.1:53411   sess=birsess_…
-wrapped         chrome-devtools ✓ proxy pid 41822   fleet-api ✓ proxy pid 41823
-recording       yes  (https://your-basein-service)
+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
 
-**Set these in one place: the terminal that runs `bir-hooks`.** 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.
+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` | *(all wrapped)* | Comma-separated server keys eligible for **direct** execution. **Set this** |
+| `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 |
@@ -254,10 +322,14 @@ there is exactly one switch and it cannot get out of step with itself.
 | `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.** Derivation is skipped and every
-parameter takes the value it had in the recorded run. For a scenario whose parameters rarely change
-— a dashboard sweep, a fixed report — that is a complete, free replay. For one that keys off the
-prompt ("check *eu-west*"), you want the key.
+**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`.
 
 ---
 
@@ -271,12 +343,12 @@ Ask the matching question again, with replay on.
 [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  params=2 costUsd=0.0011 ms=840
+[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 savedUsd=0.114
+[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.
@@ -284,31 +356,35 @@ 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 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
+[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
+[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
-`via=hook fallback=true` line means the proxy did not report in time and the hook's differently-shaped
-view was used instead — expect derived values to be empty, and treat repeats as a bug.
+`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  remaining=2 direct=1 recorded=1 skipped=0 bytes=8412 costUsd=0
-[bir] …  replay.done     outcome=diverged steps=4/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` on the compose line is the point of the whole design: the remaining steps ran through
+`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
@@ -321,13 +397,16 @@ Everything replay decides is one line. `grep` for these:
 | `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 |
+| `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 |
 
-Keep them: `bir-hooks 2>&1 | tee -a ~/.baseinstrunner/audit.log`.
+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`.
 
 ---
 
@@ -381,19 +460,22 @@ first prompt that states the task plainly.
 | 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=0` · scenario not `ready` · similarity below threshold · no step is executable |
+| `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` |
-| `replay.thread … emitted=` empty | `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 |
-| `via=hook fallback=true` 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 |
+| 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 |
-| `execution.reported … 409 invalid_ticket` | The ticket was already redeemed, or belongs to another scenario | Harmless if `duplicate: true`. Otherwise a rollover raced `SessionEnd`; the server books once |
+| `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 (plan-services.md D8, kind 3) | Nothing on the runner. The agent makes that choice and finishes the task; a model step for such judgements is planned (W3.1). The journal's `plan.armed` line lists it 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` names the kind (`step_retrying`, `step_parked … repair due`, `scenario_repairing`). To repair now by hand: `bir scenario calc <runId> --force` |
+| 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). 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`. 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. Fix the step (§9.2), or add `--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` |
 
 ---
 
@@ -401,8 +483,9 @@ first prompt that states the task plainly.
 
 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). `bir-hooks` prints its path at start. Ask the
-journal and the service together:
+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
@@ -427,6 +510,312 @@ fix*. The three questions it answers:
 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* the
+> service deploy that adds the `/scenarios/:id/steps/…` routes. The design is `editSteps.md` in the
+> BaseIn repository.
+
+`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>]
+bir scenario calc  <runId> [--force [--discard-edits]]
+bir scenario editing on|off|status
+```
+
+A `run_` id finds the run's scenario; a `scn_` id (what `bir investigate` prints) is used as it is.
+A sub-task scenario has only a `scn_` id. `--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` that
+`show` printed). `--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 |
+
+When the service runs it, only JavaScript itself is there: `JSON`, `Math`, `Date`, `RegExp` and the
+like. There is no `require`, `process`, `fetch` or timer, and code that uses one fails the check.
+
+**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 were marked *needs a judgement*. Their code
+wrote `schema + '.' + summary_table`, but the table name already carried its schema. Step 4 is shown
+here; step 3 is the same.
+
+**1. Read the step.**
+
+```bash
+bir scenario show scn_4a17a126-… --step 4
+```
+
+```
+{
+  "stepIndex": 4,
+  "toolName": "mcp__postgres__execute_sql",
+  "toolInputLogic": "return {\"sql\":\"SELECT * FROM employees.hiring_year_summary ORDER BY hire_year;\"};",
+  "nondeterministic": true,
+  "nondeterministicWhy": "input_mismatch",
+  "sampleInput": "{\"sql\":\"SELECT * FROM employees.hiring_year_summary ORDER BY hire_year;\"}",
+  …
+}
+```
+
+The stored input logic is a copy of the recorded call. 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    no later steps
+  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?
+- `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_7c1e… (revision 4). Undo: bir scenario undo scn_4a17a126-… --edit sedit_7c1e…
+```
+
+**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? Spaces inside strings 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 | the call never moves: the code returns the recorded call whatever the request says |
+| Do the later steps still give their calls? | a later step that gave its recorded call before does not any more |
+| Does the final answer still get its values? | it did before, and does not after |
+
+A recorded input of `{}` is never a copy. A recorded input that is plain text, not an object, is
+`not_checked`.
+
+A refused change says where it differs:
+
+```bash
+bir scenario edit 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 14
+           computed  …FROM employees.employees.hiring_year_summary ORDER…
+           recorded  …FROM employees.hiring_year_summary ORDER BY hire_…
+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 the same way:
+`input  is a copy: it returns the recorded call whatever the parameters say`.
+
+#### `--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: `note_required`.
+- A forced save removes the mark, unless you also pass `--freeze`.
+- It is saved as *forced*, and `bir investigate` keeps saying so, as a `warn`.
+- 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.
+  `bir scenario check … --unfreeze` asks the same question without saving.
+
+#### The history, and undo
+
+```bash
+bir scenario edits scn_4a17a126-…
+```
+
+```
+sedit_7c1e…  2026-09-25 09:12:04Z  step 4  edit    revision 3 → 4  "summary_table already carries its schema"
+             input logic changed; needs a judgement (input_mismatch) → runs by itself
+```
+
+```bash
+bir scenario undo scn_4a17a126-…
+```
+
+```
+Step 4 is back as it was before sedit_7c1e… (revision 5). Redo: bir scenario undo scn_4a17a126-… --edit sedit_9a02…
+```
+
+- `undo` puts **one step** back as it was before its newest edit: its code and its mark. Without
+  `--edit` it undoes the newest edit that can be undone.
+- The undo is a new line in the history. Undo the undo to redo.
+- Only the newest edit of a step can be undone. For an older one you get `not_latest_edit` and the
+  id of the newer edit: undo that one first.
+
+#### 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). 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)
+```
+
+The console's *Recalculate* is refused too. 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, and `bir investigate` says
+so. After `--discard-edits` the old edits stay readable, but they cannot be undone
+(`edit_replaced`).
+
+#### What `bir investigate` says
+
+It names the fix, and it reports edits. Here, after step 4 was saved and before step 3 was:
+
+```
+  1. [warn] Step 3 (mcp__postgres__execute_sql) needs a judgement, so runs hand over in front of it.
+     fix:  Recalculate once (`bir scenario calc run_… --force`) … Or fix it yourself: read it with
+           `bir scenario show scn_… --step 3`, write the input logic to a file, and run
+           `bir scenario edit scn_… --step 3 --input-logic <file>`; the service checks it against the recording.
+  2. [info] Step 4 (mcp__postgres__execute_sql) was edited by hand on 2026-09-25 (revision 4).
+     fix:  To see or undo it: `bir scenario edits scn_…`. A recalculation keeps 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
+```
+
+| Tool (`mcp__bir__…`) | Offered | Runs |
+|---|---|---|
+| `scenario_show` | always | `bir scenario show` |
+| `scenario_edits` | always | `bir scenario edits` |
+| `investigate` | always | `bir investigate` |
+| `scenario_check` | after `bir scenario editing on` | `bir scenario check` |
+| `scenario_edit` | after `bir scenario editing on` | `bir scenario edit` |
+| `scenario_undo` | after `bir scenario editing on` | `bir scenario undo` |
+
+Why it 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. **Restart the
+Claude Code session after you switch it** — a running session does not see the change.
+
+**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 was marked because its code added the
+schema twice; 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` and timers do not exist in the check |
+| 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 |
+| `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 |
+| `not_latest_edit` | A newer edit of the same step follows the one you named | Undo the newer one first; the answer names it |
+| `edit_replaced` | A recalculation replaced the plan after that edit | Nothing to undo; the edit is history now |
+| `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
@@ -446,8 +835,8 @@ tested; everything this guide describes is code you can run.
 | **R7** | Usage watermark, reporting, ticket, doctor | [control/transcript.ts](../src/control/transcript.ts), [remote-recorder.ts](../src/record/remote-recorder.ts) |
 
 ```bash
-npm test              # 195 tests, incl. test/replay.test.ts and test/replay-server.test.ts
-npm run build && node test/smoke-replay.mjs
+npm test                                                # ~400 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
@@ -473,10 +862,18 @@ Three things the implementation settled that the design left open:
 Three levels, least to most.
 
 ```bash
-export BIR_REPLAY=0     # stop arming. Matches still detected; recording still stops on a match
-bir uninstall --replay  # remove the `bir` MCP server, restore the prompt-hook timeout
-bir uninstall           # remove everything: proxies, hooks, files restored byte-for-byte
+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
 ```
 
-With `BIR_REPLAY=0` the system is exactly v1 again: it recognises a repeated prompt, declines to
+`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.