@basein/runner 0.3.9 → 0.3.10

package/dist/bin/investigate.js

@@ -45,6 +45,9 @@ const INCIDENTS = new Set([
     "run.lossy",
     "run.unmeasured",
     "run.prompt_late",
+    // What a host that is not Claude Code said with its stop.
+    "run.incomplete",
+    "run.host_failed",
 ]);
 /**
  * Group journal entries into turns. A turn opens at `run.start` and closes at
@@ -77,7 +80,14 @@ export function turnsFromJournal(entries) {
     for (const e of entries) {
         if (e.event === "run.start") {
             const runId = str(e.run) ?? `unknown-${turns.length}`;
-            const turn = { runId, sessionId: str(e.sess), startedAt: e.at, incidents: [], events: [e] };
+            const turn = {
+                runId,
+                sessionId: str(e.sess),
+                host: str(e.host),
+                startedAt: e.at,
+                incidents: [],
+                events: [e],
+            };
             turns.push(turn);
             continue;
         }
@@ -201,11 +211,45 @@ export const DECLINES = {
         cause: "the scenario has parameters and the runner had no way to derive them: no service session and no ANTHROPIC_API_KEY.",
         fix: "set BIR_AUTH_URL and `bir login` in the terminal that starts bir-hooks, or export ANTHROPIC_API_KEY there.",
     },
+    // Not a gate of the ladder: the control server's own verdict, when arming
+    // outlived the hook that would have announced the plan.
+    arm_timeout: {
+        cause: "the plan was not ready before the hook that would have announced it had to answer: the prompt hook waits 6 s in all, match included, and a tool call that starts a plan mid-task waits 1.5 s. What arming waits for is the reading of the prompt's values (the derivation). A plan that was not announced is never run.",
+        fix: "run the prompt again. If it keeps happening the reading is slow: the recorder's log (`bir status` names the file) shows when its `replay.derived` line landed. BIR_HOOK_DERIVE_BUDGET_MS does not help here, because the hook's own limit was reached first. To read values on this machine instead of asking the service, set BIR_DERIVE_API_KEY where Claude Code starts.",
+    },
+    runner_update_required: {
+        cause: "the service matched the prompt and handed over no plan: this runner is older than its plans need.",
+        fix: "update the runner (`bir update`), then run `bir setup` in each project that uses it; `bir doctor` says when the service is satisfied.",
+    },
     flatten_failed: {
         cause: "the chain could not be flattened — a sub-task it calls no longer resolves.",
         fix: "recalculate the scenario.",
     },
+    // The two gates of a host that is not Claude Code (a LangChain application).
+    host_records_only: {
+        cause: "the runner in that application's folder is older than replay for LangChain needs, so the LangChain package only records.",
+        fix: "nothing to do while replay for LangChain is not released. After that: update the runner. Until then the model does the task, and the run counts as a sample of the usual cost.",
+    },
+    host_tool_missing: {
+        cause: "the plan names a tool that the agent which asked does not have.",
+        fix: "give the agent that tool, or delete the recording so the task is recorded again; `bir scenario show <scnId>` lists the plan's tools.",
+    },
 };
+/** Whether a turn ran in a host that is not Claude Code (see {@link Turn.host}). */
+function otherHost(turn) {
+    return turn.host !== undefined && turn.host !== "claude-code";
+}
+/**
+ * Why a turn's cost is not measured, for a turn of a host that is not Claude
+ * Code. Such a host has no transcript: its adapter hands the tokens over, and
+ * each cause below is one the runner or the service names with a turn.
+ */
+const HOST_UNMEASURED = "the cost of this run was not measured. Either the runner or the LangChain package is too old: update both. " +
+    "Or the model has no price in our table: such a run is recorded and replayed, and its saving is projected, " +
+    "or not shown at all when the plan was recorded on such a model too. " +
+    "Or the plan ended without a model call, so there were no tokens to count. " +
+    "Or more than one plan started in this run, or the run was closed early, or a person said no to a step: " +
+    "then the cost is no measure of this plan, and its saving is projected.";
 /**
  * The `missing_target` fix with what this turn knows put in: the scenario, and
  * the target the gate named (`target database not found`). The code alone once
@@ -222,6 +266,42 @@ function missingTargetFix(fix, turn) {
         text = text.replaceAll("<name>", name);
     return text;
 }
+/**
+ * The cause and fix of a decline whose sentence shows that the *reading* of
+ * the prompt's values (the derivation) went wrong, and not the prompt or the
+ * sign-in its code is named for:
+ *
+ *  - `missing_target`, `target time_min not found — derivation did not answer
+ *    within 4000ms`: the wait ran out. Whether the prompt names the target was
+ *    never learned, and "name it in the prompt" sent a reader to reword a
+ *    prompt that already did (the value landed 0.6 s after the wait).
+ *  - `no_derive_key`, `service: error: target time_min`: the service was asked
+ *    and returned no reading. "No service session" sent a reader to sign in to
+ *    a service that had just answered.
+ *
+ * Undefined for every other decline: its code names the cause.
+ */
+function readingDecline(code, why) {
+    const waitedMs = code === "missing_target" ? /\bderivation did not answer within (\d+) ?ms/.exec(why)?.[1] : undefined;
+    if (waitedMs) {
+        return {
+            cause: `the plan needs a target, a value read from the prompt, and that reading (the derivation) had not answered when the runner stopped waiting for it: its wait is ${waitedMs} ms, and none while the service is cooling down after a slow or failed call. ` +
+                "Whether the prompt names the target was never learned. A replay never takes a target from the recording.",
+            fix: "nothing in the prompt needs to change: run it again. If it keeps happening the reading is slower than the wait, and the recorder's log (`bir status` names the file) has its `replay.derived` line after this decline. Give it longer: set BIR_HOOK_DERIVE_BUDGET_MS where the recorder starts, then `bir up --restart`. The prompt hook stops 6 s after the prompt arrived, whatever is set.",
+        };
+    }
+    // Gate 7 writes `<reason>: target <name>`, and `no_derive_key` itself as the
+    // reason when there was nobody to ask (replay/controller.ts).
+    const reason = code === "no_derive_key" ? why.replace(/: target \S+$/, "") : "";
+    if (reason && reason !== "no_derive_key") {
+        return {
+            cause: `the plan needs a target, a value read from the prompt. The service, which does that reading for a runner with no key of its own, was asked and returned none (\`${reason}\`). ` +
+                "A replay never takes a target from the recording.",
+            fix: "nothing to sign in to or set up here: the runner asked the service, and the reading failed there or on the way. Run the prompt again. `service: error` and `service: timeout` are the service's own model call failing or passing its limit (RUNNER_DERIVE_TIMEOUT_MS there, 6 s by default); `rate_limited`, `unaffordable`, `disabled` and `no_key` are settings of the service. To read values on this machine instead, set BIR_DERIVE_API_KEY where Claude Code starts.",
+        };
+    }
+    return undefined;
+}
 export const LOW_SAVING_PCT = 0.3;
 const usd = (v) => `$${v.toFixed(4)}`;
 const pct = (v) => `${(v * 100).toFixed(1)}%`;
