@basein/runner 0.2.11 → 0.3.0

package/dist/bin/scenario-stderr.d.ts

@@ -0,0 +1,43 @@
+/**
+ * scenario-stderr — how the `bir` MCP server (bir-scenario) reads the stderr
+ * of a `bir` it spawned for a scenario tool.
+ *
+ * Two kinds of line arrive there, mixed: `bir`'s audit lines
+ * (`[bir] <iso time> <event> …`), which belong in the log where `bir doctor`
+ * and a person look, and the sentences `bir` wrote for a person
+ * ("[bir] not signed in — run `bir login`"), which the model needs when the
+ * command failed. They are sorted line by line AS THEY ARRIVE: audit lines go
+ * straight on, and of the rest only the LAST so many characters are kept.
+ *
+ * WHY AS THEY ARRIVE, AND WHY THE LAST. Sorting after the exit, with the first
+ * 8 000 characters kept, lost exactly the line that mattered: with
+ * `BIR_VERBOSE=1` the audit lines filled the cap, and `bir`'s closing reason —
+ * the last thing it prints — never reached the model, which got "exited with
+ * code 1" and nothing to act on.
+ *
+ * Its own module so it can be tested: bir-scenario starts serving on import.
+ */
+/** `bir`'s own audit lines — for the log, not for the model. */
+export declare const AUDIT_LINE: RegExp;
+export interface StderrSorterOptions {
+    /** How much of the non-audit text is kept: the last this many characters. */
+    keepChars: number;
+    /** How much audit text is passed on, at most; the rest is dropped. */
+    forwardChars: number;
+    /** Where an audit line goes (one line, without its newline). Must not throw. */
+    forward: (line: string) => void;
+}
+export declare class StderrSorter {
+    private readonly opts;
+    private partial;
+    /** Where the rest of a line cut for length goes, once its start was sorted. */
+    private continuing;
+    private kept;
+    private forwarded;
+    constructor(opts: StderrSorterOptions);
+    push(chunk: string): void;
+    /** Everything that was not an audit line (the last of it), once the stream ended. */
+    end(): string;
+    private line;
+}
+//# sourceMappingURL=scenario-stderr.d.ts.map

package/dist/bin/scenario-stderr.js

@@ -0,0 +1,76 @@
+/**
+ * scenario-stderr — how the `bir` MCP server (bir-scenario) reads the stderr
+ * of a `bir` it spawned for a scenario tool.
+ *
+ * Two kinds of line arrive there, mixed: `bir`'s audit lines
+ * (`[bir] <iso time> <event> …`), which belong in the log where `bir doctor`
+ * and a person look, and the sentences `bir` wrote for a person
+ * ("[bir] not signed in — run `bir login`"), which the model needs when the
+ * command failed. They are sorted line by line AS THEY ARRIVE: audit lines go
+ * straight on, and of the rest only the LAST so many characters are kept.
+ *
+ * WHY AS THEY ARRIVE, AND WHY THE LAST. Sorting after the exit, with the first
+ * 8 000 characters kept, lost exactly the line that mattered: with
+ * `BIR_VERBOSE=1` the audit lines filled the cap, and `bir`'s closing reason —
+ * the last thing it prints — never reached the model, which got "exited with
+ * code 1" and nothing to act on.
+ *
+ * Its own module so it can be tested: bir-scenario starts serving on import.
+ */
+/** `bir`'s own audit lines — for the log, not for the model. */
+export const AUDIT_LINE = /^\[bir\] \d{4}-\d\d-\d\dT/;
+export class StderrSorter {
+    opts;
+    partial = "";
+    /** Where the rest of a line cut for length goes, once its start was sorted. */
+    continuing;
+    kept = "";
+    forwarded = 0;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    push(chunk) {
+        const lines = `${this.partial}${chunk}`.split("\n");
+        this.partial = lines.pop() ?? "";
+        for (const line of lines) {
+            this.line(line);
+            this.continuing = undefined;
+        }
+        // A "line" with no end in sight is sorted in pieces rather than held whole.
+        if (this.partial.length > this.opts.keepChars) {
+            this.line(this.partial);
+            this.partial = "";
+        }
+    }
+    /** Everything that was not an audit line (the last of it), once the stream ended. */
+    end() {
+        if (this.partial !== "")
+            this.line(this.partial);
+        this.partial = "";
+        this.continuing = undefined;
+        return this.kept;
+    }
+    line(raw) {
+        const line = raw.replace(/\r$/, "");
+        const kind = this.continuing ?? (AUDIT_LINE.test(line) ? "audit" : "kept");
+        this.continuing = kind;
+        if (line.trim() === "")
+            return;
+        if (kind === "audit") {
+            if (this.forwarded >= this.opts.forwardChars)
+                return;
+            this.forwarded += line.length + 1;
+            try {
+                this.opts.forward(line);
+            }
+            catch {
+                // The log is gone; nothing to do about that here.
+            }
+            return;
+        }
+        this.kept += `${line}\n`;
+        if (this.kept.length > this.opts.keepChars)
+            this.kept = this.kept.slice(-this.opts.keepChars);
+    }
+}
+//# sourceMappingURL=scenario-stderr.js.map

