@basein/runner 0.3.9 → 0.3.11

package/README.md

@@ -59,7 +59,9 @@ cd the-project-you-record-from
 bir setup --auth-url https://api.bi2202.com    # everything below, in one go
 ```
 
-or the pieces `bir setup` is made of:
+or the pieces `bir setup` is made of (on a machine with no stored address yet,
+`bir login` needs `BIR_AUTH_URL=https://api.bi2202.com` set: it does not read
+`--auth-url`):
 
 ```bash
 bir login                        # once; approve it in the browser (or --token <t> from the console)
@@ -152,7 +154,11 @@ work through (not recording, a proxy not registered yet, the service
 unreachable): exit 0, or 1 with `--strict`. `--quick` does not call the service.
 `bir status` also shows the recorder's view of the service, the off switch, a
 port the recorder could not take, a STALE local copy, and the other projects set
-up on this machine.
+up on this machine. In a folder set up for another host
+([A LangChain application](#a-langchain-application)) both add a `Host` line:
+it names the host and says that no Claude Code hooks are needed there, or, in
+a folder set up for both, names Claude Code too. `bir status --json` carries
+`hosts`, and `bir doctor` does not report missing hooks in such a folder.
 
 ### Any other MCP client
 
@@ -164,6 +170,37 @@ bir install --config /path/to/that/client/mcp.json
 bir wrap --server-name my-server -- node my-server.js    # prints an entry to paste
 ```
 
+### A LangChain application
+
+A Python program whose agent is built with LangChain's `create_agent` is set up
+in another way: nothing of Claude Code is wired. In the folder the application
+starts in:
+
+```bash
+bir setup --host langchain       # a machine with no stored address: add --auth-url https://api.bi2202.com
+```
+
+It signs in, gives the folder an entry of its own in
+`~/.baseinstrunner/installed.json` — a fixed port, a token, and replay on
+(`--no-replay` stores it off; `bir replay on` / `off` work there as anywhere) —
+starts the recorder in the background, and prints the two lines of Python to
+add to the agent. It writes nothing under `.claude/` and nothing into
+`~/.claude.json`: no hooks, no wrapped servers, no `bir` server. A folder
+already set up for Claude Code keeps that set-up as it is. While a folder is
+not set up for Claude Code as well, its recorder is started with a small
+environment — `PATH`, the home and temp folders, what the system needs to
+start a process, the proxy and certificate settings, and the `BIR_*`
+variables — so the application's keys and passwords are not in the process that
+runs scenario code unsandboxed ([What it will not do](#what-it-will-not-do)).
+A runner that does not know `--host` (0.3.9 and older) prints its usage and
+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.
+
 ### Taking it out
 
 ```bash
@@ -177,7 +214,9 @@ leaves it running switched off for this project: restart that session, then
 `bir down` (`--keep-recorder` leaves the recorder alone). While anything here
 still runs through the runner it exits 1 with `Not everything could be undone`
 and a list; fix what it names and run it again. `--server <name>` takes out only
-that server, and `--replay` only the scenario server, switching replay off.
+that server, and `--replay` only the scenario server, switching replay off. In
+a folder set up for another host it removes the folder's entry — its port,
+token and replay switch — and stops its recorder.
 
 Remove the package (`npm rm -g @basein/runner`, or delete `~/.baseinstrunner`,
 where the install line's copy lives) only after `bir uninstall --all` has
@@ -244,7 +283,8 @@ between the two is not guaranteed.
   else. Calculated replay — running a matched prompt's scenario instead of
   rediscovering it — ships, but needs `bir install --replay`, which `bir setup`
   runs unless given `--no-replay`. Once installed it is on; `bir replay off` or
-  `BIR_REPLAY=0` turns it off, for the reason in the next section.
+  `BIR_REPLAY=0` turns it off from the recorder's next start
+  (`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
@@ -448,7 +488,7 @@ what to do when they register, so there is one switch and no second copy of it:
 | `ANTHROPIC_API_KEY` | Not used by the background recorder, which has Claude Code's environment and would bill your own key — unless `BIR_USE_ANTHROPIC_API_KEY=1`. A `bir-hooks` run by hand in a terminal uses that terminal's key. |
 | `BIR_DERIVE_MODEL` | Derivation model, when you set a key of your own (default `claude-haiku-4-5-20251001`). |
 | `BIR_MATCH_BUDGET_MS` | How long the prompt hook waits for a match (default `3000`). After a match slower than `BIR_MATCH_SLOW_MS` (default `2000`), or one that timed out, prompts stop waiting for 5 min, doubling up to 30 min; a fast match ends that. |
-| `BIR_DERIVE_BUDGET_MS` / `BIR_HOOK_DERIVE_BUDGET_MS` | How long a direct run, and a hook, waits for parameters (default `8000` / `4000`; a hook waits the smaller). |
+| `BIR_DERIVE_BUDGET_MS` / `BIR_HOOK_DERIVE_BUDGET_MS` | How long a direct run, and a hook, waits for parameters (default `8000` / `8000`; a hook waits the smaller, and the prompt hook never past its own 7.5 s). |
 | `BIR_PRETOOL_REPLAY_BUDGET_MS` | Everything replay does inside one `PreToolUse` (default `9000`, at most `10000`). |
 | `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`). |
@@ -485,8 +525,9 @@ The governing rule: **a host session never fails because of BaseInstRunner.**
 | 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 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 7 s, `PreToolUse` 12 s, the others 1–2 s) and answers `{}`; so does a hook with a stale token or a malformed body |
