@basein/runner 0.2.8 → 0.2.11

package/docs/installRun.md

@@ -10,9 +10,9 @@ 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 and verified except §7: headless
-authentication is still a stopgap, and it is the one open item that needs a
-service-side decision rather than a change here.
+**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.
 
 ---
 
@@ -22,10 +22,10 @@ service-side decision rather than a change here.
 |---|---|---|
 | 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` | One prerequisite to check on a runner. |
+| 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 | 97 files, 230 kB | `dist/` + types + docs. Sourcemaps and `docs/next.md` are excluded. |
+| 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.
@@ -34,7 +34,7 @@ distributes. The delivery does not need to be clever.
 
 `files` carries two negations:
 
-- `!dist/**/*.map` — 88 files, 287 kB. The maps carry no `sourcesContent`, and
+- `!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.
@@ -59,7 +59,7 @@ documentation exists.
 
 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 `BIR_AUTH_URL` plus credentials.
+the service is gated by its address plus credentials.
 
 ---
 
@@ -154,31 +154,159 @@ Three invocation modes, one flag each:
 
 | Mode | Flag | Entry |
 |---|---|---|
-| **npx** | *(default)* | `npx -y -p @basein/runner@0.1.0 bir-proxy …` |
-| **global** | `--global` | `<node> <prefix>/node_modules/@basein/runner/dist/bin/bir-proxy.js …` |
+| **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 the bootstrap scripts pass.
-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.
+**`--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>/node_modules/@basein/runner/dist/bin/bir-proxy.js` contains no version,
-so `npm i -g @basein/runner@0.2.0` 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.
+`<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
@@ -188,72 +316,194 @@ runs":
 
 | Scope | How often | What it does |
 |---|---|---|
-| **machine** | once | Node ≥ 20, and the package installed globally |
-| **account** | once per user | `BIR_AUTH_URL`, then `bir login` (approved in a browser) → `~/.baseinstrunner/credentials.json` (0600) |
-| **project** | once per repo | `bir install --global` rewrites that project's MCP entries and wires the hooks |
-| **session** | while recording | `bir-hooks` running, discovered by `sha256(normalised cwd)` |
+| **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 `bir-hooks` must start in the *same directory* the agent
+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.
+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
 
-[`scripts/install-runner.ps1`](../scripts/install-runner.ps1) and
-[`scripts/install-runner.sh`](../scripts/install-runner.sh) do machine, account
-and project scope together:
+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
-.\scripts\install-runner.ps1 C:\work\repo -AuthUrl https://basein.example.com
+$env:BIR_SETUP_TOKEN="<token>"; irm https://api.bi2202.com/install.ps1 | iex
 ```
 
