@basein/runner 0.3.25 → 0.3.27

package/README.md

@@ -3,7 +3,7 @@
 A recording MCP **proxy**. It sits between any MCP client (Claude Code, Cursor,
 Codex, an Agent SDK session) and every MCP server that client uses, executes each
 call on the client's behalf, and records the run as a reusable scenario in the
-BaseIn service.
+Basic2202 service (called BaseIn in the runner's own messages).
 
 The design this implements is [docs/BaseInstRunner.md](docs/BaseInstRunner.md).
 This README is the operator's half: how to run it, what it records, and what it
@@ -36,22 +36,23 @@ $env:BIR_SETUP_TOKEN="<token>"; irm https://api.bi2202.com/install.ps1 | iex
 curl -fsSL https://api.bi2202.com/install.sh | BIR_SETUP_TOKEN="<token>" sh       # macOS / Linux
 ```
 
-That installs Node if the machine has none (a private copy, never on PATH),
+That installs Node if the machine has none it can use (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
+safe, and is also how you upgrade (or `bir update`, then `bir setup` in each
+project). 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,
+The scripts are `scripts/install.ps1` and `scripts/install.sh` in this
+package; the API serves them with its own address filled in, at
+<https://api.bi2202.com/install.ps1> and <https://api.bi2202.com/install.sh>. Step by step, and what each line does:
+[the handbook's Getting started](https://docs.bi2202.com/#start). For a fleet — packaging, releases,
 offline installs, updates: [docs/installRun.md](docs/installRun.md).
 
-By hand, or when developing BaseInstRunner itself:
+By hand (Node 20 or newer), or when developing BaseInstRunner itself:
 
 ```bash
 npm i -g @basein/runner          # or: npm install && npm run build, in a checkout
@@ -197,9 +198,9 @@ exits 2; it sets nothing up.
 
 Those two lines load a LangChain middleware from the Python package
 `langchain-basic2202`, which reports every call to the recorder. That package
-and the service's LangChain part are needed too, and neither is out yet. The
-how-to is [langChainGuide.md](langChainGuide.md) in the repository's root; it
-is not in the npm package.
+is needed too, and it is not out yet: it is not on PyPI. The
+how-to is the handbook's LangChain page,
+[docs.bi2202.com/#langchain](https://docs.bi2202.com/#langchain).
 
 ### Taking it out
 
@@ -287,7 +288,7 @@ between the two is not guaranteed.
   (`bir up --restart`), for the reason in the next section.
 - **Change what the model does.** Tool descriptions are never edited. The
   model-visible changes are one declared schema key (below), the first-party
-  `bir` server's `run_scenario` (only with `--replay`), and replay's own
+  `bir` server's `run_scenario` and `report_wrong_result` (the agent's way to say a replay's results are wrong; both only with `--replay`), and replay's own
   `[BaseInstRunner calculated replay]` notes when a prompt matches a scenario.
   The `bir` server's three tools that only read a scenario (`scenario_show`,
   `scenario_edits`, `investigate`) and the three for changing one
@@ -298,11 +299,11 @@ between the two is not guaranteed.
   forced past the scenario check (`force`) still asks the person first. Their
   definitions ride along with every request, so `bir scenario editing off`
   takes the six away, and a later setup leaves that off. A bare
-  `bir install --replay` lists `run_scenario` alone until
+  `bir install --replay` lists only `run_scenario` and `report_wrong_result` until
   `bir scenario editing on` (or `BIR_SCENARIO_TOOLS=read` in the server's
   environment, for the reading three). With the runner off it lists no tools
   at all.
-- **Record its own `bir` calls** (next version, not yet released). A session
+- **Record its own `bir` calls.** A session
   that fixes a plan is not a task to replay. The `bir` server's tools other
   than `run_scenario`, and a `Bash` or `PowerShell` command made only of `bir`
   commands, are never recorded as steps and never count as leaving a plan.
@@ -311,7 +312,7 @@ between the two is not guaranteed.
   runs here, in the recorder's own process and context (Node's `vm`, not a
   sandbox), next to your sign-in and your wrapped servers. It has a time limit
   (`BIR_LOGIC_TIMEOUT_MS`, 1 s by default) and no memory limit.
