@basein/runner 0.2.7 → 0.2.10

package/dist/replay/tool-error.d.ts

@@ -20,4 +20,19 @@
  * not. `serialized` is the proxy's own serialization — the whole result, as JSON.
  */
 export declare function toolResultError(serialized: string): string | undefined;
+/**
+ * What a server says when a tool no longer exists — the one failure a grace
+ * period cannot cure (plan-services.md D8, kind 2).
+ *
+ * Read from the text, because the proxy keeps only a JSON-RPC error's message
+ * and servers word it differently: the TypeScript SDK answers `Tool X not
+ * found`, the Python SDK `Unknown tool: X`, a hand-rolled server whatever it
+ * likes. Kept narrow on purpose — `not available` is what a server says during
+ * an outage, and a repair in the middle of one is the wrong answer. A miss here
+ * costs only the wait; a false hit costs one recording and one calculation,
+ * which the service caps.
+ */
+export declare const MISSING_TOOL_PATTERN: RegExp;
+/** Whether an error text says the step's tool is gone from its server. */
+export declare function isMissingToolError(text: string | undefined): boolean;
 //# sourceMappingURL=tool-error.d.ts.map

package/dist/replay/tool-error.js

@@ -35,6 +35,23 @@ export function toolResultError(serialized) {
         return undefined;
     return clip(firstText(result.content) ?? "the tool reported an error");
 }
+/**
+ * What a server says when a tool no longer exists — the one failure a grace
+ * period cannot cure (plan-services.md D8, kind 2).
+ *
+ * Read from the text, because the proxy keeps only a JSON-RPC error's message
+ * and servers word it differently: the TypeScript SDK answers `Tool X not
+ * found`, the Python SDK `Unknown tool: X`, a hand-rolled server whatever it
+ * likes. Kept narrow on purpose — `not available` is what a server says during
+ * an outage, and a repair in the middle of one is the wrong answer. A miss here
+ * costs only the wait; a false hit costs one recording and one calculation,
+ * which the service caps.
+ */
+export const MISSING_TOOL_PATTERN = /\b(unknown|no such|unsupported|unrecognized) tool\b|\btool\s+['"`]?[\w.:-]+['"`]?\s+(was\s+)?(not found|does not exist|is not registered)\b/i;
+/** Whether an error text says the step's tool is gone from its server. */
+export function isMissingToolError(text) {
+    return typeof text === "string" && MISSING_TOOL_PATTERN.test(text);
+}
 function firstText(content) {
     if (!Array.isArray(content))
         return undefined;

package/dist/replay/types.d.ts

@@ -37,6 +37,25 @@ export interface InlinedSegment {
 }
 /** Why a call cannot run right now (segmented.md 9.9). */
 export type CallUnusable = "switched_off" | "not_ready" | "missing" | "stale" | "unresolved" | "depth" | "unsupported";
+/**
+ * A reason the plan stops in front of a step, as the service decided it
+ * (plan-services.md D8). The service knows the grace period, the retry clock
+ * and the calculation's own verdict on the step; the runner only reads it.
+ */
+export interface StepStop {
+    /**
+     * `parked`: the step has failed too often and its retry is not due, or its
+     * grace has ended. `nondeterministic`: the calculation could not write code
+     * that computes this step's input — a judgement — so the agent makes it.
+     */
+    kind: "parked" | "nondeterministic";
+    /** For `nondeterministic`: which check the step failed at calculation. */
+    why?: string;
+    /** For `parked` inside its grace: when the step may be tried again. */
+    retryAt?: string;
+    /** For `parked` past its grace, or whose tool is gone: a repair is due. */
+    repairDue?: boolean;
+}
 export interface SerializedScenarioStep {
     stepIndex: number;
     /**
@@ -60,6 +79,15 @@ export interface SerializedScenarioStep {
      * model in front of it. Absent from an older service, which means never park.
      */
     failureCount?: number;
+    /**
+     * Why the plan must stop in front of this step, decided by the service
+     * (plan-services.md D8). Present on every step — `null` when there is no
+     * reason — from a service that decides stops itself. A parked step whose
+     * retry is due arrives with `stop: null` and is tried. Absent altogether
+     * from an older service, where `failureCount` against
+     * `fallback.maxStepFailures` is the only rule.
+     */
+    stop?: StepStop | null;
     /**
      * The literal output recorded for this step.
      *
@@ -117,6 +145,13 @@ export declare function hasTargets(schema: ParamsSchema | null | undefined): boo
 export interface SerializedScenario {
     id: string;
     runId: string;
+    /**
+     * The run the current chain was calculated from, when it is not `runId`: a
+     * plan repaired from a fresh recording (plan-services.md W2.4). A recorded
+     * output that stands in for a step comes from this run. Absent from an older
+     * service, and from a plan that was never repaired.
+     */
+    sourceRunId?: string;
     state: string;
     intent: string;
     parameters: unknown;
@@ -159,7 +194,13 @@ export type FallbackKind =
  * gone, switched off, out of date, or nested too deep (segmented.md
  * R-CALL-29). Like a known-bad step it counts nothing against any step.
  */
- | "unusable_call";
+ | "unusable_call"
+/**
+ * The plan stopped in front of a step the calculation marked
+ * non-deterministic: its input needs a judgement no code computes
+ * (plan-services.md D8, kind 3). Never tried, counts nothing.
+ */
+ | "nondeterministic_step";
 /**
  * Upgrade order. `not_steered` is the floor — the control group, and the safe
  * answer if a turn dies mid-flight — and each later decision point can only move
@@ -205,6 +246,12 @@ export interface ExecutionStepResult {
     /** Message only — never a tool payload; this is rendered in a web page. */
     error?: string;
     durationMs?: number;
+    /**
+     * The step's tool no longer exists on its server, read from the error text
+     * (plan-services.md D8, kind 2). The service then repairs the plan without
+     * waiting out the grace period.
+     */
+    toolMissing?: boolean;
     /**
      * The scenario this step belongs to, when it ran inside a called segment: a
      * failure is counted where a repair would happen (segmented.md R-CALL-13).

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
-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
+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
 ```
 
 ---
@@ -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 '{}'
 ```
 
@@ -139,7 +164,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 +176,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 +205,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,24 +228,33 @@ 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 one tool, `mcp__bir__run_scenario` — the channel a fully-wrapped
+  scenario's results come back through;
+- 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
@@ -228,23 +267,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 +318,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 +339,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 +352,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 +393,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,17 +456,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 (the service's plan-services design, D8 kind 3 — it lives in the BaseIn repository, not this one) | 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` 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` |
 | `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` |
 
 ---
 
@@ -399,8 +479,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
@@ -444,8 +525,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
@@ -471,10 +552,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.