@basein/runner 0.2.11 → 0.3.0

package/README.md

@@ -1,350 +1,540 @@
-# BaseInstRunnerMCP
-
-A recording MCP **proxy**. It sits between any MCP client (Claude Code, Cursor,
-Codex, an Agent SDK session) and every MCP server that client uses, executes each
-call on the client's behalf, and records the run as a reusable scenario in the
-BaseIn service.
-
-The design this implements is [docs/BaseInstRunner.md](docs/BaseInstRunner.md).
-This README is the operator's half: how to run it, what it records, and what it
-cannot. For v2 — running a calculated scenario when a prompt means the same thing
-as one you have run before — see [docs/calculatedReplay.md](docs/calculatedReplay.md)
-and its runbook [docs/calculatedReplayGuide.md](docs/calculatedReplayGuide.md).
-
-```
-model ──mcp__chrome-devtools__*──▶ bir-proxy ──stdio/http──▶ chrome-devtools-mcp
-hooks ──built-ins, prompt, stop──▶ bir-hooks (control server) ──▶ BaseIn /recordings/*
-                                        ▲
-                          bir-proxy ────┘  step reports
-```
-
----
-
-## Install
-
-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, so there is no sign-in step either:
-
-```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
-```
-
-That installs Node if the machine has none (a private copy, never on PATH),
-installs this package, installs Claude Code if it is missing, and runs
-`bir setup`: it signs in, stores the service address, wraps the project's MCP
-servers, wires Claude Code's hooks, adds the scenario server, and starts the
-recorder in the background. It ends with the one thing left to do: `claude`.
-Without a token the same line signs in through the browser. Re-running it is
-safe, and is also how you upgrade. To record another project: `cd` there and
-run `bir setup` (no token needed; the sign-in is kept).
-
-The scripts are [scripts/install.ps1](scripts/install.ps1) and
-[scripts/install.sh](scripts/install.sh); the API serves them with its own
-address filled in. Step by step, and what each line does:
-[docs/quickstart.md](docs/quickstart.md). For a fleet — packaging, releases,
-offline installs, updates: [docs/installRun.md](docs/installRun.md).
-
-By hand, or when developing BaseInstRunner itself:
-
-```bash
-npm i -g @basein/runner          # or: npm install && npm run build, in a checkout
-cd the-project-you-record-from
-bir setup --auth-url https://api.bi2202.com    # everything below, in one go
-```
-
-or the pieces `bir setup` is made of:
-
-```bash
-bir login                        # once; approve it in the browser (or --token <t> from the console)
-bir install --global --replay    # --local from a checkout; plain `bir install` writes a pinned npx entry
-bir up                           # the recorder, in the background; the SessionStart hook does this too
-claude                           # your session, now recorded
-```
-
-`bir install` rewrites your MCP entries in place, keeping every key (so
-`mcp__<server>__<tool>` names never change), and wires Claude Code's hooks into
-`.claude/settings.local.json` — your file, not the one a team commits; in a git
-repository it is added to `.git/info/exclude`. It stashes the original text of
-every file first — `bir uninstall` puts a file back byte-for-byte when nothing
-else has edited it since, and repairs it entry by entry when something has. A
-project remembers whether it was installed with `--global`, `--local` or the
-pinned-npx default, so a later `bir install` with no flag keeps that shape.
-
-**Nothing has to stay open.** The SessionStart hook is `bir-hooks ensure`: it
-starts the recorder for the project when none is running, in the background,
-with its audit log at `~/.baseinstrunner/logs/<project-key>.log`. `bir up`
-starts it by hand, `bir down` stops it, `bir status` shows it. Running
-`bir-hooks` in a terminal still works and is what the hook does for you.
-
-The service address is stored by `bir setup` and `bir login` in
-`~/.baseinstrunner/config.json`; `BIR_AUTH_URL` in the environment overrides
-it. A cached session is bound to the service that issued it and is never sent
-anywhere else.
-
-`bir login` prints a link and a short code and waits for you to approve it in
-the browser — the OAuth device grant, the same shape `gh auth login` uses. It
-never handles a password, so it works for accounts that only sign in with
-Google, and the link can be opened on any device, which is what makes it usable
-on a headless runner. `--no-browser` prints the link without opening one;
-`--token <value>` redeems a one-time setup token made on the console's *Set up
-the runner* page, with no browser step at all (service 2026-09 or newer);
-`--password` is the deprecated email-and-password prompt, removed next release.
-
-Check it:
-
-```bash
-bir status     # what is wrapped, and which config scope won
-bir doctor     # is it working *right now* — exits non-zero if not
-```
-
-### Any other MCP client
-
-Nothing here knows where Cursor or Codex keep their settings, and it does not
-guess. Two paths:
-
-```bash
-bir install --config /path/to/that/client/mcp.json
-bir wrap --server-name my-server -- node my-server.js    # prints an entry to paste
-```
-
----
-
-## The two tiers
-
-Only Claude Code has hooks, so run ownership is negotiated at proxy startup.
-
-| Tier | When | Records |
-|---|---|---|
-| **1 — Bound** | a control server (`bir-hooks`) is discoverable for this cwd | built-ins **and** MCP, one ordered step stream, prompt and final answer |
-| **2 — Standalone** | no control server within 5 s | MCP calls only — no prompt, no final answer, no built-in steps |
-
-Tier 2 is not a bug; it is the honest ceiling of what an MCP proxy can observe. A
-run records which tier produced it in `metadata.tier`, so nothing downstream
-mistakes a partial trace for a complete one.
-
-Steps taken while the tier is still being decided are **buffered**, not dropped —
-the host may spawn MCP servers before `SessionStart` fires, and the ordering
-between the two is not guaranteed.
-
----
-
-## What it will not do
-
-- **Non-MCP tools without the hook binary.** `Bash`, `Read`, `Edit` and friends
-  are not MCP traffic. An MCP server sees only MCP traffic addressed to it. That
-  is a structural fact, not a limitation of this implementation.
-- **`claude-in-chrome`.** It is `scope: "dynamic"`, present in no config file, so
-  there is no entry to rewrite.
-- **Replay, unless you install it.** Recording is the whole of what runs out of
-  the box. Calculated replay — running a matched prompt's scenario instead of
-  rediscovering it — ships, but needs `bir install --replay`. Once installed it
-  is on by default; `BIR_REPLAY=0` turns it off, for the reason in the next
-  section.
-- **Change what the model does.** Tool descriptions are never edited. The
-  model-visible changes are schema relaxation, below, and — only with
-  `--replay` — the first-party `bir` server's tools: `run_scenario`, and three
-  that only read a scenario. The three that change one appear only after
-  `bir scenario editing on` in that project.
-
----
-
-## Calculated replay
-
-When the service recognises that a prompt means the same thing as one you have
-run before, it hands back the *calculated scenario* derived from that earlier
-run: an intent, a parameter schema, and one bit of logic per step that recomputes
-that step's arguments. `bir` can run it instead of letting the model rediscover
-the plan token by token.
-
-The design is [docs/calculatedReplay.md](docs/calculatedReplay.md); the runbook —
-record, calculate, check, enable, read the audit lines — is
-[docs/calculatedReplayGuide.md](docs/calculatedReplayGuide.md).
-
-```bash
-bir install --replay      # adds the `bir` MCP server, pre-approved in .claude/settings.local.json
-bir up                    # or let the SessionStart hook start the recorder; replay is on by default
-bir replay allow fleet    # the servers replay may call unattended — stored for this project
-bir replay off            # and back on with `bir replay on`; `bir replay status` shows it
-```
-
-`bir setup` does the first two. The switches are kept per project in
-`~/.baseinstrunner/installed.json`, so a recorder the hook starts — with Claude
-Code's environment, not your terminal's — keeps them; `BIR_REPLAY`,
-`BIR_REPLAY_ALLOW_SERVERS` and `BIR_MIN_STEER_SIMILARITY` in the environment
-still override them, and `bir doctor` says which source is in effect.
-
-Two switches, not one, because of what replay is: **a scenario is a pre-approved
-list of tool calls with computed arguments.** A steered step is answered
-`permissionDecision: "allow"`, so a pinned `Bash` or `Edit` runs without the
-prompt you would have seen. A *directly executed* step never reaches the
-permission system at all — it is dispatched to a `bir-proxy` and called on a
-connection that is already open. Set `BIR_REPLAY_ALLOW_SERVERS` to the servers
-you are content to have called unattended, and read
-[the guide's §5.1](docs/calculatedReplayGuide.md) before enabling it anywhere
-that matters.
-
-What it buys: on a scenario whose every step is a wrapped MCP tool, the whole
-sequence runs through connections the proxies already hold — **zero model tokens**
-— and the model's only job is one tool call that reads the results. Mixed
-scenarios steer the live session instead, pinning each step's arguments. Either
-way the turn reports what it cost, so the savings ledger measures something real.
-
-**Fixing a step.** A calculated step is code, and code can be wrong.
-`bir investigate` names such a step; `bir scenario edit` fixes it, and the
-service checks the change against the recording before it saves it. **A change
-is saved only if it reproduces the recording — or on purpose, with
-`--force --note "why"`.** Only the owner can change a scenario. Claude can do it
-too: in its terminal, or with the `bir` server's tools once
-`bir scenario editing on` was run in the project. Built 2026-09-25, not yet
-released: it needs the next `@basein/runner` version and a service deploy. Step
-by step: [the guide's §9.2](docs/calculatedReplayGuide.md).
-
-```bash
-bir scenario show  scn_… --step 3                          # read one step
-bir scenario check scn_… --step 3 --input-logic step3.js   # try a change; nothing is saved
-bir scenario edit  scn_… --step 3 --input-logic step3.js --note "why"   # the same check, then save
-bir scenario edits scn_…                                   # the history
-bir scenario undo  scn_…                                   # undo the newest edit
-bir scenario editing on                                    # let Claude's `bir` tools change scenarios here
-```
-
----
-
-## Two things to know before you turn it on
-
-**1. Correlation auto-approves wrapped MCP calls.** Merging the hook's view of a
-call with the proxy's requires carrying an id through the tool's arguments, and
-the mechanism for that is answering `PreToolUse` with
-`permissionDecision: "allow"`. That skips a permission prompt you might otherwise
-have seen for those tools. To keep the prompt:
-
-```bash
-BIR_CORRELATION_DECISION=ask bir-hooks
-```
-
-Hosts that ignore `updatedInput` on a non-allow decision then fall back to
-fingerprint matching, which is lossy under identical concurrent calls.
-
-**2. Schema relaxation is visible to the model.** Carrying that id means adding
-`additionalProperties: true` plus one declared key to each wrapped tool's schema,
-on every call — not only recorded ones. It is applied **only** in Tier 1 with
-correlation active, and **only** to wrapped servers. `--no-correlation` turns it
-off entirely and joins on `(server, tool, hash(args))` inside a 30 s window
-instead.
-
----
-
-## Configuration
-
-| Variable | Effect |
-|---|---|
-| `BIR_AUTH_URL` | BaseIn auth-service — the **API** address (normally `https://api.<your-domain>`), not the docs or app website. Overrides the address `bir setup` / `bir login` stored in `~/.baseinstrunner/config.json`. **Neither set means nothing is recorded** — everything else still works. |
-| `BIR_SETUP_TOKEN` | A one-time setup token from the console, read by `bir setup` when `--token` is not given; the install scripts pass it this way. Never inherited by the recorder. |
-| `BIR_AUTH_DISABLE=1` | Skip authentication (local dev / CI). |
-| `BIR_CONTROL_PORT` | Preferred control-server port (default 53411). |
-| `BIR_CONTROL_URL` / `BIR_CONTROL_TOKEN` | Point a proxy at a control server directly, bypassing discovery. Injected into generated config; the only reliable channel for an SDK session. |
-| `BIR_CORRELATION_DECISION` | `allow` (default) or `ask` — see above. |
-| `BIR_NO_CORRELATION=1` | Never inject a call id. |
-| `BIR_HOME` | Where state lives (default `~/.baseinstrunner`). |
-| `BIR_CLAUDE_JSON` | Override the `~/.claude.json` location. |
-| `BIR_VERBOSE=1` | Per-message detail lines on stderr. |
-
-Calculated replay adds these, all read by `bir-hooks` only — the proxies are told
-what to do when they register, so there is one switch and no second copy of it:
-
-| Variable | Effect |
-|---|---|
-| `BIR_REPLAY=0` | Disable replay. It is on by default; nothing below matters while this is `0`. |
-| `BIR_REPLAY_ALLOW_SERVERS` | Server keys eligible for **direct** execution. Unset means the list `bir replay allow` stored for the project, else every wrapped server; narrowing it is the recommendation. |
-| `BIR_MIN_STEER_SIMILARITY` | Minimum match similarity to replay (default `0.92`, above the service's own `0.9` detection threshold). |
-| `ANTHROPIC_API_KEY` | **Optional.** Working out what a new request is about — which fleet, which file, which date — is done for you by the service on its own key, as long as you are signed in. Set this only to keep that reading on your machine, on your key. Signed out *and* unset, a scenario whose values change between requests is declined rather than replayed on stale ones. |
-| `BIR_DERIVE_MODEL` | Derivation model, when you set a key of your own (default `claude-haiku-4-5-20251001`). |
-| `BIR_MATCH_BUDGET_MS` | How long the prompt hook waits for a match (default `2500`). |
-| `BIR_DERIVE_BUDGET_MS` | How long the first `PreToolUse` waits for parameters (default `8000`). |
-| `BIR_REPLAY_BUDGET_MS` / `BIR_STEP_TIMEOUT_MS` | Whole-plan and per-step ceilings for direct execution (default `120000` / `60000`). |
-
-### The audit log
-
-Every decision is one `key=value` line on **stderr** — never stdout, which is the
-host's JSON-RPC stream. A recorder started in the background (by `bir up`, `bir
-setup` or the SessionStart hook) writes them to
-`~/.baseinstrunner/logs/<project-key>.log` — `bir status` names the file. One
-started in a terminal writes them to that terminal, and persistence is the
-shell's job:
-
-```bash
-bir-hooks 2>&1 | tee -a ~/.baseinstrunner/audit.log
-grep run.lossy ~/.baseinstrunner/audit.log
-```
-
----
-
-## Failure behaviour
-
-The governing rule: **a host session never fails because of BaseInstRunner.**
-
-| Failure | Behaviour |
-|---|---|
-| No recorder running at session start | the SessionStart hook starts one in the background; a session is never blocked or failed by it |
-| Control server unreachable at startup | buffer ≤ 5 s, then Tier 2; logged once |
-| Control server dies mid-session | the proxy switches to Tier 2 for the rest; run flagged lossy |
-| Recorder HTTP fails | send dropped and logged; never retried inline |
-| Upstream fails to start | `initialize` still answers; requests return an error — one broken server, not a broken session |
-| Upstream dies mid-call | `isError: true` with the transport message, so the model can react |
-| Unknown JSON-RPC method | forwarded; any rejection is relayed back |
-| Step queue overflow | oldest dropped, run flagged lossy |
-| Host sends unparseable input | `-32700` and the relay keeps going |
-
----
-
-## Development
-
-```bash
-npm run build       # src → dist
-npm test            # ~400 tests: transcript identity, passthrough, correlation, config, replay, setup
-npm run typecheck
-npm run test:smoke  # end-to-end replay with real processes (needs build + pretest first)
-```
-
-The core test is **transcript identity**: the same scripted conversation is run
-against a fake upstream directly and through the proxy, and every host-visible
-message must match. If a change breaks transparency, that test says so first.
-
-`test/smoke-replay.mjs` is the other one worth running by hand. Everything else
-runs in-process; this starts a stand-in BaseIn service, a real `bir-hooks`, a real
-`bir-proxy` wrapping a real MCP server and a real `bir-scenario`, then drives a
-two-step scenario through actual stdio. It is what catches the seams between
-processes — and it is how the "a proxy between polls is not a missing proxy" bug
-was found.
-
-`test/fake-upstream.ts` is a scriptable MCP server — arbitrary capabilities,
-prompts, resources, `list_changed` notifications, reverse-direction
-`elicitation/create`, delays, failures, and dying on command. Everything else
-builds on it.
-
----
-
-## Known gaps
-
-- **`metadata.lossy` is the value known at run start.** A run that turns lossy
-  later says so on the audit log (`run.lossy`) and in the step gap, but the
-  metadata is not updated: the service exposes no metadata patch, and this is
-  exactly open question 1 in the design. Fixing it properly needs a server-side
-  decision, not a client-side workaround.
-- **Subagent steps are attributed, not partitioned.** `SubagentStart` /
-  `SubagentStop` give us `agent_id`, which is prefixed onto a step's `context`.
-  A real agent column is a schema change, and out of scope for v1 (D6).
-- **`--lazy` defers to the first host message, not to `tools/list`.** Deferring
-  further would mean answering `initialize` before the upstream exists — that is,
-  fabricating its capabilities, which is the thing Phase 3 exists to prevent. For
-  a client that connects at session start (Claude Code does) the flag saves
-  nothing; for one that connects on demand it saves the whole process. See
-  `src/upstream/lazy-client.ts`.
-- **Coexistence with RRepeat is untested.** Both would record the same session.
-  Runs carry `metadata.recorder`, so server-side dedupe is possible, but nothing
-  here detects the other (design §13, open question 2).
+# BaseInstRunnerMCP
+
+A recording MCP **proxy**. It sits between any MCP client (Claude Code, Cursor,
+Codex, an Agent SDK session) and every MCP server that client uses, executes each
+call on the client's behalf, and records the run as a reusable scenario in the
+BaseIn service.
+
+The design this implements is [docs/BaseInstRunner.md](docs/BaseInstRunner.md).
+This README is the operator's half: how to run it, what it records, and what it
+cannot. For v2 — running a calculated scenario when a prompt means the same thing
+as one you have run before — see [docs/calculatedReplay.md](docs/calculatedReplay.md)
+and its runbook [docs/calculatedReplayGuide.md](docs/calculatedReplayGuide.md).
+The production contract, the full environment-variable reference and the
+operations runbook are in [production.md](production.md).
+
+```
+model ──mcp__chrome-devtools__*──▶ bir-proxy ──stdio/http──▶ chrome-devtools-mcp
+hooks ──built-ins, prompt, stop──▶ bir-hooks (control server) ──▶ BaseIn /recordings/*
+                                        ▲
+                          bir-proxy ────┘  step reports
+```
+
+---
+
+## Install
+
+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, so there is no sign-in step either:
+
+```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
+```
+
+That installs Node if the machine has none (a private copy, never on PATH),
+installs this package, installs Claude Code if it is missing, and runs
+`bir setup`: it signs in, stores the service address, wraps the project's MCP
+servers, wires Claude Code's hooks, adds the scenario server, and starts the
+recorder in the background. It ends with the one thing left to do: `claude`.
+Without a token the same line signs in through the browser. Re-running it is
+safe, and is also how you upgrade. To record another project: `cd` there and
+run `bir setup` (no token needed; the sign-in is kept).
+
+The scripts are [scripts/install.ps1](scripts/install.ps1) and
+[scripts/install.sh](scripts/install.sh); the API serves them with its own
+address filled in. Step by step, and what each line does:
+[docs/quickstart.md](docs/quickstart.md). For a fleet — packaging, releases,
+offline installs, updates: [docs/installRun.md](docs/installRun.md).
+
+By hand, or when developing BaseInstRunner itself:
+
+```bash
+npm i -g @basein/runner          # or: npm install && npm run build, in a checkout
+cd the-project-you-record-from
+bir setup --auth-url https://api.bi2202.com    # everything below, in one go
+```
+
+or the pieces `bir setup` is made of:
+
+```bash
+bir login                        # once; approve it in the browser (or --token <t> from the console)
+bir install --replay             # absolute paths to this package; --npx for pinned npx, --local from a checkout
+bir up                           # the recorder, in the background; the SessionStart hook does this too
+claude                           # your session, now recorded
+```
+
+`bir install` leaves your shared MCP configuration as it is. Each server it wraps gets
+a wrapped copy in this project's *local scope* — in `~/.claude.json`
+(`$CLAUDE_CONFIG_DIR/.claude.json` when that is set), under the key Claude Code
+uses for the project — which takes precedence over the `.mcp.json` or
+user-scope entry of the same name, so `mcp__<server>__<tool>` names never
+change (a server defined in the local scope itself is wrapped where it is).
+`.mcp.json`, the file a team commits, and your user scope are never
+written; wraps an older install made there are put back. `--mcp-json` (or
+`BIR_WRAP_MCP_JSON=1`) is that old in-place shape, for a `.mcp.json` nobody
+commits. The hooks go into `.claude/settings.local.json` — your file, not the
+one a team commits; in a git repository it is added to `.git/info/exclude`.
+Uninstall repairs `~/.claude.json` (and a `--config` file) entry by entry;
+`settings.local.json` it puts back byte-for-byte when nothing else has edited
+it since, and repairs entry by entry when something has. A project remembers
+whether it was installed with `--global` (absolute paths, the default for an
+installed `bir`), `--local` or `--npx`, so a later `bir install` with no flag
+keeps that shape.
+
+Some servers are left as Claude Code runs them. Their calls are still recorded
+by the hooks, and `bir setup` says why for each:
+
+- a `.mcp.json` server Claude Code has not approved yet: approve it in Claude
+  Code, then run `bir setup` again (`bir install --server <name>` wraps it now,
+  and it then starts without Claude Code's question). A rejected one is never
+  wrapped.
+- a remote server Claude Code signs in itself (see
+  [What it will not do](#what-it-will-not-do)).
+- every server, under a managed policy that matches servers by command or URL,
+  or allows only the organisation's own servers.
+- every server, in a subdirectory or linked worktree of a repository: Claude
+  Code keeps the local scope per repository, so run `bir setup` in its root.
+  Linked worktrees then run the root's wrapped servers too.
+
+A local copy remembers the entry it was made from. When that entry changes,
+`bir status` marks the server STALE and `bir doctor` reports it; `bir setup`
+copies it again.
+
+**Nothing has to stay open.** The SessionStart hook is `bir-hooks ensure`, for
+every install shape (an `--npx` one runs it through npx): it starts the recorder
+for the project when none is running, in the background, with its audit log at
+`~/.baseinstrunner/logs/<project-key>.log`, and never holds a session start
+longer than about 11.5 s. `bir up` starts it by hand, `bir down` stops it,
+`bir status` shows it. Running `bir-hooks` in a terminal still works and is what
+the hook does for you. A recorder that dies mid-session is started again by that
+session's proxies or `bir` server. `bir down` stops only the recorder, which
+then stays down until the next session start, `bir up` or `bir setup`; the
+hooks stay installed, so a session open there shows a "hook error" on each
+prompt and tool call until it ends. To take the runner out of the way instead:
+`bir off` ([When something goes wrong](#when-something-goes-wrong)).
+
+The service address is stored by `bir setup` and `bir login` in
+`~/.baseinstrunner/config.json`; `BIR_AUTH_URL` in the environment overrides
+it. A cached session is bound to the service that issued it and is never sent
+anywhere else.
+
+`bir login` prints a link and a short code and waits for you to approve it in
+the browser — the OAuth device grant, the same shape `gh auth login` uses. It
+never handles a password, so it works for accounts that only sign in with
+Google, and the link can be opened on any device, which is what makes it usable
+on a headless runner. `--no-browser` prints the link without opening one;
+`--token <value>` redeems a one-time setup token made on the console's *Set up
+the runner* page, with no browser step at all (service 2026-09 or newer);
+`--password` is the deprecated email-and-password prompt, removed next release.
+The link is opened only when it is `https` (`http` only for an `http` service),
+and on Windows without `cmd.exe`. `bir logout` removes this machine's session
+first, then asks the service that issued it to revoke it (best effort, at most
+8 s); running recorders stop sending within seconds, and start again by
+themselves after the next `bir login`.
+
+Check it:
+
+```bash
+bir status     # what is wrapped, which config scope won, whether the runner is on
+bir doctor     # is it working *right now* — exits 1 only for what breaks a session here
+```
+
+`bir doctor` sorts what it finds into problems — a server, hook or recorder a
+Claude Code session here would fail on: exit 1 — and warnings, which sessions
+work through (not recording, a proxy not registered yet, the service
+unreachable): exit 0, or 1 with `--strict`. `--quick` does not call the service.
+`bir status` also shows the recorder's view of the service, the off switch, a
+port the recorder could not take, a STALE local copy, and the other projects set
+up on this machine.
+
+### Any other MCP client
+
+Nothing here knows where Cursor or Codex keep their settings, and it does not
+guess. Two paths:
+
+```bash
+bir install --config /path/to/that/client/mcp.json
+bir wrap --server-name my-server -- node my-server.js    # prints an entry to paste
+```
+
+### Taking it out
+
+```bash
+bir uninstall          # this project: its wrapped copies, hooks and scenario server; stops its recorder
+bir uninstall --all    # every project on this machine — run it before removing the package
+```
+
+`bir uninstall` touches only this project, and names the other projects still
+set up. It stops the project's recorder or, while a session is still using it,
+leaves it running switched off for this project: restart that session, then
+`bir down` (`--keep-recorder` leaves the recorder alone). While anything here
+still runs through the runner it exits 1 with `Not everything could be undone`
+and a list; fix what it names and run it again. `--server <name>` takes out only
+that server, and `--replay` only the scenario server, switching replay off.
+
+Remove the package (`npm rm -g @basein/runner`, or delete `~/.baseinstrunner`,
+where the install line's copy lives) only after `bir uninstall --all` has
+finished cleanly: otherwise every other project's wrapped servers and hooks name
+files that are gone. (`bir logout` first revokes this machine's sign-in, which
+deleting `~/.baseinstrunner` alone does not.) With `BIR_UNINSTALL=1` the install line runs
+`bir uninstall --all` for you, downloading nothing; deleting the files is left
+to you:
+
+```powershell
+$env:BIR_UNINSTALL="1"; irm https://api.bi2202.com/install.ps1 | iex              # Windows (PowerShell)
+```
+
+```bash
+curl -fsSL https://api.bi2202.com/install.sh | BIR_UNINSTALL=1 sh                 # macOS / Linux
+```
+
+Going back to an older runner (`BIR_VERSION=0.2.12`, or
+`npm i -g @basein/runner@0.2.12`) needs `bir uninstall --all` first, run with
+the current one.
+
+---
+
+## The two tiers
+
+Only Claude Code has hooks, so run ownership is negotiated at proxy startup.
+
+| Tier | When | Records |
+|---|---|---|
+| **1 — Bound** | a control server (`bir-hooks`) is discoverable for this cwd | built-ins **and** MCP, one ordered step stream, prompt and final answer |
+| **2 — Standalone** | no control server within 10 s | MCP calls only — no prompt, no final answer, no built-in steps |
+| **Passthrough** | as Tier 2, but for a user-scope entry an older install wrapped, started in a directory that was never set up and has no recorder | nothing — it only relays |
+
+Tier 2 is not a bug; it is the honest ceiling of what an MCP proxy can observe. A
+run records which tier produced it in `metadata.tier`, so nothing downstream
+mistakes a partial trace for a complete one. A proxy that is not bound keeps
+looking every 15 s and binds to a recorder that starts late or was restarted; it
+records at most one standalone run of its own.
+
+Steps taken while the tier is still being decided are **buffered**, not dropped —
+the host may spawn MCP servers before `SessionStart` fires, and the ordering
+between the two is not guaranteed.
+
+---
+
+## What it will not do
+
+- **Non-MCP tools without the hook binary.** `Bash`, `Read`, `Edit` and friends
+  are not MCP traffic. An MCP server sees only MCP traffic addressed to it. That
+  is a structural fact, not a limitation of this implementation.
+- **`claude-in-chrome`.** It is `scope: "dynamic"`, present in no config file, so
+  there is no entry to rewrite.
+- **Wrap a remote server Claude Code signs in itself.** An `oauth` block, a
+  `headersHelper`, `${VAR}` headers or no credential header means Claude Code
+  holds the credentials, and a proxy would get none (the server would answer
+  `upstream requires sign-in`). Such a server is left unwrapped, its calls
+  recorded by the hooks, unless `bir install --server <name>` asks for it,
+  which is remembered. A static credential header travels in the wrapped
+  entry's env (`BIR_UPSTREAM_HEADERS`), not on its command line.
+- **Approve your MCP calls.** Outside a matched replay, and unless you opt back
+  in, Claude Code asks about a wrapped MCP call exactly as it would unwrapped.
+  0.2.12 approved them all; see [below](#two-things-to-know-before-you-turn-it-on).
+- **Replay, unless you install it.** A first plain `bir install` records and nothing
+  else. Calculated replay — running a matched prompt's scenario instead of
+  rediscovering it — ships, but needs `bir install --replay`, which `bir setup`
+  runs unless given `--no-replay`. Once installed it is on; `bir replay off` or
+  `BIR_REPLAY=0` turns it off, for the reason in the next section.
+- **Change what the model does.** Tool descriptions are never edited. The
+  model-visible changes are one declared schema key (below), the first-party
+  `bir` server's `run_scenario` (only with `--replay`), and replay's own
+  `[BaseInstRunner calculated replay]` notes when a prompt matches a scenario.
+  The `bir` server's three tools that only read a scenario (`scenario_show`,
+  `scenario_edits`, `investigate`) are listed only after `bir scenario editing on`,
+  or with `BIR_SCENARIO_TOOLS=read` in its environment: their definitions ride
+  along with every request. The three for changing one (`scenario_check`,
+  `scenario_edit`, `scenario_undo`) appear only after `bir scenario editing on`
+  in that project (not yet released, see below). With the runner off it lists
+  no tools at all.
+- **Record its own `bir` calls** (next version, not yet released). A session
+  that fixes a plan is not a task to replay. The `bir` server's tools other
+  than `run_scenario`, and a `Bash` or `PowerShell` command made only of `bir`
+  commands, are never recorded as steps and never count as leaving a plan.
+  `npm test && bir investigate` is still recorded: `npm test` is real work.
+- **Sandbox scenario code on this machine.** A calculated or hand-edited step
+  runs here, in the recorder's own process and context (Node's `vm`, not a
+  sandbox), next to your sign-in and your wrapped servers. It has a time limit
+  (`BIR_LOGIC_TIMEOUT_MS`, 1 s by default) and no memory limit.
+  The service will sandbox its own runs of the same code (with its next deploy);
+  the runner does not. The service's check of a hand edit only judges what the
+  code returns for the recording's values, so it cannot prove what the code
+  does here: read a hand edit before it is saved. See
+  [the design's §13.1](docs/calculatedReplay.md).
+
+---
+
+## Calculated replay
+
+When the service recognises that a prompt means the same thing as one you have
+run before, it hands back the *calculated scenario* derived from that earlier
+run: an intent, a parameter schema, and one bit of logic per step that recomputes
+that step's arguments. `bir` can run it instead of letting the model rediscover
+the plan token by token.
+
+The design is [docs/calculatedReplay.md](docs/calculatedReplay.md); the runbook —
+record, calculate, check, enable, read the audit lines — is
+[docs/calculatedReplayGuide.md](docs/calculatedReplayGuide.md).
+
+```bash
+bir install --replay      # adds the `bir` MCP server (local scope: Claude Code does not ask about it), replay on
+bir up                    # or let the SessionStart hook start the recorder
+bir replay allow fleet    # the servers replay may call unattended — stored for this project
+bir replay off            # and back on with `bir replay on`; `bir replay status` shows it
+```
+
+`bir setup` does the first two; `bir setup --no-replay` stores replay off, and so
+does a plain `bir install` where replay was never set up. `bir install --replay`
+never turns back on a `bir replay off` of yours. The switches are kept per
+project in `~/.baseinstrunner/installed.json`, so a recorder the hook starts — with Claude
+Code's environment, not your terminal's — keeps them. A recorder reads them when
+it starts: `bir up --restart` applies a change. `BIR_REPLAY`,
+`BIR_REPLAY_ALLOW_SERVERS` and `BIR_MIN_STEER_SIMILARITY` in the environment
+still override them, and `bir doctor` says which source is in effect.
+
+Two switches, not one, because of what replay is: **a scenario is a pre-approved
+list of tool calls with computed arguments.** A steered step is answered
+`permissionDecision: "allow"`, so a pinned `Bash` or `Edit` runs without the
+prompt you would have seen — only a call that plausibly is the step, though (the
+same command, the same file, the same kind of arguments); any other call runs as
+written and is asked about as usual. A *directly executed* step never reaches the
+permission system at all — it is dispatched to a `bir-proxy` and called on a
+connection that is already open — and `run_scenario`, the call that starts the
+run, is answered `allow` while the recorder has announced the plan. In plan mode
+nothing is announced and nothing is approved. Set `BIR_REPLAY_ALLOW_SERVERS` to
+the servers you are content to have called unattended (it also covers a steered
+plan's recovery), and read [the guide's §5.1](docs/calculatedReplayGuide.md)
+before enabling it anywhere that matters.
+
+What it buys: on a scenario whose every step is a wrapped MCP tool, the whole
+sequence runs through connections the proxies already hold — **zero model tokens**
+— and the model's only job is one tool call that reads the results. Such a plan
+is announced only while a `bir` server has told the recorder it is connected,
+and runs only through `run_scenario`: if the model calls anything else first,
+the plan is retired and nothing runs. Mixed scenarios steer the live session
+instead, pinning each step's arguments. Either way the turn reports what it
+cost, so the savings ledger measures something real.
+
+**Fixing a step.** Built 2026-09-25, not yet released: it needs the next
+`@basein/runner` version and a service deploy. A calculated step is code, and
+code can be wrong. `bir investigate` names such a step; `bir scenario edit`
+fixes it, and the service checks the 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"`.** Only the owner can change
+a scenario. `bir scenario undo` takes changes back one at a time: run it again
+to go one further back. An undo is checked too, and is refused if it would
+break a later step or the final answer, unless you add `--force --note "why"`.
+Claude can do all of this: in its terminal, or with the `bir` server's tools
+once `bir scenario editing on` was run in the project. Step by step, with real
+output:
+[the guide's §9.2](docs/calculatedReplayGuide.md).
+
+```bash
+bir scenario show  scn_… --step 3                          # read one step (scenarioId and chainRevision first)
+bir scenario check scn_… --step 3 --input-logic step3.js   # try a change; nothing is saved
+bir scenario edit  scn_… --step 3 --input-logic step3.js --note "why"   # the same check, then save
+bir scenario edits scn_…                                   # the history, newest first
+bir scenario undo  scn_…                                   # take back the newest edit; again to go further back
+bir scenario undo  scn_… --step 3                          # take back step 3's newest edit only
+bir scenario calc  scn_… --force --discard-edits           # recalculate this plan, dropping its hand edits
+bir scenario editing on                                    # let Claude's `bir` tools change scenarios here
+```
+
+---
+
+## Two things to know before you turn it on
+
+**1. Wrapped MCP calls are not auto-approved.** Merging the hook's view of a
+call with the proxy's is exact only when an id rides through the tool's
+arguments, and the mechanism for that is answering `PreToolUse` with
+`permissionDecision: "allow"` — which skips the permission prompt. So by default
+the recorder answers an ordinary wrapped MCP call with no decision: Claude Code
+asks exactly as it would without the runner, and the two views are joined on
+`(server, tool, hash(args))` instead, which is lossy only under identical
+concurrent calls. By default an id is carried only where that changes nothing
+you are asked: a `bypassPermissions` session, and a replay-pinned step. Never in
+plan mode, and never into a server whose proxy is not running.
+
+0.2.12 answered every wrapped call `allow`. Under `claude -p` in a workspace
+whose `permissions.allow` is not read, those calls are now denied: allow them
+with `permissions.allow` in a trusted workspace or `--allowedTools`, or opt back
+in to auto-approval where the recorder starts — the shell you restart it from,
+and the environment Claude Code starts in, since its SessionStart hook starts
+the next one:
+
+```bash
+BIR_CORRELATION_DECISION=allow bir up --restart
+```
+
+`BIR_CORRELATION_DECISION=ask` carries the id and keeps the prompt. Hosts that
+ignore `updatedInput` on a non-allow decision then fall back to fingerprint
+matching.
+
+**2. One schema key is visible to the model.** Carrying that id needs a place in
+the tool's arguments, so while a recorder may inject one — a bound proxy, or one
+still looking for its recorder in a project set up for it — every wrapped tool's
+input schema declares one more property, `__bir_call_id__`
+(`"Reserved. Leave unset."`), on every `tools/list`, whether or not an id is
+ever sent. `additionalProperties` is left as the server declared it, and the id
+is stripped before the server sees a call. Nothing is declared with
+`--standalone` or while the runner is off. `--no-correlation` turns it off
+entirely; steps then always join on `(server, tool, hash(args))`.
+
+---
+
+## Configuration
+
+| Variable | Effect |
+|---|---|
+| `BIR_AUTH_URL` | BaseIn auth-service — the **API** address (normally `https://api.<your-domain>`), not the docs or app website. Overrides the address `bir setup` / `bir login` stored in `~/.baseinstrunner/config.json`. **Neither set means nothing is recorded** — everything else still works. |
+| `BIR_SETUP_TOKEN` | A one-time setup token from the console, read by `bir setup` when `--token` is not given; the install scripts pass it this way. Never inherited by the recorder. |
+| `BIR_AUTH_DISABLE=1` | Skip authentication (local dev / CI). |
+| `BIR_OFF=1` | The kill switch for one Claude Code window: set in the environment Claude Code starts in, that window's hooks answer nothing, its wrapped servers run as plain pipes and its `bir` server lists no tools; other windows keep recording. `bir off` switches off the whole machine, `bir off --here` one project. |
+| `BIR_CONTROL_PORT` | The recorder's control-server port. Default: the project's own, which `bir install` picks from 53411 up so no two projects share one. `0` is any free port (tests; installed hooks name a fixed one); a value that is not a port is ignored. |
+| `BIR_CONTROL_URL` / `BIR_CONTROL_TOKEN` | Together, point a proxy (and the `bir` server) at a control server directly, bypassing discovery — the only reliable channel for an SDK session. Generated entries carry `BIR_CONTROL_URL` alone, which marks them hooks-wired; they bind to their directory's recorder through its discovery file. |
+| `BIR_CORRELATION_DECISION` | Unset (default: no decision; fingerprint join), `allow` (every wrapped MCP call auto-approved, as 0.2.12 did) or `ask` — see above. Read by the recorder. |
+| `BIR_NO_CORRELATION=1` | Never inject a call id. |
+| `BIR_WRAP_MCP_JSON=1` | Same as `--mcp-json`: wrap `.mcp.json` servers in place. |
+| `BIR_HOME` | Where state lives (default `~/.baseinstrunner`). |
+| `BIR_CLAUDE_JSON` | Override the `~/.claude.json` location. Unset, it is `$CLAUDE_CONFIG_DIR/.claude.json` when `CLAUDE_CONFIG_DIR` is set, as in Claude Code. |
+| `BIR_VERBOSE=1` | Detail lines on stderr: per message, plus the routine start-up, binding and stream lines that are otherwise left out. |
+
+Calculated replay adds these, all read by `bir-hooks` only — the proxies are told
+what to do when they register, so there is one switch and no second copy of it:
+
+| Variable | Effect |
+|---|---|
+| `BIR_REPLAY` | `0` turns replay off and any other value on, over the project's stored switch (`bir replay on` / `off`; a first plain `bir install` stores off). Nothing below matters while it is off. |
+| `BIR_REPLAY_ALLOW_SERVERS` | Server keys bir may call unattended: **direct** execution, and a steered plan's recovery. Unset means the list `bir replay allow` stored for the project, else every wrapped server; narrowing it is the recommendation. |
+| `BIR_MIN_STEER_SIMILARITY` | Minimum match similarity to replay (default `0.92`, above the service's own `0.9` detection threshold). |
+| `BIR_DERIVE_API_KEY` | **Optional.** Working out what a new request is about — which fleet, which file, which date — is done for you by the service on its own key, as long as you are signed in. Set this (an Anthropic key) only to keep that reading on your machine, on your key. Signed out *and* unset, a scenario whose values change between requests is declined rather than replayed on stale ones. |
+| `ANTHROPIC_API_KEY` | Not used by the background recorder, which has Claude Code's environment and would bill your own key — unless `BIR_USE_ANTHROPIC_API_KEY=1`. A `bir-hooks` run by hand in a terminal uses that terminal's key. |
+| `BIR_DERIVE_MODEL` | Derivation model, when you set a key of your own (default `claude-haiku-4-5-20251001`). |
+| `BIR_MATCH_BUDGET_MS` | How long the prompt hook waits for a match (default `1500`). After a match slower than `BIR_MATCH_SLOW_MS` (default `800`), or one that timed out, prompts stop waiting for 5 min, doubling up to 30 min; a fast match ends that. |
+| `BIR_DERIVE_BUDGET_MS` / `BIR_HOOK_DERIVE_BUDGET_MS` | How long a direct run, and a hook, waits for parameters (default `8000` / `4000`; a hook waits the smaller). |
+| `BIR_PRETOOL_REPLAY_BUDGET_MS` | Everything replay does inside one `PreToolUse` (default `9000`, at most `10000`). |
+| `BIR_REPLAY_BUDGET_MS` / `BIR_STEP_TIMEOUT_MS` | Whole-plan and per-step ceilings for direct execution (default `100000` / `60000`; `BIR_REPLAY_PLAN_BUDGET_MS` also sets the first). A direct run's parameter wait plus its plan are held under 270 s. |
+| `BIR_LOGIC_TIMEOUT_MS` | How long one scenario logic body may run before it is stopped and the plan hands over (default `1000`, at most `10000`). |
+| `BIR_REPLAY_RECORDED_OUTPUTS=1` | Let a step's recorded output stand in when the step could not be sent. Unset, the plan stops at that step and hands the task back. |
+
+The `bir` server reads its own: `BIR_SCENARIO_TOOLS=read` lists its three reading
+tools without `bir scenario editing on`, and `BIR_SCENARIO_RUN_TIMEOUT_MS` is how
+long `run_scenario` waits for a run (default `290000`). Everything else — remote
+upstreams, the recorder's backlog, service timeouts, the `bir` server's output
+caps — is in [production.md](production.md).
+
+### The audit log
+
+Every decision is one `key=value` line on **stderr** — never stdout, which is the
+host's JSON-RPC stream. A recorder started in the background (by `bir up`, `bir
+setup` or the SessionStart hook) writes them to
+`~/.baseinstrunner/logs/<project-key>.log` — `bir status` names the file. One
+started in a terminal writes them to that terminal, and persistence is the
+shell's job:
+
+```bash
+bir-hooks 2>&1 | tee -a ~/.baseinstrunner/audit.log
+grep run.lossy ~/.baseinstrunner/audit.log
+```
+
+---
+
+## Failure behaviour
+
+The governing rule: **a host session never fails because of BaseInstRunner.**
+
+| Failure | Behaviour |
+|---|---|
+| No recorder running at session start | the SessionStart hook starts one in the background; it always exits 0 and never holds the start longer than about 11.5 s |
+| Control server unreachable at startup | steps buffered ≤ 10 s, then Tier 2 (passthrough: nothing); the proxy keeps looking every 15 s and binds when one answers |
+| Control server dies mid-session | the proxy records to a Tier 2 run of its own (flagged lossy), starts the recorder again in the background (not after `bir down`), and binds to it once it answers |
+| A hook the recorder cannot answer in time | every route has a hard deadline (prompt 7 s, `PreToolUse` 12 s, the others 1–2 s) and answers `{}`; so does a hook with a stale token or a malformed body |
+| BaseIn service slow or down | hooks stop waiting on it after one failure (a cool-down of 5 s, doubling to 60 s); sends go on in the background, retried once only when they cannot have arrived (429, 503, a refused connection); past 500 queued sends or 32 MiB the oldest steps are dropped |
+| Upstream fails to start, or exits | calls in flight are answered (`MCP server "<name>" is not available`, `isError: true` for a `tools/call`), then `bir-proxy` exits with the server's own status, so Claude Code shows the server as failed, as it would unwrapped. `BIR_PROXY_STAY_UP=1` keeps the proxy up answering that instead |
+| Remote upstream unreachable or refusing | the request gets a short error (`upstream unreachable: …`, `upstream requires sign-in (HTTP 401)`), never the server's body; only connecting is bounded (10 s), never how long a tool runs |
+| Result over 128 MiB | the call ends with an error saying the result was too large to deliver, instead of hanging |
+| Unknown JSON-RPC method | forwarded; any rejection is relayed back |
+| Step queue overflow | oldest dropped, run flagged lossy |
+| Host sends unparseable input | `-32700` and the relay keeps going |
+
+---
+
+## When something goes wrong
+
+**`bir off` first.** It takes the runner out of the way at once, in every
+project, and uninstalls nothing: hooks answer with nothing within about a
+second, in sessions already open too, and nothing is recorded, replayed or sent;
+wrapped MCP servers run as plain pipes to the real server from their next start
+(a new session, or `/mcp` → reconnect), and keep recording until then; the `bir`
+server lists no tools. `bir off --here` does the same for one project (from a
+subdirectory, the installed project it is in), and `bir on` or `bir on --here`
+undoes it. If the problem goes away, the runner was the cause; if it stays, the
+runner is ruled out. A recorder older than the switch (0.2.12) ignores it:
+`bir off` replaces one no session is using and names any other, which
+`bir up --restart` replaces once its session ends. Not `bir down`: it leaves
+the hooks, and an open session then shows a hook error on every prompt and tool
+call.
+
+**Then `bir doctor`**, in the project: what breaks a session here (exit 1), what
+only keeps the runner from doing all of its job (warnings), and the fix for
+each. `bir status` names the recorder's log, where every decision is one line
+([The audit log](#the-audit-log)).
+
+**Then [production.md](production.md)**: the production contract, the full
+environment-variable reference, the operations runbook and the findings ledger.
+
+---
+
+## Development
+
+```bash
+npm run build       # src → dist
+npm test            # ~1,000 tests: transcript identity, passthrough, correlation, config, replay, setup
+npm run typecheck
+npm run test:smoke  # end-to-end replay with real processes (needs build + pretest first)
+```
+
+The core test is **transcript identity**: the same scripted conversation is run
+against a fake upstream directly and through the proxy, and every host-visible
+message must match. If a change breaks transparency, that test says so first.
+
+`test/smoke-replay.mjs` is the other one worth running by hand. Everything else
+runs in-process; this starts a stand-in BaseIn service, a real `bir-hooks`, a real
+`bir-proxy` wrapping a real MCP server and a real `bir-scenario`, then drives a
+two-step scenario through actual stdio. It is what catches the seams between
+processes — and it is how the "a proxy between polls is not a missing proxy" bug
+was found.
+
+`test/fake-upstream.ts` is a scriptable MCP server — arbitrary capabilities,
+prompts, resources, `list_changed` notifications, reverse-direction
+`elicitation/create`, delays, failures, and dying on command. Everything else
+builds on it.
+
+---
+
+## Known gaps
+
+- **`metadata.lossy` is the value known at run start.** A run that turns lossy
+  later says so on the audit log (`run.lossy`) and in the step gap, but the
+  metadata is not updated: the service exposes no metadata patch, and this is
+  exactly open question 1 in the design. Fixing it properly needs a server-side
+  decision, not a client-side workaround.
+- **Subagent steps are attributed, not partitioned.** `SubagentStart` /
+  `SubagentStop` give us `agent_id`, which is prefixed onto a step's `context`.
+  A real agent column is a schema change, and out of scope for v1 (D6).
+- **`--lazy` defers to the first host message, not to `tools/list`.** Deferring
+  further would mean answering `initialize` before the upstream exists — that is,
+  fabricating its capabilities, which is the thing Phase 3 exists to prevent. For
+  a client that connects at session start (Claude Code does) the flag saves
+  nothing; for one that connects on demand it saves the whole process. See
+  `src/upstream/lazy-client.ts`.
+- **Coexistence with RRepeat is untested.** Both would record the same session.
+  Runs carry `metadata.recorder`, so server-side dedupe is possible, but nothing
+  here detects the other (design §13, open question 2).