-  The service will sandbox its own runs of the same code (with its next deploy);
+  The service sandboxes its own runs of the same code;
   the runner does not. The service's check of a hand edit only judges what the
   code returns for the recording's values, so it cannot prove what the code
   does here: read a hand edit before it is saved. See
@@ -379,8 +380,7 @@ the plan is retired and nothing runs. Mixed scenarios steer the live session
 instead, pinning each step's arguments. Either way the turn reports what it
 cost, so the savings ledger measures something real.
 
-**Fixing a step.** Built 2026-09-25, not yet released: it needs the next
-`@basein/runner` version and a service deploy. A calculated step is code, and
+**Fixing a step.** From runner 0.3.0. A calculated step is code, and
 code can be wrong. `bir investigate` names such a step; `bir scenario edit`
 fixes it, and the service checks the change against the recording before it
 saves it. **A change is saved only if it reproduces the recording and is not a
@@ -394,7 +394,7 @@ which `bir setup` turns on (`bir scenario editing on` in a project wired by
 [the guide's §9.2](docs/calculatedReplayGuide.md).
 
 The service can correct a plan itself too, after the agent did a planned task
-again its own way (built 2026-10-23, not yet released). `bir scenario edits`
+again its own way (from runner 0.3.16). `bir scenario edits`
 lists such a correction beside the hand edits, under its `scor_` id. Undoing it
 puts back the whole plan from before, and the plan is then held until you
 choose "Use it again" on the recording page.
@@ -411,7 +411,7 @@ bir scenario calc  scn_… --force --discard-edits           # recalculate this
 bir scenario editing on                                    # let Claude's `bir` tools change scenarios here (setup did)
 ```
 
-**A value no prompt names.** Built 2026-09-28, not yet released. Every
+**A value no prompt names.** From runner 0.3.4. Every
 parameter is a *target* (a prompt must name it, or the plan is declined:
 `missing_target`) or a *setting* (its recorded value is used when a prompt
 names none). When the calculation made a database, a host or a working folder a
@@ -449,7 +449,7 @@ the next one:
 BIR_CORRELATION_DECISION=allow bir up --restart
 ```
 
-`BIR_CORRELATION_DECISION=ask` carries the id and keeps the prompt. Hosts that
+`BIR_CORRELATION_DECISION=ask` carries the id and has Claude Code ask about each wrapped call, even one you allowed. Hosts that
 ignore `updatedInput` on a non-allow decision then fall back to fingerprint
 matching.
 
@@ -501,6 +501,7 @@ what to do when they register, so there is one switch and no second copy of it:
 | `BIR_REPLAY_BUDGET_MS` / `BIR_STEP_TIMEOUT_MS` | Whole-plan and per-step ceilings for direct execution (default `100000` / `60000`; `BIR_REPLAY_PLAN_BUDGET_MS` also sets the first). A direct run's parameter wait plus its plan are held under 270 s. |
 | `BIR_LOGIC_TIMEOUT_MS` | How long one scenario logic body may run before it is stopped and the plan hands over (default `1000`, at most `10000`). |
 | `BIR_REPLAY_RECORDED_OUTPUTS=1` | Let a step's recorded output stand in when the step could not be sent. Unset, the plan stops at that step and hands the task back. |
+| `BIR_CONTINUATIONS` | After a plan hands the task back, the agent's next call asks the service once for the plan of the work recorded after an earlier hand-over at that step, and that plan does the rest of the task (from 0.3.23). `0` turns it off, and so does `BIR_INTENT_MATCH=0`. |
 
 The `bir` server reads its own: `BIR_SCENARIO_TOOLS=read` lists its three reading
 tools where scenario editing is off, and `BIR_SCENARIO_RUN_TIMEOUT_MS` is how
@@ -531,11 +532,11 @@ The governing rule: **a host session never fails because of BaseInstRunner.**
 | Failure | Behaviour |
 |---|---|
 | No recorder running at session start | the SessionStart hook starts one in the background; it always exits 0 and never holds the start longer than about 11.5 s |
-| Control server unreachable at startup | steps buffered ≤ 10 s, then Tier 2 (passthrough: nothing); the proxy keeps looking every 15 s and binds when one answers |
+| Control server unreachable at startup | steps buffered for about 10 s, then Tier 2 (passthrough: nothing); the proxy keeps looking every 15 s and binds when one answers |
 | Control server dies mid-session | the proxy records to a Tier 2 run of its own (flagged lossy), starts the recorder again in the background (not after `bir down`), and binds to it once it answers |
 | A hook the recorder cannot answer in time | every route has a hard deadline (prompt 8.5 s, `PreToolUse` 12 s, the others 1–2 s) and answers `{}`; so does a hook with a stale token or a malformed body |
-| BaseIn service slow or down | hooks stop waiting on it after one failure (a cool-down of 5 s, doubling to 60 s); sends go on in the background, retried once only when they cannot have arrived (429, 503, a refused connection); past 500 queued sends or 32 MiB the oldest steps are dropped |
-| BaseIn service answers `429`: the account is over one of its limits | the send — a run's create, a step, a report — goes once more, at most 2 s later, and is then dropped, with `recorder.send_failed … HTTP 429` on the log (one line per run). A dropped step is a hole in its recording; a run whose create was refused runs without its plan; a `429` the second try did not cure starts the cool-down above. The limits are settings of the service, per account — by default 120 runs and 3,000 steps a minute (a tool call is two steps), 10 title requests a minute, and 20 Calculate, Prefer and Recalculate requests in any one hour — and are built there, not deployed yet |
+| BaseIn service slow or down | hooks stop waiting on it after one failure (a cool-down of 5 s, doubling to 60 s); sends go on in the background, retried once only when they cannot have arrived (429, 503, a refused connection); past 500 queued sends or 32 MiB the oldest steps are dropped, and so is a send that has waited a minute for a service still down |
+| BaseIn service answers `429`: the account is over one of its limits | the send — a run's create, a step, a report — goes once more, at most 2 s later, and is then dropped, with `recorder.send_failed … HTTP 429` on the log (one line per run). A dropped step is a hole in its recording; a run whose create was refused runs without its plan; a `429` the second try did not cure starts the cool-down above. The limits are settings of the service, per account — by default 120 runs and 3,000 steps a minute (a tool call is two steps), 10 title requests a minute, and 20 Calculate, Prefer and Recalculate requests in any one hour |
 | Upstream fails to start, or exits | calls in flight are answered (`MCP server "<name>" is not available`, `isError: true` for a `tools/call`), then `bir-proxy` exits with the server's own status, so Claude Code shows the server as failed, as it would unwrapped. `BIR_PROXY_STAY_UP=1` keeps the proxy up answering that instead |
 | Remote upstream unreachable or refusing | the request gets a short error (`upstream unreachable: …`, `upstream requires sign-in (HTTP 401)`), never the server's body; only connecting is bounded (10 s), never how long a tool runs |
 | Result over 128 MiB | the call ends with an error saying the result was too large to deliver, instead of hanging |
@@ -551,7 +552,7 @@ The governing rule: **a host session never fails because of BaseInstRunner.**
 project, and uninstalls nothing: hooks answer with nothing within about a
 second, in sessions already open too, and nothing is recorded, replayed or sent;
 wrapped MCP servers run as plain pipes to the real server from their next start
-(a new session, or `/mcp` → reconnect), and keep recording until then; the `bir`
+(a new session, or `/mcp` → reconnect), and record nothing until then; the `bir`
 server lists no tools. `bir off --here` does the same for one project (from a
 subdirectory, the installed project it is in), and `bir on` or `bir on --here`
 undoes it. If the problem goes away, the runner was the cause; if it stays, the
@@ -575,7 +576,7 @@ environment-variable reference, the operations runbook and the findings ledger.
 
 ```bash
 npm run build       # src → dist
-npm test            # ~1,000 tests: transcript identity, passthrough, correlation, config, replay, setup
+npm test            # ~1,300 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)
 ```
@@ -584,7 +585,7 @@ The core test is **transcript identity**: the same scripted conversation is run
 against a fake upstream directly and through the proxy, and every host-visible
 message must match. If a change breaks transparency, that test says so first.
 
-`test/smoke-replay.mjs` is the other one worth running by hand. Everything else
+`test/smoke-replay.mjs` is the other one worth running by hand. Most of the suite
 runs in-process; this starts a stand-in BaseIn service, a real `bir-hooks`, a real
 `bir-proxy` wrapping a real MCP server and a real `bir-scenario`, then drives a
 two-step scenario through actual stdio. It is what catches the seams between

package/dist/auth/client.d.ts

@@ -12,7 +12,10 @@
  *
  *   1. Load the cached session from ~/.baseinstrunner/credentials.json.
  *   2. If the access token is still valid, reuse it.
- *   3. Else if a refresh token is present, POST /auth/refresh (silent).
+ *   3. Else if a refresh token is present, POST /auth/refresh (silent). A
+ *      refusal is checked against the file before it is believed: the service
+ *      rotates refresh tokens, and a sibling process may have spent this one
+ *      a moment ago and saved the session it got for it.
  *   4. Else give up and return undefined.
  *
  * It used to have a fifth step — prompt for a password — and that had to go

package/dist/auth/client.js

@@ -12,7 +12,10 @@
  *
  *   1. Load the cached session from ~/.baseinstrunner/credentials.json.
  *   2. If the access token is still valid, reuse it.
- *   3. Else if a refresh token is present, POST /auth/refresh (silent).
+ *   3. Else if a refresh token is present, POST /auth/refresh (silent). A
+ *      refusal is checked against the file before it is believed: the service
+ *      rotates refresh tokens, and a sibling process may have spent this one
+ *      a moment ago and saved the session it got for it.
  *   4. Else give up and return undefined.
  *
  * It used to have a fifth step — prompt for a password — and that had to go
@@ -44,7 +47,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync } from "node
 import { hostname } from "node:os";
 import { configDir, configPath, ensureDir } from "../control/paths.js";
 import { join } from "node:path";
-import { logLine, errText } from "../util/log.js";
+import { logDetail, logLine, errText } from "../util/log.js";
 import { packageVersion } from "../util/version.js";
 import { serviceHeaders } from "../util/service-headers.js";
 import { writeFileAtomic } from "../util/atomic-write.js";
@@ -536,6 +539,22 @@ async function tryRefresh(authUrl, refreshToken) {
         return { rejected };
     }
 }
