@basein/runner 0.2.8 → 0.2.11

package/README.md

@@ -22,40 +22,70 @@ hooks ──built-ins, prompt, stop──▶ bir-hooks (control server) ──
 
 ## Install
 
-On a runner machine, one command does machine, account and project scope:
+One line, pasted into a terminal **opened in the project you start Claude Code
+in**. The console's *Set up the runner* page shows it with a one-time setup
+token filled in, so there is no sign-in step either:
 
 ```powershell
-.\scripts\install-runner.ps1 C:\work\repo -AuthUrl https://your-basein-service   # Windows
+$env:BIR_SETUP_TOKEN="<token>"; irm https://api.bi2202.com/install.ps1 | iex      # Windows (PowerShell)
 ```
 
 ```bash
-BIR_AUTH_URL=https://your-basein-service ./scripts/install-runner.sh ~/work/repo  # macOS/Linux
+curl -fsSL https://api.bi2202.com/install.sh | BIR_SETUP_TOKEN="<token>" sh       # macOS / Linux
 ```
 
-Step by step, for one machine: [docs/quickstart.md](docs/quickstart.md).
-For a fleet — packaging, releases, offline installs, updates:
-[docs/installRun.md](docs/installRun.md).
+That installs Node if the machine has none (a private copy, never on PATH),
+installs this package, installs Claude Code if it is missing, and runs
+`bir setup`: it signs in, stores the service address, wraps the project's MCP
+servers, wires Claude Code's hooks, adds the scenario server, and starts the
+recorder in the background. It ends with the one thing left to do: `claude`.
+Without a token the same line signs in through the browser. Re-running it is
+safe, and is also how you upgrade. To record another project: `cd` there and
+run `bir setup` (no token needed; the sign-in is kept).
+
+The scripts are [scripts/install.ps1](scripts/install.ps1) and
+[scripts/install.sh](scripts/install.sh); the API serves them with its own
+address filled in. Step by step, and what each line does:
+[docs/quickstart.md](docs/quickstart.md). For a fleet — packaging, releases,
+offline installs, updates: [docs/installRun.md](docs/installRun.md).
 
 By hand, or when developing BaseInstRunner itself:
 
 ```bash
 npm i -g @basein/runner          # or: npm install && npm run build, in a checkout
 cd the-project-you-record-from
-bir install --global             # --local from a checkout; plain `bir install` writes a pinned npx entry
+bir setup --auth-url https://api.bi2202.com    # everything below, in one go
 ```
 
-`bir install` rewrites your MCP entries in place, keeping every key (so
-`mcp__<server>__<tool>` names never change), and wires Claude Code's hooks. It
-stashes the original text of every file first — `bir uninstall` puts it back
-byte-for-byte.
+or the pieces `bir setup` is made of:
 
 ```bash
-export BIR_AUTH_URL=https://your-basein-service   # required to record anything
-bir login                                        # once; approve it in the browser
-bir-hooks                                        # leave running; Ctrl-C to stop
-claude                                           # your session, now recorded
+bir login                        # once; approve it in the browser (or --token <t> from the console)
+bir install --global --replay    # --local from a checkout; plain `bir install` writes a pinned npx entry
+bir up                           # the recorder, in the background; the SessionStart hook does this too
+claude                           # your session, now recorded
 ```
 
