@basein/runner 0.2.11 → 0.3.0

package/docs/installRun.md

@@ -1,772 +1,1013 @@
-# Packaging BaseInstRunner for runner machines
-
-**The approach: publish to npm as `@basein/runner`, and install it globally at a
-pinned version.** The code already assumed this — the installer writes an `npx`
-invocation of its own package name into every wrapped MCP entry — so publishing
-was less a new distribution channel than closing a loop that was already there.
-
-This is the fleet-facing reference: what ships, how a runner machine goes from
-bare to recording, how it gets updated, and what to do when there is no registry
-to reach. For one person setting up one machine, [quickstart.md](quickstart.md)
-is shorter and assumes nothing.
-
-**Status.** Everything here is implemented except the last item of §7: a
-non-interactive grant for machines with no person attached needs a service-side
-decision rather than a change here.
-
----
-
-## 1. Why this package is an easy case
-
-| Property | Value | Why it matters for packaging |
-|---|---|---|
-| Runtime dependencies | **none** | The tarball is self-contained. No lockfile resolution, no transitive CVEs, no native builds, and offline install just works. |
-| Module format | pure ESM (`"type": "module"`) | No dual-build gymnastics. |
-| Node floor | `>=20` | The one prerequisite — and the served line installs a private copy when the machine has none, or only one the hook must not pin: a version-managed, Homebrew or snap Node, or one with no npm beside it (§5.1). |
-| Build | `tsc` → `dist/`, `prepublishOnly` wired | `npm publish` cannot ship a stale `dist/`. |
-| Bins | `bir`, `bir-proxy`, `bir-hooks`, `bir-scenario`, all with `#!/usr/bin/env node` | npm creates the shims, including `.cmd`/`.ps1` on Windows. |
-| Tarball | 120 files, ~390 kB | `dist/` + types + docs + `scripts/` (the install scripts, so a tarball can bootstrap an offline machine). Sourcemaps and `docs/next.md` are excluded. |
-
-A zero-dependency, pure-JS, four-bin package is the best-behaved thing npm
-distributes. The delivery does not need to be clever.
-
-### What is excluded, and why
-
-`files` carries two negations:
-
-- `!dist/**/*.map` — 106 files, ~490 kB. The maps carry no `sourcesContent`, and
-  `src/` is not published, so they cannot resolve a single stack frame. They were
-  bytes that did nothing on every install and every `npx` cold start.
-- `!docs/next.md` — a working scratchpad, not documentation.
-
-The rest of `docs/` **does** ship, and deliberately: the GitHub repository is
-private, so for anyone on a runner machine the tarball is the only place this
-documentation exists.
-
----
-
-## 2. The options, and why this one
-
-| Approach | Runner install | Good for | Cost |
-|---|---|---|---|
-| **npm registry (public)** ← chosen | `npm i -g @basein/runner@0.1.0` | the default; makes the generated entries resolvable | the code is public |
-| npm registry (private, scoped) | same, plus an `.npmrc` token | code you cannot publish | every runner needs a read token, and so does `npx` |
-| GitHub Packages | same, `registry=https://npm.pkg.github.com` | no second account | GH tokens are clumsier to rotate across a fleet |
-| Tarball from a Release | `npm i -g ./basein-runner-0.1.0.tgz` | airgapped runners | no registry resolution — see §6 |
-| `npm i -g git+ssh://…#v0.1.0` | one line, no registry | a handful of machines | needs git and a toolchain on every runner; slowest and most fragile |
-| Node SEA / bundled binary | copy one file | machines where Node cannot be installed | you own a three-OS build matrix |
-| **Docker** | — | **not suitable** | The proxy spawns the host's own MCP servers as child processes, rewrites config in the user's home, and shares a cwd with the agent session. A container isolates exactly what this tool must reach. |
-
-The package is public; the repository is private. Those are separate decisions
-and this project makes them differently. Nothing operational leaks either way —
-the service is gated by its address plus credentials.
-
----
-
-## 3. Publishing
-
-### 3.1 Manifest — done
-
-`package.json` carries `repository` (npm requires it for provenance) and
-`publishConfig.access: public` (a scoped package is private by default, and
-`npm publish` on a scope you have no paid plan for otherwise fails).
-
-There is deliberately **no** `provenance`, and no `--provenance` in the workflow:
-npm's attestation requires a *public* repository. Turn both on the day that
-changes; nothing else has to move.
-
-`homepage` and `bugs` are also omitted, for the same reason — they would be dead
-links on a public package page.
-
-### 3.2 The name is load-bearing
-
-`PACKAGE_NAME` in [generate.ts](../src/config/generate.ts) is written into every
-config file the installer produces. Renaming after runners are deployed points
-every previously-installed project at a package that no longer resolves. It is
-settled now; treat it as fixed.
-
-### 3.3 The publishing credential
-
-The `basein` org exists on npmjs.com (free tier, public packages), and
-`NPM_TOKEN` is set as a repository secret in GitHub Actions.
-
-It is a **granular** token, not a classic automation one, because npm now steers
-you there:
-
-| Property | Value |
-|---|---|
-| Name | `github-actions-release` |
-| Scope | `basein`, read and write |
-| Organizations | no access — publishing needs the scope, not org administration |
-| 2FA | bypassed, which is what lets CI publish unattended |
-| **Expires** | **2026-10-05** |
-
-**Two dates to keep.**
-
-*2026-10-05 — the token dies.* Granular tokens must carry an expiry; npm offers
-no perpetual option. When a release starts failing with `ENEEDAUTH` around then,
-this is why. Regenerate with the same settings and overwrite the secret.
-
-*January 2027 — direct token publishing ends.* The token summary says so
-outright: "Publish new versions directly (deprecated — ends January 2027)". The
-replacement is **trusted publishing**, where the workflow authenticates to npm
-over OIDC and there is no stored credential at all — no secret to leak, and no
-expiry to forget. Migrating also removes the first date above, so doing it before
-2026-10-05 turns two chores into one.
-
-Releasing is then a tag:
-
-```bash
-git tag v0.1.0 && git push origin v0.1.0
-```
-
-### 3.4 The workflows — done
-
-- [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) — every push and PR
-  to main, on Ubuntu, Windows and macOS.
-- [`.github/workflows/release.yml`](../.github/workflows/release.yml) — on a
-  `v*` tag: the same three-platform suite, then publish, then attach the tarball
-  to a GitHub Release.
-
-Three platforms is not decoration. `resolveCommand` shells a `.cmd` upstream
-through `cmd.exe` with its own quoting, and `normalizePath` reconciles Claude
-Code's forward slashes with `process.cwd()`'s backslashes — the failure the code
-itself calls "the number one cause of *installed but never runs*". Neither is
-exercised on Linux.
-
-Both workflows run `npm run build` before the tests, because `test:smoke` spawns
-the real binaries out of `dist/` while `npm test` only builds `.test-build/`.
-
-The release job refuses to publish when the tag disagrees with `package.json` —
-npm has no undo past 72 hours, and a mismatched tag publishes a version nobody
-asked for.
-
-**One known flake.** `run_scenario finds the session whose plan is armed` loses
-an arming race roughly one run in three. It is unrelated to packaging, and the
-test steps retry once so it cannot redden a release at random. Remove the retry
-the day that test is made deterministic.
-
----
-
-## 4. What `bir install` writes
-
-Three invocation modes, one flag each:
-
-| Mode | Flag | Entry |
-|---|---|---|
-| **npx** | *(default)* | `npx -y -p @basein/runner@0.2.9 bir-proxy …` |
-| **global** | `--global` | `<node> <prefix>/lib/node_modules/@basein/runner/dist/bin/bir-proxy.js …` (Windows: `<prefix>/node_modules/@basein/runner/…`) |
-| **local** | `--local` | `<node> <this checkout>/dist/bin/bir-proxy.js …` |
-
-`<node>` is the absolute path of the Node that ran the install, symlinks
-resolved. Under the served line (§5.1) that is the machine's own Node when it
-qualifies (20 or newer, not under a version manager, npm beside it), else the
-private Node in `~/.baseinstrunner/node/v<V>/`; `<prefix>` is
-`~/.baseinstrunner/npm` either way. By hand it is whatever `npm i -g` used.
-npm's global layout differs by platform:
-the package is at `<prefix>/lib/node_modules/@basein/runner` on macOS and Linux
-and at `<prefix>/node_modules/@basein/runner` on Windows.
-
-**The npx spec is pinned.** It was not, and that was the one real defect in the
-original packaging story: two runners provisioned a week apart could run
-different proxy versions against the same service, with nothing in a recording to
-say which.
-
-**`--global` is what a fleet wants**, and it is what `bir setup` uses: from an
-installed package it runs `bir install --global --replay` in-process (from a
-checkout, `--local`, since `--global` refuses one). It removes the registry from the hot
-path entirely: no resolution before the MCP server can start, no dependence on
-the MCP host seeing the same `PATH` as the shell that installed things — which
-GUI-launched hosts on Windows do not — and it works with no network at all.
-
-It also survives upgrades. The path
-`<prefix>/lib/node_modules/@basein/runner/dist/bin/bir-proxy.js` contains no
-version, so `npm i -g @basein/runner@<version>` changes what that path points at
-without changing the path. **A pinned-npx install, by contrast, must re-run
-`bir install` on every upgrade** to move the pin.
-
-A flag-less `bir install` keeps the invocation the project was installed with
-(`invocation` in its record, §4.3): a `bir install --replay` after `bir setup`
-keeps the absolute paths and the command SessionStart hook instead of quietly
-turning every entry into a pinned-npx one.
-
-**An entry whose runner moved is re-wrapped.** `bir install` compares each
-wrapped entry — its Node path, its proxy path, or its pinned npx version — with
-the package it is running from, and regenerates any that disagree from the
-stashed original: `~ fleet — re-wrapping: its runner moved (was …)`. The
-scenario entry gets the same check. That is what lets `bir setup` be the upgrade
-path even when the package changed prefix (from the machine's npm prefix to the
-private one) or the Node moved (a version manager, a reinstall), instead of
-printing "already wrapped" about an entry the host would keep spawning from a
-path that is gone.
-
-`--global` refuses to run from a checkout: it asserts a path that outlives the
-shell, and a checkout's `dist/` moves with the checkout. Use `--local` when you
-mean the checkout on purpose.
-
-### 4.1 Hooks go to `.claude/settings.local.json`
-
-Claude Code's hooks are written to `<project>/.claude/settings.local.json`, not
-to the `.claude/settings.json` a team commits. They carry a bearer token and an
-absolute path to this machine's Node; neither belongs in a teammate's clone.
-Inside a git repository `bir` adds the line `.claude/settings.local.json` to
-`.git/info/exclude` — the person's own, untracked list, never a `.gitignore` the
-team would see in a diff — and says so. A worktree's `gitdir:` pointer is
-followed. Outside a repository, or when the exclude file cannot be written, that
-is a note, not a failed install.
-
-An install that finds `bir` hooks in a legacy `.claude/settings.json` removes
-them from there on the way (`- hooks removed from … (they live in
-settings.local.json now)`). `bir uninstall` cleans both files and takes the
-`.claude/settings.local.json` line out of `.git/info/exclude` again. It restores
-a file byte-for-byte only when nothing else edited it since the install; a file
-it created — usually `settings.local.json` itself — stays behind, empty of our
-entries.
-
-With `--replay`, `bir install` does two more things: the `bir` scenario server
-goes into `.mcp.json` (project scope — never `~/.claude.json`, whose per-project
-map Claude Code keys with forward slashes, so an entry written from a Windows
-cwd lands under a key it never reads), and `bir` is merged into
-`enabledMcpjsonServers` in `settings.local.json`, so Claude Code never shows its
-approval dialog for the scenario server. A "No" there leaves a direct replay
-with nowhere to deliver its results, and nothing to say so.
-`bir uninstall --replay` removes only the scenario server; the proxies, the
-hooks and the pre-approval stay as they are.
-
-### 4.2 SessionStart is a command hook
-
-For `--global` and `--local` installs the SessionStart hook is a command hook in
-Claude Code's exec form — `command` spawned directly with `args` as its argument
-vector, no shell in between, so a path with a space needs no quoting and it runs
-the same under Git Bash, PowerShell and cmd.exe:
-
-```json
-{ "type": "command", "command": "<node>", "args": ["<dist>/bin/bir-hooks.js", "ensure"], "timeout": 30 }
-```
-
-`bir-hooks ensure` reads the SessionStart payload from stdin, starts the
-recorder for this directory in the background when none answers `/health`, and
-relays the payload to it. It *replaces* the HTTP SessionStart hook rather than
-sitting beside it: Claude Code runs every hook of an event in parallel, and an
-HTTP hook racing the daemon it depends on would fail on every first session of
-the day. It prints nothing on stdout — which Claude Code adds to the model's
-context — unless the control server answered with something, and it always exits
-0: a recorder that would not start is one line on stderr and a session that
-records Tier 2, exactly what happened before the hook existed.
-
-Every other event (`UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`,
-`SessionEnd`, …) stays an HTTP hook aimed at the control server, with the
-project's bearer token in its `Authorization` header.
-
-A pinned-npx install keeps the HTTP SessionStart hook: resolving a package
-inside a hook is too slow to start a recorder from, so those installs need a
-recorder somebody started (`bir up`).
-
-`bir doctor` checks that the hook's `command` still exists and, when it does
-not, reports:
-
-```
-the SessionStart hook in <file> points at a Node that is gone (<command>) — run `bir setup` here again
-```
-
-That is the failure a version manager's per-shell directory produces, and it is
-why the bootstrap script installs a private Node rather than pin one that lives
-under `fnm_multishells` or `.nvm` (§5.1).
-
-### 4.3 One port and one token per project
-
-`~/.baseinstrunner/installed.json` keeps a record per project directory:
-
-```
-projects[<normalised cwd>] = { port, token, replay, invocation }
-```
-
-**Port.** The first project on a machine gets 53411; the next gets the lowest
-port above it that no other project holds *and* that is free right now — it is
-bound once to check, because 53411 sits inside the ranges Hyper-V and WSL
-reserve on Windows, and a recorder told to use an excluded port exits while every
-session records Tier 2. Once recorded the port is kept; the hooks name it.
-`bir setup --port <n>` (or `bir install --port <n>`) overrides. A *background*
-recorder — the one the hook, `bir up` or `bir setup` starts — for a project with
-a recorded port (or with `BIR_CONTROL_PORT` set) does not fall back to an
-ephemeral one: it exits 1 with `control.port_busy` on its log, whose `fix` reads
-"port N is held by another program or excluded by the system — run `bir setup
---port <another>` in this directory", and the hook turns that into one stderr
-line, rather than let the project's hooks post to whatever else is listening
-there. `bir-hooks` run by hand in a terminal still falls back to an ephemeral
-port, and says so on the same log line. Two projects used to share 53411 and one
-project's steps landed in the other's run; this is the fix.
-
-**Invocation.** `global`, `local` or `npx` — what the entries were generated
-with, so a later flag-less `bir install` keeps the same shape (§4).
-
-**Token.** Generated once per project, so a token in one project's settings
-file opens that project's recorder and no other. A record written by 0.2.8 has
-none and falls back to the machine-wide `token` in the same file.
-
-**Replay.** The switches `bir replay on|off|allow …` and
-`bir setup --allow-servers` store, read by the recorder at start (§5.1).
-
----
-
-## 5. Provisioning a runner
-
-Four scopes, and conflating them is the usual source of "installed but never
-runs":
-
-| Scope | How often | What it does |
-|---|---|---|
-| **machine** | once | Node ≥ 20 and the package. The served line uses the machine's Node when it qualifies and otherwise puts a private one under `~/.baseinstrunner/node/`; the package goes under `~/.baseinstrunner/npm/`, and `bir` / `bir-hooks` launchers in `~/.baseinstrunner/bin/`, first on the user PATH |
-| **account** | once per user | the sign-in → `~/.baseinstrunner/credentials.json` (0600); the service address → `~/.baseinstrunner/config.json`. `bir setup` stores both; so does `bir login` |
-| **project** | once per repo | `bir setup` in that directory: `bir install --global --replay` (`--local` from a checkout) rewrites the MCP entries, wires the hooks into `.claude/settings.local.json`, records the port, token and invocation |
-| **session** | while recording | the recorder — `bir-hooks` as a background process — started by the SessionStart hook, discovered by `sha256(normalised cwd)` |
-
-That cwd keying is why the recorder must run in the *same directory* the agent
-session runs in. A control server started elsewhere is invisible, and the run
-silently degrades to Tier 2. It is also why the hook is what starts it: the hook
-already runs in the right directory, with the right environment, at exactly the
-right moment.
-
-### 5.1 One command
-
-The console's *Set up the runner* page shows one line, with a fresh one-time
-setup token filled in, to paste into a terminal opened in the project folder:
-
-```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
-```
-
-The first is Windows PowerShell, the second the same line from cmd.exe (a
-terminal opened from Start is often cmd), the third macOS and Linux. Without the
-variable the line still installs everything; `bir setup` then opens the browser
-for the device flow — even under the scripts, where its output is a pipe — and
-over SSH prints the link instead (§7).
-
-The scripts are [`scripts/install.ps1`](../scripts/install.ps1) and
-[`scripts/install.sh`](../scripts/install.sh); they replace
-`install-runner.ps1` and `install-runner.sh`, and they ship in the tarball. The
-API serves copies at `/install.ps1` and `/install.sh` with two placeholders
-filled in: `__BIR_AUTH_URL__` (the service's `PUBLIC_API_URL`, else the origin
-the request arrived on) and `__BIR_VERSION__` (`RUNNER_VERSION`, default
-`latest`). Run straight from the repository or the tarball the placeholders are
-unreplaced, which counts as unset: `BIR_AUTH_URL` must then be in the
-environment, and the version is `latest`.
-
-What they do, in order, the same on every platform:
-
-0. **Stop before any download** if the current directory is the home folder or
-   a drive root: "This is your home folder. Open a terminal in the project you
-   start Claude Code in (cd there) and paste the line again." Nothing is
-   installed, nobody is signed in and the token is unused, so the fix is
-   exactly that — `cd` to the project and paste the *same* line
-   (`BIR_PROJECT=<dir>` names the project instead; the script `cd`s there
-   first). Move `BIR_SETUP_TOKEN` out of the environment into a local variable,
-   so npm, the Claude Code installer and the `claude` the person starts next
-   never see it.
-1. **Node.** A Node ≥ 20 already on PATH is used by its real binary — unless
-   that binary is one the hook must not pin: under a version manager's
-   per-shell or per-version directory (nvm, fnm, Volta, asdf, mise and nodenv
-   on every platform; Scoop on Windows) or, on macOS and Linux, a Homebrew Node
-   (`*/Cellar/*` — a `brew upgrade` moves the path the hook pinned) or a snap
-   one. Both scripts also insist on npm's `npm-cli.js` beside the binary
-   (`lib/node_modules/npm/bin/` on macOS and Linux, `node_modules\npm\bin\` on
-   Windows). Otherwise a private Node is installed instead: pinned version,
-   digest embedded in the script and checked, unpacked to
-   `~/.baseinstrunner/node/v<V>/`, never put on PATH. The SessionStart hook
-   pins an absolute node path, and a path that changes with the shell is a
-   hook that fails every session. `BIR_NODE_ARCHIVE=<file>` uses a downloaded
-   archive instead of nodejs.org.
-2. **The package.** `@basein/runner@<version>` into the private prefix
-   `~/.baseinstrunner/npm`, always — never the machine's npm prefix, which is
-   root-owned under a `.pkg` or apt Node and per-version under nvm, Volta, Scoop
-   or asdf, where a global install vanishes on the next switch.
-   `BIR_TARBALL=<file.tgz>` instead of the registry. Launchers go into
-   `~/.baseinstrunner/bin`, which is put first on the user PATH; in PowerShell
-   `bir` then resolves to `bir.cmd`, so there is no execution-policy change,
-   ever. The PowerShell window the line was pasted into gets `bir` in place —
-   the script's last two lines are "bir works in every new terminal (and in
-   this window when it is PowerShell); `bir doctor` checks the setup" and the
-   cmd hint below — but the cmd variant
-   runs the script in a child `powershell.exe`, so a cmd window sees `bir` only
-   once it is a new window, or after the `set PATH=…` line the script prints
-   for it. On macOS and Linux the script prints the
-   `export PATH="$HOME/.baseinstrunner/bin:$PATH"` line for the terminal it ran
-   in (with `~/.local/bin` added when it just installed Claude Code); every new
-   terminal has it from the profile.
-3. **Claude Code**, through its official installer, when `claude` is not on
-   PATH. `BIR_NO_CLAUDE=1` skips it. It needs a Claude subscription and asks to
-   sign in the first time it starts.
-4. **`bir setup --auth-url <url> --project <cwd>`**, with the token in that
-   child's environment only. It signs in, stores the service address, runs
-   `bir install --global --replay`, starts the recorder in the background, and
-   prints a summary that names the account, the wrapped servers (`(no MCP
-   servers here)` and "steer mode only" mean none in *any* scope — `.mcp.json`,
-   and the user and local scopes of `~/.claude.json`), the recorder's pid and
-   log file, and the one thing left to do: `claude`.
-
-Both scripts are idempotent, neither prompts (under `curl | sh` stdin is the
-script itself), and `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` and
-`NODE_EXTRA_CA_CERTS` pass through — to the scripts' own downloads and to every
-node and npm they run. The one fetch they cannot reach is the `irm` that fetches
-the script itself: Windows PowerShell 5.1's `irm` uses the system (WinINET)
-proxy, not `HTTPS_PROXY`. `bir setup` exits 1 when the recorder reports it has
-no session to record with, so a provisioning script can gate on the exit code.
-
-The scripts never reach `bir setup` from the home folder (step 0). `bir setup`
-run *by hand* there, with the runner already installed, is different: it keeps
-the sign-in, wires nothing, prints the two commands left — `cd <project>` and
-`bir setup` — and exits 0. The second needs no token; the session is cached.
-That is also how a second project on the same machine is added.
-
-Fleet switches on `bir setup`: `--allow-servers a,b` stores the servers replay
-may call unattended for this project; `bir replay allow|on|off|status` changes
-it later. Both live in the project record (§4.3), so a recorder the hook starts
-— with Claude Code's environment, not the operator's terminal — keeps them;
-`BIR_REPLAY`, `BIR_REPLAY_ALLOW_SERVERS` and `BIR_MIN_STEER_SIMILARITY` in the
-recorder's environment still override, and `bir doctor` says which source is in
-effect. `--no-replay` records without the scenario server; `--no-daemon` wires
-everything and starts nothing; `--no-browser` prints the sign-in link without
-opening one.
-
-Two things the scripts deliberately do not do: supervise the recorder (the hook
-does, §5.2) and mint the token (the console does, §7).
-
-The PowerShell script is **pure ASCII** on purpose. Windows PowerShell 5.1
-decodes a BOM-less `.ps1` using the machine's ANSI codepage, and PowerShell
-accepts curly quotes as string delimiters — so a UTF-8 em-dash in a comment can
-decode into a quote and swallow the rest of the file. It parsed fine on one
-machine and failed on another before this was fixed. Keep it ASCII. It also
-never calls `exit` — under `iex` that closes the person's window — and it sets
-strict mode and `$ErrorActionPreference` inside a function so neither leaks into
-the caller's session.
-
-### 5.2 Keeping the recorder alive
-
-Not needed. The SessionStart hook is `bir-hooks ensure` (§4.2): every Claude
-Code session in the project starts the recorder when there is none, in the
-background, so a recorder that died or was never started is running by the first
-prompt. Nothing has to stay open. `bir up` starts it by hand, `bir up --restart`
-replaces it, `bir down` stops it — it asks first (`POST /control/stop`, which
-finishes the run being written), signals only a pid that answered `/health` with
-the token, and says "forced" when it had to — and `bir status` and `bir doctor`
-show its pid and log. Two Claude Code windows opened together take a lock, so
-only one spawns.
-
-On POSIX the daemon is a detached spawn with its stdio ignored. On Windows it is
-launched through `Start-Process -WindowStyle Hidden` in a short-lived
-`powershell.exe`, because a node started under a PowerShell layer carries an
-extra copy of its stdout pipe and a daemon that inherited it would hold that pipe
-open for days.
-
-Its audit lines go to `~/.baseinstrunner/logs/<project-key>.log`: the daemon
-opens the file itself, appends, and rolls it to `.1` when it starts and the
-file is past 8 MB. `bir status` names the file. The old shape still works —
-`bir-hooks` in a terminal writes them to that terminal — and is what the hook
-does for you.
-
-```bash
-grep version.skew ~/.baseinstrunner/logs/*.log
-grep run.lossy    ~/.baseinstrunner/logs/*.log
-```
-
-What the hook does not give you is restart-on-crash mid-session, which the
-proxies already survive (they fall to Tier 2 and say so). A service manager is
-optional. If you want one — a machine that records SDK sessions with nobody
-starting Claude Code, or a recorder up before the first session — have it run
-`bir up` in the project directory at logon, and nothing else: `bir up` returns
-once the recorder answers and leaves it running, so a supervisor must not expect
-a long-lived process. The three recipes below are recipes — nothing the package
-ships or its tests cover.
-
-**Windows** — a Scheduled Task at logon, with *Start in* set to the project
-directory (`bir.cmd` is the launcher the served line writes; a by-hand install
-has `bir` wherever npm put it):
-
-```powershell
-$action  = New-ScheduledTaskAction -Execute "$env:USERPROFILE\.baseinstrunner\bin\bir.cmd" -Argument 'up' -WorkingDirectory 'C:\work\repo'
-$trigger = New-ScheduledTaskTrigger -AtLogOn
-Register-ScheduledTask -TaskName 'bir up (repo)' -Action $action -Trigger $trigger
-```
-
-**macOS** — a launchd agent at `~/Library/LaunchAgents/com.basein.up.plist`
-running `$HOME/.baseinstrunner/bin/bir up` with `WorkingDirectory` set to the
-project and `RunAtLoad` (not `KeepAlive`), then `launchctl load` it.
-
-**Linux** — a systemd user unit, `Type=oneshot` with `RemainAfterExit=yes` (so
-the unit does not stop and take the recorder down with it), `ExecStart=%h/.baseinstrunner/bin/bir up`,
-`WorkingDirectory=` the project, plus `loginctl enable-linger "$USER"` so it
-runs without a login session.
-
-### 5.3 Verify
-
-```bash
-bir doctor --json      # exits non-zero if it is not working right now
-```
-
-`bir doctor` asks the control server which proxies actually registered; it never
-reads the config file back. That makes it the right gate for a provisioning
-script. `bir status` only describes intent. `bir doctor` also says when there is
-no recorder ("no control server for this directory — recording will be Tier 2
-(MCP only); `bir up` starts one, and the SessionStart hook starts one with each
-session"), when the recorder has nowhere to record to ("the recorder is running
-but has nowhere to send steps — run `bir setup` (or set BIR_AUTH_URL and
-`bir login`), then `bir up --restart`"), and when the SessionStart hook names a
-Node that is gone (§4.2).
-
----
-
-## 6. Machines with no registry
-
-Zero dependencies makes offline install trivial — no `npm ci --offline`, no
-vendored `node_modules`. The install script ships in the tarball, takes a local
-tarball instead of the registry and a local Node archive instead of nodejs.org,
-and can skip the Claude Code installer:
-
-```bash
-# on a connected machine
-npm pack @basein/runner@<version>          # or download the Release asset
-tar -xzf basein-runner-<version>.tgz package/scripts
-# plus the Node archive for the runner's platform from nodejs.org/dist, if the
-# runner has no Node ≥ 20 (the script names the pinned version, 24.21.0)
-
-# on the runner
-BIR_AUTH_URL=https://api.example.com \
-BIR_TARBALL=./basein-runner-<version>.tgz \
-BIR_NODE_ARCHIVE=./node-v24.21.0-linux-x64.tar.gz \
-BIR_NO_CLAUDE=1 sh ./package/scripts/install.sh
-```
-
-```powershell
-$env:BIR_AUTH_URL='https://api.example.com'; $env:BIR_TARBALL='.\basein-runner-<version>.tgz'; $env:BIR_NODE_ARCHIVE='.\node-v24.21.0-win-x64.zip'; $env:BIR_NO_CLAUDE=1; Get-Content -Raw .\package\scripts\install.ps1 | iex
-```
-
-`<version>` is whatever the registry holds (`npm view @basein/runner version`).
-The PowerShell line pipes the file through `iex`, as the served line does: a
-`.ps1` invoked by path is subject to the execution policy, and a default client
-(Restricted) refuses it with "running scripts is disabled". The script is
-written to be run that way — everything inside one function, no `exit`.
-
-`BIR_AUTH_URL` is required here because the raw script's placeholder is
-unreplaced (§5.1). Claude Code has to come from somewhere too; `BIR_NO_CLAUDE=1`
-only stops the script from fetching it. The service itself must be reachable —
-"no registry" is not "no network" — or the sign-in has nothing to talk to.
-
-`bir setup` passes `--global`, so the resulting configs contain absolute paths
-and never reach for a registry. Nothing further is needed.
-
-Note that a private repository's Release assets require a GitHub token to fetch,
-so the tarball has to be carried to the runner by whatever means you already use.
-
----
-
-## 7. Headless authentication
-
-`bir login` signs in through the browser — the OAuth 2.0 device grant (RFC 8628,
-[loginWeb.md](loginWeb.md)) — and caches
-`{accessToken, refreshToken, accessExpiresAt, user, authUrl}` at
-`~/.baseinstrunner/credentials.json`, mode 0600. `bir setup` does the same
-sign-in and stores the service address beside it in
-`~/.baseinstrunner/config.json`, so no process afterwards needs `BIR_AUTH_URL`
-(it still overrides when set).
-
-**The setup token.** The served line carries `BIR_SETUP_TOKEN`: a one-time token
-minted by the console's *Set up the runner* page — ten-minute TTL, single use,
-hashed at rest, and minting a new one retires the person's earlier unused ones.
-It travels as an environment-variable assignment rather than an argument so that
-it is never on a command line, where a process listing would show it; the
-variable's *name* is what keeps the pasted line out of PSReadLine's on-disk
-history, which drops lines containing "token" (a `--token` argument would be
-dropped just the same). The script moves it out of the environment as its first
-statement and hands it to `bir setup` through that child's environment only;
-`bir setup` deletes it again the moment it has read it, so the recorder it
-starts never holds it. By hand: `bir setup --token <t>` or
-`bir login --token <t>`. It signs in one person on one machine with no browser
-step; it is not a fleet credential.
-
-What `bir setup` says about a token that is not fresh:
-
-- pasted a second time after a successful paste — "the setup token was already
-  used; keeping the sign-in from before (<email>)", and it goes on; that is the
-  upgrade path (§8) and the retry after a failure past the sign-in;
-- used or expired, with no cached sign-in to keep — "this setup token has
-  expired or was already used — make a new one on the console's Set up the
-  runner page and paste it within ten minutes";
-- not a token at all — "that is not a valid setup token — copy the whole token
-  from the console's Set up the runner page".
-
-"sign-in failed: …" is reserved for the unexpected, and "not signed in — run
-`bir setup` again (or `bir login`)." for a sign-in that ended with no session.
-
-**Credentials are bound to the service that issued them.** `credentials.json`
-carries `authUrl`, and `authenticate()` refuses to use or refresh a session
-against another origin — `auth.url_mismatch` on the audit log, and the runner
-records nothing rather than send a session where it was not minted. A file from
-before the binding is trusted as before. So a copied `credentials.json` works
-only where `config.json` (or `BIR_AUTH_URL`) names the same service, and a stale
-`BIR_AUTH_URL` in a profile file now means "not recording" — `bir setup` warns
-when the environment names a different address than the one being set up, or
-than the stored one (a bare `bir setup` in a second project included), and says
-to remove the variable.
-
-**For a machine with a person attached, headless is no longer a problem.** The
-runner prints a link and a short code and waits; the link opens on *any* device,
-so a box with no browser, no display, or only an SSH session is signed in from a
-phone. Nothing is typed into the terminal, so nothing lands in a shell history or
-a CI transcript. `bir login --no-browser` (or `bir setup --no-browser`) skips
-even trying to open one, which is the right flag in a provisioning script (over
-SSH it is the default; a pipe on stdout is not — under the install scripts
-`bir setup` still opens the browser, because somebody just pasted the line). The
-setup token removes even the waiting.
-
-For machines with **no person attached**, in order of preference:
-
-1. **A service account, signed in once.** Approve the device code for a dedicated
-   account, then copy `credentials.json` to each machine at 0600, together with
-   a `config.json` naming the same service. The rotating refresh token keeps it
-   alive and nothing ever prompts. It is still a shared long-lived secret, so
-   never a person's account.
-2. **No service address at all** for runners that should record nothing: no
-   address in `~/.baseinstrunner/config.json` and no `BIR_AUTH_URL`. The
-   recorder then starts with a null recorder (`recorder.disabled` on its log)
-   and everything else still works; `bir up` and `bir doctor` exit 1 to say so.
-   `BIR_AUTH_DISABLE=1` is *not* that: it fakes a session and records with a
-   bogus token — a local-dev and CI switch, not a fleet one.
-3. **Ask the service for a non-interactive grant** — a long-lived runner token,
-   created in the console and read from an env var. This remains the right answer
-   for a large fleet and is still a service-side change; the device grant and the
-   setup token make it less urgent, not unnecessary.
-
-`bir logout` revokes the session server-side before clearing the file, so
-decommissioning a runner ends its access rather than merely tidying the disk.
-
-`BIR_HOME` relocates all of this if state belongs somewhere other than
-`~/.baseinstrunner`.
-
----
-
-## 8. Updating a runner
-
-Paste the line again — the same line, used token and all. It installs the
-version the service serves (`RUNNER_VERSION`, default `latest`), keeps the
-sign-in it already has ("the setup token was already used; keeping the sign-in
-from before (<email>)"), and runs `bir setup`, which re-wraps whatever moved and
-restarts the recorder. For a machine installed by hand: the new package, then
-`bir setup` in each recorded project.
-
-```bash
-npm i -g @basein/runner@<version> && cd ~/work/repo && bir setup
-```
-
-Two rules used to follow, and neither is a step now:
-
-- **Restarting the recorder.** A running process is still the old code, and
-  this was the step people forgot. `bir setup`, `bir up` and the SessionStart
-  hook all restart a running recorder whose version is not the package's —
-  provided no session is mid-run. A recorder still serving an open Claude Code
-  session is left alone; `bir setup` says so ("recorder 0.2.8 is still serving
-  an open Claude Code session; it restarts to 0.2.9 with the next session") and
-  the next session's hook does it. `bir up --restart` forces it now.
-- **Re-running `bir install`.** `bir setup` does. A `--global` entry whose path
-  did not change needs nothing (§4); one whose runner moved — a new prefix, a
-  new Node — is re-wrapped from the stashed original; a pinned-npx entry always
-  has its pin moved.
-
-Rolling back: install the older version by hand and run `bir setup`.
-
-### The half-upgraded machine
-
-This is the update failure that looks like success: the package is new, but a
-proxy is still the old code because a config points elsewhere, or the recorder
-is a process that outlived the upgrade. Everything keeps working, and quietly
-runs code you did not ship.
-
-The restart-on-skew above closes the common case. For the rest, a proxy reports
-its version when it registers, the control server compares it with its own, and
-a mismatch is one line on the audit log:
-
-```
-[bir] … version.skew server=fleet proxy=0.0.9 hooks=0.1.0 fix="restart bir-hooks after upgrading, …"
-```
-
-`bir doctor --json` carries the same facts structurally — under `health`,
-`hooksVersion` and a `version` on each entry of `registeredProxies` — so a
-provisioning script can assert agreement rather than grep a log. A proxy too old
-to report a version is not treated as skewed: silence, not a false alarm.
-
----
-
-## 9. Per-release verification
-
-CI does this on three platforms. To do it by hand on a clean machine:
-
-```bash
-npm run build && npm test          # ~400 tests (npm runs pretest first)
-npm run test:smoke                 # real processes: hooks + proxy + scenario over stdio;
-                                   # needs the build and the pretest above
-npm pack && npm i -g ./basein-runner-*.tgz
-cd /tmp/scratch && bir setup --auth-url <api> --token <t>   # or BIR_AUTH_URL=<api> bir login, then bir install --global && bir up
-bir doctor --json                  # must exit 0
-bir uninstall                      # must restore the config byte-for-byte
-```
-
-`test:smoke` is the one that matters for packaging: it is the only test that
-crosses process boundaries, which is exactly where a bad `files` list, a missing
-shebang, or a broken bin mapping shows up.
-
-Sandbox a manual run with `BIR_HOME` and `BIR_CLAUDE_JSON` so it cannot touch
-your real Claude Code configuration. A fresh `BIR_HOME` has no sign-in, which is
-why the recipe signs in: a bare `bir install --global && bir up` there starts a
-recorder with nothing to record to, `bir up` ends with "it has no session to
-record with" and exit 1, and `bir doctor --json` exits 1 for the same reason.
-`bir uninstall` restores byte-for-byte only what nothing else edited since the
-install; a file it created stays behind, empty of our entries.
-
----
-
-## 10. Where things stand
-
-| # | Item | State |
-|---|---|---|
-| 1 | Name settled; `PACKAGE_NAME` aligned | done |
-| 2 | `repository` + `publishConfig`; provenance deferred (private repo) | done |
-| 3 | Tarball trimmed — no dead sourcemaps, no scratchpad; `scripts/` ships | done |
-| 4 | npx spec pinned; `--global` added; moved runners re-wrapped | done |
-| 5 | CI and release workflows, three platforms | done |
-| 6 | `scripts/install.{ps1,sh}`, served by the API at `/install.ps1` and `/install.sh` (replace `install-runner.*`) | done |
-| 7 | Version-skew detection on registration; recorder restarts itself between sessions | done |
-| 8 | UTF-8 BOM tolerated in MCP configs | done |
-| 9 | npm org `basein`, `NPM_TOKEN` secret | done |
-| 10 | `bir setup`: sign-in, wrap, replay, recorder in one command | done |
-| 11 | Background recorder started by the SessionStart hook (`bir-hooks ensure`); `bir up` / `bir down`; log per project | done |
-| 12 | Hooks in `.claude/settings.local.json` + `.git/info/exclude`; one port and token per project | done |
-| 13 | Setup token (`BIR_SETUP_TOKEN`) for the first sign-in; credentials bound to their service; address in `config.json` | done |
-| 14 | Tag `v0.2.9` to publish | ready |
-| 15 | Non-interactive auth grant for fleets | **needs the service** |
-| 16 | Migrate to trusted publishing before Jan 2027 (§3.3) | scheduled |
-
-Item 15 is the only one that needs somebody else.
-
----
-
-## Appendix: the BOM
-
-`bir` used to reject any MCP config saved with a UTF-8 byte order mark. Notepad
-writes one, so does VS Code's "UTF-8 with BOM", and so does PowerShell's
-`Out-File -Encoding utf8`. `readFileSync(path, "utf8")` decodes the BOM to U+FEFF
-rather than consuming it, and `JSON.parse` then rejects the file.
-
-The failure mode was the bad part: `bir install` logged the parse error and
-**still reported success**, so an operator saw a green run and no wrapping. On
-Windows runners this was a matter of time.
-
-`parseJsonFile` now strips it, which covers every user-authored config read.
-Restoring is unaffected — the uninstall backup stashes raw text on a separate
-path, so a BOM'd file comes back with its BOM intact.
+# Packaging BaseInstRunner for runner machines
+
+**The approach: publish to npm as `@basein/runner`, and install it globally at a
+pinned version.** The code already assumed this — the installer wrote an `npx`
+invocation of its own package name into every wrapped MCP entry (it still does
+with `--npx`, §4) — so publishing was less a new distribution channel than
+closing a loop that was already there.
+
+This is the fleet-facing reference: what ships, how a runner machine goes from
+bare to recording, how it gets updated, and what to do when there is no registry
+to reach. For one person setting up one machine, [quickstart.md](quickstart.md)
+is shorter and assumes nothing.
+
+**Status.** Everything here is implemented except the last item of §7: a
+non-interactive grant for machines with no person attached needs a service-side
+decision rather than a change here.
+
+---
+
+## 1. Why this package is an easy case
+
+| Property | Value | Why it matters for packaging |
+|---|---|---|
+| Runtime dependencies | **none** | The tarball is self-contained. No lockfile resolution, no transitive CVEs, no native builds, and offline install just works. |
+| Module format | pure ESM (`"type": "module"`) | No dual-build gymnastics. |
+| Node floor | `>=20` | The one prerequisite — and the served line installs a private copy when the machine has none, or only one the hook must not pin: a version-managed, Homebrew or snap Node, or one with no npm beside it (§5.1). |
+| Build | `tsc` → `dist/`, `prepublishOnly` wired | `npm publish` cannot ship a stale `dist/`. |
+| Bins | `bir`, `bir-proxy`, `bir-hooks`, `bir-scenario`, all with `#!/usr/bin/env node` | npm creates the shims, including `.cmd`/`.ps1` on Windows. |
+| Tarball | 161 files, ~910 kB | `dist/` + types + docs + `production.md` + `scripts/` (the install scripts, so a tarball can bootstrap an offline machine). Sourcemaps and `docs/next.md` are excluded. |
+
+A zero-dependency, pure-JS, four-bin package is the best-behaved thing npm
+distributes. The delivery does not need to be clever.
+
+### What is excluded, and why
+
+`files` carries two negations:
+
+- `!dist/**/*.map` — 146 files, ~1.2 MB. The maps carry no `sourcesContent`, and
+  `src/` is not published, so they cannot resolve a single stack frame. They were
+  bytes that did nothing on every install and every `npx` cold start.
+- `!docs/next.md` — a working scratchpad, not documentation.
+
+The rest of `docs/` **does** ship, and deliberately: the GitHub repository is
+private, so for anyone on a runner machine the tarball is the only place this
+documentation exists.
+
+---
+
+## 2. The options, and why this one
+
+| Approach | Runner install | Good for | Cost |
+|---|---|---|---|
+| **npm registry (public)** ← chosen | `npm i -g @basein/runner@0.1.0` | the default; makes the generated entries resolvable | the code is public |
+| npm registry (private, scoped) | same, plus an `.npmrc` token | code you cannot publish | every runner needs a read token, and so does `npx` |
+| GitHub Packages | same, `registry=https://npm.pkg.github.com` | no second account | GH tokens are clumsier to rotate across a fleet |
+| Tarball from a Release | `npm i -g ./basein-runner-0.1.0.tgz` | airgapped runners | no registry resolution — see §6 |
+| `npm i -g git+ssh://…#v0.1.0` | one line, no registry | a handful of machines | needs git and a toolchain on every runner; slowest and most fragile |
+| Node SEA / bundled binary | copy one file | machines where Node cannot be installed | you own a three-OS build matrix |
+| **Docker** | — | **not suitable** | The proxy spawns the host's own MCP servers as child processes, rewrites config in the user's home, and shares a cwd with the agent session. A container isolates exactly what this tool must reach. |
+
+The package is public; the repository is private. Those are separate decisions
+and this project makes them differently. Nothing operational leaks either way —
+the service is gated by its address plus credentials.
+
+---
+
+## 3. Publishing
+
+### 3.1 Manifest — done
+
+`package.json` carries `repository` (npm requires it for provenance) and
+`publishConfig.access: public` (a scoped package is private by default, and
+`npm publish` on a scope you have no paid plan for otherwise fails).
+
+There is deliberately **no** `provenance`, and no `--provenance` in the workflow:
+npm's attestation requires a *public* repository. Turn both on the day that
+changes; nothing else has to move.
+
+`homepage` and `bugs` are also omitted, for the same reason — they would be dead
+links on a public package page.
+
+### 3.2 The name is load-bearing
+
+`PACKAGE_NAME` in [generate.ts](../src/config/generate.ts) is written into every
+config file the installer produces. Renaming after runners are deployed points
+every previously-installed project at a package that no longer resolves. It is
+settled now; treat it as fixed.
+
+### 3.3 The publishing credential
+
+The `basein` org exists on npmjs.com (free tier, public packages), and
+`NPM_TOKEN` is set as a repository secret in GitHub Actions.
+
+It is a **granular** token, not a classic automation one, because npm now steers
+you there:
+
+| Property | Value |
+|---|---|
+| Name | `github-actions-release` |
+| Scope | `basein`, read and write |
+| Organizations | no access — publishing needs the scope, not org administration |
+| 2FA | bypassed, which is what lets CI publish unattended |
+| **Expires** | **2026-10-05** |
+
+**Two dates to keep.**
+
+*2026-10-05 — the token dies.* Granular tokens must carry an expiry; npm offers
+no perpetual option. When a release starts failing with `ENEEDAUTH` around then,
+this is why. Regenerate with the same settings and overwrite the secret.
+
+*January 2027 — direct token publishing ends.* The token summary says so
+outright: "Publish new versions directly (deprecated — ends January 2027)". The
+replacement is **trusted publishing**, where the workflow authenticates to npm
+over OIDC and there is no stored credential at all — no secret to leak, and no
+expiry to forget. Migrating also removes the first date above, so doing it before
+2026-10-05 turns two chores into one.
+
+Releasing is then a tag:
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+### 3.4 The workflows — done
+
+- [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) — every push and PR
+  to main, on Ubuntu, Windows and macOS.
+- [`.github/workflows/release.yml`](../.github/workflows/release.yml) — on a
+  `v*` tag: the same three-platform suite, then publish, then attach the tarball
+  to a GitHub Release.
+
+Three platforms is not decoration. `resolveCommand` shells a `.cmd` upstream
+through `cmd.exe` with its own quoting, and `normalizePath` reconciles Claude
+Code's forward slashes with `process.cwd()`'s backslashes — the failure the code
+itself calls "the number one cause of *installed but never runs*". Neither is
+exercised on Linux.
+
+Both workflows run `npm run build` before the tests, because `test:smoke` spawns
+the real binaries out of `dist/` while `npm test` only builds `.test-build/`.
+
+The release job refuses to publish when the tag disagrees with `package.json` —
+npm has no undo past 72 hours, and a mismatched tag publishes a version nobody
+asked for.
+
+**One known flake.** `run_scenario finds the session whose plan is armed` loses
+an arming race roughly one run in three. It is unrelated to packaging, and the
+test steps retry once so it cannot redden a release at random. Remove the retry
+the day that test is made deterministic.
+
+---
+
+## 4. What `bir install` writes
+
+Three invocation modes, one flag each:
+
+| Mode | Flag | Entry |
+|---|---|---|
+| **global** | `--global`; the flag-less default when `bir` runs from an installed package | `<node> [flags] <prefix>/lib/node_modules/@basein/runner/dist/bin/bir-proxy.js …` (Windows: `<prefix>/node_modules/@basein/runner/…`) |
+| **npx** | `--npx`; the flag-less default only from a checkout or from npx's cache | `npx --prefer-offline -y -p @basein/runner@0.2.9 bir-proxy …` — plain `npx` on Windows too; only the npx SessionStart hook runs through `cmd /c` there |
+| **local** | `--local` | `<node> [flags] <this checkout>/dist/bin/bir-proxy.js …` |
+
+Where the entries are written — this project's local scope in `~/.claude.json`,
+not `.mcp.json` — is §4.4.
+
+`<node>` is the Node that ran the install, by absolute path: on macOS and Linux
+with symlinks resolved, except that a Homebrew keg is named by Homebrew's stable
+`opt/<formula>/bin/node` link, which a `brew upgrade` keeps; on Windows the path
+it was launched through (nvm-windows' and Scoop's stable links), except fnm's
+per-shell directory. A Node that a version manager will move gets a one-line
+warning at install. `[flags]` are `--use-system-ca` when the install ran with
+it, and `--use-env-proxy` when it did or a proxy is set — either way only while
+`NO_PROXY` exempts `127.0.0.1` (§5.1). Under the served line that Node is the
+machine's own when it qualifies (20 or newer, not under a version manager, npm
+beside it), else the private Node in `~/.baseinstrunner/node/v<V>/`; `<prefix>`
+is `~/.baseinstrunner/npm` either way. By hand it is whatever `npm i -g` used.
+npm's global layout differs by platform:
+the package is at `<prefix>/lib/node_modules/@basein/runner` on macOS and Linux
+and at `<prefix>/node_modules/@basein/runner` on Windows.
+
+**The npx spec is pinned.** It was not, and that was the one real defect in the
+original packaging story: two runners provisioned a week apart could run
+different proxy versions against the same service, with nothing in a recording to
+say which. Pinned is also what makes `--prefer-offline` safe: a cached copy of an
+exact version starts without asking the registry.
+
+**Absolute paths are what a fleet wants**, and they are the default: a flag-less
+`bir install` from an installed package writes `global` entries, and `bir setup`
+runs `bir install --global --replay` in-process (from a checkout `--local`, since
+`--global` refuses one; run as `npx @basein/runner setup`, pinned npx, never a
+path into npx's cache). It removes the registry from the hot
+path entirely: no resolution before the MCP server can start, no dependence on
+the MCP host seeing the same `PATH` as the shell that installed things — which
+GUI-launched hosts on Windows do not — and it works with no network at all.
+
+It also survives upgrades. The path
+`<prefix>/lib/node_modules/@basein/runner/dist/bin/bir-proxy.js` contains no
+version, so `npm i -g @basein/runner@<version>` changes what that path points at
+without changing the path. **A pinned-npx install, by contrast, must re-run
+`bir install` on every upgrade** to move the pin.
+
+A flag-less `bir install` keeps the invocation the project was installed with
+(`invocation` in its record, §4.3): a `bir install --replay` after `bir setup`
+keeps the absolute paths instead of quietly turning every entry into a
+pinned-npx one. The one exception is a remembered npx that nobody asked for with
+`--npx` — the flag-less default of older versions — which an installed `bir`
+turns into absolute paths.
+
+**An entry whose runner moved is re-wrapped.** `bir install` regenerates each
+wrapped entry and compares it with what is there — its Node path and flags, its
+proxy path or pinned npx version, its control port, the upstream entry it
+wraps — and rewrites any that differ from its source:
+`~ fleet — re-wrapping: its runner moved (was …)`. The
+scenario entry gets the same check. That is what lets `bir setup` be the upgrade
+path even when the package changed prefix (from the machine's npm prefix to the
+private one) or the Node moved (a version manager, a reinstall), instead of
+printing "already wrapped" about an entry the host would keep spawning from a
+path that is gone.
+
+`--global` refuses to run from a checkout: it asserts a path that outlives the
+shell, and a checkout's `dist/` moves with the checkout. Use `--local` when you
+mean the checkout on purpose.
+
+### 4.1 Hooks go to `.claude/settings.local.json`
+
+Claude Code's hooks are written to `<project>/.claude/settings.local.json`, not
+to the `.claude/settings.json` a team commits. They carry a bearer token and an
+absolute path to this machine's Node; neither belongs in a teammate's clone.
+Inside a git repository `bir` adds the line `.claude/settings.local.json` to
+`.git/info/exclude` — the person's own, untracked list, never a `.gitignore` the
+team would see in a diff — and says so. A linked worktree's `gitdir:` pointer
+is followed to the repository's common exclude file, the only one git reads for
+it; nothing is created inside the worktree. Outside a repository, or when the
+exclude file cannot be written, that is a note, not a failed install.
+
+An install that finds `bir` hooks in a legacy `.claude/settings.json` removes
+them from there on the way (`- hooks removed from … (they live in
+settings.local.json now)`). `bir uninstall` cleans both files and takes the
+`.claude/settings.local.json` line out of `.git/info/exclude` again — unless the
+line was there before the install. It restores
+a file byte-for-byte only when nothing else edited it since the install; a file
+it created — usually `settings.local.json` itself — stays behind, empty of our
+entries.
+
+With `--replay`, `bir install` also adds the `bir` scenario server, beside the
+wrapped entries in this project's local scope (§4.4). Claude Code never asks
+before it starts a local-scope server, so there is no `enabledMcpjsonServers`
+pre-approval any more; an install finds an older one in `settings.local.json`
+and takes it out. Without `--replay`, in a project with no scenario server,
+replay is stored *off* (§4.3). `bir uninstall --replay` removes only the
+scenario server and switches replay off, restarting an idle recorder so that
+applies at once; the proxies and the hooks stay as they are, and
+`bir install --replay` turns both back on.
+
+### 4.2 SessionStart is a command hook
+
+Every install writes the SessionStart hook as a command hook in
+Claude Code's exec form — `command` spawned directly with `args` as its argument
+vector, no shell in between, so a path with a space needs no quoting and it runs
+the same under Git Bash, PowerShell and cmd.exe:
+
+```json
+{ "type": "command", "command": "<node>", "args": ["<dist>/bin/bir-hooks.js", "ensure"], "timeout": 15 }
+```
+
+(`args` begins with the node flags of §4 when there are any.) A pinned-npx
+install writes the same hook through npx —
+`npx --prefer-offline -y -p @basein/runner@<v> bir-hooks ensure --budget-ms 8000`,
+inside `cmd /c` on Windows — so npx's start-up is paid once per session and still
+fits the 15 s. The hook's own work is capped at 11 s (8 s for the npx form) and
+never waits on the BaseIn service.
+
+`bir-hooks ensure` reads the SessionStart payload from stdin, starts the
+recorder for this directory in the background when none answers `/health`, and
+relays the payload to it. It *replaces* the HTTP SessionStart hook rather than
+sitting beside it: Claude Code runs every hook of an event in parallel, and an
+HTTP hook racing the daemon it depends on would fail on every first session of
+the day. It prints nothing on stdout — which Claude Code adds to the model's
+context — unless the control server answered with something, and it always exits
+0: a recorder that would not start is one line on stderr and a session that
+records Tier 2, exactly what happened before the hook existed.
+
+Every other event (`UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`,
+`SessionEnd`, …) stays an HTTP hook aimed at the control server, with the
+project's bearer token in its `Authorization` header. Their timeouts are the
+longest a hung service could make a person wait, so they are short:
+`UserPromptSubmit` 10 s, `PreToolUse` 15 s, `PostToolUse`/`PostToolUseFailure`,
+`Stop`/`StopFailure` 5 s, `SubagentStart`/`SubagentStop` and `SessionEnd` 3 s.
+The control server answers each well inside its timeout, `{}` on an overrun
+(see [production.md](../production.md)). Re-running `bir setup` rewrites
+the timeouts of an older install.
+
+`bir doctor` checks that the hook's `command` and script still exist and, when
+the Node does not, reports:
+
+```
+the SessionStart hook in <file> points at a Node that is gone (<command>) — run `bir setup` here again
+```
+
+That is the failure a version manager's per-shell directory produces, and it is
+why the bootstrap script installs a private Node rather than pin one that lives
+under `fnm_multishells` or `.nvm` (§5.1).
+
+### 4.3 One port and one token per project
+
+`~/.baseinstrunner/installed.json` keeps a record per project directory:
+
+```
+projects[<normalised cwd>] = { port, token, replay, invocation, … }
+```
+
+The rest is bookkeeping for `bir uninstall`: whether the exclude line was
+added by the install, and every `.claude.json` the install wrote to
+(`CLAUDE_CONFIG_DIR` moves it, §4.4).
+
+**Port.** The first project on a machine gets 53411; the next gets the lowest
+port above it that no other project holds *and* that is free right now — it is
+bound once to check, because 53411 sits inside the ranges Hyper-V, WSL and
+Docker reserve on Windows, and a recorder told to use an excluded port exits.
+Once recorded the port is kept; the hooks name it.
+`bir setup --port <n>` (or `bir install --port <n>`) overrides. A *background*
+recorder — the one the hook, `bir up` or `bir setup` starts — for a project with
+a recorded port (or with `BIR_CONTROL_PORT` set) does not fall back to an
+ephemeral one, rather than let the project's hooks post to whatever else is
+listening there. It finds out who holds the port — the system's reservation,
+another project's recorder, another program — and exits 1 with
+`control.port_busy` on its log; its `fix` reads "run `bir setup --port <another
+port>` in <project> (below 49152 avoids the ranges the system reserves); the
+next Claude Code session then uses it". It also writes
+`~/.baseinstrunner/control/<key>.port.json`, which `bir doctor` reports as a
+problem ("the recorder could not take port N: …") and `bir status` as a `Port`
+line, and the hook adds one stderr line. When the holder is this project's own
+recorder, the new process steps aside and exits 0 (`control.already_running`).
+`bir setup` without `--port` repairs this itself: a recorded port this machine
+no longer lets it bind — reservations move across reboots — is replaced by the
+lowest free one ("port N is not available on this machine; this project moves
+to M"), and the hooks and entries are rewritten with it. `bir-hooks` run by hand
+in a terminal still falls back to an ephemeral port. Two projects used to share
+53411 and one project's steps landed in the other's run; this is the fix.
+
+**A port change with a window open.** Claude Code reads a session's hooks when
+the session starts, so a window opened before the port moved still posts to the
+old one. That recorder keeps serving it, as a *superseded* recorder — `bir
+status` lists it, it logs to `logs/<key>.superseded-<port>.log` — while a second
+one serves the new port. It exits by itself once it has had nothing to serve for
+a day (`BIR_SUPERSEDED_EXIT_MS`); `bir down` stops both.
+
+**Invocation.** `global`, `local` or `npx` — what the entries were generated
+with, so a later flag-less `bir install` keeps the same shape (§4).
+
+**Token.** Generated once per project, so a token in one project's settings
+file opens that project's recorder and no other. A record written by 0.2.8 has
+none and falls back to the machine-wide `token` in the same file. A running
+recorder re-reads the project's current token from this file (at most every
+3 s), so a reinstall that changes it needs no restart.
+
+**Replay.** The switches `bir replay on|off|allow …` and
+`bir setup --allow-servers` store, read by the recorder at start (§5.1).
+`bir setup --no-replay` and `bir uninstall --replay` store replay off, and so
+does a `bir install` without `--replay` where no scenario server is installed;
+an install with `--replay` turns such an off back on, but never a
+`bir replay off` of your own.
+
+### 4.4 Wrapped entries go to the local scope
+
+`bir install` does not rewrite `.mcp.json` or the user scope. It writes a
+wrapped copy of each server, under the same key, into this project's *local
+scope*: `projects[<key>].mcpServers` in `~/.claude.json` (in
+`$CLAUDE_CONFIG_DIR/.claude.json` when that is set, as Claude Code does), under
+the key Claude Code itself uses — the canonical git root, forward slashes on
+Windows. The local scope outranks the project and user scopes, so the copy is
+what Claude Code starts here, other projects are untouched, and the team's
+`.mcp.json` never carries this machine's paths.
+
+What is copied, and what is left as Claude Code runs it (its calls are still
+recorded by the hooks):
+
+- **A `.mcp.json` server only once Claude Code has approved it** — "Use this MCP
+  server", `enabledMcpjsonServers` or `enableAllProjectMcpServers` in a settings
+  file Claude Code honours for that. Claude Code asks before it starts a
+  `.mcp.json` server and never asks about a local-scope one, so a copy would
+  skip the question: a rejected server is never copied, and one never asked
+  about (a fresh clone) is left unwrapped with a line saying so. On a fresh
+  clone that means `bir setup`, then `claude` and approve the servers, then
+  `bir setup` again. `bir install --server <name>` wraps a pending one anyway,
+  and later installs remember it. A fleet that runs `claude -p`, where nobody
+  answers the question, sets `enableAllProjectMcpServers` in user or managed
+  settings.
+- **A remote (`http`/`sse`) server only when its entry carries a literal
+  credential header.** One Claude Code signs in itself — OAuth, a
+  `headersHelper`, `${VAR}` headers — would reach the proxy with no credentials
+  and answer 401, so it is left unwrapped; `--server <name>` wraps it anyway. A
+  wrapped remote entry carries its headers in its env (`BIR_UPSTREAM_HEADERS`),
+  not on the command line.
+- **Nothing** when managed settings set `allowManagedMcpServersOnly`, or match
+  servers by `serverCommand` or `serverUrl` — wrapping changes the command.
+- **Nothing in a subdirectory or a linked worktree** of a repository: Claude Code
+  keeps the local scope per repository, so a copy would apply to the root and
+  every worktree. Hooks only; `bir setup` in the root wraps the servers. From the
+  root, the install names the linked worktrees that now run the wrapped servers
+  too, and leaves a server alone where a worktree's own `.mcp.json` defines it
+  differently.
+
+A copy remembers what it copied. When the `.mcp.json` or user-scope entry
+changes, or its approval is withdrawn, `bir doctor` reports the copy (a changed
+or removed source exits 1), `bir status` marks it `STALE`, the SessionStart hook
+names it in the recorder log (`overrides.stale`), and `bir setup` copies it
+again or removes it. `bir install` refuses, changing nothing, when
+`~/.claude.json`, `.mcp.json`, `settings.local.json` or a `--config` file is not
+plain JSON (comments, a trailing comma). `bir uninstall` repairs
+`~/.claude.json` entry by entry; it never restores that file whole.
+
+`--mcp-json` (or `BIR_WRAP_MCP_JSON=1`) keeps the old shape — `.mcp.json`
+servers wrapped in place, the scenario server added there and pre-approved in
+`settings.local.json` — for a `.mcp.json` nobody commits. An install over an
+older one that used that shape puts `.mcp.json` back as it was, byte for byte
+when nothing else changed it, and moves the entries to the local scope.
+
+---
+
+## 5. Provisioning a runner
+
+Four scopes, and conflating them is the usual source of "installed but never
+runs":
+
+| Scope | How often | What it does |
+|---|---|---|
+| **machine** | once | Node ≥ 20 and the package. The served line uses the machine's Node when it qualifies and otherwise puts a private one under `~/.baseinstrunner/node/`; the package goes under `~/.baseinstrunner/npm/`, and `bir` / `bir-hooks` launchers in `~/.baseinstrunner/bin/`, first on the user PATH |
+| **account** | once per user | the sign-in → `~/.baseinstrunner/credentials.json` (0600); the service address → `~/.baseinstrunner/config.json`. `bir setup` stores both; so does `bir login` |
+| **project** | once per repo | `bir setup` in that directory: `bir install --global --replay` (`--local` from a checkout) writes wrapped copies of the MCP servers into the project's local scope (§4.4), wires the hooks into `.claude/settings.local.json`, records the port, token and invocation |
+| **session** | while recording | the recorder — `bir-hooks` as a background process — started by the SessionStart hook, discovered by `sha256(normalised cwd)` |
+
+That cwd keying is why the recorder must be started for the *same directory*
+the agent session runs in. A control server started for another one is
+invisible, and the run silently degrades to Tier 2. It is also why the hook is
+what starts it: the hook already runs in the right directory, with the right
+environment, at exactly the right moment. (The background process itself runs
+in `~/.baseinstrunner` and is told the project in `BIR_DAEMON_CWD`, so the
+project folder can be renamed, deleted or `git worktree remove`d while it
+runs.)
+
+### 5.1 One command
+
+The console's *Set up the runner* page shows one line, with a fresh one-time
+setup token filled in, to paste into a terminal opened in the project folder:
+
+```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
+```
+
+The first is Windows PowerShell, the second the same line from cmd.exe (a
+terminal opened from Start is often cmd), the third macOS and Linux. Without the
+variable the line still installs everything; `bir setup` then opens the browser
+for the device flow — even under the scripts, where its output is a pipe — and
+over SSH prints the link instead (§7).
+
+The scripts are [`scripts/install.ps1`](../scripts/install.ps1) and
+[`scripts/install.sh`](../scripts/install.sh); they replace
+`install-runner.ps1` and `install-runner.sh`, and they ship in the tarball. The
+API serves copies at `/install.ps1` and `/install.sh` with two placeholders
+filled in: `__BIR_AUTH_URL__` (the service's `PUBLIC_API_URL`, else the origin
+the request arrived on) and `__BIR_VERSION__` (`RUNNER_VERSION`, default
+`latest`). Run straight from the repository or the tarball the placeholders are
+unreplaced, which counts as unset: `BIR_AUTH_URL` must then be in the
+environment, and the version is `latest`.
+
+What they do, in order, the same on every platform:
+
+0. **Stop before any download** if the current directory is the home folder or
+   a drive root: "This is your home folder. Open a terminal in the project you
+   start Claude Code in (cd there) and paste the line again." Nothing is
+   installed, nobody is signed in and the token is unused, so the fix is
+   exactly that — `cd` to the project and paste the *same* line
+   (`BIR_PROJECT=<dir>` names the project instead; the script `cd`s there
+   first). Move `BIR_SETUP_TOKEN` out of the environment into a local variable,
+   so npm, the Claude Code installer and the `claude` the person starts next
+   never see it.
+1. **Node.** A Node ≥ 20 already on PATH is used by its real binary — unless
+   that binary is one the hook must not pin: under a version manager's
+   per-shell or per-version directory (nvm, fnm, Volta, asdf, mise and nodenv
+   on every platform; Scoop on Windows) or, on macOS and Linux, a Homebrew Node
+   (`*/Cellar/*` — a `brew upgrade` moves the path the hook pinned) or a snap
+   one. Both scripts also insist on npm's `npm-cli.js` beside the binary
+   (`lib/node_modules/npm/bin/` on macOS and Linux, `node_modules\npm\bin\` on
+   Windows). Otherwise a private Node is installed instead: pinned version,
+   digest embedded in the script and checked, unpacked to
+   `~/.baseinstrunner/node/v<V>/`, never put on PATH. The SessionStart hook
+   pins an absolute node path, and a path that changes with the shell is a
+   hook that fails every session. `BIR_NODE_ARCHIVE=<file>` uses a downloaded
+   archive instead of nodejs.org.
+2. **The package.** `@basein/runner@<version>` into the private prefix
+   `~/.baseinstrunner/npm`, always — never the machine's npm prefix, which is
+   root-owned under a `.pkg` or apt Node and per-version under nvm, Volta, Scoop
+   or asdf, where a global install vanishes on the next switch.
+   `BIR_TARBALL=<file.tgz>` instead of the registry. Launchers go into
+   `~/.baseinstrunner/bin`, which is put first on the user PATH; in PowerShell
+   `bir` then resolves to `bir.cmd`, so there is no execution-policy change,
+   ever. The PowerShell window the line was pasted into gets `bir` in place —
+   the script's last two lines are "bir works in every new terminal (and in
+   this window when it is PowerShell); `bir doctor` checks the setup" and the
+   cmd hint below — but the cmd variant
+   runs the script in a child `powershell.exe`, so a cmd window sees `bir` only
+   once it is a new window, or after the `set PATH=…` line the script prints
+   for it. On macOS and Linux the script prints the
+   `export PATH="$HOME/.baseinstrunner/bin:$PATH"` line for the terminal it ran
+   in (with `~/.local/bin` added when it just installed Claude Code); every new
+   terminal has it from the profile.
+3. **Claude Code**, through its official installer, when `claude` is not on
+   PATH. `BIR_NO_CLAUDE=1` skips it. It needs a Claude subscription and asks to
+   sign in the first time it starts.
+4. **`bir setup --auth-url <url> --project <cwd>`**, with the token in that
+   child's environment only. It signs in, stores the service address, runs
+   `bir install --global --replay`, starts the recorder in the background, and
+   prints a summary that names the account, the wrapped servers (`(no MCP
+   servers here)` means none in *any* scope — `.mcp.json`, and the user and
+   local scopes of `~/.claude.json`; `(none — x, y left as they are, see
+   above)` means servers exist but none could be wrapped, for the reasons of
+   §4.4; replay is "steer mode only" in both cases), the recorder's pid and log
+   file, and the one thing left to do: `claude`.
+
+`BIR_UNINSTALL=1` on the same line runs the other direction and nothing else:
+`bir uninstall --all` with the runner already installed (§8). It downloads
+nothing and needs no project folder and no token; `BIR_DRY_RUN=1` prints it.
+
+Both scripts are idempotent and neither prompts (under `curl | sh` stdin is the
+script itself). `bir setup` exits 1 when the recorder reports it has no session
+to record with, so a provisioning script can gate on the exit code.
+
+Behind a corporate proxy:
+
+- The scripts' own downloads and npm use `HTTPS_PROXY`, `HTTP_PROXY` and
+  `NO_PROXY` as they are. The one fetch they cannot reach is the `irm` that
+  fetches the script itself: Windows PowerShell 5.1's `irm` uses the system
+  (WinINET) proxy, not `HTTPS_PROXY`.
+- The runner's own calls to the service — the sign-in, the recorder's uploads —
+  go through Node's `fetch`, which ignores those variables unless node runs with
+  `--use-env-proxy`. The scripts add that flag to the launchers and to
+  `bir setup`, which carries it into every entry, hook and recorder it writes,
+  only when the Node accepts it (the node is asked, not judged by its version;
+  recent 22.x and 24.x have it) **and** `NO_PROXY` exempts `127.0.0.1` — as
+  `127.0.0.1`, `*` or a suffix such as `.0.0.1`; `localhost` alone is not
+  enough. Without that exemption the flag would send the runner's own loopback
+  calls — the SessionStart hook reaching the recorder, proxies registering,
+  `bir setup` waiting for it — to the proxy, so it is
+  left out, the runner reaches the service directly or not at all, and the
+  script says so. Set `NO_PROXY=127.0.0.1,localhost,::1` (plus your own
+  entries) before the line; `bir install` prints the same hint.
+- A remote (`http`/`sse`) MCP server behind `bir-proxy` is reached through
+  `HTTPS_PROXY`/`NO_PROXY` by Node's `http.Agent` `proxyEnv`, flag or not, on
+  Node 24.5+ and 22.21+. An older Node connects directly and logs
+  `upstream.proxy_env_ignored`; loopback upstreams always connect directly, and
+  `BIR_UPSTREAM_PROXY_ENV=0` turns this off.
+- `NODE_EXTRA_CA_CERTS` passes through to every node and npm the scripts run. A
+  Node that knows `--use-system-ca` also trusts the system certificate store,
+  and the launchers carry that flag too.
+
+The scripts never reach `bir setup` from the home folder (step 0). `bir setup`
+run *by hand* there, with the runner already installed, is different: it keeps
+the sign-in, wires nothing, prints the two commands left — `cd <project>` and
+`bir setup` — and exits 0. The second needs no token; the session is cached.
+That is also how a second project on the same machine is added.
+
+Fleet switches on `bir setup`: `--allow-servers a,b` stores the servers replay
+may call unattended for this project; `bir replay allow|on|off|status` changes
+it later. Both live in the project record (§4.3), so a recorder the hook starts
+— with Claude Code's environment, not the operator's terminal — keeps them;
+`BIR_REPLAY`, `BIR_REPLAY_ALLOW_SERVERS` and `BIR_MIN_STEER_SIMILARITY` in the
+recorder's environment still override, and `bir doctor` says which source is in
+effect. `--no-replay` adds no scenario server (one an earlier setup added stays
+until `bir uninstall --replay`) and stores replay off (`bir replay on` turns it
+on); `--no-daemon` wires everything and starts
+nothing; `--no-browser` prints the sign-in link without opening one.
+
+**Permissions on a fleet.** The runner does not approve wrapped MCP tool calls:
+Claude Code asks about them as it would without the runner. (0.2.12 answered
+every one "allow"; §8.) Headless `claude -p` runs must allow those tools
+themselves — `permissions.allow` in a trusted workspace, or `--allowedTools` —
+or set `BIR_CORRELATION_DECISION=allow` in the environment the recorder starts
+in — Claude Code's when the SessionStart hook starts it, the shell's for
+`bir up --restart` — which brings the old auto-approval back. A recorder already
+running keeps what it started with. `bir doctor` says which applies. A
+matched calculated scenario's own steps are still approved by the runner
+([calculatedReplayGuide.md §5.1](calculatedReplayGuide.md)).
+
+Two things the scripts deliberately do not do: supervise the recorder (the hook
+does, §5.2) and mint the token (the console does, §7).
+
+The PowerShell script is **pure ASCII** on purpose. Windows PowerShell 5.1
+decodes a BOM-less `.ps1` using the machine's ANSI codepage, and PowerShell
+accepts curly quotes as string delimiters — so a UTF-8 em-dash in a comment can
+decode into a quote and swallow the rest of the file. It parsed fine on one
+machine and failed on another before this was fixed. Keep it ASCII. It also
+never calls `exit` — under `iex` that closes the person's window — and it sets
+strict mode and `$ErrorActionPreference` inside a function so neither leaks into
+the caller's session.
+
+### 5.2 Keeping the recorder alive
+
+Not needed. The SessionStart hook is `bir-hooks ensure` (§4.2): every Claude
+Code session in the project starts the recorder when there is none, in the
+background, so a recorder that died or was never started is running by the first
+prompt. Nothing has to stay open. `bir up` starts it by hand, `bir up --restart`
+replaces it, `bir down` stops it — it asks first (`POST /control/stop`, which
+finishes the run being written), signals only a pid that answered `/health` with
+the token, and says "forced" when it had to — and `bir status` and `bir doctor`
+show its pid and log. Two Claude Code windows opened together take a lock, so
+only one spawns.
+
+`bir down` stops the recorder and nothing else: the hooks stay installed, so a
+Claude Code session open in the project 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. It also stops superseded recorders (§4.3), and it stays down
+against the automatic revival below until the next session start, `bir up` or
+`bir setup`. To take the runner out of the way without hook errors, use the
+kill switch instead: `bir off --here` for one project, `bir off` for every
+project (`bir on` undoes it). Hooks then answer with nothing within about a
+second, in open sessions too; wrapped servers run as plain pipes from their next
+start; nothing is uninstalled.
+
+On POSIX the daemon is a detached spawn with its stdio ignored. On Windows it is
+launched through `Start-Process -WindowStyle Hidden` in a short-lived
+`powershell.exe`, because a node started under a PowerShell layer carries an
+extra copy of its stdout pipe and a daemon that inherited it would hold that pipe
+open for days. That costs about a second, once per project per boot.
+`BIR_WINDOWS_LAUNCH=spawn` opts into a direct hidden spawn instead — faster, and
+unsafe only when something above Claude Code captures its output
+(`$r = claude -p …`).
+
+Its audit lines go to `~/.baseinstrunner/logs/<project-key>.log`: the daemon
+opens the file itself, appends, and rolls it to `.1` once it is past 8 MB — at
+start and while it runs. `bir status` names the file. The old shape still works —
+`bir-hooks` in a terminal writes them to that terminal — and is what the hook
+does for you.
+
+```bash
+grep version.skew ~/.baseinstrunner/logs/*.log
+grep run.lossy    ~/.baseinstrunner/logs/*.log
+```
+
+Restart-on-crash mid-session is the session's own part: a bound `bir-proxy`, or
+the `bir` scenario server, that finds the project's recorder gone — its pid dead
+and its port refusing — starts it again with `bir-hooks revive`
+(`proxy.recorder_revive` / `scenario.recorder_revive` on stderr), rate-limited,
+and never after `bir down`. A session with neither is back on the next session
+start or `/clear`. A service manager is
+optional. If you want one — a machine that records SDK sessions with nobody
+starting Claude Code, or a recorder up before the first session — have it run
+`bir up` in the project directory at logon, and nothing else: `bir up` returns
+once the recorder answers and leaves it running, so a supervisor must not expect
+a long-lived process. The three recipes below are recipes — nothing the package
+ships or its tests cover.
+
+**Windows** — a Scheduled Task at logon, with *Start in* set to the project
+directory (`bir.cmd` is the launcher the served line writes; a by-hand install
+has `bir` wherever npm put it):
+
+```powershell
+$action  = New-ScheduledTaskAction -Execute "$env:USERPROFILE\.baseinstrunner\bin\bir.cmd" -Argument 'up' -WorkingDirectory 'C:\work\repo'
+$trigger = New-ScheduledTaskTrigger -AtLogOn
+Register-ScheduledTask -TaskName 'bir up (repo)' -Action $action -Trigger $trigger
+```
+
+**macOS** — a launchd agent at `~/Library/LaunchAgents/com.basein.up.plist`
+running `$HOME/.baseinstrunner/bin/bir up` with `WorkingDirectory` set to the
+project and `RunAtLoad` (not `KeepAlive`), then `launchctl load` it.
+
+**Linux** — a systemd user unit, `Type=oneshot` with `RemainAfterExit=yes` (so
+the unit does not stop and take the recorder down with it), `ExecStart=%h/.baseinstrunner/bin/bir up`,
+`WorkingDirectory=` the project, plus `loginctl enable-linger "$USER"` so it
+runs without a login session.
+
+### 5.3 Verify
+
+```bash
+bir doctor --json            # exits 1 if something here breaks a Claude Code session
+bir doctor --json --strict   # exits 1 on warnings too: not recording, a proxy not registered, …
+```
+
+`bir doctor` asks the control server which proxies actually registered; it never
+reads the config file back. That makes it the right gate for a provisioning
+script. `bir status` only describes intent. It sorts what it finds three ways.
+*Problems* break a session and are the only thing that exits 1: a wrapped
+server, the scenario server or the SessionStart hook naming a Node or script
+that is gone (§4.2), a local copy out of date with its source (§4.4), a remote
+server wrapped without credentials, hooks posting to a port the recorder is not
+on or could not take (§4.3), hooks with nothing to start the recorder, a
+recorder that does not answer. *Warnings* exit 0 unless `--strict`: the
+recorder has nowhere to record to ("the recorder is running but has nowhere to
+send steps — run `bir setup` …"), a proxy has not registered while sessions
+run, the service is not answering the recorder, a recorder of another version.
+*Notes* are facts, such as "the recorder is not running; the SessionStart hook
+starts it with the next session (`bir up` starts it now)", who approves wrapped
+MCP calls, and the other projects set up on the machine. `--quick` skips the
+network call; `--json` carries `problems`, `warnings`, `notes`, `off`,
+`service`, `otherProjects` and `portProblem`.
+
+---
+
+## 6. Machines with no registry
+
+Zero dependencies makes offline install trivial — no `npm ci --offline`, no
+vendored `node_modules`. The install script ships in the tarball, takes a local
+tarball instead of the registry and a local Node archive instead of nodejs.org,
+and can skip the Claude Code installer:
+
+```bash
+# on a connected machine
+npm pack @basein/runner@<version>          # or download the Release asset
+tar -xzf basein-runner-<version>.tgz package/scripts
+# plus the Node archive for the runner's platform from nodejs.org/dist, if the
+# runner has no Node ≥ 20 (the script names the pinned version, 24.21.0)
+
+# on the runner
+BIR_AUTH_URL=https://api.example.com \
+BIR_TARBALL=./basein-runner-<version>.tgz \
+BIR_NODE_ARCHIVE=./node-v24.21.0-linux-x64.tar.gz \
+BIR_NO_CLAUDE=1 sh ./package/scripts/install.sh
+```
+
+```powershell
+$env:BIR_AUTH_URL='https://api.example.com'; $env:BIR_TARBALL='.\basein-runner-<version>.tgz'; $env:BIR_NODE_ARCHIVE='.\node-v24.21.0-win-x64.zip'; $env:BIR_NO_CLAUDE=1; Get-Content -Raw .\package\scripts\install.ps1 | iex
+```
+
+`<version>` is whatever the registry holds (`npm view @basein/runner version`).
+The PowerShell line pipes the file through `iex`, as the served line does: a
+`.ps1` invoked by path is subject to the execution policy, and a default client
+(Restricted) refuses it with "running scripts is disabled". The script is
+written to be run that way — everything inside one function, no `exit`.
+
+`BIR_AUTH_URL` is required here because the raw script's placeholder is
+unreplaced (§5.1). Claude Code has to come from somewhere too; `BIR_NO_CLAUDE=1`
+only stops the script from fetching it. The service itself must be reachable —
+"no registry" is not "no network" — or the sign-in has nothing to talk to.
+
+`bir setup` passes `--global`, so the resulting configs contain absolute paths
+and never reach for a registry. Nothing further is needed.
+
+Note that a private repository's Release assets require a GitHub token to fetch,
+so the tarball has to be carried to the runner by whatever means you already use.
+
+---
+
+## 7. Headless authentication
+
+`bir login` signs in through the browser — the OAuth 2.0 device grant (RFC 8628,
+[loginWeb.md](loginWeb.md)) — and caches
+`{accessToken, refreshToken, accessExpiresAt, user, authUrl}` at
+`~/.baseinstrunner/credentials.json`, mode 0600. `bir setup` does the same
+sign-in and stores the service address beside it in
+`~/.baseinstrunner/config.json`, so no process afterwards needs `BIR_AUTH_URL`
+(it still overrides when set).
+
+**The setup token.** The served line carries `BIR_SETUP_TOKEN`: a one-time token
+minted by the console's *Set up the runner* page — ten-minute TTL, single use,
+hashed at rest, and minting a new one retires the person's earlier unused ones.
+It travels as an environment-variable assignment rather than an argument so that
+it is never on a command line, where a process listing would show it; the
+variable's *name* is what keeps the pasted line out of PSReadLine's on-disk
+history, which drops lines containing "token" (a `--token` argument would be
+dropped just the same). The script moves it out of the environment as its first
+statement and hands it to `bir setup` through that child's environment only;
+`bir setup` deletes it again the moment it has read it, so the recorder it
+starts never holds it. By hand: `bir setup --token <t>` or
+`bir login --token <t>`. It signs in one person on one machine with no browser
+step; it is not a fleet credential.
+
+What `bir setup` says about a token that is not fresh:
+
+- pasted a second time after a successful paste — "the setup token was already
+  used; keeping the sign-in from before (<email>)", and it goes on; that is the
+  upgrade path (§8) and the retry after a failure past the sign-in;
+- used or expired, with no cached sign-in to keep — "this setup token has
+  expired or was already used — make a new one on the console's Set up the
+  runner page and paste it within ten minutes";
+- not a token at all — "that is not a valid setup token — copy the whole token
+  from the console's Set up the runner page".
+
+"sign-in failed: …" is reserved for the unexpected, and "not signed in — run
+`bir setup` again (or `bir login`)." for a sign-in that ended with no session.
+
+**Credentials are bound to the service that issued them.** `credentials.json`
+carries `authUrl`, and `authenticate()` refuses to use or refresh a session
+against another origin — `auth.url_mismatch` on the audit log, and the runner
+records nothing rather than send a session where it was not minted. A file from
+before the binding is trusted as before. So a copied `credentials.json` works
+only where `config.json` (or `BIR_AUTH_URL`) names the same service, and a stale
+`BIR_AUTH_URL` in a profile file now means "not recording" — `bir setup` warns
+when the environment names a different address than the one being set up, or
+than the stored one (a bare `bir setup` in a second project included), and says
+to remove the variable.
+
+**For a machine with a person attached, headless is no longer a problem.** The
+runner prints a link and a short code and waits; the link opens on *any* device,
+so a box with no browser, no display, or only an SSH session is signed in from a
+phone. Nothing is typed into the terminal, so nothing lands in a shell history or
+a CI transcript. `bir login --no-browser` (or `bir setup --no-browser`) skips
+even trying to open one, which is the right flag in a provisioning script (over
+SSH it is the default; a pipe on stdout is not — under the install scripts
+`bir setup` still opens the browser, because somebody just pasted the line). The
+setup token removes even the waiting.
+
+For machines with **no person attached**, in order of preference:
+
+1. **A service account, signed in once.** Approve the device code for a dedicated
+   account, then copy `credentials.json` to each machine at 0600, together with
+   a `config.json` naming the same service. The rotating refresh token keeps it
+   alive and nothing ever prompts. It is still a shared long-lived secret, so
+   never a person's account.
+2. **No service address at all** for runners that should record nothing: no
+   address in `~/.baseinstrunner/config.json` and no `BIR_AUTH_URL`. The
+   recorder then starts with a null recorder (`recorder.disabled` on its log)
+   and everything else still works; `bir up` exits 1 to say so, and
+   `bir doctor` warns (exit 1 only with `--strict`).
+   `BIR_AUTH_DISABLE=1` is *not* that: it fakes a session and records with a
+   bogus token — a local-dev and CI switch, not a fleet one.
+3. **Ask the service for a non-interactive grant** — a long-lived runner token,
+   created in the console and read from an env var. This remains the right answer
+   for a large fleet and is still a service-side change; the device grant and the
+   setup token make it less urgent, not unnecessary.
+
+`bir logout` clears the file first — a hung service or a Ctrl-C cannot leave the
+machine signed in — and then revokes the session at the service that issued it
+(the one `credentials.json` names, not whatever `BIR_AUTH_URL` says), best
+effort and within 8 s, so decommissioning a runner ends its access rather than
+merely tidying the disk. Running recorders stop sending within seconds.
+Decommissioning also means `bir uninstall --all` first (§8).
+
+`BIR_HOME` relocates all of this if state belongs somewhere other than
+`~/.baseinstrunner`.
+
+---
+
+## 8. Updating a runner
+
+Paste the line again — the same line, used token and all. It installs the
+version the service serves (`RUNNER_VERSION`, default `latest`), keeps the
+sign-in it already has ("the setup token was already used; keeping the sign-in
+from before (<email>)"), and runs `bir setup`, which re-wraps whatever moved and
+restarts an older recorder. For a machine installed by hand: the new package,
+then `bir setup` in each recorded project.
+
+```bash
+npm i -g @basein/runner@<version> && cd ~/work/repo && bir setup
+```
+
+Two rules used to follow, and neither is a step now:
+
+- **Restarting the recorder.** A running process is still the old code, and
+  this was the step people forgot. `bir setup`, `bir up` and the SessionStart
+  hook all replace a running recorder that is older than the package — provided
+  no session is mid-turn. A newer one (another runner copy on the machine) is
+  kept. A recorder still serving a turn is left alone, and `bir setup` says so:
+  "it is still 0.2.12, serving a Claude Code session that is mid-turn; it keeps
+  running as 0.2.12 until `bir up --restart` (run it once that session ends)
+  replaces it with <version>". The next session's hook replaces it when no turn
+  is open, but a 0.2.12 recorder can report an interrupted turn as open for good;
+  `bir setup` and `bir up` look twice, a few seconds apart, and replace one when
+  nothing moved in between and no session's proxy is alive. `bir up --restart`
+  forces it now.
+- **Re-running `bir install`.** `bir setup` does. A `--global` entry whose path
+  did not change needs nothing (§4); one whose runner moved — a new prefix, a
+  new Node — is re-wrapped from its source; a pinned-npx entry always
+  has its pin moved.
+
+**Upgrading from 0.2.12.** The first `bir setup` after it changes more than
+paths:
+
+- Wrapped entries move to the local scope (§4.4). `.mcp.json` is put back as it
+  was; a user-scope server 0.2.12 wrapped in place is put back too, and every
+  other project that recorded it that way needs `bir setup` there again (the
+  install names them). A `.mcp.json` server Claude Code has not approved is no
+  longer wrapped.
+- The runner no longer approves wrapped MCP tool calls; 0.2.12 answered every
+  one "allow". `bir install` and `bir setup` say so once per project. Headless
+  `claude -p` fleets must allow those tools themselves, or set
+  `BIR_CORRELATION_DECISION=allow` (§5.1).
+- In a project with no scenario server (a plain `bir install`), the next
+  install without `--replay` switches replay off (§4.3); `bir replay on` turns
+  it back on.
+- Until it is replaced, a 0.2.12 recorder still running keeps approving those
+  calls and ignores `bir off`; `bir doctor` warns about a recorder of another
+  version, and `bir up --restart` replaces it once its session ends.
+
+**Rolling back.** First run `bir uninstall --all` with the version installed
+now: an older runner cannot read everything this one wrote, and would find no
+record for some wrapped entries and leave them — credentials included — in
+place. Then install the older version (`BIR_VERSION=<version>` on the macOS and
+Linux line, or by hand) and run `bir setup` in each project.
+
+### The half-upgraded machine
+
+This is the update failure that looks like success: the package is new, but a
+proxy is still the old code because a config points elsewhere, or the recorder
+is a process that outlived the upgrade. Everything keeps working, and quietly
+runs code you did not ship.
+
+The restart-on-skew above closes the common case. For the rest, a proxy reports
+its version when it registers, the control server compares it with its own, and
+a mismatch is one line on the audit log:
+
+```
+[bir] … version.skew server=fleet proxy=0.0.9 hooks=0.1.0 fix="restart bir-hooks after upgrading, …"
+```
+
+`bir doctor --json` carries the same facts structurally — under `health`,
+`hooksVersion` and a `version` on each entry of `registeredProxies` — so a
+provisioning script can assert agreement rather than grep a log. A proxy too old
+to report a version is not treated as skewed: silence, not a false alarm.
+
+### Removing a runner
+
+`bir uninstall` covers one project. Before `npm rm -g @basein/runner` or
+deleting `~/.baseinstrunner`, run `bir uninstall --all` — or paste the install
+line with `BIR_UNINSTALL=1`, which runs just that:
+
+```bash
+curl -fsSL https://api.bi2202.com/install.sh | BIR_UNINSTALL=1 sh
+```
+
+```powershell
+$env:BIR_UNINSTALL="1"; irm https://api.bi2202.com/install.ps1 | iex
+```
+
+Every wrapped server and every hook names a file under the runner's install,
+so removing it first breaks every project still set up, with no `bir` left to
+repair them. `--all` undoes every installed project as `bir uninstall` would
+there, sweeps every `.claude.json` an install wrote to (user scope included),
+stops every recorder, superseded ones too, and clears the off switches. When
+something could not be undone it lists it, keeps the off switch in place, and
+exits 1 ("Not everything could be undone"); fix that and run it again before
+removing anything. Then `bir logout` (§7), then remove the package.
+
+---
+
+## 9. Per-release verification
+
+CI does this on three platforms. To do it by hand on a clean machine:
+
+```bash
+npm run build && npm test          # ~1,000 tests (npm runs pretest first)
+npm run test:smoke                 # real processes: hooks + proxy + scenario over stdio;
+                                   # needs the build and the pretest above
+npm pack && npm i -g ./basein-runner-*.tgz
+cd /tmp/scratch && bir setup --auth-url <api> --token <t>   # or BIR_AUTH_URL=<api> bir login, then bir install --global && bir up
+bir doctor --json                  # must exit 0 (--strict: no warnings either)
+bir uninstall                      # must end with "Uninstalled." and exit 0
+```
+
+`test:smoke` is the one that matters for packaging: it is the only test that
+crosses process boundaries, which is exactly where a bad `files` list, a missing
+shebang, or a broken bin mapping shows up.
+
+Sandbox a manual run with `BIR_HOME` and `BIR_CLAUDE_JSON` so it cannot touch
+your real Claude Code configuration. A fresh `BIR_HOME` has no sign-in, which is
+why the recipe signs in: a bare `bir install --global && bir up` there starts a
+recorder with nothing to record to, `bir up` ends with "it has no session to
+record with" and exit 1, and `bir doctor --json` warns about the same thing
+(exit 1 with `--strict`). `bir uninstall` restores byte-for-byte only a project
+file nothing else edited since the install, and repairs `~/.claude.json` entry
+by entry; a file it created stays behind, empty of our entries. It exits 1 with
+"Not everything could be undone" while anything here still runs through the
+runner.
+
+---
+
+## 10. Where things stand
+
+| # | Item | State |
+|---|---|---|
+| 1 | Name settled; `PACKAGE_NAME` aligned | done |
+| 2 | `repository` + `publishConfig`; provenance deferred (private repo) | done |
+| 3 | Tarball trimmed — no dead sourcemaps, no scratchpad; `scripts/` ships | done |
+| 4 | npx spec pinned; `--global` added; moved runners re-wrapped | done |
+| 5 | CI and release workflows, three platforms | done |
+| 6 | `scripts/install.{ps1,sh}`, served by the API at `/install.ps1` and `/install.sh` (replace `install-runner.*`) | done |
+| 7 | Version-skew detection on registration; recorder restarts itself between sessions | done |
+| 8 | UTF-8 BOM tolerated in MCP configs | done |
+| 9 | npm org `basein`, `NPM_TOKEN` secret | done |
+| 10 | `bir setup`: sign-in, wrap, replay, recorder in one command | done |
+| 11 | Background recorder started by the SessionStart hook (`bir-hooks ensure`); `bir up` / `bir down`; log per project | done |
+| 12 | Hooks in `.claude/settings.local.json` + `.git/info/exclude`; one port and token per project | done |
+| 13 | Setup token (`BIR_SETUP_TOKEN`) for the first sign-in; credentials bound to their service; address in `config.json` | done |
+| 14 | Tag `v0.2.9` to publish | ready |
+| 15 | Non-interactive auth grant for fleets | **needs the service** |
+| 16 | Migrate to trusted publishing before Jan 2027 (§3.3) | scheduled |
+| 17 | Production readiness: local-scope wrapping (§4.4), no auto-approval of wrapped calls, `bir off` / `bir on`, `bir uninstall --all` and `BIR_UNINSTALL=1` (§8) — contract and measurements in [production.md](../production.md) | done, unreleased |
+
+Item 15 is the only one that needs somebody else.
+
+---
+
+## Appendix: the BOM
+
+`bir` used to reject any MCP config saved with a UTF-8 byte order mark. Notepad
+writes one, so does VS Code's "UTF-8 with BOM", and so does PowerShell's
+`Out-File -Encoding utf8`. `readFileSync(path, "utf8")` decodes the BOM to U+FEFF
+rather than consuming it, and `JSON.parse` then rejects the file.
+
+The failure mode was the bad part: `bir install` logged the parse error and
+**still reported success**, so an operator saw a green run and no wrapping. On
+Windows runners this was a matter of time.
+
+`parseJsonFile` now strips it, which covers every user-authored config read.
+Restoring is unaffected — the uninstall backup keeps the file's own text (its
+env and header values replaced by placeholders) on a separate path, so a BOM'd
+file comes back with its BOM intact.