@basein/runner 0.2.8 → 0.2.10

package/dist/control/server.d.ts

@@ -53,6 +53,14 @@ export interface ControlServerOptions {
     cwd: string;
     /** Preferred port; 0 (or a busy port) falls back to an ephemeral one. */
     port?: number;
+    /**
+     * Whether a busy `port` may fall back to an ephemeral one. Default true — a
+     * recorder in a terminal is better on some port than not at all. A background
+     * recorder whose port is written into a project's hooks passes false: on a
+     * fallback port it would answer SessionStart and then every other hook would
+     * post into the void, which is worse than exiting with a reason.
+     */
+    portFallback?: boolean;
     /** Loopback bearer token. Generated when omitted. */
     token?: string;
     /** Config keys of the servers a proxy wraps. Grows as proxies register. */
@@ -90,6 +98,26 @@ export interface ControlServerOptions {
      * recording and nothing else happens.
      */
     replay?: ReplayOptions;
+    /**
+     * Where the replay switches came from — the environment, the project's
+     * stored policy, or the defaults. Reported on `/health` so `bir doctor` can
+     * say which, because "the allow-list I set is gone" has exactly one cause.
+     */
+    replaySource?: "env" | "sidecar" | "default";
+    /**
+     * Whose account the recordings land in, for `/health` and `bir doctor`. "The
+     * run is not in Recordings" is, more often than not, "it is in somebody
+     * else's", and nothing said which until now.
+     */
+    account?: string;
+    /**
+     * What 'POST /control/stop' does after answering. 'bir-hooks' passes its own
+     * shutdown; a test passes nothing and the route merely says it would. The
+     * route exists so a background recorder can be stopped the way Ctrl-C stops
+     * one in a terminal — finishing the run and draining the queue — rather than
+     * killed, which on Windows is the only other option.
+     */
+    onStopRequested?: () => void;
 }
 export interface ControlServerAddress {
     url: string;

package/dist/control/server.js

@@ -38,6 +38,7 @@ import { calculateCostUsd } from "../replay/pricing.js";
 import { logDetail, logLine, errText } from "../util/log.js";
 import { journal } from "../util/journal.js";
 import { packageVersion } from "../util/version.js";
+import { resolveAuthUrl } from "../auth/client.js";
 /** How long a `/tool/post` waits for the proxy's own report before recording its own view. */
 const PROXY_REPORT_GRACE_MS = 1_500;
 /** One MCP call, as seen from up to two sides. */
@@ -127,7 +128,7 @@ export class ControlServer {
                     resolve(this.address);
                 });
             };