+/**
+ * After a refused refresh, how long to wait before the second look at
+ * credentials.json: the sibling that spent the token a moment ago has the
+ * service's answer and may not have written it yet. The recorder waits the
+ * same (record/remote-recorder.ts).
+ */
+const REFUSED_RECHECK_MS = 1_500;
+/**
+ * The session in credentials.json, when it is one for `authUrl` that carries
+ * another refresh token than `spent`: what a sibling's refresh, or a new
+ * sign-in, saved after this process read the file.
+ */
+function savedSince(authUrl, spent) {
+    const stored = loadCredentials();
+    return stored && stored.refreshToken !== spent && issuedFor(stored, authUrl) ? stored : undefined;
+}
 /**
  * Authenticate and return a valid session, or `undefined` when none can be
  * obtained. Callers degrade to not-recording rather than failing the session.
@@ -571,25 +590,75 @@ export async function authenticate(opts) {
     if (cached && isAccessValid(cached))
         return cached;
     if (cached?.refreshToken) {
-        const { session: refreshed, rejected } = await tryRefresh(authUrl, cached.refreshToken);
+        // The session whose refresh token is being spent: the cached one, or the
+        // one a sibling wrote while ours was being refused.
+        let spent = cached;
+        let { session: refreshed, rejected } = await tryRefresh(authUrl, spent.refreshToken);
+        if (rejected) {
+            // The service rotates refresh tokens — each works once — and every
+            // process reads the same file. Two proxies that start together on an
+            // expired access token both read r1; the one whose refresh arrives
+            // second is refused, while the winner's session is in the file or about
+            // to be. Believing that refusal left this process signed out for its
+            // whole life beside a valid session: a proxy recorded nothing, and the
+            // CLI said "run `bir login`". So the file is read again — now, and once
+            // more when the winner has had time to write — as the recorder does
+            // (record/remote-recorder.ts, refresh).
+            let newer = savedSince(authUrl, spent.refreshToken);
+            if (!newer) {
+                await defaultSleep(REFUSED_RECHECK_MS);
+                newer = savedSince(authUrl, spent.refreshToken);
+            }
+            if (newer) {
+                logDetail("auth.adopted", { why: "another process had already refreshed" });
+                if (isAccessValid(newer))
+                    return newer;
+                // Newer, and expired all the same. Its refresh token is not the one
+                // that was just refused, so it gets its one try.
+                spent = newer;
+                ({ session: refreshed, rejected } = await tryRefresh(authUrl, spent.refreshToken));
+            }
+        }
         if (!refreshed && !rejected && opts?.keepStaleOnNoAnswer) {
             logLine("auth.refresh_deferred", {
                 why: "the service did not answer the refresh — starting with the expired session; it is renewed once the service is back",
             });
-            return cached;
+            return spent;
         }
         if (refreshed) {
-            try {
-                saveCredentials(refreshed);
-            }
-            catch (err) {
-                // The service has already rotated the refresh token, so the one on
-                // disk is dead either way. Throwing here would also lose the new one
-                // and kill the recorder at start; returning it keeps this process
-                // recording, and the next save (a later refresh) repairs the file.
-                logLine("auth.save_failed", { error: errText(err), why: "the new session still works in this process" });
+            // Saved only while the file still holds the token this refresh spent
+            // (the keeper's rule: control/recorder-keeper.ts, saveRefreshed). A
+            // refresh can take seconds, and `bir logout` or a sign-in as someone
+            // else may finish meanwhile; saving over that signed the machine back
+            // in, or put the account just left back in the file.
+            //
+            // A file that is there and cannot be read (a lock, a moment's torn
+            // write) is no sign-in to protect: it is written over, as the recorder
+            // does (record/remote-recorder.ts). Taken for a sign-out, it lost the
+            // session the service had just rotated to, and left the dead token on
+            // disk: every process signed out until `bir login`.
+            const onDisk = loadCredentials();
+            const unreadable = onDisk === undefined && existsSync(credentialsPath());
+            if (unreadable || onDisk?.refreshToken === spent.refreshToken) {
+                try {
+                    saveCredentials(refreshed);
+                }
+                catch (err) {
+                    // The service has already rotated the refresh token, so the one on
+                    // disk is dead either way. Throwing here would also lose the new one
+                    // and kill the recorder at start; returning it keeps this process
+                    // recording, and the next save (a later refresh) repairs the file.
+                    logLine("auth.save_failed", { error: errText(err), why: "the new session still works in this process" });
+                }
+                return refreshed;
             }
-            return refreshed;
+            // Not ours to overwrite, and not ours to use either: this process would
+            // act for an account the machine has left. What is on disk decides.
+            logDetail("auth.refresh_superseded", {
+                why: "the sign-in on disk changed while a refresh was out; what is on disk now decides",
+            });
+            if (onDisk && issuedFor(onDisk, authUrl) && isAccessValid(onDisk))
+                return onDisk;
         }
     }
     // No session, and this function does not make one. Signing in is a browser

package/dist/bin/bir-hooks.js

@@ -139,7 +139,7 @@ import { dirname, resolve } from "node:path";
 import { Writable } from "node:stream";
 import { ENSURE_ARG } from "../config/adapters/claude-code.js";
 import { exemptLoopbackFromProxy } from "../config/generate.js";
-import { REVIVE_ARG } from "../control/daemon.js";
+import { REVIVE_ARG, exitLogged } from "../control/daemon.js";
 import { daemonLogPath, ensureDir } from "../control/paths.js";
 import { errText, logLine } from "../util/log.js";
 /**
@@ -263,6 +263,8 @@ void main().catch((err) => {
         process.exit(0);
     }
     logLine("control.fatal", { error: errText(err) });
-    process.exit(1);
+    // Not `process.exit(1)`: the recorder's log is written in the background,
+    // and the line above — the reason it stopped — would be lost with the rest.
+    exitLogged(1);
 });
 //# sourceMappingURL=bir-hooks.js.map