@basein/runner 0.2.12 → 0.3.1

package/docs/quickstart.md

@@ -1,311 +1,384 @@
-# Setting up a runner machine
-
-One person, one computer: from nothing to a project whose every Claude Code
-session is recorded and whose calculated scenarios run. It takes a few minutes,
-most of them downloads. Nothing has to stay open afterwards.
-
-**What you are setting up.** BaseInstRunner sits between Claude Code and the
-tools it uses, records each session to the BaseIn service, and — when a new
-prompt means the same thing as one it has seen — runs the calculated scenario
-instead of letting the model rediscover the plan. Otherwise it does not change
-what the model does.
-
----
-
-## Before you start
-
-A BaseIn account. That is all: Node and Claude Code are installed for you if the
-machine has neither. On Windows use PowerShell or cmd, whichever your terminal
-is; the console shows a line for each.
-
----
-
-## Step 1 — paste the line
-
-Sign in to the console and open **Set up the runner**. The first thing on the
-page is one line with a one-time setup token filled in (valid for ten minutes,
-usable once). Open a terminal **in the project folder you start Claude Code in**
-and paste it:
-
-```powershell
-$env:BIR_SETUP_TOKEN="<token>"; irm https://api.bi2202.com/install.ps1 | iex
-```
-
-```cmd
-powershell -NoProfile -Command "$env:BIR_SETUP_TOKEN='<token>'; irm https://api.bi2202.com/install.ps1 | iex"
-```
-
-```bash
-curl -fsSL https://api.bi2202.com/install.sh | BIR_SETUP_TOKEN="<token>" sh
-```
-
-Without a token — it expired, or you are not at the console — the same line
-without the `BIR_SETUP_TOKEN` part works: `bir setup` uses the sign-in already
-cached on this computer if there is one, and otherwise opens your browser to
-approve the sign-in and waits. Over SSH it prints the link and a short code
-instead; they work from any device, a phone included.
-
-The script prints a `==>` line per stage and never asks a question. Before it
-downloads anything it checks that this is not your home folder or a drive root;
-if it is, it stops and asks you to `cd` to the project and paste again. Then:
-
-1. **Node.** A Node 20+ on PATH is used when npm sits beside it and nothing
-   can move it: a Node from nvm, fnm, Volta, asdf, mise or nodenv changes path
-   per shell or per version, and so does one from Homebrew or snap (macOS and
-   Linux) or Scoop (Windows) — a `brew upgrade` moves the path the hook pins.
-   Any of those, or no Node at all, and a private copy goes under
-   `~/.baseinstrunner/node/v<version>/`. It is never put on your PATH.
-2. **The runner.** `@basein/runner` is installed under `~/.baseinstrunner/npm/`,
-   with `bir` and `bir-hooks` launchers in `~/.baseinstrunner/bin/`, which goes
-   first on your user PATH. No execution-policy change on Windows.
-3. **Claude Code.** Installed with its official installer if `claude` is not on
-   PATH. This can take a minute.
-4. **`bir setup`**, which prints:
-
-```
-==> Setting up the runner (0.2.9)
-    service   https://api.bi2202.com
-    account   you@example.com
-==> Wiring the project
-  + chrome-devtools → bir-proxy (project scope, upstream: npx)
-  + bir → bir-scenario (calculated replay; project scope)
-  + hooks → C:\work\repo\.claude\settings.local.json (control server on http://127.0.0.1:53411; the recorder starts itself with each session)
-  + .claude/settings.local.json is listed in C:\work\repo\.git\info\exclude
-
-Wrapped 1 server.
-…
-==> Starting the recorder in the background
-
-Done. Recording and replay are on for C:\work\repo
-  account    you@example.com  (https://api.bi2202.com)
-  wrapped    chrome-devtools
-  replay     on — direct execution allowed for: all wrapped (narrow it with `bir replay allow chrome-devtools`)
-  recorder   started in the background (pid 1234) — it starts itself with every Claude Code session
-  log        C:\Users\you\.baseinstrunner\logs\3f9c1a2b7d4e5f60.log
-
-Now:  claude
-  first time in this folder: say Yes to "trust this folder"
-  just installed Claude Code? it asks you to sign in to Claude (it needs a Claude subscription)
-  give it a task that takes 4+ tool calls — it appears at https://bi2202.com/recordings within a minute of finishing
-Any time:  bir doctor     bir investigate     bir down (stop)     bir uninstall (undo)
-```
-
-Line by line: *service* is the API address, now stored so no terminal needs
-`BIR_AUTH_URL`; *account* is who the recordings belong to; *wrapped* is the
-project's MCP servers, each now routed through `bir-proxy` under its old name;
-*replay* says which of them a calculated scenario may call unattended — narrow
-it with `bir replay allow <names>`, turn it off with `bir replay off`, and read
-[calculatedReplayGuide.md §5.1](calculatedReplayGuide.md) before leaving it wide
-anywhere that matters; *recorder* is the background process, and *log* is where
-its audit lines go.
-
-A project with no MCP servers in any scope — none in `.mcp.json`, and none for
-this project or your user in `~/.claude.json` — shows `wrapped (no MCP servers
-here)` and `replay steer mode only`: built-in tools and prompts are still
-recorded, and a scenario still steers the session, but there is nothing to
-execute directly.
-
-Pasted in the home folder anyway? The script stops before it downloads anything
-— `This is your home folder. Open a terminal in the project you start Claude
-Code in (cd there) and paste the line again.` Nothing was installed, nobody was
-signed in and the token is unused, so `cd` to the project and paste the same
-line. It is `bir setup` run by hand in the home folder, with the runner already
-installed, that keeps the sign-in and prints the two commands left:
-`cd <your project>` and `bir setup`. No token is needed then; the sign-in is
-kept on this computer.
-
-On macOS and Linux the script cannot change the terminal it was pasted into, so
-it ends with a line to paste — `export PATH="$HOME/.baseinstrunner/bin:$PATH"` —
-or open a new terminal. On Windows it ends with `bir works in every new terminal
-(and in this window when it is PowerShell)`: the PowerShell line puts `bir` on
-that window's PATH in place, but the cmd line runs the script in a child
-`powershell.exe`, so a cmd window has to be a new one.
-
----
-
-## Step 2 — start Claude Code
-
-In the same folder:
-
-```
-claude
-```
-
-The first time in a folder Claude Code asks whether to trust it: say Yes, or the
-hooks do not run. If the script just installed Claude Code, it asks you to sign
-in to Claude; that is Claude's own subscription, separate from BaseIn.
-
-Then give it a task that takes four or more tool calls. It appears on the
-console's Recordings page within a minute of finishing.
-
-Nothing else to start. The SessionStart hook (`bir-hooks ensure`) starts the
-recorder in the background whenever this folder has none, so a session started
-tomorrow, or after a reboot, records the same way.
-
----
-
-## Step 3 — check it
-
-```
-bir doctor     # is it working right now? exits non-zero if not
-bir status     # what is installed for this folder; needs nothing running
-```
-
-`bir doctor` asks the running recorder rather than reading a settings file: it
-says which service it records to, that the recorder runs in the background
-(with its pid and log file), and what replay is set to and where that setting
-came from. `bir status` prints the service address, the wrapped servers and the
-control server's address and log.
-
-Then open https://bi2202.com/recordings. The run from Step 2 is there, with
-its prompt, its tool calls and its final answer.
-
----
-
-## What it changed on your machine
-
-| Path | What it holds |
-|---|---|
-| `~/.baseinstrunner/config.json` | the service address; `BIR_AUTH_URL` in the environment overrides it, and `bir setup` warns when the two differ |
-| `~/.baseinstrunner/credentials.json` | the cached session, bound to the service that issued it |
-| `~/.baseinstrunner/installed.json` | the original text of every file it rewrote, and each project's port, token and replay switches, and whether Claude's `bir` tools may change scenarios there (`bir scenario editing on`) |
-| `~/.baseinstrunner/logs/<key>.log` | the recorder's audit log, one file per project |
-| `~/.baseinstrunner/node/` | a private Node, only if the machine had no usable one; not on PATH |
-| `~/.baseinstrunner/npm/` | the runner package |
-| `~/.baseinstrunner/bin/` | the `bir` and `bir-hooks` launchers, first on your user PATH |
-| `<project>/.claude/settings.local.json` | Claude Code's hooks for this project and the pre-approved `bir` scenario server. Yours, not the team's: it carries this project's token and an absolute Node path |
-| `<project>/.mcp.json` (or `~/.claude.json`, whichever scope an entry lives in) | each MCP entry rewritten to run through `bir-proxy`, same keys; plus the `bir` scenario entry, which always goes in `.mcp.json` (project scope), never in `~/.claude.json` |
-| `<project>/.git/info/exclude` | one line, `.claude/settings.local.json`, so it never shows in `git status` |
-
-Each project gets its own control port (from 53411 up) and its own token, so one
-project's settings file cannot reach another project's recorder.
-
----
-
-## Another project
-
-```
-cd the-other-project
-bir setup
-```
-
-No token: the sign-in is kept. The project gets its own port, token and log.
-
----
-
-## Updating
-
-Paste the line from the console again — the very same line is fine, used token
-and all: `bir setup` says `the setup token was already used; keeping the sign-in
-from before (you@example.com)` and goes on. It installs the newest version and
-runs `bir setup`, which re-wraps any entry whose runner moved. If you installed
-by hand with `npm i -g @basein/runner`, upgrade the same way and then run
-`bir setup` in each project.
-
-A recorder of the older version is replaced only at the moments that look for
-one — the SessionStart hook, `bir up`, `bir setup` — and only when no session
-is mid-run right then; nothing watches for a session to end. `bir setup` says
-so when one is open (`recorder 0.2.8 is still serving an open Claude Code
-session; it restarts to 0.2.9 with the next session`). `bir up --restart` does
-it now.
-
----
-
-## Undoing
-
-```
-bir down          # stop this project's recorder
-bir uninstall     # put every file back byte-for-byte; remove hooks and the bir entry
-```
-
-`bir uninstall` also forgets the project's port and token and takes the
-`.claude/settings.local.json` line back out of `.git/info/exclude`.
-Byte-for-byte holds for a file nothing else edited since the install; one you
-edited is repaired entry by entry instead, and it says so. A file the install
-created — usually `.claude/settings.local.json` — stays behind, empty of our
-entries.
-
-To remove the software: `bir logout` first, so the session is revoked on the
-service rather than only forgotten here. Then `npm rm -g @basein/runner` if
-you installed by hand, or delete `~/.baseinstrunner` (the runner, its private
-Node, the launchers, the session and the logs) and remove
-`~/.baseinstrunner/bin` from your PATH.
-
----
-
-## When something is wrong
-
-`bir doctor` first. It names the broken link in the chain, which is most of the
-answer. Then:
-
-| You see | Why | Do |
-|---|---|---|
-| `This is your home folder…` from the script | a terminal opened from the Start menu begins in the home folder; the script stopped before downloading anything, so nothing is installed, nobody is signed in and the token is unused | `cd` to the project and paste the same line again |
-| `Signed in as … This is your home folder, so nothing was wired here` from `bir setup` | the same folder, but `bir setup` run by hand with the runner already installed; the sign-in is kept | `cd` to the project and run `bir setup` — no token needed |
-| `… is not a BaseIn service` | the address is the website (docs or app), not the API; or a stale `BIR_AUTH_URL` in a shell profile — `bir setup` warns when the two disagree | `bir setup --auth-url https://api.bi2202.com`; remove the variable from the profile |
-| `control.port_busy` in the log (`port N is held by another program or excluded by the system`); the recorder did not start | another program holds this project's port, or the system reserves the range it falls in — on Windows, Hyper-V and WSL exclude blocks that 53411 sits inside | `bir setup --port <n>` (by hand: `bir install --replay --port <n>` — a flag-less install keeps the way the project was installed — then `bir up --restart`) |
-| `recorder.disabled … no BaseIn session` in the log; `bir doctor` says the recorder has nowhere to send steps; or `bir setup` ends with ``not signed in — run `bir setup` again (or `bir login`)`` | not signed in, or signed in to another service | `bir setup`, then `bir up --restart` |
-| `that is not a valid setup token`, or `this setup token has expired or was already used` from `bir setup` | the token was cut short in the paste; or it is older than ten minutes or already redeemed, with no cached sign-in to fall back on | make a new one on the console's *Set up the runner* page and paste the whole line within ten minutes |
-| the tools were recorded but not the prompt | no recorder was running for this folder, so the proxies recorded on their own (Tier 2) | `bir doctor` says whether a recorder runs for this folder; `bir up` starts one now — the next session starts it anyway |
-| the run is not in Recordings | fewer than four tool calls; or the runner is signed in as a different account than the console | give a bigger task; compare the *account* line of `bir setup` with the console |
-| `bir doctor`: `the SessionStart hook … points at a Node that is gone` | the Node the hook names was removed or moved by a version manager | `bir setup` — it rewires the hook to the current Node |
-| Claude Code asks you to sign in | Claude Code was just installed; it needs a Claude subscription | sign in; nothing to do on the runner side |
-| `bir` is not recognised in the terminal the line was pasted into | on macOS and Linux the script cannot change that terminal's PATH; on Windows the cmd line runs the script in a child `powershell.exe`, whose PATH dies with it (the PowerShell line changes its own window) | macOS / Linux: `export PATH="$HOME/.baseinstrunner/bin:$PATH"`, or open a new terminal; Windows cmd: open a new window |
-| `invalid JSON at …/.mcp.json` | something edited the file into a shape that no longer parses | open it and fix the comma or bracket |
-
-For a turn that did not do what you expected — a scenario that did not run, a
-saving that was not made — `bir investigate` reads the journal and the service
-and says why. When it names a step whose code is wrong, you can fix that step
-yourself: see the next section.
-
----
-
-## Fixing a step (not yet released)
-
-Built 2026-09-25. It needs the next `@basein/runner` version and a service
-deploy, so it does not work yet. The full guide, with real output, is
-[calculatedReplayGuide.md](calculatedReplayGuide.md) §9.2.
-
-A calculated step is code. When `bir investigate` says a step's code is wrong,
-you can change that step. The service checks your change against the
-recording. It saves it only if it gives the same call the recording made, and
-is not a pasted copy of that call. Only the owner of a scenario can change it.
-
-1. **Read the step.** `bir scenario show scn_… --step 4` (the `scn_` id and the
-   step number are the ones `bir investigate` printed).
-2. **Write the new code to a file,** for example `step4.js`. Never on the
-   command line: the shell breaks JavaScript.
-3. **Check it.** `bir scenario check scn_… --step 4 --input-logic step4.js`.
-   Nothing is saved. You should see `input    reproduces the recorded call`.
-4. **Save it.** `bir scenario edit scn_… --step 4 --input-logic step4.js --note "why"`.
-   You should see a line that starts `Saved as sedit_…`.
-5. **Changed your mind?** `bir scenario undo scn_…` takes back the newest
-   change. Run it again to go one further back. With `--step 4` it takes
-   back only step 4's changes, newest first. An undo that would break a later
-   step or the final answer is refused (`undo_refused`).
-
-If the check refuses your change, it says why. For example, the `input` line
-says where your call differs from the recorded one. Fix the code and check
-again. `--force --note "why"` saves it anyway, but use it only when the
-recording itself was wrong.
-
-The saved code runs on your machine without asking you, like the code the
-calculation wrote. The check only tests what it sends for the recording's
-values. So read the code before it is saved, yours or Claude's.
-
-Claude can do this for you. Ask it in the session; it runs the same commands,
-and Claude Code asks you before each one, unless you allowed it. Or run
-`bir scenario editing on` in the project folder and restart Claude Code: the
-`bir` server then also offers tools that change a scenario. These `bir` calls
-are never recorded as part of your task.
-
----
-
-## Where to go next
-
-- [installRun.md](installRun.md) — the fleet version: packaging, releases,
-  offline installs, updates.
-- [calculatedReplayGuide.md](calculatedReplayGuide.md) — record, calculate,
-  check, enable, and read the audit lines.
-- [../README.md](../README.md) — what is recorded, what cannot be, and every
-  configuration switch.
+# Setting up a runner machine
+
+One person, one computer: from nothing to a project whose every Claude Code
+session is recorded and whose calculated scenarios run. It takes a few minutes,
+most of them downloads. Nothing has to stay open afterwards.
+
+**What you are setting up.** BaseInstRunner sits between Claude Code and the
+tools it uses, records each session to the BaseIn service, and — when a new
+prompt means the same thing as one it has seen — runs the calculated scenario
+instead of letting the model rediscover the plan. Otherwise it does not change
+what the model does.
+
+---
+
+## Before you start
+
+A BaseIn account. That is all: Node and Claude Code are installed for you if the
+machine has neither. On Windows use PowerShell or cmd, whichever your terminal
+is; the console shows a line for each.
+
+---
+
+## Step 1 — paste the line
+
+Sign in to the console and open **Set up the runner**. The first thing on the
+page is one line with a one-time setup token filled in (valid for ten minutes,
+usable once). Open a terminal **in the project folder you start Claude Code in**
+and paste it:
+
+```powershell
+$env:BIR_SETUP_TOKEN="<token>"; irm https://api.bi2202.com/install.ps1 | iex
+```
+
+```cmd
+powershell -NoProfile -Command "$env:BIR_SETUP_TOKEN='<token>'; irm https://api.bi2202.com/install.ps1 | iex"
+```
+
+```bash
+curl -fsSL https://api.bi2202.com/install.sh | BIR_SETUP_TOKEN="<token>" sh
+```
+
+Without a token — it expired, or you are not at the console — the same line
+without the `BIR_SETUP_TOKEN` part works: `bir setup` uses the sign-in already
+cached on this computer if there is one, and otherwise opens your browser to
+approve the sign-in and waits. Over SSH it prints the link and a short code
+instead; they work from any device, a phone included.
+
+Behind a corporate proxy, set `NO_PROXY=127.0.0.1,localhost,::1` (plus your own
+entries) as well as `HTTPS_PROXY` before you paste. The runner uses the proxy
+only when `NO_PROXY` exempts `127.0.0.1` — otherwise the proxy would swallow its
+own local calls — and the script prints a note when it does not
+([installRun.md §5.1](installRun.md)).
+
+The script prints a `==>` line per stage and never asks a question. Before it
+downloads anything it checks that this is not your home folder or a drive root;
+if it is, it stops and asks you to `cd` to the project and paste again. Then:
+
+1. **Node.** A Node 20+ on PATH is used when npm sits beside it and nothing
+   can move it: a Node from nvm, fnm, Volta, asdf, mise or nodenv changes path
+   per shell or per version, and so does one from Homebrew or snap (macOS and
+   Linux) or Scoop (Windows) — a `brew upgrade` moves the path the hook pins.
+   Any of those, or no Node at all, and a private copy goes under
+   `~/.baseinstrunner/node/v<version>/`. It is never put on your PATH.
+2. **The runner.** `@basein/runner` is installed under `~/.baseinstrunner/npm/`,
+   with `bir` and `bir-hooks` launchers in `~/.baseinstrunner/bin/`, which goes
+   first on your user PATH. No execution-policy change on Windows.
+3. **Claude Code.** Installed with its official installer if `claude` is not on
+   PATH. This can take a minute.
+4. **`bir setup`**, which prints:
+
+```
+==> Setting up the runner (0.2.9)
+    service   https://api.bi2202.com
+    account   you@example.com
+==> Wiring the project
+  + chrome-devtools → bir-proxy (local scope, over the .mcp.json entry; upstream: npx)
+  + bir → bir-scenario (calculated replay; local scope)
+  + hooks → C:\work\repo\.claude\settings.local.json (control server on http://127.0.0.1:53411; the recorder starts itself with each session)
+  + .claude/settings.local.json is listed in C:\work\repo\.git\info\exclude
+
+Wrapped 1 server.
+…
+==> Starting the recorder in the background
+
+Done. Recording and replay are on for C:\work\repo
+  account    you@example.com  (https://api.bi2202.com)
+  wrapped    chrome-devtools
+  replay     on — direct execution allowed for: all wrapped (narrow it with `bir replay allow chrome-devtools`)
+  recorder   started in the background (pid 1234) — it starts itself with every Claude Code session
+  log        C:\Users\you\.baseinstrunner\logs\3f9c1a2b7d4e5f60.log
+
+Now:  claude
+  first time in this folder: say Yes to "trust this folder"
+  just installed Claude Code? it asks you to sign in to Claude (it needs a Claude subscription)
+  give it a task that takes 4+ tool calls — it appears at https://bi2202.com/recordings within a minute of finishing
+Any time:  bir doctor     bir investigate     bir off (out of the way, at once)     bir uninstall (undo)
+```
+
+Line by line: *service* is the API address, now stored so no terminal needs
+`BIR_AUTH_URL`; *account* is who the recordings belong to; *wrapped* is the
+project's MCP servers now routed through `bir-proxy` under their old names — as
+copies in this project's local scope in `~/.claude.json`, so `.mcp.json` itself
+is not changed;
+*replay* says which of them a calculated scenario may call unattended — narrow
+it with `bir replay allow <names>`, turn it off with `bir replay off`, and read
+[calculatedReplayGuide.md §5.1](calculatedReplayGuide.md) before leaving it wide
+anywhere that matters; *recorder* is the background process, and *log* is where
+its audit lines go.
+
+A project with no MCP servers in any scope — none in `.mcp.json`, and none for
+this project or your user in `~/.claude.json` — shows `wrapped (no MCP servers
+here)` and `replay steer mode only`: built-in tools and prompts are still
+recorded, and a scenario still steers the session, but there is nothing to
+execute directly.
+
+Only servers Claude Code already runs here are wrapped. A `.mcp.json` server
+Claude Code has not asked you about yet — a fresh clone, say — is left as it is
+(`- <name> — left unwrapped: Claude Code has not been told to use it yet (it
+asks first); …`); when nothing could be wrapped, *wrapped* reads `(none —
+<name> left as they are, see above)`. Start `claude`, approve the server when it
+asks, and run `bir setup` again to wrap it; until then the hooks record its
+calls. A remote server that Claude Code signs in itself (OAuth) is left
+unwrapped the same way.
+
+Pasted in the home folder anyway? The script stops before it downloads anything
+— `This is your home folder. Open a terminal in the project you start Claude
+Code in (cd there) and paste the line again.` Nothing was installed, nobody was
+signed in and the token is unused, so `cd` to the project and paste the same
+line. It is `bir setup` run by hand in the home folder, with the runner already
+installed, that keeps the sign-in and prints the two commands left:
+`cd <your project>` and `bir setup`. No token is needed then; the sign-in is
+kept on this computer.
+
+On macOS and Linux the script cannot change the terminal it was pasted into, so
+it ends with a line to paste — `export PATH="$HOME/.baseinstrunner/bin:$PATH"` —
+or open a new terminal. On Windows it ends with `bir works in every new terminal
+(and in this window when it is PowerShell)`: the PowerShell line puts `bir` on
+that window's PATH in place, but the cmd line runs the script in a child
+`powershell.exe`, so a cmd window has to be a new one.
+
+---
+
+## Step 2 — start Claude Code
+
+In the same folder:
+
+```
+claude
+```
+
+The first time in a folder Claude Code asks whether to trust it: say Yes, or the
+hooks do not run. If the script just installed Claude Code, it asks you to sign
+in to Claude; that is Claude's own subscription, separate from BaseIn. If it
+asks whether to use a server from the project's `.mcp.json` that `bir setup`
+left unwrapped, say Yes and run `bir setup` again afterwards.
+
+Then give it a task that takes four or more tool calls. It appears on the
+console's Recordings page within a minute of finishing.
+
+Nothing else to start. The SessionStart hook (`bir-hooks ensure`) starts the
+recorder in the background whenever this folder has none, so a session started
+tomorrow, or after a reboot, records the same way.
+
+---
+
+## Step 3 — check it
+
+```
+bir doctor     # is it working right now? exits 1 only for what breaks a session
+bir status     # what is installed for this folder; needs nothing running
+```
+
+`bir doctor` asks the running recorder rather than reading a settings file: it
+says which service it records to, that the recorder runs in the background
+(with its pid and log file), what replay is set to and where that setting
+came from, and who approves wrapped MCP calls. It sorts the rest into problems
+(these break a Claude Code session, and only these exit 1), warnings (the
+runner is not doing all it should — not recording, say; `--strict` fails on
+these too) and notes. `bir status` prints the service address, the wrapped
+servers, the control server's address and log, and whether the runner is off.
+
+Then open https://bi2202.com/recordings. The run from Step 2 is there, with
+its prompt, its tool calls and its final answer.
+
+---
+
+## What it changed on your machine
+
+| Path | What it holds |
+|---|---|
+| `~/.baseinstrunner/config.json` | the service address; `BIR_AUTH_URL` in the environment overrides it, and `bir setup` warns when the two differ |
+| `~/.baseinstrunner/credentials.json` | the cached session, bound to the service that issued it |
+| `~/.baseinstrunner/installed.json` | what `bir uninstall` needs to undo each change — the original text of the project files it rewrote, with their credential values left out — and each project's port, token and replay switches, and whether Claude's `bir` tools may change scenarios there (`bir scenario editing on`) |
+| `~/.baseinstrunner/logs/<key>.log` | the recorder's audit log, one file per project |
+| `~/.baseinstrunner/node/` | a private Node, only if the machine had no usable one; not on PATH |
+| `~/.baseinstrunner/npm/` | the runner package |
+| `~/.baseinstrunner/bin/` | the `bir` and `bir-hooks` launchers, first on your user PATH |
+| `<project>/.claude/settings.local.json` | Claude Code's hooks for this project. Yours, not the team's: it carries this project's token and an absolute Node path |
+| `~/.claude.json` (`$CLAUDE_CONFIG_DIR/.claude.json` when that is set), this project's local scope | a copy of each MCP server it wraps, under the same name, running through `bir-proxy`; plus the `bir` scenario server. The copy takes precedence in this project only; `.mcp.json` and your user-scope servers are not changed |
+| `<project>/.git/info/exclude` | one line, `.claude/settings.local.json`, so it never shows in `git status` |
+
+Each project gets its own control port (from 53411 up) and its own token, so one
+project's settings file cannot reach another project's recorder.
+
+---
+
+## Another project
+
+```
+cd the-other-project
+bir setup
+```
+
+No token: the sign-in is kept. The project gets its own port, token and log.
+
+---
+
+## Updating
+
+Paste the line from the console again — the very same line is fine, used token
+and all: `bir setup` says `the setup token was already used; keeping the sign-in
+from before (you@example.com)` and goes on. It installs the newest version and
+runs `bir setup`, which re-wraps any entry whose runner moved. If you installed
+by hand with `npm i -g @basein/runner`, upgrade the same way and then run
+`bir setup` in each project.
+
+A recorder of an older version is replaced only at the moments that look for
+one — the SessionStart hook, `bir up`, `bir setup` — and only when no session
+is mid-turn right then; nothing watches for a session to end. `bir setup` says
+so when one is (``it is still <old>, serving a Claude Code session that is
+mid-turn; it keeps running as <old> until `bir up --restart` (run it once that
+session ends) replaces it with <new>``). Run `bir up --restart` once that
+session ends.
+
+**From 0.2.12.** The runner no longer approves wrapped MCP tool calls itself
+(0.2.12 answered every one "allow"): Claude Code asks about them as it would
+without the runner, and `bir setup` says so once. For headless `claude -p` runs,
+allow them in `permissions.allow` or with `--allowedTools`, or set
+`BIR_CORRELATION_DECISION=allow` where the recorder starts (then
+`bir up --restart` from there). Wrapped entries move
+out of `.mcp.json` into the local scope, and `.mcp.json` is put back as it was.
+A 0.2.12 recorder still running keeps approving those calls, and ignores
+`bir off`, until `bir up --restart` replaces it.
+
+Going back to an older version: run `bir uninstall --all` with this one first
+(an older runner cannot undo everything this one wrote), then install the older
+one and run `bir setup`.
+
+---
+
+## Undoing
+
+```
+bir off --here    # out of the way at once, open sessions included; nothing is uninstalled
+bir down          # stop this project's recorder
+bir uninstall     # undo the install here, and stop this project's recorder
+```
+
+`bir off --here` (this project) or `bir off` (every project) is the first thing
+to try when a session misbehaves, or when support wants to rule the runner out:
+hooks answer with nothing within about a second, in sessions already open too;
+wrapped MCP servers run as plain pipes to the real ones from their next start
+(a new session, or `/mcp` → reconnect), and the `bir` server offers no tools
+from its next start.
+`bir on --here` / `bir on` turns it back on. `BIR_OFF=1` in the environment
+Claude Code starts in switches off just that window's session.
+
+`bir down` only stops the recorder. The hooks stay installed, so a Claude Code
+session open here shows a "hook error" on each prompt and tool call (the session
+keeps working) until it ends, and the next session starts the recorder again.
+
+`bir uninstall` covers this project only. It puts back what the install changed
+— a file nothing else edited since, byte-for-byte; `~/.claude.json`, and a file
+you edited, entry by entry — removes the hooks and the `bir` entry, forgets the
+project's port and token, and takes the `.claude/settings.local.json` line back
+out of `.git/info/exclude` (unless it was there before). It also stops the
+project's recorder — unless a session here still uses it: then the recorder
+stays up, switched off for this project, and it tells you to restart that
+session and run `bir down`. A file the install created — usually
+`.claude/settings.local.json` — stays behind, empty of our entries. If anything
+here still runs through the runner it ends with `Not everything could be
+undone`, names it, and exits 1.
+
+To remove the software, take the runner out of every project first — otherwise
+their wrapped servers and hooks keep naming files you are about to delete:
+
+```
+bir uninstall --all
+```
+
+or paste the install line with `BIR_UNINSTALL=1`, which runs just that:
+`curl -fsSL https://api.bi2202.com/install.sh | BIR_UNINSTALL=1 sh`, or
+`$env:BIR_UNINSTALL="1"; irm https://api.bi2202.com/install.ps1 | iex` in
+PowerShell. Once it ends cleanly: `bir logout`, so the session is revoked on the
+service rather than only forgotten here. Then `npm rm -g @basein/runner` if
+you installed by hand, or delete `~/.baseinstrunner` (the runner, its private
+Node, the launchers, the session and the logs) and remove
+`~/.baseinstrunner/bin` from your PATH.
+
+---
+
+## When something is wrong
+
+`bir doctor` first. It names the broken link in the chain, which is most of the
+answer. Then:
+
+| You see | Why | Do |
+|---|---|---|
+| `This is your home folder…` from the script | a terminal opened from the Start menu begins in the home folder; the script stopped before downloading anything, so nothing is installed, nobody is signed in and the token is unused | `cd` to the project and paste the same line again |
+| `Signed in as … This is your home folder, so nothing was wired here` from `bir setup` | the same folder, but `bir setup` run by hand with the runner already installed; the sign-in is kept | `cd` to the project and run `bir setup` — no token needed |
+| `… is not a BaseIn service` | the address is the website (docs or app), not the API; or a stale `BIR_AUTH_URL` in a shell profile — `bir setup` warns when the two disagree | `bir setup --auth-url https://api.bi2202.com`; remove the variable from the profile |
+| `control.port_busy` in the log; `bir doctor`: `the recorder could not take port N: …`; the recorder did not start | another program holds this project's port, or the system reserves the range it falls in — on Windows, Hyper-V, WSL and Docker reserve blocks that 53411 sits inside, and they move at boot | `bir setup` — it moves the project to a free port when its own cannot be bound; or `bir setup --port <n>` (below 49152 avoids the reserved ranges; by hand: `bir install --replay --port <n>` — a flag-less install keeps the way the project was installed — then `bir up --restart`) |
+| `recorder.disabled` or `recorder.signed_out` in the log (`not signed in`, `no service address`); `bir doctor` warns the recorder has nowhere to send steps; or `bir setup` ends with ``not signed in — run `bir setup` again (or `bir login`)`` | not signed in, or signed in to another service | `bir setup` — the running recorder starts recording by itself once the sign-in is there, no restart needed |
+| `- <name> — left unwrapped: Claude Code has not been told to use it yet` from `bir setup` | a `.mcp.json` server Claude Code has not approved (a fresh clone); a copy would start it without asking | start `claude`, approve it, then `bir setup` again; `bir install --server <name>` wraps it anyway |
+| a `claude -p` run is denied a wrapped MCP tool (since upgrading from 0.2.12) | the runner no longer approves wrapped MCP calls; Claude Code's own permissions decide | allow the tools in `permissions.allow` or with `--allowedTools`, or set `BIR_CORRELATION_DECISION=allow` where the recorder starts, then `bir up --restart` from there |
+| a "hook error" on each prompt and tool call | the recorder was stopped (`bir down`) under an open session | `bir up`; `bir off --here` afterwards if you want the runner out of the way; a new session also starts it |
+| `that is not a valid setup token`, or `this setup token has expired or was already used` from `bir setup` | the token was cut short in the paste; or it is older than ten minutes or already redeemed, with no cached sign-in to fall back on | make a new one on the console's *Set up the runner* page and paste the whole line within ten minutes |
+| the tools were recorded but not the prompt | no recorder was running for this folder, so the proxies recorded on their own (Tier 2) | `bir doctor` says whether a recorder runs for this folder; `bir up` starts one now — the next session starts it anyway |
+| the run is not in Recordings | fewer than four tool calls; or the runner is signed in as a different account than the console | give a bigger task; compare the *account* line of `bir setup` with the console |
+| `bir doctor`: `the SessionStart hook … points at a Node that is gone` | the Node the hook names was removed or moved by a version manager | `bir setup` — it rewires the hook to the current Node |
+| Claude Code asks you to sign in | Claude Code was just installed; it needs a Claude subscription | sign in; nothing to do on the runner side |
+| `bir` is not recognised in the terminal the line was pasted into | on macOS and Linux the script cannot change that terminal's PATH; on Windows the cmd line runs the script in a child `powershell.exe`, whose PATH dies with it (the PowerShell line changes its own window) | macOS / Linux: `export PATH="$HOME/.baseinstrunner/bin:$PATH"`, or open a new terminal; Windows cmd: open a new window |
+| `invalid JSON at …/.mcp.json` | something edited the file into a shape that no longer parses (comments count); `bir setup` changes nothing until it does | open it and fix the comma or bracket |
+| `… is set but NO_PROXY does not name 127.0.0.1 …` from the script or `bir setup` | the runner leaves the proxy out rather than send its own local calls through it | set `NO_PROXY=127.0.0.1,localhost,::1` plus your own entries, and paste the line again |
+
+For a turn that did not do what you expected — a scenario that did not run, a
+saving that was not made — `bir investigate` reads the journal and the service
+and says why. When it names a step whose code is wrong, you can fix that step
+yourself: see the next section.
+
+---
+
+## Fixing a step (not yet released)
+
+Built 2026-09-25. It needs the next `@basein/runner` version and a service
+deploy, so it does not work yet. The full guide, with real output, is
+[calculatedReplayGuide.md](calculatedReplayGuide.md) §9.2.
+
+A calculated step is code. When `bir investigate` says a step's code is wrong,
+you can change that step. The service checks your change against the
+recording. It saves it only if it gives the same call the recording made, and
+is not a pasted copy of that call. Only the owner of a scenario can change it.
+
+1. **Read the step.** `bir scenario show scn_… --step 4` (the `scn_` id and the
+   step number are the ones `bir investigate` printed).
+2. **Write the new code to a file,** for example `step4.js`. Never on the
+   command line: the shell breaks JavaScript.
+3. **Check it.** `bir scenario check scn_… --step 4 --input-logic step4.js`.
+   Nothing is saved. You should see `input    reproduces the recorded call`.
+4. **Save it.** `bir scenario edit scn_… --step 4 --input-logic step4.js --note "why"`.
+   You should see a line that starts `Saved as sedit_…`.
+5. **Changed your mind?** `bir scenario undo scn_…` takes back the newest
+   change. Run it again to go one further back. With `--step 4` it takes
+   back only step 4's changes, newest first. An undo that would break a later
+   step or the final answer is refused (`undo_refused`).
+
+If the check refuses your change, it says why. For example, the `input` line
+says where your call differs from the recorded one. Fix the code and check
+again. `--force --note "why"` saves it anyway, but use it only when the
+recording itself was wrong.
+
+The saved code runs on your machine without asking you, like the code the
+calculation wrote. The check only tests what it sends for the recording's
+values. So read the code before it is saved, yours or Claude's.
+
+Claude can do this for you. Ask it in the session; it runs the same commands,
+and Claude Code asks you before each one, unless you allowed it. Or run
+`bir scenario editing on` in the project folder and restart Claude Code: the
+`bir` server then also offers the tools that read and change a scenario (by
+default it offers only `run_scenario`). These `bir` calls
+are never recorded as part of your task.
+
+---
+
+## Where to go next
+
+- [installRun.md](installRun.md) — the fleet version: packaging, releases,
+  offline installs, proxies, updates, removal.
+- [../production.md](../production.md) — the production contract: timeouts,
+  environment variables, what happens when the service is down.
+- [calculatedReplayGuide.md](calculatedReplayGuide.md) — record, calculate,
+  check, enable, and read the audit lines.
+- [../README.md](../README.md) — what is recorded, what cannot be, and every
+  configuration switch.