@@ -239,12 +319,14 @@ export function localFindings(turn) {
     else if (turn.decision?.verdict === "no-steer") {
         const code = turn.decision.code ?? "";
         const known = DECLINES[code];
+        const reading = readingDecline(code, turn.decision.why ?? "");
         out.push({
             code: `declined_${code || "unknown"}`,
             severity: code === "not_ready" && !turn.matched.scenarioId ? "info" : "problem",
             title: `Matched ${turn.matched.runId} but declined to steer: ${turn.decision.why ?? code}.`,
-            cause: known?.cause ?? "the runner's log line carries the reason text.",
-            fix: (known && code === "missing_target" ? missingTargetFix(known.fix, turn) : known?.fix) ??
+            cause: reading?.cause ?? known?.cause ?? "the runner's log line carries the reason text.",
+            fix: reading?.fix ??
+                (known && code === "missing_target" ? missingTargetFix(known.fix, turn) : known?.fix) ??
                 (turn.matched.scenarioId
                     ? "read the `replay.decision` line above."
                     : "the matched recording has no scenario yet — calculate it, or let the service pick it up after enough hits."),
@@ -266,7 +348,10 @@ export function localFindings(turn) {
         const live = coverage
             .map((c, i) => (c === "live" ? (tools[i] ?? `step ${i}`) : undefined))
             .filter((t) => Boolean(t));
-        if (turn.plan.mode === "steer" && live.length > 0) {
+        // Not for a turn of another host: there every step is one only the host
+        // can run, and stepping through them is the full mode — its adapter
+        // answers in the model's place, so no model call is paid per step.
+        if (turn.plan.mode === "steer" && live.length > 0 && !otherHost(turn)) {
             const lowSaving = savedPct(turn) != null && savedPct(turn) < LOW_SAVING_PCT;
             const names = [...new Set(live)];
             // One of the runner's own built-ins steered only because it was off the
@@ -310,22 +395,36 @@ export function localFindings(turn) {
                 .map(([k, v]) => `${k}=${String(v)}`)
                 .join("  "),
             fix: i.event === "run.unmeasured"
-                ? "the turn's cost could not be read from the transcript, so its report is unmeasured; run bir-hooks where the Claude Code transcript is readable."
+                ? otherHost(turn)
+                    ? HOST_UNMEASURED
+                    : "the turn's cost could not be read from the transcript, or the runner has no price for the model: update it. Its report is unmeasured; run bir-hooks where the Claude Code transcript is readable."
                 : i.event === "replay.diverge" || i.event === "replay.handover"
                     ? "the model left the script or the runner handed the turn back; the service section shows what the fallback cost."
-                    : "see the guide's troubleshooting table for this line.",
+                    : i.event === "run.incomplete"
+                        ? "the recording is not the whole run, so it is never calculated and no longer catches its prompt; run the task again to record it whole."
+                        : i.event === "run.host_failed"
+                            ? "the application's run failed; its recording is closed with that error and never becomes a plan."
+                            : "see the guide's troubleshooting table for this line.",
         });
     }
     const r = turn.reported;
     if (r) {
         if (r.measured === false) {
-            out.push({
-                code: "unmeasured",
-                severity: "warn",
-                title: "The execution report is unmeasured: the session's tokens could not be read.",
-                cause: "Without the transcript delta the report carries the derivation cost alone, and `baseline − cost` overstates the saving.",
-                fix: "Run bir-hooks on the machine and user that own the Claude Code transcript; `run.unmeasured` names what was missing.",
-            });
+            out.push(otherHost(turn)
+                ? {
+                    code: "unmeasured",
+                    severity: "warn",
+                    title: "The execution report is unmeasured.",
+                    cause: HOST_UNMEASURED,
+                    fix: "Update the runner and the LangChain package; `run.unmeasured` names what was missing, and the model when it has no price.",
+                }
+                : {
+                    code: "unmeasured",
+                    severity: "warn",
+                    title: "The execution report is unmeasured: the session's tokens could not be read, or the runner has no price for the model.",
+                    cause: "Without the transcript delta the report carries the derivation cost alone, and `baseline − cost` overstates the saving.",
+                    fix: "Run bir-hooks on the machine and user that own the Claude Code transcript, or update the runner when it has no price for the model; `run.unmeasured` names what was missing.",
+                });
         }
         const p = savedPct(turn);
         const cost = r.derive + r.session + r.fallback;
@@ -340,12 +439,15 @@ export function localFindings(turn) {
             });
         }
         else if (p != null && p < LOW_SAVING_PCT && r.outcome === "steered_full") {
+            // In another host a steer plan is not the mode that pays for the whole
+            // turn: its adapter makes the plan's calls, and the model is called once.
+            const paysTheTurn = turn.plan?.mode === "steer" && !otherHost(turn);
             out.push({
                 code: "saving_low",
                 severity: "warn",
                 title: `Saved ${pct(p)}: ${usd(r.savedUsd ?? 0)} of a ${usd((r.savedUsd ?? 0) + cost)} baseline.`,
-                cause: `The live session cost ${usd(r.session)} of that baseline${turn.plan?.mode === "steer" ? " — steer mode pays for the whole turn." : "."}`,
-                fix: turn.plan?.mode === "steer"
+                cause: `The live session cost ${usd(r.session)} of that baseline${paysTheTurn ? " — steer mode pays for the whole turn." : "."}`,
+                fix: paysTheTurn
                     ? "Direct mode is the fix (see steer_mode for what kept this plan out of it)."
                     : "Compare the baseline with a few unsteered runs (BIR_REPLAY=0); a single cheap source run makes any replay look poor.",
                 evidence: { ...r, costUsd: cost, savedPct: p },

package/dist/bin/setup.d.ts

@@ -53,7 +53,19 @@ export interface SetupArgs {
      * replaced (see {@link runSetup}, step 4).
      */
     portExplicit?: boolean;
+    /**
+     * `--host langchain`: set the folder up for an application of another host
+     * than Claude Code. Nothing of Claude Code's is wired — no hooks, no wrapped
+     * server, nothing under `.claude/` or in `~/.claude.json` — see
+     * {@link setupForHost}.
+     */
+    host?: string;
 }
+/** The hosts `bir setup --host` knows, and what each one's adapter is called. */
+export declare const SETUP_HOSTS: Readonly<Record<string, {
+    title: string;
+    lines: readonly string[];
+}>>;
 /**
  * The project directory every later step keys by: the PHYSICAL path on POSIX.
  *

package/dist/bin/setup.js

@@ -32,6 +32,7 @@
  * `cd <project>` and `bir setup`. The second needs no token; the session is
  * cached.
  */
+import { randomBytes } from "node:crypto";
 import { existsSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, join, parse as parsePath, resolve as resolvePath } from "node:path";
@@ -39,13 +40,23 @@ import { pidAlive, readDiscovery } from "../control/discovery.js";
 import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, describeAuthService, deviceLogin, loadStoredConfig, normalizeAuthUrl, rememberAuthUrl, tokenLogin, } from "../auth/client.js";
 import { activeSessions, compareVersions, ensureDaemon, SETUP_TOKEN_ENV, stopDaemon, } from "../control/daemon.js";
 import { normalizePath } from "../control/paths.js";
-import { allowRules, BIR_TOOLS_RULE, claudeCodePaths } from "../config/adapters/claude-code.js";
-import { allocateReplacementPort, editingEnabled, isScenarioServer, isWrapped, LOOPBACK_NO_PROXY, probeFreePort, proxyConfigured, projectRecord, readSidecar, SCENARIO_SERVER_KEY, setProjectRecord, writeSidecar, allocateFreeProjectPort, } from "../config/generate.js";
+import { allowRules, BIR_TOOLS_RULE, claudeCodePaths, claudeCodeSetUp } from "../config/adapters/claude-code.js";
+import { allocateReplacementPort, editingEnabled, isScenarioServer, isWrapped, LOOPBACK_NO_PROXY, probeFreePort, proxyConfigured, projectRecord, readSidecar, SCENARIO_SERVER_KEY, setProjectRecord, settleReplaySwitch, writeSidecar, allocateFreeProjectPort, } from "../config/generate.js";
 import { resolveServers } from "../config/resolve.js";
 import { EDIT_TOOLS, READ_TOOLS } from "./scenario-edit.js";
 import { errText } from "../util/log.js";
 import { offSource } from "../util/off-switch.js";
 import { packageVersion } from "../util/version.js";
+/** The hosts `bir setup --host` knows, and what each one's adapter is called. */
+export const SETUP_HOSTS = {
+    langchain: {
+        title: "a LangChain agent",
+        lines: [
+            "from langchain_basic2202 import Basic2202Middleware",
+            "agent = create_agent(model, tools, middleware=[Basic2202Middleware()])",
+        ],
+    },
+};
 /**
  * The project directory every later step keys by: the PHYSICAL path on POSIX.
  *
@@ -101,6 +112,163 @@ export function consoleUrlFor(apiUrl) {
         return undefined;
     }
 }
+/**
+ * Start `project`'s recorder in the background, or keep the one that runs —
+ * replacing one that has no sign-in, sits on another port than the project's,
+ * or was started with another replay switch, whenever no session is mid-run.
+ * Throws when it does not come up.
+ */
+async function ensureRecorder(project, deps, env) {
+    const { out } = deps;
+    // probeIdle: a recorder too old to say whether its "open" turn is real
+    // (0.2.12 never closes an interrupted one) is replaced when two /health
+    // probes a few seconds apart show it idle (control/daemon.ts). Setup has
+    // the time; the SessionStart hook does not ask for it.
+    const ensureOpts = {
+        hooksScript: deps.hooksScript,
+        env,
+        restartOnSkew: true,
+        probeIdle: true,
+    };
+    let ensured = await ensureDaemon(project, ensureOpts);
+    if (!ensured.started &&
+        ensured.status.health.recording === false &&
+        activeSessions(ensured.status.health) === 0) {
+        // A recorder that came up before there was a sign-in (a `bir up` on a
+        // fresh machine, a session that expired) has nowhere to send steps.
+        // There is one now, and nothing is mid-run: replace it rather than
+        // tell the person to.
+        out("    the running recorder has no sign-in; replacing it");
+        await stopDaemon(project);
+        ensured = await ensureDaemon(project, { hooksScript: deps.hooksScript, env });
+        ensured = { ...ensured, restarted: true };
+    }
+    const port = projectRecord(readSidecar(), project)?.port;
+    if (port !== undefined &&
+        !ensured.status.info.url.endsWith(`:${port}`) &&
+        activeSessions(ensured.status.health) === 0) {
+        // A recorder still on the port this project had before (moved above,
+        // or by `--port`): the hooks now post to the new one, so it would
+        // receive nothing. Nothing is mid-run; replace it.
+        out(`    the running recorder is on ${ensured.status.info.url}, not port ${port}; replacing it`);
+        await stopDaemon(project);
+        ensured = await ensureDaemon(project, { hooksScript: deps.hooksScript, env });
+        ensured = { ...ensured, restarted: true };
+    }
+    // The replay switch is read once, when a recorder starts: one started
+    // before this setup turned replay off (--no-replay) or on would go on
+    // doing what it did. `source: "env"` is BIR_REPLAY where it started,
+    // which outranks the switch — a restart from here would not carry it.
+    const wantReplay = projectRecord(readSidecar(), project)?.replay?.enabled !== false;
+    const running = ensured.status.health.replay;
+    if (typeof running?.enabled === "boolean" && running.enabled !== wantReplay && running.source !== "env") {
+        if (activeSessions(ensured.status.health) === 0) {
+            out(`    the running recorder has replay ${running.enabled ? "on" : "off"}; replacing it`);
+            await stopDaemon(project);
+            ensured = await ensureDaemon(project, { hooksScript: deps.hooksScript, env });
+            ensured = { ...ensured, restarted: true };
+        }
+        else {
+            out(`    the running recorder keeps replay ${running.enabled ? "on" : "off"} for the session open now; ` +
+                "`bir up --restart` once it ends applies the change");
+        }
+    }
+    return ensured;
+}
+/**
+ * `bir setup --host langchain`: the folder, for an application of another
+ * host than Claude Code (the service's integratioLangChane.md, step LR7).
+ *
+ * Such a host needs none of what `bir setup` wires for Claude Code: its
+ * adapter runs inside the application, sees every tool call itself, and finds
+ * the recorder by the folder's control file. So nothing is written under
+ * `.claude/` or into `~/.claude.json`, and Claude Code is not asked for. What
+ * the folder does need is an entry of its own in the runner's settings:
+ *
+ *  - a fixed port and token. Without one the recorder takes the machine's
+ *    default port — which can be the fixed port of another project, whose
+ *    recorder then cannot start — and the machine's shared token, or a new
+ *    random one at every start;
+ *  - its replay switch: on, or off with `--no-replay`. `bir replay on|off`
+ *    work here as everywhere.
+ *
+ * Then the recorder is started — with the small environment, so the
+ * application's keys do not reach the process step code runs in
+ * (control/daemon.ts, `smallEnv`) — and the lines to add to the agent are
+ * printed.
+ *
+ * A folder that is already set up for Claude Code keeps that set-up as it
+ * is: its hooks, wrapped servers, port, token and replay switch. Only the
+ * entry notes that such an application runs here too.
+ */
+async function setupForHost(args, deps, ctx) {
+    const { out, err } = deps;
+    const { project, email, env } = ctx;
+    const host = SETUP_HOSTS[args.host];
+    const sidecar = readSidecar();
+    const before = projectRecord(sidecar, project);
+    const withClaudeCode = claudeCodeSetUp(project, sidecar);
+    const port = before?.port ?? (await allocateFreeProjectPort(sidecar, project));
+    setProjectRecord(sidecar, project, {
+        port,
+        token: before?.token ?? randomBytes(32).toString("hex"),
+        hosts: [...new Set([...(before?.hosts ?? []), args.host])],
+        // No line was added to the repository's exclude file for this folder, so
+        // an uninstall has none to take out.
+        ...(before ? {} : { excludeAdded: false }),
+    });
+    if (!withClaudeCode)
+        settleReplaySwitch(sidecar, project, args.replay ? "wanted" : "refused", false);
+    writeSidecar(sidecar);
+    if (withClaudeCode) {
+        out("    this folder is set up for Claude Code too: its hooks, wrapped servers, port and token stay as they are");
+    }
+    let ensured;
+    if (args.daemon) {
+        try {
+            ensured = await ensureRecorder(project, deps, env);
+        }
+        catch (e) {
+            err(`the recorder did not start: ${errText(e)}`);
+            err("The folder's entry is in place. Fix that, then run `bir up` here.");
+            return 1;
+        }
+    }
+    const health = ensured?.status.health;
+    const recording = health ? health.recording !== false : undefined;
+    const replay = health?.replay;
+    const policy = projectRecord(readSidecar(), project)?.replay;
+    const replayOn = replay?.source === "env" ? replay.enabled !== false : policy?.enabled !== false;
+    out();
+    out(`Signed in as ${email}`);
+    if (ensured) {
+        const { info } = ensured.status;
+        out(`Recorder ${ensured.started ? (ensured.restarted ? "restarted" : "started") : "already running"} for ${project}  ` +
+            `(${info.url}, ${info.daemon ? "background" : "in a terminal"})`);
+        if (info.logFile)
+            out(`  log     ${info.logFile}`);
+    }
+    else {
+        out(`Recorder not started for ${project} (--no-daemon); the application starts it, or run \`bir up\` here`);
+    }
+    out(replayOn
+        ? "  replay  on — `bir replay off` here makes the application only record"
+        : replay?.source === "env"
+            ? "  replay  off — BIR_REPLAY=0 where the recorder started"
+            : "  replay  off — the application only records; `bir replay on` here turns it on");
+    const off = offSource(project);
+    if (off) {
+        out(`  !! but the runner is OFF (${off === "env" ? "BIR_OFF=1 in this environment" : off === "global" ? "`bir off`, every project" : "`bir off --here`"}): nothing is recorded or replayed until \`bir on${off === "project" ? " --here" : ""}\``);
+    }
+    if (recording === false) {
+        out("  !! the recorder has no session to record with — run `bir login`; it starts recording by itself after that");
+    }
+    out(`Add this to your agent (${host.title}):`);
+    for (const line of host.lines)
+        out(`    ${line}`);
+    out("Any time:  bir doctor     bir investigate     bir off (out of the way, at once)     bir uninstall (undo)");
+    return recording === false ? 1 : 0;
+}
 export async function runSetup(args, deps) {
     const { out, err } = deps;
     const env = deps.env ?? process.env;
@@ -111,6 +279,11 @@ export async function runSetup(args, deps) {
     delete env[SETUP_TOKEN_ENV];
     if (env === process.env)
         delete process.env[SETUP_TOKEN_ENV];
+    if (args.host !== undefined && !SETUP_HOSTS[args.host]) {
+        err(`--host ${args.host || "(nothing)"}: not a host this runner knows. Known: ${Object.keys(SETUP_HOSTS).join(", ")}.`);
+        err("Leave --host out to set the folder up for Claude Code.");
+        return 1;
+    }
     // ── 1. the service ───────────────────────────────────────────────────────
     // `||`, not `??`: an environment that *sets* BIR_AUTH_URL to nothing (a
     // wrapper script, a CI job) means "not set", not "the empty address".
@@ -227,7 +400,10 @@ export async function runSetup(args, deps) {
     }
     // ── 4. the project ───────────────────────────────────────────────────────
     chdir(project);
-    if (!args.portExplicit) {
+    // `--host` in a folder that is set up for Claude Code too rewrites no hook,
+    // so it must not move the port those hooks name.
+    const keepsHooks = args.host !== undefined && claudeCodeSetUp(project, readSidecar());
+    if (!args.portExplicit && !keepsHooks) {
         // A port chosen at the first install is kept on later ones — the hooks name
         // it — but this machine may no longer let it be bound: Hyper-V, WSL and
         // Docker reserve blocks inside the dynamic range, and those move across
@@ -254,6 +430,11 @@ export async function runSetup(args, deps) {
             }
         }
     }
+    // Another host than Claude Code: nothing below is wired — no install, no
+    // hooks, no scenario server. The folder gets an entry and a recorder.
+    if (args.host !== undefined) {
+        return setupForHost({ ...args, host: args.host }, deps, { project, email: session.user.email, env });
+    }
     if (args.allowServers !== undefined) {
         // Stored before install so the recorder started below reads it at start.
         const sidecar = readSidecar();
@@ -271,59 +452,7 @@ export async function runSetup(args, deps) {
     if (args.daemon) {
         out("==> Starting the recorder in the background");
         try {
-            // probeIdle: a recorder too old to say whether its "open" turn is real
-            // (0.2.12 never closes an interrupted one) is replaced when two /health
-            // probes a few seconds apart show it idle (control/daemon.ts). Setup has
-            // the time; the SessionStart hook does not ask for it.
-            const ensureOpts = {
-                hooksScript: deps.hooksScript,
-                env,
-                restartOnSkew: true,
-                probeIdle: true,
-            };
-            ensured = await ensureDaemon(project, ensureOpts);
-            if (!ensured.started &&
-                ensured.status.health.recording === false &&
-                activeSessions(ensured.status.health) === 0) {
-                // A recorder that came up before there was a sign-in (a `bir up` on a
-                // fresh machine, a session that expired) has nowhere to send steps.
-                // There is one now, and nothing is mid-run: replace it rather than
-                // tell the person to.
-                out("    the running recorder has no sign-in; replacing it");
-                await stopDaemon(project);
-                ensured = await ensureDaemon(project, { hooksScript: deps.hooksScript, env });
-                ensured = { ...ensured, restarted: true };
-            }
-            const port = projectRecord(readSidecar(), project)?.port;
-            if (port !== undefined &&
-                !ensured.status.info.url.endsWith(`:${port}`) &&
-                activeSessions(ensured.status.health) === 0) {
-                // A recorder still on the port this project had before (moved above,
-                // or by `--port`): the hooks now post to the new one, so it would
-                // receive nothing. Nothing is mid-run; replace it.
-                out(`    the running recorder is on ${ensured.status.info.url}, not port ${port}; replacing it`);
-                await stopDaemon(project);
-                ensured = await ensureDaemon(project, { hooksScript: deps.hooksScript, env });
-                ensured = { ...ensured, restarted: true };
-            }
-            // The replay switch is read once, when a recorder starts: one started
-            // before this setup turned replay off (--no-replay) or on would go on
-            // doing what it did. `source: "env"` is BIR_REPLAY where it started,
-            // which outranks the switch — a restart from here would not carry it.
-            const wantReplay = projectRecord(readSidecar(), project)?.replay?.enabled !== false;
-            const running = ensured.status.health.replay;
-            if (typeof running?.enabled === "boolean" && running.enabled !== wantReplay && running.source !== "env") {
-                if (activeSessions(ensured.status.health) === 0) {
-                    out(`    the running recorder has replay ${running.enabled ? "on" : "off"}; replacing it`);
-                    await stopDaemon(project);
-                    ensured = await ensureDaemon(project, { hooksScript: deps.hooksScript, env });
-                    ensured = { ...ensured, restarted: true };
-                }
-                else {
-                    out(`    the running recorder keeps replay ${running.enabled ? "on" : "off"} for the session open now; ` +
-                        "`bir up --restart` once it ends applies the change");
-                }
-            }
+            ensured = await ensureRecorder(project, deps, env);
         }
         catch (e) {
             err(`the recorder did not start: ${errText(e)}`);

package/dist/bin/update.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `bir update` — put the newest version where THIS copy of the runner is.
+ *
+ * There are two ways the runner gets onto a machine, and each keeps it in a
+ * different place:
+ *
+ *   - the console's install line (scripts/install.sh, install.ps1) installs it
+ *     into `~/.baseinstrunner/npm`, with the npm that sits beside the Node its
+ *     launchers name. `npm i -g` never writes there: typed by hand it adds a
+ *     second copy in npm's own prefix and leaves the one the launchers start
+ *     as old as before, and which copy a shell then finds depends on its PATH;
+ *   - `npm install -g @basein/runner`, into npm's own prefix.
+ *
+ * So the command that updates the runner depends on where the runner is, and
+ * the copy that is running is the one that knows. A copy under
+ * `~/.baseinstrunner/npm` repeats what the install line did: the same Node,
+ * the npm beside it, `--prefix` that folder. Any other installed copy runs
+ * `npm install -g`, after asking npm where it keeps its global packages: when
+ * this copy is not there (pnpm, yarn, another Node's prefix), npm would write
+ * the second copy this command exists to prevent, so nothing is installed.
+ *
+ * It replaces the package and nothing else. `bir setup` in each project is
+ * what moves the wiring and replaces an older recorder, and it is the next
+ * thing the output names.
+ *
+ * NOT TESTED on Windows against a live session: npm replaces the folder this
+ * process and the recorder were loaded from. Neither keeps a file of it open,
+ * and the install line has always done the same replacement, but if npm ends
+ * with EPERM or EBUSY the answer is to close Claude Code and run it again.
+ */
+export interface UpdateDeps {
+    out: (line?: string) => void;
+    err: (line: string) => void;
+    /** This package's folder. Default: found from this module. */
+    packageRoot?: string;
+    /** The person's home folder. Default: `os.homedir()` (never `BIR_HOME`: the install scripts do not read it). */
+    home?: string;
+    /** Decides the layout of an npm prefix. Default: this platform's. */
+    platform?: NodeJS.Platform;
+    /** The Node that runs this `bir`. Default: `process.execPath`. */
+    execPath?: string;
+    /** The flags that Node was started with. Default: `process.execArgv`. */
+    execArgv?: string[];
+    /** The `npm-cli.js` a copy under `~/.baseinstrunner/npm` runs. Default: the one beside `execPath`. */
+    npmCli?: string;
+    /** Run a command with its output shown. Returns its exit code; null when it never started or was killed. */
+    run?: (command: string, args: string[]) => number | null;
+    /** Run a command and return what it printed. Undefined when it failed. */
+    capture?: (command: string, args: string[]) => string | undefined;
+}
+export type UpdatePlan = 
+/** A copy the install line made: npm beside its Node, into the private prefix. */
+{
+    kind: "private";
+    root: string;
+    command: string;
+    args: string[];
+}
+/** A copy `npm install -g` made. */
+ | {
+    kind: "npm";
+    root: string;
+    command: string;
+    args: string[];
+}
+/** Nothing this command can update; `why` says what to do instead. */
+ | {
+    kind: "refused";
+    why: string;
+};
+/** The folder of this package: the nearest `package.json` that names it. */
+export declare function packageRoot(from?: string): string | undefined;
+/** Where a global install into `prefix` keeps this package: npm adds `lib` everywhere but on Windows. */
+export declare function packageDirIn(prefix: string, platform?: NodeJS.Platform): string;
+/** The `npm-cli.js` that ships beside a Node binary, where the install scripts look for it. */
+export declare function npmCliBeside(execPath: string, platform?: NodeJS.Platform): string;
+/** Decide what `bir update` runs. Changes nothing. */
+export declare function planUpdate(deps?: Pick<UpdateDeps, "packageRoot" | "home" | "platform" | "execPath" | "execArgv" | "npmCli">): UpdatePlan;
+/** `bir update`. Returns the exit code: 1 when nothing was updated. */
+export declare function runUpdate(deps: UpdateDeps): number;
+//# sourceMappingURL=update.d.ts.map