+`bir install` rewrites your MCP entries in place, keeping every key (so
+`mcp__<server>__<tool>` names never change), and wires Claude Code's hooks into
+`.claude/settings.local.json` — your file, not the one a team commits; in a git
+repository it is added to `.git/info/exclude`. It stashes the original text of
+every file first — `bir uninstall` puts a file back byte-for-byte when nothing
+else has edited it since, and repairs it entry by entry when something has. A
+project remembers whether it was installed with `--global`, `--local` or the
+pinned-npx default, so a later `bir install` with no flag keeps that shape.
+
+**Nothing has to stay open.** The SessionStart hook is `bir-hooks ensure`: it
+starts the recorder for the project when none is running, in the background,
+with its audit log at `~/.baseinstrunner/logs/<project-key>.log`. `bir up`
+starts it by hand, `bir down` stops it, `bir status` shows it. Running
+`bir-hooks` in a terminal still works and is what the hook does for you.
+
+The service address is stored by `bir setup` and `bir login` in
+`~/.baseinstrunner/config.json`; `BIR_AUTH_URL` in the environment overrides
+it. A cached session is bound to the service that issued it and is never sent
+anywhere else.
+
 `bir login` prints a link and a short code and waits for you to approve it in
 the browser — the OAuth device grant, the same shape `gh auth login` uses. It
 never handles a password, so it works for accounts that only sign in with
@@ -117,7 +147,9 @@ between the two is not guaranteed.
   section.
 - **Change what the model does.** Tool descriptions are never edited. The
   model-visible changes are schema relaxation, below, and — only with
-  `--replay` — one first-party tool.
+  `--replay` — the first-party `bir` server's tools: `run_scenario`, and three
+  that only read a scenario. The three that change one appear only after
+  `bir scenario editing on` in that project.
 
 ---
 
@@ -134,10 +166,18 @@ record, calculate, check, enable, read the audit lines — is
 [docs/calculatedReplayGuide.md](docs/calculatedReplayGuide.md).
 
 ```bash
-bir install --replay      # adds the `bir` MCP server; raises the prompt-hook timeout
-bir-hooks                 # replay is on by default; BIR_REPLAY=0 bir-hooks turns it off
+bir install --replay      # adds the `bir` MCP server, pre-approved in .claude/settings.local.json
+bir up                    # or let the SessionStart hook start the recorder; replay is on by default
+bir replay allow fleet    # the servers replay may call unattended — stored for this project
+bir replay off            # and back on with `bir replay on`; `bir replay status` shows it
 ```
 
+`bir setup` does the first two. The switches are kept per project in
+`~/.baseinstrunner/installed.json`, so a recorder the hook starts — with Claude
+Code's environment, not your terminal's — keeps them; `BIR_REPLAY`,
+`BIR_REPLAY_ALLOW_SERVERS` and `BIR_MIN_STEER_SIMILARITY` in the environment
+still override them, and `bir doctor` says which source is in effect.
+
 Two switches, not one, because of what replay is: **a scenario is a pre-approved
 list of tool calls with computed arguments.** A steered step is answered
 `permissionDecision: "allow"`, so a pinned `Bash` or `Edit` runs without the
@@ -154,6 +194,25 @@ sequence runs through connections the proxies already hold — **zero model toke
 scenarios steer the live session instead, pinning each step's arguments. Either
 way the turn reports what it cost, so the savings ledger measures something real.
 