package/dist/bin/service-read.d.ts

@@ -0,0 +1,88 @@
+/**
+ * service-read — what `bir scenario show|edits` and `bir investigate` share
+ * about asking the service and printing its answer, so a slow service, a
+ * signed-out machine or a large scenario never turns into a stall or a flood.
+ *
+ * WHY A BOUND OF THEIR OWN. The `service()` these commands are handed settles
+ * the service address with a `/health` probe, may refresh the session, and
+ * then makes its request; a service (or a corporate proxy in front of it) that
+ * accepts the connection and never answers held every one of those for as long
+ * as Node's fetch waits — measured at 120 s through the `bir` MCP server, which
+ * is 120 s of a turn stalled on a debugging tool. A read is safe to abandon:
+ * nothing was asked to change. So each one gets {@link readTimeoutMs} — a
+ * command that reads twice shares it between them ({@link ReadClock}) — and
+ * then an answer in words. Writes (`check`, `edit`, `undo`, `calc`) are not
+ * bounded here — abandoning one would leave "was it saved?" unanswerable — and
+ * the MCP server bounds the whole command instead.
+ *
+ * WHY COMPACT JSON UNDER THE MCP SERVER. The `bir` MCP server runs these
+ * commands with `BIR_MCP=1` and hands their `--json` output to the model.
+ * Indentation is for a person at a terminal; in a model's context it is a
+ * quarter of the tokens and none of the meaning.
+ */
+/** Default bound on one command's reads of the service. `BIR_READ_TIMEOUT_MS` overrides it. */
+export declare const DEFAULT_READ_TIMEOUT_MS = 15000;
+/**
+ * The most any timer here is set for from the environment. Node turns a delay
+ * past 2^31 - 1 ms into 1 ms, so a mistyped `BIR_READ_TIMEOUT_MS=3000000000`
+ * used to make every read give up at once; ten minutes is already far longer
+ * than anybody waits for a debugging tool.
+ */
+export declare const MAX_ENV_TIMEOUT_MS = 600000;
+/**
+ * A number of milliseconds from the environment: positive and at most
+ * {@link MAX_ENV_TIMEOUT_MS}, or `fallback`. Out of range is a mistake, and
+ * the default is the value known to work.
+ */
+export declare function envTimeoutMs(name: string, fallback: number): number;
+export declare function readTimeoutMs(): number;
+/** True when the `bir` MCP server ran this command for a model (it sets `BIR_MCP=1`). */
+export declare function underMcp(): boolean;
+/** `--json` output: indented for a person, compact for a model. */
+export declare function jsonText(value: unknown): string;
+/**
+ * `pending`, or `{ error }` when it takes longer than `ms`. The request itself
+ * is not cancelled — `bir` exits as soon as the command returns, which is what
+ * ends it — and a late rejection is observed here, so it can never surface as
+ * an unhandled one. `statedMs` is the bound the answer names, when `ms` is
+ * only what was left of it ({@link ReadClock}).
+ */
+export declare function readWithin<T>(pending: Promise<T | {
+    error: string;
+}>, ms?: number, statedMs?: number): Promise<T | {
+    error: string;
+}>;
+/**
+ * One command's reads of the service, sharing one bound. A command that reads
+ * twice — `scenario edits` on a `run_` id finds the scenario, then its
+ * history; `investigate` tries the matched run after a "no" — used to give
+ * each read the whole bound, so a service that answered the first slowly and
+ * held the second took twice as long as the `bir` MCP server allows a
+ * reading tool, and was killed there with none of the answer the command
+ * already had (the journal half of `investigate`, say). Sharing the bound
+ * keeps the whole command inside it, and the timeout still names the bound,
+ * not the scrap of it the last read had left.
+ */
+export declare class ReadClock {
+    readonly totalMs: number;
+    private readonly deadline;
+    constructor(totalMs?: number);
+    /** What is left of the bound, in ms (0 once it is spent). */
+    remaining(): number;
+    /** {@link readWithin}, with what is left of the command's bound. */
+    within<T>(pending: Promise<T | {
+        error: string;
+    }>): Promise<T | {
+        error: string;
+    }>;
+}
+/** Whether a `{ error }` means the service could not be reached at all, as opposed to answering. */
+export declare function unreachable(error: string): boolean;
+/**
+ * A failure to reach the service, in words a person (or a model) can act on.
+ * The transport's own words — "fetch failed", "This operation was aborted" —
+ * say nothing about what to do, so they are replaced; the sentences `bir`
+ * itself wrote ("not signed in — run `bir login`") are already the answer.
+ */
+export declare function serviceProblem(error: string): string;
+//# sourceMappingURL=service-read.d.ts.map