+| 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 |
 | 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 |

package/dist/auth/client.d.ts

@@ -197,6 +197,21 @@ export declare const AUTH_URL_HINT: string;
  * strict about the content type, which is what separates a service from a page.
  */
 export declare function describeAuthService(baseUrl: string, fetchImpl?: typeof fetch): Promise<string | undefined>;
+/** What `GET /health` said about the service at an address. */
+export interface AuthServiceView {
+    /** One line saying what answered instead of a BaseIn service; absent when one did. */
+    problem?: string;
+    /** The newest contract the service speaks (util/service-headers.ts). Absent from an older service. */
+    contract?: number;
+    /** The lowest contract a runner needs to be handed a plan. Absent from an older service. */
+    minRunner?: number;
+}
+/**
+ * {@link describeAuthService}, plus the two numbers a service puts on its
+ * `/health` so a runner can tell that it is too old to be handed a plan
+ * (`bir doctor` says so). An answer without them is an older service.
+ */
+export declare function inspectAuthService(baseUrl: string, fetchImpl?: typeof fetch): Promise<AuthServiceView>;
 /**
  * Authenticate and return a valid session, or `undefined` when none can be
  * obtained. Callers degrade to not-recording rather than failing the session.

package/dist/auth/client.js

@@ -46,6 +46,7 @@ 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";
+import { serviceHeaders } from "../util/service-headers.js";
 import { writeFileAtomic } from "../util/atomic-write.js";
 import { isUnhealthyStatus, serviceHealth, serviceTimeoutMs, timeoutSignal } from "../util/service-health.js";
 /** A non-2xx answer from the service, with its status. */