-            bind(preferred, preferred !== 0);
+            bind(preferred, preferred !== 0 && this.opts.portFallback !== false);
         });
     }
     async close() {
@@ -150,6 +151,10 @@ export class ControlServer {
         const sessions = [...this.sessions.values()].map((s) => ({
             sessionId: s.sessionId,
             runId: s.run?.runId,
+            // Mid-run right now. What 'ensureDaemon' reads before it dares to restart
+            // an out-of-date recorder: a restart between turns costs nothing, one
+            // during a turn loses the turn.
+            active: Boolean(s.run) && !s.run.finished,
             steps: s.run?.ordering.next ?? 0,
             recording: s.run?.recording ?? false,
             replay: s.run?.replay
@@ -187,12 +192,13 @@ export class ControlServer {
             tier: "bound",
             // The authoritative answer to "is anything actually being saved?".
             recording: this.opts.recording ?? !(this.recorder instanceof NullRecorder),
+            account: this.opts.account ?? null,
             // Whether a handed-out segment may actually run mid-task, or whether the
             // runner is only watching (R-OUT-10, R-LIFE-8). Observe-only must never
             // be invisible: an operator has to be able to see which of the two this
             // machine is doing without reading a log file.
             segmentArm: this.replay.segmentArm,
-            authUrl: process.env.BIR_AUTH_URL ?? null,
+            authUrl: resolveAuthUrl() || null,
             sessionId: this.sessionId,
             pid: process.pid,
             cwd: this.opts.cwd,
@@ -210,6 +216,7 @@ export class ControlServer {
             // (docs/calculatedReplay.md §13.2, mitigation 3).
             replay: {
                 enabled: this.replay.enabled,
+                source: this.opts.replaySource ?? null,
                 minSimilarity: this.opts.replay?.minSimilarity ?? null,
                 allowServers: this.opts.replay?.allowServers ? [...this.opts.replay.allowServers] : null,
                 deriveKey: Boolean(this.opts.replay?.apiKey ?? process.env.ANTHROPIC_API_KEY),
@@ -248,6 +255,12 @@ export class ControlServer {
             }
             const body = await this.readJson(req);
             switch (route) {
+                case "/control/stop":
+                    // Answer first, then leave: the caller is polling for the pid to go.
+                    this.send(res, 200, { ok: Boolean(this.opts.onStopRequested) });
+                    if (this.opts.onStopRequested)
+                        setImmediate(() => this.opts.onStopRequested?.());
+                    return;
                 case "/session/start":
                     this.send(res, 200, this.onSessionStart(body));
                     return;

package/dist/proxy/session.d.ts

@@ -25,7 +25,14 @@ import type { UpstreamClient } from "../upstream/client.js";
 import type { ProxyStepReport } from "../control/correlation.js";
 import { type Recorder } from "../record/recorder.js";
 /** How long a proxy waits for a control server before falling to Tier 2. */
-export declare const DISCOVERY_WINDOW_MS = 5000;
+/**
+ * Ten seconds, not five: the recorder is now started by the SessionStart hook,
+ * which fires while the host is also spawning this proxy, and a cold start
+ * (sign-in refresh, the service's /health probe, then listen) has been
+ * measured at one to four seconds. Steps are buffered meanwhile, never
+ * dropped, and a host session is never waiting on this.
+ */
+export declare const DISCOVERY_WINDOW_MS = 10000;
 export type Tier = "bound" | "standalone" | "pending";
 export interface ProxySessionOptions {
     serverName: string;

package/dist/proxy/session.js

@@ -26,7 +26,7 @@ import { hostname } from "node:os";
 import { ControlClient } from "../control/client.js";
 import { resolveControl } from "../control/discovery.js";
 import { qualifyToolName } from "../control/correlation.js";
-import { authenticate } from "../auth/client.js";
+import { authenticate, resolveAuthUrl } from "../auth/client.js";
 import { NullRecorder } from "../record/recorder.js";
 import { RemoteRecorder } from "../record/remote-recorder.js";
 import { StepQueue } from "../record/queue.js";
@@ -36,7 +36,14 @@ import { redact } from "../record/redact.js";
 import { logLine, logDetail, errText } from "../util/log.js";
 import { packageVersion } from "../util/version.js";
 /** How long a proxy waits for a control server before falling to Tier 2. */
-export const DISCOVERY_WINDOW_MS = 5_000;
+/**
+ * Ten seconds, not five: the recorder is now started by the SessionStart hook,
+ * which fires while the host is also spawning this proxy, and a cold start
+ * (sign-in refresh, the service's /health probe, then listen) has been
+ * measured at one to four seconds. Steps are buffered meanwhile, never
+ * dropped, and a host session is never waiting on this.
+ */
+export const DISCOVERY_WINDOW_MS = 10_000;
 export class ProxySession {
     serverName;
     /** This proxy process, as the control server tells proxies apart (replay/executor.ts). */
@@ -98,6 +105,7 @@ export class ProxySession {
             return;
         }
         const window = this.opts.discoveryWindowMs ?? DISCOVERY_WINDOW_MS;
+        const deadline = Date.now() + window;
         const found = await resolveControl(this.opts.cwd, window);
         if (!found?.url) {
             await this.becomeStandalone(`no control server within ${window}ms`);
@@ -108,12 +116,24 @@ export class ProxySession {
             startedAt: this.startedAt,
             pid: process.pid,
         });
-        const registered = await client.register({
+        const info = {
             serverName: this.serverName,
             pid: process.pid,
             cwd: this.opts.cwd,
             version: packageVersion(),
-        });
+        };
+        // A control server that is still coming up — the SessionStart hook is
+        // starting it while the host spawns us — answers nothing for a moment.
+        // Keep trying inside the same window rather than settle for Tier 2 on the
+        // first refusal.
+        let registered = await client.register(info);
+        while (!registered && Date.now() < deadline) {
+            await new Promise((resolve) => {
+                const t = setTimeout(resolve, 250);
+                t.unref?.();
+            });
+            registered = await client.register(info);
+        }
         if (!registered) {
             await this.becomeStandalone("control server did not answer /proxy/register");
             return;
@@ -216,9 +236,11 @@ export class ProxySession {
         if (this.opts.recorderFactory) {
             return (await this.opts.recorderFactory()) ?? new NullRecorder();
         }
-        const baseUrl = (process.env.BIR_AUTH_URL ?? "").replace(/\/+$/, "");
+        // BIR_AUTH_URL, or the address 'bir setup' stored — the same lookup the
+        // control server and the CLI make, so no two processes disagree about it.
+        const baseUrl = resolveAuthUrl();
         if (!baseUrl) {
-            logLine("recorder.disabled", { why: "BIR_AUTH_URL is not set" });
+            logLine("recorder.disabled", { why: "no service address — run 'bir setup', or set BIR_AUTH_URL" });
             return new NullRecorder();
         }
         // A proxy runs inside the host's process tree with its stdio bound to the

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,19 +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 (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) | 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` |
 
 ---
 
@@ -401,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
@@ -446,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
@@ -473,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.