package/dist/bin/service-read.js

@@ -0,0 +1,128 @@
+/**
+ * service-read — what `bir scenario show|edits` and `bir investigate` share
+ * about asking the service and printing its answer, so a slow service, a
+ * signed-out machine or a large scenario never turns into a stall or a flood.
+ *
+ * WHY A BOUND OF THEIR OWN. The `service()` these commands are handed settles
+ * the service address with a `/health` probe, may refresh the session, and
+ * then makes its request; a service (or a corporate proxy in front of it) that
+ * accepts the connection and never answers held every one of those for as long
+ * as Node's fetch waits — measured at 120 s through the `bir` MCP server, which
+ * is 120 s of a turn stalled on a debugging tool. A read is safe to abandon:
+ * nothing was asked to change. So each one gets {@link readTimeoutMs} — a
+ * command that reads twice shares it between them ({@link ReadClock}) — and
+ * then an answer in words. Writes (`check`, `edit`, `undo`, `calc`) are not
+ * bounded here — abandoning one would leave "was it saved?" unanswerable — and
+ * the MCP server bounds the whole command instead.
+ *
+ * WHY COMPACT JSON UNDER THE MCP SERVER. The `bir` MCP server runs these
+ * commands with `BIR_MCP=1` and hands their `--json` output to the model.
+ * Indentation is for a person at a terminal; in a model's context it is a
+ * quarter of the tokens and none of the meaning.
+ */
+/** Default bound on one command's reads of the service. `BIR_READ_TIMEOUT_MS` overrides it. */
+export const DEFAULT_READ_TIMEOUT_MS = 15_000;
+/**
+ * The most any timer here is set for from the environment. Node turns a delay
+ * past 2^31 - 1 ms into 1 ms, so a mistyped `BIR_READ_TIMEOUT_MS=3000000000`
+ * used to make every read give up at once; ten minutes is already far longer
+ * than anybody waits for a debugging tool.
+ */
+export const MAX_ENV_TIMEOUT_MS = 600_000;
+/**
+ * A number of milliseconds from the environment: positive and at most
+ * {@link MAX_ENV_TIMEOUT_MS}, or `fallback`. Out of range is a mistake, and
+ * the default is the value known to work.
+ */
+export function envTimeoutMs(name, fallback) {
+    const n = Number(process.env[name]);
+    return Number.isFinite(n) && n > 0 && n <= MAX_ENV_TIMEOUT_MS ? n : fallback;
+}
+export function readTimeoutMs() {
+    return envTimeoutMs("BIR_READ_TIMEOUT_MS", DEFAULT_READ_TIMEOUT_MS);
+}
+/** True when the `bir` MCP server ran this command for a model (it sets `BIR_MCP=1`). */
+export function underMcp() {
+    return process.env.BIR_MCP === "1";
+}
+/** `--json` output: indented for a person, compact for a model. */
+export function jsonText(value) {
+    return underMcp() ? JSON.stringify(value) : JSON.stringify(value, null, 2);
+}
+/**
+ * `pending`, or `{ error }` when it takes longer than `ms`. The request itself
+ * is not cancelled — `bir` exits as soon as the command returns, which is what
+ * ends it — and a late rejection is observed here, so it can never surface as
+ * an unhandled one. `statedMs` is the bound the answer names, when `ms` is
+ * only what was left of it ({@link ReadClock}).
+ */
+export async function readWithin(pending, ms = readTimeoutMs(), statedMs = ms) {
+    pending.catch(() => undefined);
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ error: `the BaseIn service did not answer within ${seconds(statedMs)} s` }), Math.max(0, ms));
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([pending, late]);
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * One command's reads of the service, sharing one bound. A command that reads
+ * twice — `scenario edits` on a `run_` id finds the scenario, then its
+ * history; `investigate` tries the matched run after a "no" — used to give
+ * each read the whole bound, so a service that answered the first slowly and
+ * held the second took twice as long as the `bir` MCP server allows a
+ * reading tool, and was killed there with none of the answer the command
+ * already had (the journal half of `investigate`, say). Sharing the bound
+ * keeps the whole command inside it, and the timeout still names the bound,
+ * not the scrap of it the last read had left.
+ */
+export class ReadClock {
+    totalMs;
+    deadline;
+    constructor(totalMs = readTimeoutMs()) {
+        this.totalMs = totalMs;
+        this.deadline = Date.now() + totalMs;
+    }
+    /** What is left of the bound, in ms (0 once it is spent). */
+    remaining() {
+        return Math.max(0, this.deadline - Date.now());
+    }
+    /** {@link readWithin}, with what is left of the command's bound. */
+    within(pending) {
+        return readWithin(pending, this.remaining(), this.totalMs);
+    }
+}
+/** Whether a `{ error }` means the service could not be reached at all, as opposed to answering. */
+export function unreachable(error) {
+    return /did not answer within|fetch failed|ECONN|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|socket|network|aborted|timed out|UND_ERR/i.test(error);
+}
+/**
+ * A failure to reach the service, in words a person (or a model) can act on.
+ * The transport's own words — "fetch failed", "This operation was aborted" —
+ * say nothing about what to do, so they are replaced; the sentences `bir`
+ * itself wrote ("not signed in — run `bir login`") are already the answer.
+ */
+export function serviceProblem(error) {
+    if (/BIR_AUTH_URL is not set/.test(error)) {
+        return "no BaseIn service is configured on this machine — run `bir setup` or `bir login`";
+    }
+    if (/did not answer within/.test(error))
+        return error;
+    if (unreachable(error))
+        return "the BaseIn service could not be reached — check the network, or try again later";
+    return error;
+}
+function seconds(ms) {
+    const s = ms / 1000;
+    return Number.isInteger(s) ? String(s) : s.toFixed(1);
+}
+//# sourceMappingURL=service-read.js.map

