@basein/runner 0.2.10 → 0.2.12

package/README.md

@@ -147,7 +147,22 @@ between the two is not guaranteed.
   section.
 - **Change what the model does.** Tool descriptions are never edited. The
   model-visible changes are schema relaxation, below, and — only with
-  `--replay` — one first-party tool.
+  `--replay` — the first-party `bir` server's tools: `run_scenario`, and three
+  that only read a scenario. The three for changing one (`scenario_check`,
+  `scenario_edit`, `scenario_undo`) appear only after `bir scenario editing on`
+  in that project (not yet released, see below).
+- **Record its own `bir` calls** (next version, not yet released). A session
+  that fixes a plan is not a task to replay. The `bir` server's tools other
+  than `run_scenario`, and a `Bash` or `PowerShell` command made only of `bir`
+  commands, are never recorded as steps and never count as leaving a plan.
+  `npm test && bir investigate` is still recorded: `npm test` is real work.
+- **Sandbox scenario code on this machine.** A calculated or hand-edited step
+  runs here with `new Function`, next to your sign-in and your wrapped servers.
+  The service will sandbox its own runs of the same code (with its next deploy);
+  the runner does not. The service's check of a hand edit only judges what the
+  code returns for the recording's values, so it cannot prove what the code
+  does here: read a hand edit before it is saved. See
+  [the design's §13.1](docs/calculatedReplay.md).
 
 ---
 
@@ -192,6 +207,31 @@ sequence runs through connections the proxies already hold — **zero model toke
 scenarios steer the live session instead, pinning each step's arguments. Either
 way the turn reports what it cost, so the savings ledger measures something real.
 
+**Fixing a step.** Built 2026-09-25, not yet released: it needs the next
+`@basein/runner` version and a service deploy. A calculated step is code, and
+code can be wrong. `bir investigate` names such a step; `bir scenario edit`
+fixes it, and the service checks the change against the recording before it
+saves it. **A change is saved only if it reproduces the recording and is not a
+copy — or on purpose, with `--force --note "why"`.** Only the owner can change
+a scenario. `bir scenario undo` takes changes back one at a time: run it again
+to go one further back. An undo is checked too, and is refused if it would
+break a later step or the final answer, unless you add `--force --note "why"`.
+Claude can do all of this: in its terminal, or with the `bir` server's tools
+once `bir scenario editing on` was run in the project. Step by step, with real
+output:
+[the guide's §9.2](docs/calculatedReplayGuide.md).
+
+```bash
+bir scenario show  scn_… --step 3                          # read one step (scenarioId and chainRevision first)
+bir scenario check scn_… --step 3 --input-logic step3.js   # try a change; nothing is saved
+bir scenario edit  scn_… --step 3 --input-logic step3.js --note "why"   # the same check, then save
+bir scenario edits scn_…                                   # the history, newest first
+bir scenario undo  scn_…                                   # take back the newest edit; again to go further back
+bir scenario undo  scn_… --step 3                          # take back step 3's newest edit only
+bir scenario calc  scn_… --force --discard-edits           # recalculate this plan, dropping its hand edits
+bir scenario editing on                                    # let Claude's `bir` tools change scenarios here
+```
+
 ---
 
 ## Two things to know before you turn it on

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

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 /**
- * bir-scenario — a first-party MCP server with exactly one tool
- * (docs/calculatedReplay.md §6.3).
+ * bir-scenario — the first-party `bir` MCP server (docs/calculatedReplay.md §6.3):
+ * `run_scenario`, plus the tools that read and fix a calculated scenario
+ * (editSteps.md in the BaseIn repository; docs/calculatedReplayGuide.md §9.2).
  *
  * WHY THIS EXISTS. On a fully-wrapped match the whole scenario runs server-side,
  * through proxies that are already connected, and the model's only job is to read
@@ -17,6 +18,32 @@
  * control server exactly as a proxy does — `~/.baseinstrunner/control/<key>.json`,
  * mode 0600, bearer token — and forwards one call.
  *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
  * 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.
  */

package/dist/bin/bir-scenario.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 /**
- * bir-scenario — a first-party MCP server with exactly one tool
- * (docs/calculatedReplay.md §6.3).
+ * bir-scenario — the first-party `bir` MCP server (docs/calculatedReplay.md §6.3):
+ * `run_scenario`, plus the tools that read and fix a calculated scenario
+ * (editSteps.md in the BaseIn repository; docs/calculatedReplayGuide.md §9.2).
  *
  * WHY THIS EXISTS. On a fully-wrapped match the whole scenario runs server-side,
  * through proxies that are already connected, and the model's only job is to read
@@ -17,12 +18,44 @@
  * control server exactly as a proxy does — `~/.baseinstrunner/control/<key>.json`,
  * mode 0600, bearer token — and forwards one call.
  *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
  * 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.
  */
 import { readFrames, writeFrame } from "../jsonrpc/framing.js";
-import { JsonRpcErrorCode, errorResponse, isRequest, paramsObject, } from "../jsonrpc/types.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 { 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 { logLine, logDetail, errText } from "../util/log.js";
 /** Must match `DIRECT_TOOL_NAME`'s suffix in the replay controller. */
 const TOOL_NAME = "run_scenario";
@@ -105,14 +138,432 @@ function toolResult(result) {
         isError: false,
     };
 }
+// ── the scenario tools: `bir scenario …`, spawned ─────────────────────────────
+/** How long one `bir` command may take. A check replays the chain on the service. */
+const BIR_TIMEOUT_MS = 120_000;
+class BadArguments extends Error {
+}
+const TARGET = {
+    type: "string",
+    description: "A scn_ id, or the run_ id of a whole-run scenario (a sub-task scenario has only its scn_ id) — as investigate and scenario_show print them.",
+};
+const STEP = {
+    type: "integer",
+    minimum: 0,
+    description: "The step's stepIndex, as scenario_show prints it (the first step is 0).",
+};
+const INPUT_LOGIC = {
+    type: "string",
+    description: "The new input logic: the BODY of a JavaScript function of (parameters, intent, respParams) that ends in `return { … }` — the tool's input. Only JavaScript's built-ins exist when the service runs it.",
+};
+const OUTPUT_LOGIC = {
+    type: "string",
+    description: "The new output logic: the BODY of a JavaScript function of (toolOutput, parameters, intent, respParams) — toolOutput is the tool's answer as text — returning the values later steps read.",
+};
+/** A `run_`/`scn_` id: letters, digits, `_` and `-`, so it can never read as a flag. */
+function target(args) {
+    const value = args.target;
+    if (typeof value !== "string" || !/^(run|scn)_[\w-]+$/.test(value)) {
+        throw new BadArguments("`target` must be a scn_… or run_… id");
+    }
+    return value;
+}
+function step(args, required) {
+    const value = typeof args.step === "string" && /^\d+$/.test(args.step) ? Number(args.step) : args.step;
+    if (value === undefined || value === null) {
+        if (required)
+            throw new BadArguments("`step` is required: the stepIndex scenario_show prints");
+        return [];
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new BadArguments("`step` must be a whole number from 0");
+    }
+    return ["--step", String(value)];
+}
+function logic(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw new BadArguments(`\`${key}\` must be a string: a JavaScript function body`);
+    return value;
+}
+function flag(args, key, name) {
+    const value = args[key];
+    if (value === undefined || value === null || value === false)
+        return [];
+    if (value !== true)
+        throw new BadArguments(`\`${key}\` must be true or false`);
+    return [name];
+}
+/** `--note <text>`. The text is one argv element, so no quoting can split it. */
+function note(args) {
+    const value = args.note;
+    if (value === undefined || value === null)
+        return [];
+    if (typeof value !== "string")
+        throw new BadArguments("`note` must be a string");
+    return ["--note", value];
+}
+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.",
+        inputSchema: {
+            type: "object",
+            properties: { target: TARGET, step: STEP },
+            required: ["target"],
+            additionalProperties: false,
+        },
+        plan: (a) => ({ argv: ["scenario", "show", target(a), ...step(a, false)] }),
+    },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            properties: { target: TARGET },
+            required: ["target"],
+            additionalProperties: false,
+        },
+        plan: (a) => ({ argv: ["scenario", "edits", target(a)] }),
+    },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "A run_, scn_ or sexec_ id. Omit it for the newest turn in this project." },
+            },
+            additionalProperties: false,
+        },
+        plan: (a) => {
+            if (a.id === undefined || a.id === null || a.id === "")
+                return { argv: ["investigate"] };
+            if (typeof a.id !== "string" || !/^(run|scn|sexec)_[\w-]+$/.test(a.id)) {
+                throw new BadArguments("`id` must be a run_…, scn_… or sexec_… id");
+            }
+            return { argv: ["investigate", a.id] };
+        },
+    },
+    {
+        name: "scenario_check",
+        changes: 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 " +
+            "is scenario_show → scenario_check until it passes → scenario_edit with the same change and a `note` saying why. " +
+            "A failing check means the code is wrong, not that the check is in the way: fix the code.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                target: TARGET,
+                step: STEP,
+                inputLogic: INPUT_LOGIC,
+                outputLogic: OUTPUT_LOGIC,
+                unfreeze: { type: "boolean", description: "Ask whether the *needs a judgement* mark could be removed." },
+            },
+            required: ["target", "step"],
+            additionalProperties: false,
+        },
+        plan: (a) => ({
+            argv: ["scenario", "check", target(a), ...step(a, true), ...flag(a, "unfreeze", "--unfreeze")],
+            inputLogic: logic(a, "inputLogic"),
+            outputLogic: logic(a, "outputLogic"),
+        }),
+    },
+    {
+        name: "scenario_edit",
+        changes: 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 " +
+            "meanwhile is not overwritten. " +
+            "`force` saves what the check refused and is only for a recording that was itself wrong — never a way past a " +
+            "failing check. A save can be taken back with scenario_undo, which the service checks too: it refuses an undo " +
+            "that would break a later step, and a recalculation with --discard-edits replaces edits for good.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                target: TARGET,
+                step: STEP,
+                inputLogic: INPUT_LOGIC,
+                outputLogic: OUTPUT_LOGIC,
+                freeze: {
+                    type: "boolean",
+                    description: "Mark the step *needs a judgement*: runs then hand over to the agent in front of it.",
+                },
+                unfreeze: { type: "boolean", description: "Remove that mark, if the check says the step reproduces." },
+                force: {
+                    type: "boolean",
+                    description: "Save although the check refused it. Needs `note`. Only when the recording itself was wrong.",
+                },
+                note: { type: "string", description: "Why the step is changed; kept in the history. Required with `force`." },
+                revision: {
+                    type: "integer",
+                    minimum: 1,
+                    description: "The chainRevision the change was made against — at the top of a scenario_show answer with `step`; the save is refused if the plan moved on.",
+                },
+            },
+            required: ["target", "step"],
+            additionalProperties: false,
+        },
+        plan: (a) => {
+            if (a.freeze === true && a.unfreeze === true)
+                throw new BadArguments("`freeze` and `unfreeze` ask for opposite things");
+            const argv = [
+                "scenario",
+                "edit",
+                target(a),
+                ...step(a, true),
+                ...flag(a, "freeze", "--freeze"),
+                ...flag(a, "unfreeze", "--unfreeze"),
+                ...flag(a, "force", "--force"),
+            ];
+            argv.push(...note(a));
+            if (a.revision !== undefined && a.revision !== null) {
+                if (typeof a.revision !== "number" || !Number.isInteger(a.revision) || a.revision < 1) {
+                    throw new BadArguments("`revision` must be a whole number from 1");
+                }
+                argv.push("--revision", String(a.revision));
+            }
+            return { argv, inputLogic: logic(a, "inputLogic"), outputLogic: logic(a, "outputLogic") };
+        },
+    },
+    {
+        name: "scenario_undo",
+        changes: 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 " +
+            "`note` undoes it anyway. To redo, undo the undo: pass its sedit_ id as `edit` (the answer names it).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                target: TARGET,
+                edit: { type: "string", description: "The sedit_ id to undo, as scenario_edits lists it. Not with `step`." },
+                step: {
+                    ...STEP,
+                    description: "Undo the newest edit of this step (its stepIndex, as scenario_show prints it). Not with `edit`.",
+                },
+                force: {
+                    type: "boolean",
+                    description: "Undo although the check refused it (a later step or the answer would break). Needs `note`.",
+                },
+                note: { type: "string", description: "Why; kept in the history. Required with `force`." },
+            },
+            required: ["target"],
+            additionalProperties: false,
+        },
+        plan: (a) => {
+            const argv = ["scenario", "undo", target(a)];
+            if (a.edit !== undefined && a.edit !== null) {
+                if (typeof a.edit !== "string" || !/^sedit_[\w-]+$/.test(a.edit)) {
+                    throw new BadArguments("`edit` must be a sedit_… id");
+                }
+                if (a.step !== undefined && a.step !== null) {
+                    throw new BadArguments("`edit` names one entry and `step` picks one; give one of them");
+                }
+                argv.push("--edit", a.edit);
+            }
+            argv.push(...step(a, false), ...flag(a, "force", "--force"), ...note(a));
+            return { argv };
+        },
+    },
+];
+/** Whether this project may be offered the tools that change a scenario. Never throws. */
+function editingOn(cwd) {
+    try {
+        return editingEnabled(readSidecar(), cwd);
+    }
+    catch {
+        return false;
+    }
+}
+/** The tools to list for `cwd`, read now: the switch may have moved since the last list. */
+function listTools(cwd) {
+    const editing = editingOn(cwd);
+    return [
+        TOOL,
+        ...SCENARIO_TOOLS.filter((t) => !t.changes || editing).map(({ name, description, inputSchema }) => ({
+            name,
+            description,
+            inputSchema,
+        })),
+    ];
+}
+/** 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. */
+const inFlight = new Map();
+/** Remove a call's logic directory, once. Never throws: this runs on the way out. */
+function removeDir(flight) {
+    const dir = flight.dir;
+    if (!dir)
+        return;
+    flight.dir = undefined;
+    try {
+        // A child killed a moment ago may still hold a handle on Windows; retry briefly.
+        rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+    }
+    catch (err) {
+        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`. */
+function stopFlight(flight) {
+    const child = flight.child;
+    if (child && child.exitCode === null && child.signalCode === null) {
+        try {
+            child.kill();
+        }
+        catch {
+            // Already gone.
+        }
+    }
+    removeDir(flight);
+}
+function runBir(argv, cwd, flight) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [...nodeFlagsToCarry(), birPath(), ...argv], {
+            cwd,
+            env: process.env,
+            // Nothing is ever read from stdin: logic arrives as files.
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        if (flight)
+            flight.child = child;
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (c) => {
+            stdout += c;
+        });
+        child.stderr.on("data", (c) => {
+            stderr += c;
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, BIR_TIMEOUT_MS);
+        timer.unref?.();
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ code: null, stdout, stderr: `${stderr}${errText(err)}`, timedOut });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code, stdout, stderr, timedOut });
+        });
+    });
+}
+const failed = (text) => ({ content: [{ type: "text", text }], isError: true });
+/**
+ * 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
+ * directory is removed whatever happens — the code may carry a table name or a
+ * host the person would not want left lying around. "Whatever happens"
+ * includes the host leaving mid-call: the directory and the child live in
+ * `flight`, which `main` stops on the way out ({@link stopFlight}).
+ */
+async function callScenarioTool(tool, args, cwd, flight = { tool: tool.name, cancelled: false }) {
+    let plan;
+    try {
+        plan = tool.plan(args);
+    }
+    catch (err) {
+        return failed(`invalid arguments for ${tool.name}: ${errText(err)}`);
+    }
+    try {
+        const argv = [...plan.argv];
+        if (plan.inputLogic !== undefined || plan.outputLogic !== undefined) {
+            const dir = mkdtempSync(join(tmpdir(), "bir-logic-"));
+            flight.dir = dir;
+            if (plan.inputLogic !== undefined) {
+                const file = join(dir, "input.js");
+                writeFileSync(file, plan.inputLogic, { encoding: "utf8", mode: 0o600 });
+                argv.push("--input-logic", file);
+            }
+            if (plan.outputLogic !== undefined) {
+                const file = join(dir, "output.js");
+                writeFileSync(file, plan.outputLogic, { encoding: "utf8", mode: 0o600 });
+                argv.push("--output-logic", file);
+            }
+        }
+        argv.push("--json");
+        if (flight.cancelled)
+            return failed("cancelled before bir started");
+        const run = await runBir(argv, cwd, 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();
+        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 ?? "?"}`);
+    }
+    catch (err) {
+        return failed(`could not run bir: ${errText(err)}`);
+    }
+    finally {
+        removeDir(flight);
+    }
+}
 function main() {
     const cwd = process.cwd();
     let closing = false;
     const reply = (msg) => writeFrame(process.stdout, msg);
+    /**
+     * The host is gone: stop every `bir` 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.
+     */
+    const shutdown = (why) => {
+        if (closing)
+            return;
+        closing = true;
+        if (inFlight.size > 0) {
+            logLine("scenario.shutdown", { why, stopped: [...inFlight.values()].map((f) => f.tool) });
+        }
+        for (const flight of inFlight.values())
+            stopFlight(flight);
+        inFlight.clear();
+        process.exit(0);
+    };
     readFrames(process.stdin, {
         onMessage: (msg) => {
-            if (!isRequest(msg))
-                return; // notifications need no answer
+            if (!isRequest(msg)) {
+                // Notifications need no answer; one says to stop a call (MCP
+                // `notifications/cancelled`), and a stopped call is answered by nobody.
+                if (isNotification(msg) && msg.method === "notifications/cancelled") {
+                    const requestId = paramsObject(msg.params).requestId;
+                    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 });
+                        stopFlight(flight);
+                    }
+                }
+                return;
+            }
             const { id, method } = msg;
             if (method === "initialize") {
                 const params = paramsObject(msg.params);
@@ -130,7 +581,7 @@ function main() {
                 return;
             }
             if (method === "tools/list") {
-                reply({ jsonrpc: "2.0", id, result: { tools: [TOOL] } });
+                reply({ jsonrpc: "2.0", id, result: { tools: listTools(cwd) } });
                 return;
             }
             if (method === "ping") {
@@ -139,7 +590,29 @@ function main() {
             }
             if (method === "tools/call") {
                 const params = paramsObject(msg.params);
-                if (String(params.name ?? "") !== TOOL_NAME) {
+                const name = String(params.name ?? "");
+                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.
+                    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."));
+                        return;
+                    }
+                    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 });
+                    });
+                    return;
+                }
+                if (name !== TOOL_NAME) {
                     reply(errorResponse(id, JsonRpcErrorCode.MethodNotFound, `unknown tool: ${params.name}`));
                     return;
                 }