@@ -301,6 +302,7 @@ export async function normalizeAuthUrl(baseUrl, fetchImpl = fetch) {
         // timeout (10-20 s) and a host that accepts and never answers cost 300 s.
         res = await fetchImpl(`${base}/health`, {
             method: "GET",
+            headers: serviceHeaders(),
             redirect: "manual",
             signal: timeoutSignal(PROBE_TIMEOUT_MS),
         });
@@ -375,9 +377,18 @@ function causeText(err) {
  * strict about the content type, which is what separates a service from a page.
  */
 export async function describeAuthService(baseUrl, fetchImpl = fetch) {
+    return (await inspectAuthService(baseUrl, fetchImpl)).problem;
+}
+/**
+ * {@link describeAuthService}, plus the two numbers a service puts on its
+ * `/health` so a runner can tell that it is too old to be handed a plan
+ * (`bir doctor` says so). An answer without them is an older service.
+ */
+export async function inspectAuthService(baseUrl, fetchImpl = fetch) {
+    const problem = (text) => ({ problem: text });
     const base = baseUrl.replace(/\/+$/, "");
     if (!base)
-        return "no URL configured";
+        return problem("no URL configured");
     // Not reported to the health verdict, unlike every other request here: this
     // is asked of *candidate* addresses (a website someone pasted, a typo), and
     // their failure says nothing about the service the runner actually uses.
@@ -385,26 +396,37 @@ export async function describeAuthService(baseUrl, fetchImpl = fetch) {
     try {
         res = await fetchImpl(`${base}/health`, {
             method: "GET",
-            headers: { accept: "application/json" },
+            headers: { accept: "application/json", ...serviceHeaders() },
             redirect: "manual",
             signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
         });
     }
     catch (err) {
-        return `unreachable (${causeText(err)})`;
+        return problem(`unreachable (${causeText(err)})`);
     }
     if (res.status >= 300 && res.status < 400) {
-        return `redirects to ${res.headers.get("location") ?? "somewhere else"} — use the final address`;
+        return problem(`redirects to ${res.headers.get("location") ?? "somewhere else"} — use the final address`);
     }
     const type = (res.headers.get("content-type") ?? "").toLowerCase();
     if (!res.ok) {
-        return `GET /health answered HTTP ${res.status}${type.includes("html") ? " with a web page" : ""}`;
+        return problem(`GET /health answered HTTP ${res.status}${type.includes("html") ? " with a web page" : ""}`);
     }
     if (!type.includes("json")) {
         const what = type.includes("html") ? "a web page" : type ? `'${type}'` : "no content type";
-        return `GET /health answered ${what} instead of JSON — that is a website, not the BaseIn API`;
+        return problem(`GET /health answered ${what} instead of JSON — that is a website, not the BaseIn API`);
     }
-    return undefined;
+    // Still loose about the body: one that cannot be read, or has neither
+    // number, is a service that answers — an older one.
+    let body;
+    try {
+        body = JSON.parse(await res.text());
+    }
+    catch {
+        return {};
+    }
+    const b = (body && typeof body === "object" ? body : {});
+    const count = (v) => (typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : undefined);
+    return { contract: count(b.contract), minRunner: count(b.minRunner) };
 }
 function prompt(question) {
     const rl = createInterface({ input: process.stdin, output: process.stderr });
@@ -463,7 +485,7 @@ async function postJson(url, body) {
         // seconds, not minutes.
         res = await fetch(url, {
             method: "POST",
-            headers: { "content-type": "application/json" },
+            headers: { "content-type": "application/json", ...serviceHeaders() },
             body: JSON.stringify(body),
             signal: timeoutSignal(serviceTimeoutMs()),
         });
@@ -604,7 +626,7 @@ export async function startDeviceCode(authUrl, client, fetchImpl = fetch) {
     try {
         res = await fetchImpl(`${authUrl}/auth/device/code`, {
             method: "POST",
-            headers: { "content-type": "application/json" },
+            headers: { "content-type": "application/json", ...serviceHeaders() },
             body: JSON.stringify({ clientName: client.name, clientVersion: client.version }),
             signal: timeoutSignal(serviceTimeoutMs()),
         });
@@ -666,7 +688,7 @@ export async function pollDeviceToken(authUrl, deviceCode, opts) {
             // the request in flight rather than after the service answers it.
             res = await fetchImpl(`${authUrl}/auth/device/token`, {
                 method: "POST",
-                headers: { "content-type": "application/json" },
+                headers: { "content-type": "application/json", ...serviceHeaders() },
                 body: JSON.stringify({ deviceCode }),
                 signal: timeoutSignal(serviceTimeoutMs(), opts.signal),
             });
@@ -832,7 +854,7 @@ export async function tokenLogin(authUrl, token, opts = {}) {
     try {
         res = await fetchImpl(`${authUrl}/auth/device/token`, {
             method: "POST",
-            headers: { "content-type": "application/json" },
+            headers: { "content-type": "application/json", ...serviceHeaders() },
             body: JSON.stringify({ deviceCode: token.trim() }),
             signal: timeoutSignal(serviceTimeoutMs()),
         });
@@ -942,7 +964,7 @@ export async function logout(authUrl) {
         try {
             const res = await fetch(`${authUrl}/auth/logout`, {
                 method: "POST",
-                headers: { "content-type": "application/json" },
+                headers: { "content-type": "application/json", ...serviceHeaders() },
                 body: JSON.stringify({ refreshToken: cached.refreshToken }),
                 signal: timeoutSignal(LOGOUT_TIMEOUT_MS),
             });

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

@@ -91,7 +91,7 @@
  *   BIR_MATCH_BUDGET_MS       prompt-hook match wait (default 3000)
  *   BIR_DERIVE_BUDGET_MS      derivation wait before a direct run (default 8000);
  *                             inside a hook it is at most BIR_HOOK_DERIVE_BUDGET_MS
- *                             (default 4000)
+ *                             (default 8000)
  *   BIR_DERIVE_RECENT_RESULTS how many of this prompt's tool results derivation
  *                             reads, so a target named by an earlier step can be
  *                             found (default 5; 0 off)

package/dist/bin/bir-hooks.js

@@ -91,7 +91,7 @@
  *   BIR_MATCH_BUDGET_MS       prompt-hook match wait (default 3000)
  *   BIR_DERIVE_BUDGET_MS      derivation wait before a direct run (default 8000);
  *                             inside a hook it is at most BIR_HOOK_DERIVE_BUDGET_MS
- *                             (default 4000)
+ *                             (default 8000)
  *   BIR_DERIVE_RECENT_RESULTS how many of this prompt's tool results derivation
  *                             reads, so a target named by an earlier step can be
  *                             found (default 5; 0 off)

package/dist/bin/bir.d.ts

@@ -3,6 +3,7 @@
  * bir — the command line (Phase 7).
  *
  *   bir setup [--auth-url <url>] [--token <t>] [--project <dir>]   ← the one command
+ *   bir setup --host langchain   ← the folder of a LangChain application: an entry and a recorder, no Claude Code wiring
  *   bir up [--restart] | bir down
  *   bir off [--here] | bir on [--here]   ← the kill switch: inert at once, nothing uninstalled
  *   bir install [--config <path>] [--server <name>]… [--local] [--no-hooks]
@@ -11,6 +12,7 @@
  *   bir doctor [--quick]
  *   bir wrap --server-name <key> -- <command> [args…]
  *   bir login | logout
+ *   bir update   ← the newest version, into the copy that is running (update.ts)
  *   bir --version
  *
  *   bir scenario list | show <runId|scnId> [--step <n>] | calc <runId|scnId> [--force [--discard-edits]]

package/dist/bin/bir.js

@@ -3,6 +3,7 @@
  * bir — the command line (Phase 7).
  *
  *   bir setup [--auth-url <url>] [--token <t>] [--project <dir>]   ← the one command
+ *   bir setup --host langchain   ← the folder of a LangChain application: an entry and a recorder, no Claude Code wiring
  *   bir up [--restart] | bir down
  *   bir off [--here] | bir on [--here]   ← the kill switch: inert at once, nothing uninstalled
  *   bir install [--config <path>] [--server <name>]… [--local] [--no-hooks]
@@ -11,6 +12,7 @@
  *   bir doctor [--quick]
  *   bir wrap --server-name <key> -- <command> [args…]
  *   bir login | logout
+ *   bir update   ← the newest version, into the copy that is running (update.ts)
  *   bir --version
  *
  *   bir scenario list | show <runId|scnId> [--step <n>] | calc <runId|scnId> [--force [--discard-edits]]
@@ -52,11 +54,12 @@ import { claudeUserSettingsPath, managedMcpPolicyBlocker, mcpjsonApprovals } fro
 import { checkOverrides, recordServerName } from "../config/overrides.js";
 import { awaitWithin, isUnhealthyStatus, serviceHealth, serviceTimeoutMs, timeoutSignal } from "../util/service-health.js";
 import { runSetup } from "./setup.js";
+import { runUpdate } from "./update.js";
 import { claudeConfigHome, claudeProjectKey, claudeProjectRoot, isRemote, linkedWorktrees, parseJsonFile, projectKeyFor, projectKeysFor, projectScope, resolveServers, } from "../config/resolve.js";
-import { addAllowRules, allowRules, assertEditableJson, BIR_TOOLS_RULE, buildHooksBlock, claudeCodePaths, disableMcpjsonServers, enableMcpjsonServers, ENSURE_ARG, ensureGitExcludeLine, hasBirHooks, installHooks, isBirHook, LOCAL_SETTINGS_EXCLUDE, readTextOrNull, removeAllowRules, removeGitExclude, setLocalEntries, setServerEntry, sha256, uninstallHooks, } from "../config/adapters/claude-code.js";
+import { addAllowRules, allowRules, assertEditableJson, BIR_TOOLS_RULE, buildHooksBlock, claudeCodePaths, claudeCodeSetUp, disableMcpjsonServers, enableMcpjsonServers, ENSURE_ARG, ensureGitExcludeLine, hasBirHooks, installHooks, isBirHook, LOCAL_SETTINGS_EXCLUDE, otherHosts, readTextOrNull, removeAllowRules, removeGitExclude, setLocalEntries, setServerEntry, sha256, uninstallHooks, } from "../config/adapters/claude-code.js";
 import { writeFileAtomic } from "../util/atomic-write.js";
 import { readGenericServers, setGenericServerEntry } from "../config/adapters/generic.js";
-import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, clearCredentials, deviceLogin, describeAuthService, legacyPasswordLogin, tokenLogin, normalizeAuthUrl, rememberAuthUrl, resolveAuthUrl, } from "../auth/client.js";
+import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, clearCredentials, deviceLogin, describeAuthService, inspectAuthService, legacyPasswordLogin, tokenLogin, normalizeAuthUrl, rememberAuthUrl, resolveAuthUrl, } from "../auth/client.js";
 import { DEFAULT_CONTROL_PORT } from "../control/server.js";
 import { errText, logLine } from "../util/log.js";
 import { journalPath, readJournal } from "../util/journal.js";
@@ -64,6 +67,7 @@ import { investigateCommand } from "./investigate.js";
 import { SCENARIO_EDIT_SUBCOMMANDS, scenarioEditCommand } from "./scenario-edit.js";
 import { loadCredentials } from "../auth/client.js";
 import { packageVersion } from "../util/version.js";
+import { runnerOutdated, serviceHeaders } from "../util/service-headers.js";
 const VERSION = packageVersion();
 /**
  * The npx SessionStart hook's own budget, passed as `ensure --budget-ms <n>`
@@ -82,6 +86,8 @@ function usage(code = 0) {
 Commands:
   setup       the one command: sign in, wire this project, start the recorder, and give
               Claude Code every bir tool (run_scenario, investigate, scenario_*) with no prompt
+              (--host langchain: for a LangChain application instead — sign in, give the
+              folder its own port and token, start the recorder; nothing of Claude Code is wired)
   up          start the recorder for this project in the background (--restart: replace it)
   down        stop it (open sessions here then show a hook error until they restart;
               \`bir off --here\` is the quiet way to take it out of the way)
@@ -99,8 +105,10 @@ Commands:
   wrap        print a proxied entry for one server (any MCP client)
   login       sign in to the BaseIn service (opens your browser)
   logout      revoke this machine's session and forget it
+  update      install the newest version over this copy of bir, wherever it was installed
+              (the console's install line or npm); then run \`bir setup\` in each project
 
-  scenario list                     recorded runs and their calculated scenarios
+  scenario list                    recorded runs and their calculated scenarios
   scenario show <runId|scnId> [--step <n>]
                                     a scenario: intent, params, steps (--step: just that one)
   scenario calc <runId|scnId> [--force [--discard-edits]]
@@ -176,6 +184,8 @@ Options:
   --auth-url <url>  setup: the BaseIn API address (else BIR_AUTH_URL, else the stored one)
   --project <dir>   setup: the directory to record (default: this one)
   --no-replay       setup: wire recording only; add no scenario server
+  --host <name>     setup: the host the folder's agent runs in, when it is not Claude Code
+                    (langchain). Writes nothing under .claude/ and nothing into ~/.claude.json
   --allow-servers <a,b>  setup: servers replay may call unattended (default: all wrapped)
   --no-daemon       setup: wire everything, start nothing
   --restart         up: replace a running recorder
@@ -292,6 +302,11 @@ function parseArgs(argv) {
             case "--no-replay":
                 args.noReplay = true;
                 break;
+            case "--host":
+                args.host = (argv[++i] ?? "").trim().toLowerCase();
+                if (!args.host)
+                    usage(2);
+                break;
             case "--allow-servers":
                 args.allowServers = argv[++i];
                 if (args.allowServers === undefined)
@@ -1746,11 +1761,16 @@ function uninstallProject(cwd, sidecar, opts) {
     const myHookFiles = (sidecar.hookFiles ?? []).filter((f) => fileProjectDir(f) === here);
     const hookedNow = [paths.settingsLocal, paths.settings].filter((f) => hasBirHooks(f));
     const before = runnerLeftovers(cwd, sidecar, opts.configPath, otherClaude);
+    // A folder set up for another host (`bir setup --host langchain`) has no
+    // hooks and no wrapped server, and still has something to undo: its entry,
+    // and the recorder the caller stops. It goes past this point.
+    const hostEntry = !narrow && otherHosts(cwd, sidecar).length > 0;
     if (mine.length === 0 &&
         myHookFiles.length === 0 &&
         hookedNow.length === 0 &&
         before.leftovers.length === 0 &&
-        before.unreadable.length === 0) {
+        before.unreadable.length === 0 &&
+        !hostEntry) {
         return { nothing: true, remaining: [] };
     }
     // 1. Byte-for-byte: a project file we wrote, nobody touched since, and whose
@@ -1946,6 +1966,9 @@ function uninstallProject(cwd, sidecar, opts) {
             const record = projectRecord(sidecar, cwd);
             if (sidecar.projects)
                 delete sidecar.projects[here];
+            if (record?.hosts?.length) {
+                out(`  ← this folder's entry for ${record.hosts.join(", ")} removed (its port, token and replay switch)`);
+            }
             if (record?.excludeAdded !== false && existsSync(cwd) && !sharesRepository(cwd, sidecar)) {
                 const exclude = removeGitExclude(cwd);
                 if (exclude)
@@ -2686,8 +2709,11 @@ async function status(args) {
     const portProblem = openPortProblem(cwd, health ? portOf(discovery?.url) : undefined, hookPorts.length === 1 ? hookPorts[0] : undefined);
     // Recorders a reinstall on another port left serving older windows (LC-1).
     const superseded = await supersededRecorders(projectDir);
+    // Hosts other than Claude Code this folder was set up for (`bir setup --host`).
+    const hosts = args.configPath ? [] : otherHosts(projectDir, sidecar);
     const report = {
         cwd,
+        ...(hosts.length ? { hosts } : {}),
         authUrl: resolveAuthUrl() || null,
         controlServer: discovery ? { url: discovery.url, pid: discovery.pid, answering: health !== undefined } : null,
         discoveryFile: discoveryPath(cwd),
@@ -2719,6 +2745,11 @@ async function status(args) {
         return 0;
     }
     out(`Directory : ${report.cwd}`);
+    if (hosts.length) {
+        out(`Host      : set up for ${hosts.join(", ")}${claudeCodeSetUp(projectDir, sidecar)
+            ? ", and for Claude Code"
+            : " — its adapter reports every call, so no Claude Code hooks or wrapped servers are needed here"}`);
+    }
     out(`BaseIn    : ${report.authUrl ?? "(not set — run `bir setup`, or set BIR_AUTH_URL; nothing is recorded)"}`);
     out(`Control   : ${discovery
         ? `${discovery.url} (pid ${discovery.pid}${discovery.daemon ? "; background" : ""})${health ? "" : " — not answering; `bir doctor` says more"}`
@@ -2883,6 +2914,8 @@ async function doctor(args) {
     }
     const wantWrapped = entries.filter((e) => isWrapped(e.config)).map((e) => e.name);
     const hooks = hookFacts(paths);
+    // Hosts other than Claude Code this folder was set up for (`bir setup --host`).
+    const hosts = otherHosts(projectDir, sidecar);
     for (const file of hooks.unreadable) {
         warnings.push(`${file} is not plain JSON, so its hooks could not be checked (and \`bir setup\` will not rewrite it)`);
     }
@@ -2907,6 +2940,12 @@ async function doctor(args) {
         notes.push("the recorder is not running; the SessionStart hook starts it with the next session (`bir up` starts it now)" +
             (wantWrapped.length && !off ? ` — ${wantWrapped.join(", ")} register with it then` : ""));
     }
+    else if (hosts.length > 0) {
+        // Set up for another host (`bir setup --host langchain`): its adapter runs
+        // inside the application and reports every call itself, so there are no
+        // hooks to miss — and it starts the recorder when the application runs.
+        notes.push(`the recorder is not running; the ${hosts.join(", ")} application starts it when it next runs (\`bir up\` starts it now)`);
+    }
     else {
         notes.push("no hooks here: only MCP calls are recorded (standalone, Tier 2) — `bir setup` wires the hooks");
     }
@@ -3105,11 +3144,19 @@ async function doctor(args) {
     // until a password has been posted to it and it says `405`. A warning, not a
     // problem: sessions do not use this shell. `--quick` skips the network call.
     const shellAuthUrl = resolveAuthUrl();
-    const shellAuthProblem = shellAuthUrl && !args.quick ? await describeAuthService(shellAuthUrl) : undefined;
+    const shellService = shellAuthUrl && !args.quick ? await inspectAuthService(shellAuthUrl) : undefined;
+    const shellAuthProblem = shellService?.problem;
     if (shellAuthProblem) {
         warnings.push(`BIR_AUTH_URL in this shell (${shellAuthUrl}) is not a BaseIn service: ${shellAuthProblem}. ` +
             `\`bir login\` and \`bir scenario\` here will fail — ${AUTH_URL_HINT}`);
     }
+    // THE SERVICE HANDS PLANS ONLY TO A NEWER RUNNER. Its `/health` names the
+    // lowest contract it serves (util/service-headers.ts). Under it, every match
+    // comes back with no plan (`runner_update_required`) and the agent does each
+    // task: sessions work and recording goes on, but nothing is replayed.
+    const outdated = runnerOutdated(shellService);
+    if (outdated)
+        warnings.push(outdated);
     // THE SESSIONSTART HOOK NAMES A NODE BY ABSOLUTE PATH. A version manager's
     // per-shell directory, an uninstalled Node, a moved private Node: the hook
     // then fails on every session and the recorder is never started, which
@@ -3318,6 +3365,9 @@ async function doctor(args) {
     else if (health) {
         out("Replay            : off");
     }
+    if (hosts.length) {
+        out(`Host              : ${hosts.join(", ")}${claudeCodeSetUp(projectDir, sidecar) ? ", and Claude Code" : " (no Claude Code hooks are needed here)"}`);
+    }
     out(`Wrapped in config : ${wantWrapped.join(", ") || "(none)"}`);
     out(`Registered proxies: ${[...registered].join(", ") || "(none)"}`);
     out(`Control server    : ${discovery?.url ?? "not running"}`);
@@ -3381,6 +3431,7 @@ async function service(method, path, body) {
             headers: {
                 "content-type": "application/json",
                 authorization: `Bearer ${session.accessToken}`,
+                ...serviceHeaders(),
             },
             body: body === undefined ? undefined : JSON.stringify(body),
             signal: timeoutSignal(serviceTimeoutMs()),
@@ -3710,7 +3761,7 @@ async function revokeRefreshToken(configured, refreshToken) {
         const authUrl = await normalizeAuthUrl(configured);
         const res = await fetch(`${authUrl}/auth/logout`, {
             method: "POST",
-            headers: { "content-type": "application/json" },
+            headers: { "content-type": "application/json", ...serviceHeaders() },
             body: JSON.stringify({ refreshToken }),
             signal: timeoutSignal(LOGOUT_REVOKE_BUDGET_MS),
         });
@@ -3814,6 +3865,7 @@ async function main() {
                 daemon: !args.noDaemon,
                 allowServers: args.allowServers,
                 portExplicit: args.portExplicit,
+                host: args.host,
             }, {
                 out,
                 err: (line) => process.stderr.write(`[bir] ${line}\n`),
@@ -3904,6 +3956,8 @@ async function main() {
         case "off":
         case "on":
             return offCommand(args, args.command === "off");
+        case "update":
+            return runUpdate({ out, err: (line) => process.stderr.write(`[bir] ${line}\n`) });
         case "login": {
             // Settle the URL the way every other command does, then refuse to go on
             // when what is there is not the service. "Signed in" must mean the service

package/dist/bin/investigate.d.ts

@@ -21,6 +21,11 @@ import type { JournalEntry } from "../util/journal.js";
 export interface Turn {
     runId: string;
     sessionId?: string;
+    /**
+     * The host the turn ran in, when its session said it is not Claude Code
+     * (`langchain`): `run.start` names it. Absent for a Claude Code turn.
+     */
+    host?: string;
     startedAt: string;
     finishedAt?: string;
     prompt?: string;