@basein/runner 0.2.12 → 0.3.0

package/dist/bin/bir-scenario.js

@@ -18,31 +18,71 @@
  * control server exactly as a proxy does — `~/.baseinstrunner/control/<key>.json`,
  * mode 0600, bearer token — and forwards one call.
  *
+ * WHOSE CALL. A stdio MCP server is never told its session, and the control
+ * server runs a plan only for the session whose `PreToolUse` for
+ * `mcp__bir__run_scenario` it saw. Claude Code names the tool use in every
+ * MCP call's `params._meta["claudecode/toolUseId"]` — the same id that hook
+ * carried as `tool_use_id` — so the request forwards it as `toolUseId` and the
+ * control server matches it exactly instead of inferring the session. A host
+ * that names nothing sends an empty body, as before.
+ *
+ * IT RUNS IN EVERY SESSION, SO IT MUST NEVER BE WHY ONE GOES WRONG. Startup and
+ * `tools/list` are answered from local files alone (the hello to the recorder
+ * that follows them is sent after the answer, and never awaited). `run_scenario` never answers
+ * with an error or with the runner's internals ("fetch failed", "not_ready",
+ * "HTTP 404"): a turn with nothing to run is told so in one neutral sentence,
+ * and a replay that cannot be delivered becomes "do the task normally" — the
+ * real reason goes to the audit log, where `bir doctor` and a person look. A
+ * model called it on its own in the first session of every freshly installed
+ * project; a red error under a tool the user never asked about, five seconds
+ * late, was the result. `BIR_SCENARIO_DEBUG=1` brings the raw reasons back.
+ *
  * THE SCENARIO TOOLS RUN `bir` ITSELF. `scenario_show`, `scenario_check` and
  * the rest are the `bir scenario …` commands, spawned from this same package
  * with `--json` (D1: one path, whether a person types it or the model calls
  * it). That keeps this server credential-free — `bir` signs in the way it
- * always does — and means the model sees exactly the answer a person would.
- * Logic bodies travel through temporary files, never argv, and a non-zero exit
- * is an `isError` result that carries the output, refusal and report included.
+ * always does — and means the model sees exactly the answer a person would,
+ * compact (`BIR_MCP=1`) and capped in size. Logic bodies travel through
+ * temporary files, never argv, and a non-zero exit is an `isError` result that
+ * carries the output, refusal and report included.
  *
- * A CALL IN FLIGHT IS OWNED UNTIL IT ENDS. Each scenario call's `bir` child and
- * its temporary directory are tracked. When the host goes away (stdin closes,
- * SIGINT, SIGTERM) the children are stopped and the directories removed before
- * the process exits — `process.exit` never resumes a pending `finally`, so
- * cleanup left to one was cleanup that did not happen, and an orphaned `bir`
- * went on to save an edit for a session that had ended (C13). A
- * `notifications/cancelled` (the person pressed Esc) stops that call's child
- * the same way, and the call gets no answer, as MCP asks. A request the
- * service already received may still complete there; nothing here can call
- * it back, and `bir scenario edits` shows it.
+ * A CALL IN FLIGHT IS OWNED UNTIL IT ENDS. Each call's `bir` child, temporary
+ * directory or control-server request is tracked. When the host goes away
+ * (stdin closes, SIGINT, SIGTERM) the children are stopped and the directories
+ * removed before the process exits — `process.exit` never resumes a pending
+ * `finally`, so cleanup left to one was cleanup that did not happen, and an
+ * orphaned `bir` went on to save an edit for a session that had ended (C13). A
+ * `notifications/cancelled` (the person pressed Esc) stops that call the same
+ * way — a `run_scenario` request is aborted, and the control server stops
+ * starting steps when its request closes — and the call gets no answer, as MCP
+ * asks. A request the service already received may still complete there;
+ * nothing here can call it back, and `bir scenario edits` shows it.
  *
- * The tools that CHANGE a scenario are offered only where a person ran
- * `bir scenario editing on` (D2): this server runs in every session of every
- * installed project, a fleet included, and a plan must not change because some
- * agent there decided it should. The switch is read when the host lists the
- * tools, and again on every call, so a call to a tool that was never offered —
- * or was offered before the switch went off — is refused rather than run.
+ * WHICH TOOLS ARE OFFERED. `run_scenario`, always — unless the runner is
+ * switched off (`bir off`), when nothing is: an inert runner adds nothing to
+ * the model's context, and a call from a list taken before the switch starts
+ * nothing and asks nobody. The reading tools come with `bir scenario editing on`
+ * (or `BIR_SCENARIO_TOOLS=read` in this server's environment): their
+ * definitions ride along with every request of every session, and only
+ * somebody working on a scenario ever calls them. The tools that CHANGE a
+ * scenario are offered only where a person ran `bir scenario editing on` (D2):
+ * this server runs in every session of every installed project, a fleet
+ * included, and a plan must not change because some agent there decided it
+ * should. The switch is read when the host lists the tools, and again on every
+ * call, so a call to a tool that was never offered — or was offered before the
+ * switch went off — is refused rather than run. Turning the runner off or on
+ * mid-session tells the host its list changed (`notifications/tools/list_changed`).
+ *
+ * IT SAYS IT IS HERE, AND IT BRINGS THE RECORDER BACK (scenario-liveness.ts).
+ * A configured `bir` server is not a connected one, so the recorder announces
+ * a direct plan — "call run_scenario first" — only on this server's word: a
+ * `POST /scenario/hello` (pid, version, how many tools, off or not) on
+ * `initialize`, on `tools/list`, when the off switch flips, to each new
+ * recorder, and every 5 min. And this is the one long-lived process in every
+ * session of an installed project, so when the recorder's pid is dead and its
+ * address refuses, it starts `bir-hooks revive` — detached, rate-limited —
+ * rather than leave every later hook to fail until the next session start.
+ * Neither is ever awaited on the MCP path.
  *
  * STDOUT IS SACRED, as in every MCP server here: it is the host's JSON-RPC
  * stream, and every log line goes to stderr instead.
@@ -50,32 +90,113 @@
 import { readFrames, writeFrame } from "../jsonrpc/framing.js";
 import { JsonRpcErrorCode, errorResponse, isNotification, isRequest, paramsObject, } from "../jsonrpc/types.js";
 import { spawn } from "node:child_process";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveControl } from "../control/discovery.js";