@@ -159,17 +632,12 @@ function main() {
             reply(errorResponse(id, JsonRpcErrorCode.MethodNotFound, `unsupported method: ${method}`));
         },
         onParseError: (detail) => logLine("scenario.frame_error", { reason: detail.reason }),
-        onEnd: () => {
-            // The host closed our stdin: the session is over.
-            if (closing)
-                return;
-            closing = true;
-            process.exit(0);
-        },
+        // The host closed our stdin: the session is over.
+        onEnd: () => shutdown("stdin closed"),
     });
     logLine("scenario.started", { cwd, pid: process.pid });
-    process.on("SIGINT", () => process.exit(0));
-    process.on("SIGTERM", () => process.exit(0));
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
     process.on("uncaughtException", (err) => logLine("scenario.uncaught", { error: errText(err) }));
     process.on("unhandledRejection", (err) => logLine("scenario.unhandled_rejection", { error: errText(err) }));
 }

package/dist/bin/bir.d.ts

@@ -12,6 +12,16 @@
  *   bir login | logout
  *   bir --version
  *
+ *   bir scenario list | show <runId|scnId> [--step <n>] | calc <runId|scnId> [--force [--discard-edits]]
+ *   bir scenario check|edit <runId|scnId> --step <n> --input-logic <file|-> …   ← fix one step
+ *   bir scenario edits | undo <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
+ *   bir scenario editing on|off|status   ← may this project's `bir` MCP server change a scenario?
+ *   bir scenario replay <scnId> --prompt "…" [--dry]  |  bir replay status|on|off|allow …
+ *   bir investigate [<id>] | list | executions
+ *
+ * The `scenario` words that read or change one step live in scenario-edit.ts
+ * (editSteps.md in the BaseIn repository); `investigate` in investigate.ts.
+ *
  * `bir install` is reversible by construction: every file it edits is stashed
  * verbatim first, so `bir uninstall` restores it byte-for-byte unless somebody
  * else edited it in the meantime (in which case it repairs the entries and says