package/dist/bin/setup.d.ts

@@ -43,7 +43,26 @@ export interface SetupArgs {
     daemon: boolean;
     /** `--allow-servers a,b`: the servers replay may call unattended, stored for this project. */
     allowServers?: string;
+    /**
+     * `--port` was given: the port is the person's, and is never moved. Without
+     * it a recorded port this machine no longer lets the recorder bind is
+     * replaced (see {@link runSetup}, step 4).
+     */
+    portExplicit?: boolean;
 }
+/**
+ * The project directory every later step keys by: the PHYSICAL path on POSIX.
+ *
+ * After `chdir`, `process.cwd()` — which install keys the sidecar by and the
+ * recorder keys its discovery file by — is the resolved path. Keying setup's own
+ * steps by the logical one (a symlinked ~/code, macOS's /tmp → /private/tmp)
+ * made it wait 15 s for a discovery file that was written under the other
+ * spelling, report "the recorder did not start" while it ran, and store
+ * `--allow-servers` where the recorder never looks. Windows keeps the path as
+ * given: its cwd is not resolved through junctions, and resolving would only
+ * change the drive letter's case.
+ */
+export declare function canonicalProject(dir: string, platform?: NodeJS.Platform): string;
 export interface SetupDeps {
     out: (line?: string) => void;
     err: (line: string) => void;

package/dist/bin/setup.js

@@ -28,16 +28,41 @@
  * `cd <project>` and `bir setup`. The second needs no token; the session is
  * cached.
  */
-import { existsSync, statSync } from "node:fs";
+import { existsSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, join, parse as parsePath, resolve as resolvePath } from "node:path";
+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, ensureDaemon, SETUP_TOKEN_ENV, stopDaemon, } from "../control/daemon.js";
+import { activeSessions, compareVersions, ensureDaemon, SETUP_TOKEN_ENV, stopDaemon, } from "../control/daemon.js";
 import { normalizePath } from "../control/paths.js";