-import { editingEnabled, nodeFlagsToCarry, readSidecar } from "../config/generate.js";
+import { editingEnabled, exemptLoopbackFromProxy, nodeFlagsToCarry, readSidecar } from "../config/generate.js";
+import { credentialsPath, resolveAuthUrl } from "../auth/client.js";
+import { isRunnerOff } from "../util/off-switch.js";
 import { logLine, logDetail, errText } from "../util/log.js";
+import { packageVersion } from "../util/version.js";
+import { envTimeoutMs, readTimeoutMs } from "./service-read.js";
+import { StderrSorter } from "./scenario-stderr.js";
+import { ScenarioLiveness } from "./scenario-liveness.js";
 /** Must match `DIRECT_TOOL_NAME`'s suffix in the replay controller. */
 const TOOL_NAME = "run_scenario";
-/** How long to look for a control server before answering that there is none. */
-const DISCOVERY_MS = 5_000;
-/** The plan can be long; the whole-plan budget lives on the control server. */
-const RUN_TIMEOUT_MS = 180_000;
+/**
+ * How long to look for the control server before answering that there is
+ * nothing to run. A plan is armed only by a live control server, and that
+ * server wrote its discovery file before it could arm anything — so a missing
+ * file is a certain "no plan", and waiting for one (this used to be 5 s) only
+ * delayed that answer. The grace covers a file being replaced at that instant.
+ */
+const DISCOVERY_GRACE_MS = 250;
+/**
+ * The whole `run_scenario` request. The run's own budgets live on the control
+ * server (derivation, then the plan, each step clipped to it — about 200 s at
+ * the very worst), and this sits well above them, so a replay that finished is
+ * never thrown away as a client timeout. It also sits BELOW the host's own
+ * limit: Claude Code gives up on an MCP call that has been quiet for 5 min
+ * (`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`), and this server sends no progress, so
+ * at exactly 5 min its red timeout raced our neutral answer. Ours goes first.
+ * `BIR_SCENARIO_RUN_TIMEOUT_MS` overrides it (up to 10 min; past that, or
+ * nonsense, is the default — a delay past 2^31 ms is 1 ms to Node, which
+ * silently turned every replay off).
+ */
+const RUN_TIMEOUT_MS = envTimeoutMs("BIR_SCENARIO_RUN_TIMEOUT_MS", 290_000);
+/**
+ * `BIR_SCENARIO_DEBUG=1`: `run_scenario` answers with the raw reason, as an
+ * error, as it used to — the old sentences included, so "no recorder here" and
+ * "the recorder has no plan" can be told apart.
+ */
+const DEBUG = process.env.BIR_SCENARIO_DEBUG === "1";
+/** What the model reads when no plan is armed — the common case, and never an error. */
+const NO_PLAN_TEXT = "Nothing to run for this request; continue normally.";
+/** What the model reads when an armed plan could not be delivered, whatever the reason. */
+const UNAVAILABLE_TEXT = "The prepared results are not available for this request. Do the task normally with your tools.";
+/**
+ * What the model reads when a second `run_scenario` arrives while the plan is
+ * still running for the first (the control server refuses a second execution:
+ * it would repeat every step). The results come back on the first call, so
+ * this one must never read "do the task normally" — that is the model
+ * repeating, by hand, the very steps the run is making.
+ */
+const ALREADY_RUNNING_TEXT = "The prepared results for this request are already being produced for an earlier run_scenario call, and they come back there. Do not call run_scenario again, and do not repeat its steps.";
+/** Appended to a delivered replay that stopped before its last step: out of time, or its caller left. */
+const PARTIAL_TEXT = "(partial: the scenario stopped before all of its steps ran)";
+/** Every model-directed note the replay controller writes opens with this. */
+const NOTE_PREFIX = "[BaseInstRunner calculated replay]";
+/**
+ * The key Claude Code names the tool use under in a `tools/call`'s `_meta`:
+ * `{ ...mcpRequestMeta, "claudecode/toolUseId": <id> }` (seen in Claude Code
+ * 2.1.280) — the id its `PreToolUse` hook carried as `tool_use_id`.
+ */
+const TOOL_USE_ID_META = "claudecode/toolUseId";
+/** Ids longer than this are not a host's tool-use id, and are not forwarded. */
+const MAX_TOOL_USE_ID_CHARS = 256;
+/** The host's tool-use id for this `tools/call`, when it named one. Never throws. */
+function toolUseIdOf(params) {
+    const value = paramsObject(params._meta)[TOOL_USE_ID_META];
+    return typeof value === "string" && value.trim() !== "" && value.length <= MAX_TOOL_USE_ID_CHARS ? value : undefined;
+}
 const TOOL = {
     name: TOOL_NAME,
-    description: "Run the pre-calculated tool sequence BaseInstRunner has armed for the current request, " +
-        "and return its results. Call once, with no arguments, when instructed to.",
+    // Narrow on purpose. "Call once, when instructed to" read to models as an
+    // invitation: they called it on their own, to see what it did.
+    //
+    // "A note", not "a message": the directive never arrives as a message of its
+    // own. At prompt time it is hook context the host wraps in its own words; for
+    // a sub-task plan it is the reason a tool call was refused, or that call's
+    // result. A model reading "a message starting with" literally found none and
+    // did the work by hand.
+    description: "Returns the results BaseInstRunner prepared for the current request. Call it only when a BaseInstRunner " +
+        `note in this turn (text beginning "${NOTE_PREFIX}", in a system note or a tool result) tells you to; ` +
+        "never otherwise.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
 };