-```bash
-BIR_AUTH_URL=https://basein.example.com ./scripts/install-runner.sh ~/work/repo
+```cmd
+powershell -NoProfile -Command "$env:BIR_SETUP_TOKEN='<token>'; irm https://api.bi2202.com/install.ps1 | iex"
 ```
 
-Both are idempotent, both validate everything checkable **before** changing
-anything (a failed run leaves no half-provisioned machine), both skip `bir login`
-when a session is already cached, and both accept a local tarball
-(`-Tarball` / `BIR_TARBALL`) instead of the registry.
+```bash
+curl -fsSL https://api.bi2202.com/install.sh | BIR_SETUP_TOKEN="<token>" sh
+```
 
-Two things they deliberately do not do: supervise `bir-hooks`, and automate
-authentication. See §5.2 and §7.
+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.
+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.
 
-### 5.2 Keeping `bir-hooks` alive
+```bash
+grep version.skew ~/.baseinstrunner/logs/*.log
+grep run.lossy    ~/.baseinstrunner/logs/*.log
+```
 
-One process per project cwd. On a headless runner, supervise it rather than
-leaving it in a shell.
+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:
+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 'bir-hooks' -WorkingDirectory 'C:\work\repo'
+$action  = New-ScheduledTaskAction -Execute "$env:USERPROFILE\.baseinstrunner\bin\bir.cmd" -Argument 'up' -WorkingDirectory 'C:\work\repo'
 $trigger = New-ScheduledTaskTrigger -AtLogOn
-Register-ScheduledTask -TaskName 'bir-hooks (repo)' -Action $action -Trigger $trigger
+Register-ScheduledTask -TaskName 'bir up (repo)' -Action $action -Trigger $trigger
 ```
 
-**macOS** — a launchd agent at `~/Library/LaunchAgents/com.basein.hooks.plist`,
-with `WorkingDirectory` set to the project and `StandardErrorPath` to a log file,
-then `launchctl load` it.
-
-**Linux** — a systemd user unit with `WorkingDirectory=`, plus
-`loginctl enable-linger "$USER"` so it survives logout.
+**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.
 
-Whichever you use, redirect stderr to a file. Every decision is one `key=value`
-line on stderr and there is no file sink to configure, so the supervisor's
-redirection *is* the sink:
-
-```bash
-grep version.skew ~/.baseinstrunner/audit.log
-grep run.lossy   ~/.baseinstrunner/audit.log
-```
+**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
 
@@ -263,25 +513,54 @@ 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.
+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`:
+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@0.1.0        # or download the Release asset
+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_TARBALL=./basein-runner-0.1.0.tgz ./scripts/install-runner.sh ~/work/repo
+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
 ```
 
-The bootstrap scripts already pass `--global`, so the resulting configs contain
-absolute paths and never reach for a registry. Nothing further is needed.
+```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.
@@ -292,30 +571,80 @@ so the tarball has to be carried to the runner by whatever means you already use
 
 `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}` at
-`~/.baseinstrunner/credentials.json`, mode 0600.
+`{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` skips even trying to open one, which is
-the right flag in a provisioning script (it is also the default over SSH).
+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. 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. **`BIR_AUTH_DISABLE=1`** for runners that should record nothing. Everything
-   else still works.
+   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 makes
-   it less urgent, not unnecessary.
+   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` now revokes the session server-side before clearing the file, so
+`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
@@ -325,45 +654,52 @@ decommissioning a runner ends its access rather than merely tidying the disk.
 
 ## 8. Updating a runner
 
-Re-run the bootstrap script with the new version. It is idempotent, it will not
-prompt for a login it already has, and `bir install` will not double-wrap:
-
-```powershell
-.\scripts\install-runner.ps1 C:\work\repo -Version 0.2.0 -AuthUrl https://basein.example.com
-```
+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
-BIR_VERSION=0.2.0 BIR_AUTH_URL=https://basein.example.com ./scripts/install-runner.sh ~/work/repo
+npm i -g @basein/runner@<version> && cd ~/work/repo && bir setup
 ```
 
-Then two rules:
+Two rules used to follow, and neither is a step now:
 
-- **Restart `bir-hooks`.** A running process is still the old code. This is the
-  step people forget.
-- **Re-run `bir install` only if the entry shape changed** — or always, since it
-  is idempotent. With `--global` entries an upgrade needs no re-install at all
-  (§4). With pinned-npx entries it always does.
+- **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 is the same command with the older version.
+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 `bir-hooks` was
-never restarted. Everything keeps working, and quietly runs code you did not
-ship.
+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.
 
-A proxy now reports its version when it registers, the control server compares it
-with its own, and a mismatch is one line on the audit log:
+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 — `hooksVersion` at the
-top 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.
+`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.
 
 ---
 
@@ -372,10 +708,11 @@ version is not treated as skewed: silence, not a false alarm.
 CI does this on three platforms. To do it by hand on a clean machine:
 
 ```bash
-npm run build && npm test          # 233 tests
-npm run test:smoke                 # real processes: hooks + proxy + scenario over stdio
+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 install --global && bir-hooks &
+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
 ```
@@ -385,7 +722,12 @@ 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.
+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.
 
 ---
 
@@ -395,18 +737,22 @@ your real Claude Code configuration.
 |---|---|---|
 | 1 | Name settled; `PACKAGE_NAME` aligned | done |
 | 2 | `repository` + `publishConfig`; provenance deferred (private repo) | done |
-| 3 | Tarball trimmed — no dead sourcemaps, no scratchpad | done |
-| 4 | npx spec pinned; `--global` added | 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-runner.{ps1,sh}` | done |
-| 7 | Version-skew detection on registration | 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 | Tag `v0.1.0` to publish | ready |
-| 11 | Non-interactive auth grant for fleets | **needs the service** |
-| 12 | Migrate to trusted publishing before Jan 2027 (§3.3) | scheduled |
-
-Item 11 is the only one that needs somebody else.
+| 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.
 
 ---