+**Fixing a step.** A calculated step is code, and code can be wrong.
+`bir investigate` names such a step; `bir scenario edit` fixes it, and the
+service checks the change against the recording before it saves it. **A change
+is saved only if it reproduces the recording — or on purpose, with
+`--force --note "why"`.** Only the owner can change a scenario. Claude can do it
+too: in its terminal, or with the `bir` server's tools once
+`bir scenario editing on` was run in the project. Built 2026-09-25, not yet
+released: it needs the next `@basein/runner` version and a service deploy. Step
+by step: [the guide's §9.2](docs/calculatedReplayGuide.md).
+
+```bash
+bir scenario show  scn_… --step 3                          # read one step
+bir scenario check scn_… --step 3 --input-logic step3.js   # try a change; nothing is saved
+bir scenario edit  scn_… --step 3 --input-logic step3.js --note "why"   # the same check, then save
+bir scenario edits scn_…                                   # the history
+bir scenario undo  scn_…                                   # undo the newest edit
+bir scenario editing on                                    # let Claude's `bir` tools change scenarios here
+```
+
 ---
 
 ## Two things to know before you turn it on
@@ -184,7 +243,8 @@ instead.
 
 | Variable | Effect |
 |---|---|
-| `BIR_AUTH_URL` | BaseIn auth-service — the **API** address (normally `https://api.<your-domain>`), not the docs or app website. **Unset means nothing is recorded** — everything else still works. |
+| `BIR_AUTH_URL` | BaseIn auth-service — the **API** address (normally `https://api.<your-domain>`), not the docs or app website. Overrides the address `bir setup` / `bir login` stored in `~/.baseinstrunner/config.json`. **Neither set means nothing is recorded** — everything else still works. |
+| `BIR_SETUP_TOKEN` | A one-time setup token from the console, read by `bir setup` when `--token` is not given; the install scripts pass it this way. Never inherited by the recorder. |
 | `BIR_AUTH_DISABLE=1` | Skip authentication (local dev / CI). |
 | `BIR_CONTROL_PORT` | Preferred control-server port (default 53411). |
 | `BIR_CONTROL_URL` / `BIR_CONTROL_TOKEN` | Point a proxy at a control server directly, bypassing discovery. Injected into generated config; the only reliable channel for an SDK session. |
@@ -200,7 +260,7 @@ what to do when they register, so there is one switch and no second copy of it:
 | Variable | Effect |
 |---|---|
 | `BIR_REPLAY=0` | Disable replay. It is on by default; nothing below matters while this is `0`. |
-| `BIR_REPLAY_ALLOW_SERVERS` | Server keys eligible for **direct** execution. Unset means every wrapped server; setting it is the recommendation. |
+| `BIR_REPLAY_ALLOW_SERVERS` | Server keys eligible for **direct** execution. Unset means the list `bir replay allow` stored for the project, else every wrapped server; narrowing it is the recommendation. |
 | `BIR_MIN_STEER_SIMILARITY` | Minimum match similarity to replay (default `0.92`, above the service's own `0.9` detection threshold). |
 | `ANTHROPIC_API_KEY` | **Optional.** Working out what a new request is about — which fleet, which file, which date — is done for you by the service on its own key, as long as you are signed in. Set this only to keep that reading on your machine, on your key. Signed out *and* unset, a scenario whose values change between requests is declined rather than replayed on stale ones. |
 | `BIR_DERIVE_MODEL` | Derivation model, when you set a key of your own (default `claude-haiku-4-5-20251001`). |
@@ -211,7 +271,10 @@ what to do when they register, so there is one switch and no second copy of it:
 ### The audit log
 
 Every decision is one `key=value` line on **stderr** — never stdout, which is the
-host's JSON-RPC stream. There is no file sink to configure; persistence is the
+host's JSON-RPC stream. A recorder started in the background (by `bir up`, `bir
+setup` or the SessionStart hook) writes them to
+`~/.baseinstrunner/logs/<project-key>.log` — `bir status` names the file. One
+started in a terminal writes them to that terminal, and persistence is the
 shell's job:
 
 ```bash
@@ -227,6 +290,7 @@ The governing rule: **a host session never fails because of BaseInstRunner.**
 
 | Failure | Behaviour |
 |---|---|
+| No recorder running at session start | the SessionStart hook starts one in the background; a session is never blocked or failed by it |
 | Control server unreachable at startup | buffer ≤ 5 s, then Tier 2; logged once |
 | Control server dies mid-session | the proxy switches to Tier 2 for the rest; run flagged lossy |
 | Recorder HTTP fails | send dropped and logged; never retried inline |
@@ -242,7 +306,7 @@ The governing rule: **a host session never fails because of BaseInstRunner.**
 
 ```bash
 npm run build       # src → dist
-npm test            # 233 tests: transcript identity, passthrough, correlation, config, replay
+npm test            # ~400 tests: transcript identity, passthrough, correlation, config, replay, setup
 npm run typecheck
 npm run test:smoke  # end-to-end replay with real processes (needs build + pretest first)
 ```

package/dist/auth/client.d.ts

@@ -32,7 +32,10 @@
  * server the host is waiting on. Callers get `undefined` and decide.
  *
  * Config:
- *   BIR_AUTH_URL      base URL of the BaseIn auth-service (required).
+ *   BIR_AUTH_URL      base URL of the BaseIn auth-service. When unset, the
+ *                     address `bir setup` / `bir login` stored in
+ *                     ~/.baseinstrunner/config.json is used — see
+ *                     {@link resolveAuthUrl}.
  *   BIR_AUTH_DISABLE  "1" to skip auth entirely (local dev / CI).
  */
 export interface AuthUser {
@@ -46,6 +49,15 @@ export interface AuthSession {
     /** Epoch milliseconds at which the access token expires. */
     accessExpiresAt: number;
     user: AuthUser;
+    /**
+     * The service that issued this session. `authenticate()` refuses to hand the
+     * tokens to any other origin: a stale `BIR_AUTH_URL` in some profile file, or
+     * one set by a repository's settings, must degrade to not-recording rather
+     * than send a live refresh token and every recording somewhere else. Absent
+     * on a file written before this field existed; those are trusted as before
+     * and re-bound by the next sign-in.
+     */
+    authUrl?: string;
 }
 export interface AuthenticateOptions {
     /** Base URL of the auth service. Defaults to BIR_AUTH_URL. */
@@ -73,6 +85,33 @@ export declare function loadCredentials(): AuthSession | undefined;
 export declare function saveCredentials(session: AuthSession): void;
 /** Remove the cached session (`bir logout`). No-op if absent. */
 export declare function clearCredentials(): void;
+/** The persisted settings in ~/.baseinstrunner/config.json. */
+export interface StoredConfig {
+    /** The service address 'bir setup' or 'bir login' last signed in against. */
+    authUrl?: string;
+}
+/** Read the stored settings; an absent or unreadable file is an empty one. */
+export declare function loadStoredConfig(): StoredConfig;
+/** Merge 'patch' into the stored settings and write them back, mode 0600. */
+export declare function saveStoredConfig(patch: StoredConfig): StoredConfig;
+/**
+ * Remember the service address, so no later process needs BIR_AUTH_URL.
+ *
+ * Called by 'bir setup' and 'bir login' — the two moments a person has just
+ * proved the address is right by signing in to it. A wrong address is never
+ * stored, because a session was never issued for it.
+ */
+export declare function rememberAuthUrl(authUrl: string): void;
+/**
+ * The service address this process should talk to, or "" when there is none.
+ *
+ * Three sources, in order: an explicit option, BIR_AUTH_URL, and the address
+ * stored by 'bir setup' / 'bir login'. The third is what makes the install a
+ * single step: a recorder started by a Claude Code hook inherits whatever
+ * environment the host had, which on a GUI-launched host is not the shell the
+ * person set things up in. The stored address is read the same way from every
+ * process, so they cannot disagree about where the recording goes.
+ */
 export declare function resolveAuthUrl(opts?: AuthenticateOptions): string;
 /**
  * Follow a redirect on the base URL *once*, so a bearer token is never sent to

package/dist/auth/client.js

@@ -32,14 +32,17 @@
  * server the host is waiting on. Callers get `undefined` and decide.
  *
  * Config:
- *   BIR_AUTH_URL      base URL of the BaseIn auth-service (required).
+ *   BIR_AUTH_URL      base URL of the BaseIn auth-service. When unset, the
+ *                     address `bir setup` / `bir login` stored in
+ *                     ~/.baseinstrunner/config.json is used — see
+ *                     {@link resolveAuthUrl}.
  *   BIR_AUTH_DISABLE  "1" to skip auth entirely (local dev / CI).
  */
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
-import { configDir } from "../control/paths.js";
+import { configDir, configPath, ensureDir } from "../control/paths.js";
 import { join } from "node:path";
 import { logLine, errText } from "../util/log.js";
 import { packageVersion } from "../util/version.js";
@@ -103,16 +106,70 @@ export function clearCredentials() {
 function isAccessValid(session) {
     return session.accessExpiresAt - EXPIRY_SKEW_MS > Date.now();
 }
-function toSession(res) {
+function toSession(res, authUrl) {
     return {
         accessToken: res.accessToken,
         refreshToken: res.refreshToken,
         accessExpiresAt: Date.now() + res.expiresIn * 1000,
         user: res.user,
+        ...(authUrl ? { authUrl: authUrl.replace(/\/+$/, "") } : {}),
     };
 }
+/** True when a cached session may be used against `authUrl`. */
+function issuedFor(session, authUrl) {
+    if (!session.authUrl)
+        return true; // pre-binding file: trusted as before
+    return session.authUrl === authUrl.replace(/\/+$/, "");
+}
+/** Read the stored settings; an absent or unreadable file is an empty one. */
+export function loadStoredConfig() {
+    try {
+        if (!existsSync(configPath()))
+            return {};
+        const parsed = JSON.parse(readFileSync(configPath(), "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Merge 'patch' into the stored settings and write them back, mode 0600. */
+export function saveStoredConfig(patch) {
+    const next = { ...loadStoredConfig(), ...patch };
+    ensureDir(configDir());
+    writeFileSync(configPath(), JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+    return next;
+}
+/**
+ * Remember the service address, so no later process needs BIR_AUTH_URL.
+ *
+ * Called by 'bir setup' and 'bir login' — the two moments a person has just
+ * proved the address is right by signing in to it. A wrong address is never
+ * stored, because a session was never issued for it.
+ */
+export function rememberAuthUrl(authUrl) {
+    const url = authUrl.replace(/\/+$/, "");
+    if (!url)
+        return;
+    if (loadStoredConfig().authUrl === url)
+        return;
+    saveStoredConfig({ authUrl: url });
+}
+/**
+ * The service address this process should talk to, or "" when there is none.
+ *
+ * Three sources, in order: an explicit option, BIR_AUTH_URL, and the address
+ * stored by 'bir setup' / 'bir login'. The third is what makes the install a
+ * single step: a recorder started by a Claude Code hook inherits whatever
+ * environment the host had, which on a GUI-launched host is not the shell the
+ * person set things up in. The stored address is read the same way from every
+ * process, so they cannot disagree about where the recording goes.
+ */
 export function resolveAuthUrl(opts) {
-    return (opts?.authUrl ?? process.env.BIR_AUTH_URL ?? "").replace(/\/+$/, "");
+    const explicit = opts?.authUrl ?? process.env.BIR_AUTH_URL;
+    if (explicit !== undefined && explicit !== "")
+        return explicit.replace(/\/+$/, "");
+    return (loadStoredConfig().authUrl ?? "").replace(/\/+$/, "");
 }
 /**
  * Follow a redirect on the base URL *once*, so a bearer token is never sent to
@@ -304,7 +361,7 @@ async function postJson(url, body) {
 /** Exchange a refresh token for a new session. Undefined on failure. */
 async function tryRefresh(authUrl, refreshToken) {
     try {
-        return toSession(await postJson(`${authUrl}/auth/refresh`, { refreshToken }));
+        return toSession(await postJson(`${authUrl}/auth/refresh`, { refreshToken }), authUrl);
     }
     catch {
         return undefined;
@@ -326,11 +383,22 @@ export async function authenticate(opts) {
     const authUrl = resolveAuthUrl(opts);
     if (!authUrl) {
         logLine("auth.unconfigured", {
-            why: "BIR_AUTH_URL is not set — nothing will be recorded",
+            why: "no service address — run `bir setup`, or set BIR_AUTH_URL; nothing will be recorded",
         });
         return undefined;
     }
     const cached = loadCredentials();
+    if (cached && !issuedFor(cached, authUrl)) {
+        // The tokens on disk belong to another service. Using them here would
+        // hand a live session to whatever this address is; refreshing them here
+        // would hand it the refresh token too. Neither is ever the right call.
+        logLine("auth.url_mismatch", {
+            cached: cached.authUrl,
+            requested: authUrl,
+            why: "the cached session was issued by another service — run `bir setup` (or `bir login`) for this one",
+        });
+        return undefined;
+    }
     if (cached && isAccessValid(cached))
         return cached;
     if (cached?.refreshToken) {
@@ -513,7 +581,7 @@ export async function deviceLogin(authUrl, opts = {}) {
         sleep: opts.sleep,
         signal: opts.signal,
     });
-    const session = toSession(res);
+    const session = toSession(res, authUrl);
     saveCredentials(session);
     return session;
 }
@@ -536,7 +604,7 @@ export async function tokenLogin(authUrl, token, opts = {}) {
     if (res.status === 404)
         throw new DeviceFlowUnsupported();
     if (res.ok) {
-        const session = toSession((await res.json()));
+        const session = toSession((await res.json()), authUrl);
         saveCredentials(session);
         logLine("auth.token_login", { url: authUrl });
         return session;
@@ -604,7 +672,7 @@ export async function legacyPasswordLogin(authUrl) {
         return undefined;
     }
     try {
-        const session = toSession(await postJson(`${authUrl}/auth/login`, { email, password }));
+        const session = toSession(await postJson(`${authUrl}/auth/login`, { email, password }), authUrl);
         saveCredentials(session);
         return session;
     }

package/dist/bin/bir-hooks.d.ts

@@ -2,7 +2,11 @@
 /**
  * bir-hooks — the Claude Code hook receiver and the control server (Tier 1).
  *
- * Run it in the project you will launch `claude` from, in its own terminal:
+ * Normally nobody runs it: `bir install` makes it the SessionStart hook
+ * (`bir-hooks ensure`), which starts it in the background for the project when no
+ * recorder is running there, and `bir up` / `bir down` start and stop that
+ * background process by hand. Its audit lines then go to
+ * ~/.baseinstrunner/logs/<project-key>.log. It can still be run in a terminal:
  *
  *     bir-hooks                       # start; Ctrl-C to stop
  *     bir-hooks 2>&1 | tee -a ~/.baseinstrunner/audit.log
@@ -13,7 +17,8 @@
  *   3. owns run identity, the monotonic `stepIndex`, and the recorder chain (D5).
  *
  * Environment:
- *   BIR_AUTH_URL              BaseIn auth-service (required to record anything)
+ *   BIR_AUTH_URL              BaseIn auth-service. Unset, the address `bir setup`
+ *                             stored in ~/.baseinstrunner/config.json is used
  *   BIR_CONTROL_PORT          preferred port (default 53411; falls back if busy)
  *   BIR_CORRELATION_DECISION  `allow` (default) or `ask` — see below
  *   BIR_NO_CORRELATION=1      never inject a call id; join on fingerprints
@@ -60,5 +65,15 @@
  * hosts that ignore `updatedInput` on a non-allow decision then fall back to
  * fingerprint matching, which is lossy under identical concurrent calls.
  */
-export {};
+/**
+ * Assemble the replay configuration (docs/calculatedReplay.md §5.3 of the guide).
+ *
+ * The steer threshold defaults **above** the service's own detection threshold
+ * (0.9). Detection decides "do not record this again", which is cheap — the worst
+ * case is a lost recording. Steering decides "do not think about this again",
+ * which is a much stronger claim, and a 0.90-similar prompt usually covers only
+ * part of the live task.
+ */
+/** Where the three replay switches came from, for `/health` and `bir doctor`. */
+export type ReplaySource = "env" | "sidecar" | "default";
 //# sourceMappingURL=bir-hooks.d.ts.map