-/** Ask the control server to run the armed plan. Never throws. */
-async function runArmedPlan(cwd) {
-    const found = await resolveControl(cwd, DISCOVERY_MS);
-    if (!found?.url)
-        return { ok: false, why: "no control server for this directory" };
+/**
+ * Ask the control server to run the armed plan. Never throws. The reasons it
+ * returns are for the audit log; {@link toolResult} decides what the model reads.
+ * `toolUseId` is the host's id for this call, which the control server matches
+ * to the `PreToolUse` it saw (see WHOSE CALL above).
+ */
+async function runArmedPlan(cwd, flight, toolUseId) {
+    const found = await resolveControl(cwd, DISCOVERY_GRACE_MS, 50);
+    // No file, or `BIR_CONTROL_URL` with no token to go with it: no control
+    // server that could have armed anything is running for this directory.
+    if (!found?.url || !found.token)
+        return { ok: false, why: "no_plan", kind: "no_control" };
+    if (flight.cancelled)
+        return { ok: false, why: "cancelled" };
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), RUN_TIMEOUT_MS);
+    flight.abort = controller;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, RUN_TIMEOUT_MS);
     timer.unref?.();
     try {
         const res = await fetch(`${found.url.replace(/\/+$/, "")}/scenario/run`, {
@@ -84,63 +205,179 @@ async function runArmedPlan(cwd) {
                 "content-type": "application/json",
                 authorization: `Bearer ${found.token}`,
             },
-            body: "{}",
+            body: JSON.stringify(toolUseId ? { toolUseId } : {}),
             signal: controller.signal,
         });
+        const raw = await res.text();
         if (!res.ok)
             return { ok: false, why: `control server answered HTTP ${res.status}` };
-        return (await res.json());
+        let body;
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            return { ok: false, why: "control server answered something that is not JSON" };
+        }
+        // Something else on a reused port can answer `null`, a number or a list;
+        // reading `.ok` off that used to throw where nothing answered the call.
+        if (!body || typeof body !== "object" || Array.isArray(body)) {
+            return { ok: false, why: "control server answered no result object" };
+        }
+        return body;
     }
     catch (err) {
-        return { ok: false, why: errText(err) };
+        if (flight.cancelled)
+            return { ok: false, why: "cancelled" };
+        if (timedOut)
+            return { ok: false, why: `no answer within ${RUN_TIMEOUT_MS / 1000} s` };
+        // `unreachable`: the recorder may be gone, so the caller has it looked at.
+        return { ok: false, why: errText(err), kind: "unreachable" };
     }
     finally {
         clearTimeout(timer);
+        flight.abort = undefined;
     }
 }