-import { isWrapped, projectRecord, readSidecar, SCENARIO_SERVER_KEY, setProjectRecord, writeSidecar, allocateFreeProjectPort, } from "../config/generate.js";
+import { allocateReplacementPort, isScenarioServer, isWrapped, LOOPBACK_NO_PROXY, probeFreePort, proxyConfigured, projectRecord, readSidecar, SCENARIO_SERVER_KEY, setProjectRecord, writeSidecar, allocateFreeProjectPort, } from "../config/generate.js";
 import { resolveServers } from "../config/resolve.js";
 import { errText } from "../util/log.js";
+import { offSource } from "../util/off-switch.js";
 import { packageVersion } from "../util/version.js";
+/**
+ * The project directory every later step keys by: the PHYSICAL path on POSIX.
+ *
+ * After `chdir`, `process.cwd()` — which install keys the sidecar by and the
+ * recorder keys its discovery file by — is the resolved path. Keying setup's own
+ * steps by the logical one (a symlinked ~/code, macOS's /tmp → /private/tmp)
+ * made it wait 15 s for a discovery file that was written under the other
+ * spelling, report "the recorder did not start" while it ran, and store
+ * `--allow-servers` where the recorder never looks. Windows keeps the path as
+ * given: its cwd is not resolved through junctions, and resolving would only
+ * change the drive letter's case.
+ */
+export function canonicalProject(dir, platform = process.platform) {
+    const logical = resolvePath(dir);
+    if (platform === "win32")
+        return logical;
+    try {
+        return realpathSync(logical);
+    }
+    catch {
+        return logical;
+    }
+}
 /** True when `claude` (Claude Code) is on PATH or in its native install location. */
 export function claudeOnPath(env = process.env) {
     const names = process.platform === "win32" ? ["claude.exe", "claude.cmd", "claude"] : ["claude"];
@@ -93,7 +118,18 @@ export async function runSetup(args, deps) {
     const problem = await describeAuthService(baseUrl);
     if (problem) {
         err(`${baseUrl} is not a BaseIn service: ${problem}.`);
-        err(AUTH_URL_HINT);
+        if (/unreachable/.test(problem) && proxyConfigured(env) && !process.execArgv.includes("--use-env-proxy")) {
+            // Behind a proxy-only network the likeliest cause, and not the address:
+            // Node's fetch ignores HTTPS_PROXY unless it is started with this flag.
+            // NO_PROXY too: with the flag, the runner's own calls to 127.0.0.1 would
+            // go to the proxy as well, and install leaves the flag out without it.
+            err("HTTPS_PROXY/HTTP_PROXY is set, but this node does not use it without --use-env-proxy: set " +
+                `NO_PROXY=${LOOPBACK_NO_PROXY} (plus your own entries) and run ` +
+                "`node --use-env-proxy <path to bir.js> setup …` (the install line does this for you).");
+        }
+        else {
+            err(AUTH_URL_HINT);
+        }
         return 1;
     }
     const envUrl = (env.BIR_AUTH_URL ?? "").replace(/\/+$/, "");
@@ -107,7 +143,7 @@ export async function runSetup(args, deps) {
         err(`BIR_AUTH_URL in this environment is ${envUrl}, but ${args.authUrl ? "this sets up" : "the stored address is"} ${args.authUrl ? baseUrl : storedUrl}.`);
         err("Remove that variable (check your shell profile), or the recorder will not record.");
     }
-    const project = resolvePath(args.project ?? process.cwd());
+    const project = canonicalProject(args.project ?? process.cwd());
     if (!existsSync(project) || !statSync(project).isDirectory()) {
         err(`Project directory not found: ${project}`);
         return 1;
@@ -185,6 +221,33 @@ export async function runSetup(args, deps) {
     }
     // ── 4. the project ───────────────────────────────────────────────────────
     chdir(project);
+    if (!args.portExplicit) {
+        // 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
+        // reboots. A recorder told to use it exits, and every hook of every session
+        // then fails. Setup is the upgrade and repair path, so it moves the project
+        // to a free port and lets install rewrite the hooks and entries with it —
+        // unless the port is busy because THIS project's recorder is on it.
+        const sidecar = readSidecar();
+        const recorded = projectRecord(sidecar, project);
+        if (recorded) {
+            // Age does not matter here, only a live pid: a recorder whose file went
+            // stale over a long sleep (or an older runner's, whose heartbeat is
+            // slower) still holds the port, and moving away from it would leave
+            // two recorders and hooks pointing at the new one.
+            const ours = readDiscovery(project, { ignoreAge: true });
+            const heldByUs = Boolean(ours && pidAlive(ours.pid) && ours.url.endsWith(`:${recorded.port}`));
+            if (!heldByUs && !(await probeFreePort(recorded.port))) {
+                const next = await allocateReplacementPort(sidecar, project, recorded.port);
+                if (next !== undefined) {
+                    setProjectRecord(sidecar, project, { port: next });
+                    writeSidecar(sidecar);
+                    out(`    port ${recorded.port} is not available on this machine; this project moves to ${next}`);
+                }
+            }
+        }
+    }
     if (args.allowServers !== undefined) {
         // Stored before install so the recorder started below reads it at start.
         const sidecar = readSidecar();
@@ -202,11 +265,17 @@ export async function runSetup(args, deps) {
     if (args.daemon) {
         out("==> Starting the recorder in the background");
         try {
-            ensured = await ensureDaemon(project, {
+            // 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) {
@@ -219,6 +288,36 @@ export async function runSetup(args, deps) {
                 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");
+                }
+            }
         }
         catch (e) {
             err(`the recorder did not start: ${errText(e)}`);
@@ -227,40 +326,67 @@ export async function runSetup(args, deps) {
         }
     }
     // ── 6. the summary ───────────────────────────────────────────────────────
-    const wrapped = resolveServers(project)
-        .filter((s) => s.name !== SCENARIO_SERVER_KEY && isWrapped(s.config))
-        .map((s) => s.name);
+    const live = resolveServers(project).filter((s) => s.name !== SCENARIO_SERVER_KEY);
+    const wrapped = live.filter((s) => isWrapped(s.config)).map((s) => s.name);
+    // Servers install left as Claude Code runs them (not approved there yet, a
+    // remote it signs in itself, …) are still here: "no MCP servers" would lie.
+    const unwrapped = live.filter((s) => !isWrapped(s.config)).map((s) => s.name);
     const health = ensured?.status.health;
     const replay = health?.replay;
     const recording = health ? health.recording !== false : undefined;
     const policy = projectRecord(readSidecar(), project)?.replay;
     const allow = replay?.allowServers ?? policy?.allowServers ?? null;
+    // The stored switch, which every recorder here reads at start — unless the
+    // one that answered was started with BIR_REPLAY, which outranks it.
+    const replayOn = replay?.source === "env" ? replay.enabled !== false : policy?.enabled !== false;
     out();
-    out(`Done. Recording${args.replay ? " and replay are" : " is"} on for ${project}`);
+    out(`Done. Recording${args.replay && replayOn ? " and replay are" : " is"} on for ${project}`);
+    // The kill switch outranks all of it, and setup leaves it as the person set
+    // it: turning the runner back on is theirs to decide, not an upgrade's.
+    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" : ""}\``);
+    }
     out(`  account    ${session.user.email}  (${baseUrl})`);
-    out(`  wrapped    ${wrapped.length ? wrapped.join(", ") : "(no MCP servers here)"}`);
+    out(`  wrapped    ${wrapped.length ? wrapped.join(", ") : unwrapped.length ? `(none — ${unwrapped.join(", ")} left as they are, see above)` : "(no MCP servers here)"}`);
     if (!args.replay) {
-        out("  replay     not installed (--no-replay)");
+        const scenarioLeft = resolveServers(project).some((s) => s.name === SCENARIO_SERVER_KEY && isScenarioServer(s.config));
+        out(replayOn
+            ? "  replay     ON despite --no-replay: BIR_REPLAY is set where the recorder started"
+            : `  replay     off (--no-replay) — \`bir replay on\` turns it on${scenarioLeft ? "; the scenario server an earlier setup added stays (`bir uninstall --replay` removes it)" : ""}`);
+    }
+    else if (!replayOn) {
+        out(replay?.source === "env"
+            ? "  replay     off — BIR_REPLAY=0 where the recorder started"
+            : "  replay     off here (`bir replay off`) — `bir replay on` turns it on");
     }
     else if (wrapped.length === 0) {
-        out("  replay     steer mode only — no MCP servers wrapped here; add a .mcp.json and run `bir setup` again for direct replay");
+        out(unwrapped.length
+            ? "  replay     steer mode only — none of this project's MCP servers is wrapped (why is above); `bir setup` again once one can be, for direct replay"
+            : "  replay     steer mode only — no MCP servers wrapped here; add a .mcp.json and run `bir setup` again for direct replay");
     }
     else {
-        const on = replay ? replay.enabled !== false : policy?.enabled !== false;
-        out(`  replay     ${on ? "on" : "off"} — direct execution allowed for: ${allow?.length ? allow.join(", ") : `all wrapped (narrow it with \`bir replay allow ${wrapped[0]}\`)`}`);
+        out(`  replay     on — direct execution allowed for: ${allow?.length ? allow.join(", ") : `all wrapped (narrow it with \`bir replay allow ${wrapped[0]}\`)`}`);
     }
     if (ensured) {
         const { info, health: h } = ensured.status;
         const theirs = String(h.hooksVersion ?? info.version ?? "");
         out(`  recorder   ${ensured.started ? (ensured.restarted ? "restarted" : "started") : "already running"} in the background (pid ${info.pid})` +
             " — it starts itself with every Claude Code session");
-        if (theirs && theirs !== packageVersion()) {
-            out(`             recorder ${theirs} is still serving an open Claude Code session; it restarts to ${packageVersion()} with the next session`);
+        // Only for an OLDER recorder: a newer one is kept on purpose
+        // (daemon.newer_kept) and nothing about it waits on a restart.
+        if (theirs && compareVersions(theirs, packageVersion()) === -1) {
+            // Said as it is: nothing replaces it by itself while that session runs —
+            // the next session's start keeps it too, as long as it reports a turn
+            // open — and until it is replaced it behaves as ${theirs} does (0.2.12:
+            // approves every wrapped MCP call, ignores `bir off`).
+            out(`             it is still ${theirs}, serving a Claude Code session that is mid-turn; it keeps running as ${theirs} ` +
+                `until \`bir up --restart\` (run it once that session ends) replaces it with ${packageVersion()}`);
         }
         if (info.logFile)
             out(`  log        ${info.logFile}`);
         if (recording === false) {
-            out("  !! the recorder has no session to record with — run `bir login`, then `bir up --restart`");
+            out("  !! the recorder has no session to record with — run `bir login`; it starts recording by itself after that");
         }
     }
     else {
@@ -280,7 +406,7 @@ export async function runSetup(args, deps) {
     out('  first time in this folder: say Yes to "trust this folder"');
     out("  just installed Claude Code? it asks you to sign in to Claude (it needs a Claude subscription)");
     out(`  give it a task that takes 4+ tool calls — it appears ${console_ ? `at ${console_}/recordings` : "in the console's Recordings"} within a minute of finishing`);
-    out("Any time:  bir doctor     bir investigate     bir down (stop)     bir uninstall (undo)");
+    out("Any time:  bir doctor     bir investigate     bir off (out of the way, at once)     bir uninstall (undo)");
     return recording === false ? 1 : 0;
 }
 //# sourceMappingURL=setup.js.map