+/** A model-directed hand-over note: the plan stopped, and the note says what is left. */
+function isHandover(result, why) {
+    return why !== "" && (result.note === true || result.kind === "handover" || why.startsWith(NOTE_PREFIX));
+}
 /**
- * A `CallToolResult`. A turn with no armed plan is a **tool failure**, not a
- * protocol error: the model called a tool that had nothing to do — usually
- * because it remembered the tool from an earlier turn — and reacting to that is
- * something models do well and routinely.
+ * The control server's "this scenario is already running for this turn"
+ * (server.ts, `ALREADY_RUNNING`): matched on its words, which are all it
+ * sends. Checked after {@link isHandover}, so a note that happens to use the
+ * phrase still reaches the model whole.
+ */
+function isAlreadyRunning(why) {
+    return /\balready running\b/i.test(why);
+}
+const said = (text) => ({ content: [{ type: "text", text }], isError: false });
+/**
+ * The results a run delivered, or "" when it delivered none. A hand-over whose
+ * note was empty leaves the bundle behind a blank line or two; they go.
+ */
+function delivered(result) {
+    return result.ok === true && typeof result.text === "string" ? result.text.replace(/^\s+/, "") : "";
+}
+/**
+ * The raw reason `BIR_SCENARIO_DEBUG=1` answers with. The three ways of having
+ * nothing to run share the code `no_plan` for the model's sake; whoever turned
+ * debugging on is asking which one it was.
+ */
+function debugReason(result, why) {
+    if (result.kind === "no_control")
+        return "no control server for this directory";
+    if (result.kind === "off")
+        return "BaseInstRunner is switched off here (`bir on` turns it back on)";
+    if (why === "no_plan")
+        return "no scenario is armed for this turn — answer the user's request normally";
+    return why || "the scenario could not be run";
+}
+/**
+ * A `CallToolResult`, and never an error. Nothing to run is the common case —
+ * a model that remembered the tool, or tried it unasked — and a replay that
+ * could not be delivered leaves the task exactly where it was: the model does
+ * it itself. Neither is something the user should see a red error for, and
+ * neither is helped by the runner's own words for what went wrong. The one
+ * reason that passes through is the controller's hand-over note, which is
+ * written for the model and says what is left to do. A second call while the
+ * plan still runs is told, in words of its own, that the results come back on
+ * the first — not to do the task, which would repeat the steps being run.
  */
 function toolResult(result) {
-    if (!result.ok || !result.text) {
-        const why = result.why === "no_plan"
-            ? "no scenario is armed for this turn — answer the user's request normally"
-            : (result.why ?? "the scenario could not be run");
-        return { content: [{ type: "text", text: why }], isError: true };
+    const bundle = delivered(result);
+    if (bundle !== "") {
+        const notes = [];
+        // A budget stop and a run whose caller left are both `partial`; the
+        // hand-over note in front of the bundle already says which steps ran.
+        if (result.partial === true)
+            notes.push(PARTIAL_TEXT);
+        const structured = result.responseModel && typeof result.responseModel === "object" && Object.keys(result.responseModel).length > 0
+            ? `\n\nResponse model (derived by the scenario's own logic):\n${JSON.stringify(result.responseModel)}`
+            : "";
+        // NO `structuredContent`, AND THAT IS THE WHOLE POINT.
+        //
+        // A client that receives both MAY render `structuredContent` and drop
+        // `content` — Claude Code does. The replay then reaches the model as the bare
+        // response model: a few hundred bytes of derived keys, with no bundle header,
+        // no per-step calls and no tool results. Observed in a real session as a
+        // 744-character `{"services":[…],"worstService":…}` where a 30 KB, 8-step
+        // bundle should have been.
+        //
+        // The model behaved correctly given what it saw — it could not answer from
+        // that, so it re-ran all eight tools itself. The replay had executed
+        // perfectly, cost nothing, and bought nothing, because its results never
+        // arrived. The bundle is the payload; the response model rides inside it as
+        // text rather than competing with it for the client's attention.
+        return said(`${bundle}${structured}${notes.length ? `\n\n${notes.join(" ")}` : ""}`);
     }
-    const notes = [];
-    if (result.partial)
-        notes.push("(partial: the plan's time budget was reached)");
-    const structured = result.responseModel && Object.keys(result.responseModel).length > 0
-        ? `\n\nResponse model (derived by the scenario's own logic):\n${JSON.stringify(result.responseModel)}`
-        : "";
-    // NO `structuredContent`, AND THAT IS THE WHOLE POINT.
-    //
-    // A client that receives both MAY render `structuredContent` and drop
-    // `content` — Claude Code does. The replay then reaches the model as the bare
-    // response model: a few hundred bytes of derived keys, with no bundle header,
-    // no per-step calls and no tool results. Observed in a real session as a
-    // 744-character `{"services":[…],"worstService":…}` where a 30 KB, 8-step
-    // bundle should have been.
-    //
-    // The model behaved correctly given what it saw — it could not answer from
-    // that, so it re-ran all eight tools itself. The replay had executed
-    // perfectly, cost nothing, and bought nothing, because its results never
-    // arrived. The bundle is the payload; the response model rides inside it as
-    // text rather than competing with it for the client's attention.
-    return {
-        content: [
-            { type: "text", text: `${result.text}${structured}${notes.length ? `\n\n${notes.join(" ")}` : ""}` },
-        ],
-        isError: false,
-    };
+    const why = typeof result.why === "string" ? result.why : "";
+    if (DEBUG)
+        return { content: [{ type: "text", text: debugReason(result, why) }], isError: true };
+    if (why === "no_plan")
+        return said(NO_PLAN_TEXT);
+    // Written by the controller and capped there (4 000 characters); capped
+    // again here, because a port can be answered by something else.
+    if (isHandover(result, why))
+        return said(why.length > 8_000 ? `${why.slice(0, 8_000)}…` : why);
+    if (isAlreadyRunning(why))
+        return said(ALREADY_RUNNING_TEXT);
+    return said(UNAVAILABLE_TEXT);
 }
 // ── the scenario tools: `bir scenario …`, spawned ─────────────────────────────
-/** How long one `bir` command may take. A check replays the chain on the service. */
+/** How long a `bir` that may change a scenario may take. A check replays the chain on the service. */
 const BIR_TIMEOUT_MS = 120_000;
+/**
+ * How long a reading tool's `bir` may take: the command's bounded reads of the
+ * service (`BIR_READ_TIMEOUT_MS`, 15 s by default — one bound for the whole
+ * command, even where it reads twice: `ReadClock` in service-read.ts) plus
+ * Node's start and some margin. A read used to share the 120 s above, which a
+ * service that accepted the connection and never answered used in full.
+ */
+function readToolTimeoutMs() {
+    return readTimeoutMs() + 10_000;
+}
+/**
+ * The most of a `bir` answer that reaches the model, by default. A whole
+ * scenario with its recorded inputs and outputs runs to hundreds of kilobytes;
+ * past the cap it is dropped as it arrives (so it is not held here either) and
+ * the answer says how to ask for less.
+ *
+ * The HOST has a limit too, and ours must land first: Claude Code refuses or
+ * cuts an MCP answer past 25 000 tokens (`MAX_MCP_OUTPUT_TOKENS`) with an error
+ * of its own, and warns the person past 10 000. Compact scenario JSON — ids,
+ * escaped recorded outputs — runs at 2.5–3 characters a token, so 80 000
+ * characters (the first cap) was 27–32 thousand tokens: the host's error, not
+ * our hint. 24 000 characters stays under the warning.
+ */
+const DEFAULT_MAX_OUTPUT_CHARS = 24_000;
+/** Whatever the settings say, no more than this is held in memory for one answer. */
+const HARD_MAX_OUTPUT_CHARS = 400_000;
+/**
+ * The cap for this server: `BIR_SCENARIO_MAX_OUTPUT_CHARS` when set; else, when
+ * the person raised (or lowered) the host's own limit with
+ * `MAX_MCP_OUTPUT_TOKENS`, 1.5 characters a token of it — under the limit even
+ * for the densest JSON; else {@link DEFAULT_MAX_OUTPUT_CHARS}.
+ */
+function maxOutputChars() {
+    const explicit = Number(process.env.BIR_SCENARIO_MAX_OUTPUT_CHARS);
+    if (Number.isFinite(explicit) && explicit >= 1_000)
+        return Math.min(Math.floor(explicit), HARD_MAX_OUTPUT_CHARS);
+    const tokens = Number(process.env.MAX_MCP_OUTPUT_TOKENS);
+    if (Number.isFinite(tokens) && tokens > 0) {
+        return Math.max(2_000, Math.min(Math.floor(tokens * 1.5), HARD_MAX_OUTPUT_CHARS));
+    }
+    return DEFAULT_MAX_OUTPUT_CHARS;
+}
+const MAX_OUTPUT_CHARS = maxOutputChars();
+/**
+ * Of `bir`'s stderr that is not an audit line — the sentences it wrote for a
+ * person — the LAST this many characters are kept: `bir`'s reason for failing
+ * ("not signed in — run `bir login`") is the last thing it prints.
+ */
+const MAX_STDERR_CHARS = 8_000;
+/** Of `bir`'s audit lines, passed on to this server's log as they arrive. */
+const MAX_AUDIT_FORWARD_CHARS = 64_000;
 class BadArguments extends Error {
 }
 const TARGET = {
@@ -209,9 +446,10 @@ const SCENARIO_TOOLS = [
     {
         name: "scenario_show",
         changes: false,
-        description: "Read a calculated scenario of this account: the whole plan, or with `step` just that step — its input logic, " +
-            "output logic, whether it is marked *needs a judgement* (nondeterministic) and the recorded input and output " +
-            "it has to reproduce, with the scenario's `scenarioId` and `chainRevision` at the top. Read a step here before changing it.",
+        service: true,
+        description: "Read a calculated scenario: the whole plan, or with `step` one step — its input and output logic, its " +
+            "*needs a judgement* mark and the recorded call it must reproduce, under the scenario's `scenarioId` and " +
+            "`chainRevision`. Read a step here before changing it.",
         inputSchema: {
             type: "object",
             properties: { target: TARGET, step: STEP },
@@ -223,8 +461,9 @@ const SCENARIO_TOOLS = [
     {
         name: "scenario_edits",
         changes: false,
-        description: "List the hand edits of a calculated scenario, newest first: which step changed, the note, the revision, " +
-            "and whether it was saved on purpose (forced), undone, or replaced by a recalculation.",
+        service: true,
+        description: "List a calculated scenario's hand edits, newest first: step, note, revision, and whether each was forced, " +
+            "undone or replaced by a recalculation.",
         inputSchema: {
             type: "object",
             properties: { target: TARGET },
@@ -236,9 +475,10 @@ const SCENARIO_TOOLS = [
     {
         name: "investigate",
         changes: false,
-        description: "Explain why a turn in this project did or did not replay its calculated scenario, what it cost and saved, " +
-            "and what to fix. Without `id`, the newest turn here; with a run_, scn_ or sexec_ id, that one. A finding " +
-            "that names a step can be read with scenario_show and, where editing is on, fixed with scenario_check and scenario_edit.",
+        // The journal half needs no service; the service half says why it is missing.
+        service: false,
+        description: "Explain why a turn here did or did not replay its calculated scenario, what it cost and saved, and what " +
+            "to fix. Without `id`, the newest turn; with a run_, scn_ or sexec_ id, that one.",
         inputSchema: {
             type: "object",
             properties: {
@@ -258,6 +498,7 @@ const SCENARIO_TOOLS = [
     {
         name: "scenario_check",
         changes: true,
+        service: true,
         description: "Try a change to one step of a calculated scenario without saving anything: the service runs the new " +
             "`inputLogic` and/or `outputLogic` with the recording's values and reports whether this step and every later " +
             "step still reproduce the recorded calls, and what happens to the step's *needs a judgement* mark. The workflow " +
@@ -284,6 +525,7 @@ const SCENARIO_TOOLS = [
     {
         name: "scenario_edit",
         changes: true,
+        service: true,
         description: "Save a change to one step of a calculated scenario. It runs the same check as scenario_check and saves only " +
             "if the step reproduces the recording and is not a copy of the recorded call; always give a `note` saying why, " +
             "and `revision` (the `chainRevision` at the top of a scenario_show answer with `step`) so a plan that changed " +
@@ -342,6 +584,7 @@ const SCENARIO_TOOLS = [
     {
         name: "scenario_undo",
         changes: true,
+        service: true,
         description: "Take back a hand edit of a calculated scenario: its step goes back as it was before that edit. Without `edit`, " +
             "the newest edit that can be undone (of `step`, when given); calling it again goes one further back. The service " +
             "checks the undo like a save and refuses it when a later step or the final answer would break — `force` with a " +
@@ -389,23 +632,71 @@ function editingOn(cwd) {
         return false;
     }
 }
-/** The tools to list for `cwd`, read now: the switch may have moved since the last list. */
+/** `bir off` (everywhere, or for this project): the runner stays out of the way. Never throws. */
+function runnerOff(cwd) {
+    try {
+        return isRunnerOff(cwd);
+    }
+    catch {
+        return false;
+    }
+}
+/** `BIR_SCENARIO_TOOLS=read`: offer the reading tools without turning editing on. */
+function readToolsOptedIn() {
+    const value = (process.env.BIR_SCENARIO_TOOLS ?? "").trim().toLowerCase();
+    return value === "read" || value === "1" || value === "on" || value === "true";
+}
+/** The tools to list for `cwd`, read now: the switches may have moved since the last list. */
 function listTools(cwd) {
+    if (runnerOff(cwd))
+        return [];
     const editing = editingOn(cwd);
+    const reading = editing || readToolsOptedIn();
     return [
         TOOL,
-        ...SCENARIO_TOOLS.filter((t) => !t.changes || editing).map(({ name, description, inputSchema }) => ({
+        ...SCENARIO_TOOLS.filter((t) => (t.changes ? editing : reading)).map(({ name, description, inputSchema }) => ({
             name,
             description,
             inputSchema,
         })),
     ];
 }
+/**
+ * Why a tool that needs the service cannot have it on this machine, found
+ * without the network — or undefined. Checked before `bir` starts, because
+ * `bir` settles the service address with a request *before* it looks for a
+ * session, and a signed-out machine with an unreachable service then waited
+ * out that request for nothing. Only whether the files exist is looked at:
+ * this server holds no credentials.
+ */
+function signInProblem() {
+    if (process.env.BIR_AUTH_DISABLE === "1")
+        return undefined;
+    let url = "";
+    try {
+        url = resolveAuthUrl();
+    }
+    catch {
+        url = "";
+    }
+    if (!url) {
+        return "No BaseIn service is configured on this machine, so there is nothing to read or change. A person runs `bir setup` (or `bir login`) in a terminal.";
+    }
+    try {
+        if (!existsSync(credentialsPath())) {
+            return "Not signed in to BaseIn on this machine. A person runs `bir login` in a terminal; then this works.";
+        }
+    }
+    catch {
+        // Cannot tell: let `bir` find out.
+    }
+    return undefined;
+}
 /** This package's own `bir`, beside this file — never whatever `bir` is first on PATH. */
 function birPath() {
     return resolvePath(dirname(fileURLToPath(import.meta.url)), "bir.js");
 }
-/** Scenario tool calls in flight, by JSON-RPC request id. */
+/** Calls in flight, by JSON-RPC request id. */
 const inFlight = new Map();
 /** Remove a call's logic directory, once. Never throws: this runs on the way out. */
 function removeDir(flight) {
@@ -421,7 +712,11 @@ function removeDir(flight) {
         logLine("scenario.tmp_left", { dir, error: errText(err) });
     }
 }
-/** Stop a call's `bir` (if it still runs) and remove its logic files. Synchronous: it runs before `process.exit`. */
+/**
+ * Stop a call: its `bir` (if it still runs), its logic files, its request to
+ * the control server — whose closing is what tells the control server to stop
+ * starting steps. Synchronous: it runs before `process.exit`.
+ */
 function stopFlight(flight) {
     const child = flight.child;
     if (child && child.exitCode === null && child.signalCode === null) {
@@ -432,13 +727,20 @@ function stopFlight(flight) {
             // Already gone.
         }
     }
+    try {
+        flight.abort?.abort();
+    }
+    catch {
+        // Nothing left to abort.
+    }
     removeDir(flight);
 }
-function runBir(argv, cwd, flight) {
+function runBir(argv, cwd, timeoutMs, flight) {
     return new Promise((resolve) => {
         const child = spawn(process.execPath, [...nodeFlagsToCarry(), birPath(), ...argv], {
             cwd,
-            env: process.env,
+            // BIR_MCP: compact JSON, and no raw journal lines — the answer is for a model.
+            env: { ...process.env, BIR_MCP: "1" },
             // Nothing is ever read from stdin: logic arrives as files.
             stdio: ["ignore", "pipe", "pipe"],
             windowsHide: true,
@@ -446,32 +748,53 @@ function runBir(argv, cwd, flight) {
         if (flight)
             flight.child = child;
         let stdout = "";
-        let stderr = "";
+        // Audit lines go on to this server's log as they arrive, as its own would;
+        // only the sentences `bir` wrote for a person are kept for the model.
+        const stderr = new StderrSorter({
+            keepChars: MAX_STDERR_CHARS,
+            forwardChars: MAX_AUDIT_FORWARD_CHARS,
+            forward: (line) => process.stderr.write(`${line}\n`),
+        });
         let timedOut = false;
+        let truncated = false;
         child.stdout.setEncoding("utf8");
         child.stderr.setEncoding("utf8");
+        // Past the cap the pipe is still drained — a child blocked on a full pipe
+        // never exits — but nothing more is kept.
         child.stdout.on("data", (c) => {
-            stdout += c;
-        });
-        child.stderr.on("data", (c) => {
-            stderr += c;
+            const room = MAX_OUTPUT_CHARS - stdout.length;
+            if (c.length > room)
+                truncated = true;
+            if (room > 0)
+                stdout += c.length > room ? c.slice(0, room) : c;
         });
+        child.stderr.on("data", (c) => stderr.push(c));
         const timer = setTimeout(() => {
             timedOut = true;
             child.kill();
-        }, BIR_TIMEOUT_MS);
+        }, timeoutMs);
         timer.unref?.();
         child.on("error", (err) => {
             clearTimeout(timer);
-            resolve({ code: null, stdout, stderr: `${stderr}${errText(err)}`, timedOut });
+            resolve({ code: null, stdout, stderr: `${stderr.end()}${errText(err)}`, timedOut, truncated });
         });
         child.on("close", (code) => {
             clearTimeout(timer);
-            resolve({ code, stdout, stderr, timedOut });
+            resolve({ code, stdout, stderr: stderr.end(), timedOut, truncated });
         });
     });
 }
 const failed = (text) => ({ content: [{ type: "text", text }], isError: true });
+/** What a model reads when `bir` ran out of time: what it means, and what to do. */
+function timeoutText(tool, argv, ms) {
+    const opening = `${tool.name} did not finish within ${Math.round(ms / 1000)} s — the BaseIn service may be slow or unreachable.`;
+    if (!tool.changes) {
+        return `${opening} Try again later; a person can also run \`bir ${argv.join(" ")}\` in a terminal.`;
+    }
+    return tool.name === "scenario_check"
+        ? `${opening} Nothing was saved.`
+        : `${opening} It may still have been saved: scenario_edits lists what was.`;
+}
 /**
  * Run one scenario tool. Never throws. The logic bodies are written to a
  * directory of their own under the OS temp directory, owner-only, and the
@@ -488,6 +811,9 @@ async function callScenarioTool(tool, args, cwd, flight = { tool: tool.name, can
     catch (err) {
         return failed(`invalid arguments for ${tool.name}: ${errText(err)}`);
     }
+    const problem = tool.service ? signInProblem() : undefined;
+    if (problem)
+        return failed(problem);
     try {
         const argv = [...plan.argv];
         if (plan.inputLogic !== undefined || plan.outputLogic !== undefined) {
@@ -507,18 +833,31 @@ async function callScenarioTool(tool, args, cwd, flight = { tool: tool.name, can
         argv.push("--json");
         if (flight.cancelled)
             return failed("cancelled before bir started");
-        const run = await runBir(argv, cwd, flight);
+        const timeoutMs = tool.changes ? BIR_TIMEOUT_MS : readToolTimeoutMs();
+        const run = await runBir(argv, cwd, timeoutMs, flight);
         if (flight.cancelled)
             return failed("cancelled");
-        if (run.timedOut)
-            return failed(`bir did not finish in ${BIR_TIMEOUT_MS / 1000} s`);
-        const stdout = run.stdout.trim();
+        // `bir`'s audit lines went to this server's log as they arrived, as its
+        // own would; `run.stderr` is only the sentences it wrote for a person.
+        if (run.timedOut) {
+            logLine("scenario.tool_timeout", { tool: tool.name, ms: timeoutMs });
+            return failed(timeoutText(tool, plan.argv, timeoutMs));
+        }
+        let stdout = run.stdout.trim();
+        if (run.truncated) {
+            logLine("scenario.tool_truncated", { tool: tool.name, kept: MAX_OUTPUT_CHARS });
+            const less = tool.name === "scenario_show" && !plan.argv.includes("--step")
+                ? "Ask for one step at a time with `step`."
+                : `A person can run \`bir ${plan.argv.join(" ")}\` in a terminal for all of it.`;
+            stdout += `\n…(truncated: the answer passed ${MAX_OUTPUT_CHARS} characters. ${less})`;
+        }
         if (run.code === 0)
             return { content: [{ type: "text", text: stdout || "(no output)" }], isError: false };
         // The refusal and its report are on stdout; why bir itself failed, if it
         // did (not signed in, no service address), is on stderr. The model needs both.
-        const text = [stdout, run.stderr.trim()].filter(Boolean).join("\n");
-        return failed(text || `bir exited with code ${run.code ?? "?"}`);
+        const reason = run.stderr.trim();
+        const text = [stdout, reason].filter(Boolean).join("\n");
+        return failed(text || `${tool.name} failed: bir exited with code ${run.code ?? "?"}`);
     }
     catch (err) {
         return failed(`could not run bir: ${errText(err)}`);
@@ -527,12 +866,39 @@ async function callScenarioTool(tool, args, cwd, flight = { tool: tool.name, can
         removeDir(flight);
     }
 }
+/** How often the off switch is looked at, so the host can be told its tool list changed. */
+const SWITCH_POLL_MS = 2_000;
 function main() {
+    // Started with --use-env-proxy in a shell whose NO_PROXY does not name
+    // 127.0.0.1: without this, `run_scenario`'s request to the control server
+    // goes to the proxy, which refuses or swallows it, and every replay became
+    // "not available". Before anything here fetches; the `bir` it spawns does
+    // the same for itself.
+    try {
+        exemptLoopbackFromProxy();
+    }
+    catch (err) {
+        logLine("scenario.no_proxy_failed", { error: errText(err) });
+    }
     const cwd = process.cwd();
     let closing = false;
+    /** The host has asked for the tools, so it has a list a change could make stale. */
+    let listed = false;
     const reply = (msg) => writeFrame(process.stdout, msg);
     /**
-     * The host is gone: stop every `bir` still running for it and remove its
+     * The hello and the revive (scenario-liveness.ts). Every call to it returns
+     * at once and is made after the answer it follows was written: nothing a
+     * host waits for waits on the recorder.
+     */
+    const liveness = new ScenarioLiveness({
+        cwd,
+        state: () => {
+            const off = runnerOff(cwd);
+            return { tools: off ? 0 : listTools(cwd).length, off };
+        },
+    });
+    /**
+     * The host is gone: stop every call still running for it and remove its
      * logic files, then exit. Everything here is synchronous, because nothing
      * after `process.exit` runs — not a pending call's `finally` either.
      */
@@ -540,6 +906,7 @@ function main() {
         if (closing)
             return;
         closing = true;
+        liveness.stop();
         if (inFlight.size > 0) {
             logLine("scenario.shutdown", { why, stopped: [...inFlight.values()].map((f) => f.tool) });
         }
@@ -548,6 +915,68 @@ function main() {
         inFlight.clear();
         process.exit(0);
     };
+    /** `run_scenario`: ask the control server, and answer exactly once — unless cancelled. */
+    const answerRun = async (id, flight, toolUseId) => {
+        let result;
+        try {
+            result = await runArmedPlan(cwd, flight, toolUseId);
+        }
+        catch (err) {
+            result = { ok: false, why: errText(err) };
+        }
+        if (inFlight.get(id) === flight)
+            inFlight.delete(id);
+        // No live recorder, or none that took the request: have it looked at —
+        // after the answer below is on its way, never before.
+        if (result.kind === "no_control" || result.kind === "unreachable") {
+            liveness.recorderGone("run_scenario found no recorder");
+        }
+        if (flight.cancelled || closing)
+            return;
+        // `ok` is what the model got: an "ok" with no results to show is not one.
+        const ok = delivered(result) !== "";
+        const why = ok
+            ? undefined
+            : typeof result.why === "string"
+                ? result.why
+                : result.ok === true
+                    ? "the control server answered ok with no results"
+                    : "no reason given";
+        logLine("scenario.answered", {
+            ok,
+            steps: typeof result.steps === "number" ? result.steps : undefined,
+            partial: (ok && result.partial === true) || undefined,
+            why: why && why.length > 200 ? `${why.slice(0, 200)}…` : why,
+            // Whether the host named its tool use, so the control server matched the call exactly.
+            bound: toolUseId !== undefined || undefined,
+            detail: result.kind === "no_control" ? "no control server for this directory" : undefined,
+        });
+        let answer;
+        try {
+            answer = toolResult(result);
+        }
+        catch (err) {
+            logLine("scenario.answer_failed", { error: errText(err) });
+            answer = said(UNAVAILABLE_TEXT);
+        }
+        reply({ jsonrpc: "2.0", id, result: answer });
+    };
+    /** A scenario tool: run `bir`, and answer exactly once — unless cancelled. */
+    const answerTool = async (id, tool, args, flight) => {
+        let result;
+        try {
+            result = await callScenarioTool(tool, args, cwd, flight);
+        }
+        catch (err) {
+            result = failed(`could not run bir: ${errText(err)}`);
+        }
+        if (inFlight.get(id) === flight)
+            inFlight.delete(id);
+        if (flight.cancelled || closing)
+            return;
+        logLine("scenario.tool_answered", { tool: tool.name, isError: result.isError === true });
+        reply({ jsonrpc: "2.0", id, result });
+    };
     readFrames(process.stdin, {
         onMessage: (msg) => {
             if (!isRequest(msg)) {
@@ -558,7 +987,10 @@ function main() {
                     const flight = typeof requestId === "string" || typeof requestId === "number" ? inFlight.get(requestId) : undefined;
                     if (flight && !flight.cancelled) {
                         flight.cancelled = true;
-                        logLine("scenario.tool_cancelled", { tool: flight.tool, running: flight.child !== undefined });
+                        logLine("scenario.tool_cancelled", {
+                            tool: flight.tool,
+                            running: flight.child !== undefined || flight.abort !== undefined,
+                        });
                         stopFlight(flight);
                     }
                 }
@@ -574,14 +1006,20 @@ function main() {
                         // Echo the host's protocol version when it names one; a server that
                         // insists on its own is a server the host may refuse to talk to.
                         protocolVersion: String(params.protocolVersion ?? "2025-06-18"),
-                        capabilities: { tools: {} },
-                        serverInfo: { name: "bir-scenario", version: "1" },
+                        // listChanged: `bir off` / `bir on` mid-session changes the list.
+                        capabilities: { tools: { listChanged: true } },
+                        // The package's version, so a session still talking to a server
+                        // from before an upgrade shows which one it is.
+                        serverInfo: { name: "bir-scenario", version: packageVersion() },
                     },
                 });
+                liveness.hello("initialize");
                 return;
             }
             if (method === "tools/list") {
+                listed = true;
                 reply({ jsonrpc: "2.0", id, result: { tools: listTools(cwd) } });
+                liveness.hello("tools/list");
                 return;
             }
             if (method === "ping") {
@@ -594,7 +1032,25 @@ function main() {
                 const scenarioTool = SCENARIO_TOOLS.find((t) => t.name === name);
                 if (scenarioTool) {
                     // Asked again, not remembered from tools/list: a host may call a tool
-                    // it listed before the switch went off, or one it was never offered.
+                    // it listed before a switch went off, or one it was never offered.
+                    //
+                    // Off is off for the reading tools too: a host still holding the list
+                    // from before `bir off` must not start a `bir` that asks the service —
+                    // the service misbehaving is a reason people switch the runner off.
+                    // Nothing was asked to change, so it is said plainly, not as an error.
+                    if (!scenarioTool.changes && runnerOff(cwd)) {
+                        logLine("scenario.tool_answered", { tool: name, isError: false, detail: "runner is off" });
+                        reply({
+                            jsonrpc: "2.0",
+                            id,
+                            result: said(`BaseInstRunner is switched off here, so ${name} has nothing to read. A person turns it back on with \`bir on\`.`),
+                        });
+                        return;
+                    }
+                    if (scenarioTool.changes && runnerOff(cwd)) {
+                        reply(errorResponse(id, JsonRpcErrorCode.MethodNotFound, `${name} is not offered: BaseInstRunner is switched off here (\`bir on\` turns it back on).`));
+                        return;
+                    }
                     if (scenarioTool.changes && !editingOn(cwd)) {
                         reply(errorResponse(id, JsonRpcErrorCode.MethodNotFound, `${name} is not offered in this project: scenario editing is off. ` +
                             "A person turns it on with `bir scenario editing on` in this directory, then restarts the session."));
@@ -603,28 +1059,24 @@ function main() {
                     logDetail("scenario.tool", { cwd, tool: name });
                     const flight = { tool: name, cancelled: false };
                     inFlight.set(id, flight);
-                    void callScenarioTool(scenarioTool, paramsObject(params.arguments), cwd, flight).then((result) => {
-                        inFlight.delete(id);
-                        if (flight.cancelled || closing)
-                            return;
-                        logLine("scenario.tool_answered", { tool: name, isError: result.isError === true });
-                        reply({ jsonrpc: "2.0", id, result });
-                    });
+                    void answerTool(id, scenarioTool, paramsObject(params.arguments), flight);
                     return;
                 }
                 if (name !== TOOL_NAME) {
                     reply(errorResponse(id, JsonRpcErrorCode.MethodNotFound, `unknown tool: ${params.name}`));
                     return;
                 }
-                logDetail("scenario.call", { cwd });
-                void runArmedPlan(cwd).then((result) => {
-                    logLine("scenario.answered", {
-                        ok: result.ok ?? false,
-                        steps: result.steps,
-                        why: result.ok ? undefined : result.why,
-                    });
-                    reply({ jsonrpc: "2.0", id, result: toolResult(result) });
-                });
+                // Off: the recorder arms nothing, so there is nothing to ask it for.
+                if (runnerOff(cwd)) {
+                    logLine("scenario.answered", { ok: false, why: "no_plan", detail: "runner is off" });
+                    reply({ jsonrpc: "2.0", id, result: toolResult({ ok: false, why: "no_plan", kind: "off" }) });
+                    return;
+                }
+                const toolUseId = toolUseIdOf(params);
+                logDetail("scenario.call", { cwd, toolUseId });
+                const flight = { tool: TOOL_NAME, cancelled: false };
+                inFlight.set(id, flight);
+                void answerRun(id, flight, toolUseId);
                 return;
             }
             // Anything else: this server advertises only tools, so an unknown method
@@ -635,7 +1087,26 @@ function main() {
         // The host closed our stdin: the session is over.
         onEnd: () => shutdown("stdin closed"),
     });
-    logLine("scenario.started", { cwd, pid: process.pid });
+    // `bir off` / `bir on` while the session runs: the host lists the tools once,
+    // so it is told when the answer changes rather than keeping `run_scenario`
+    // on an inert runner (or missing it on a live one) until a restart. One
+    // `stat` every couple of seconds, on a timer that never keeps us alive.
+    let wasOff = runnerOff(cwd);
+    const watch = setInterval(() => {
+        const off = runnerOff(cwd);
+        if (off === wasOff)
+            return;
+        wasOff = off;
+        logLine("scenario.switched", { off });
+        if (listed && !closing) {
+            writeFrame(process.stdout, { jsonrpc: "2.0", method: "notifications/tools/list_changed" });
+        }
+        // The recorder must stop announcing direct plans on our word while we list nothing.
+        liveness.hello("switched");
+    }, SWITCH_POLL_MS);
+    watch.unref();
+    liveness.start();
+    logLine("scenario.started", { cwd, pid: process.pid, ...(wasOff ? { off: true } : {}) });
     process.on("SIGINT", () => shutdown("SIGINT"));
     process.on("SIGTERM", () => shutdown("SIGTERM"));
     process.on("uncaughtException", (err) => logLine("scenario.uncaught", { error: errText(err) }));