@basein/runner 0.2.11 → 0.2.12

package/README.md

@@ -148,8 +148,21 @@ between the two is not guaranteed.
 - **Change what the model does.** Tool descriptions are never edited. The
   model-visible changes are schema relaxation, below, and — only with
   `--replay` — the first-party `bir` server's tools: `run_scenario`, and three
-  that only read a scenario. The three that change one appear only after
-  `bir scenario editing on` in that project.
+  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).
 
 ---
 
@@ -194,22 +207,28 @@ 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.** 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 — or on purpose, with
-`--force --note "why"`.** Only the owner can change a scenario. Claude can do it
-too: in its terminal, or with the `bir` server's tools once
-`bir scenario editing on` was run in the project. Built 2026-09-25, not yet
-released: it needs the next `@basein/runner` version and a service deploy. Step
-by step: [the guide's §9.2](docs/calculatedReplayGuide.md).
+**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
+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
-bir scenario undo  scn_…                                   # undo the newest edit
+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
 ```
 

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

@@ -26,6 +26,17 @@
  * 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

package/dist/bin/bir-scenario.js

@@ -26,6 +26,17 @@
  * 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
@@ -37,7 +48,7 @@
  * 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";
@@ -134,7 +145,7 @@ class BadArguments extends Error {
 }
 const TARGET = {
     type: "string",
-    description: "The scenario's scn_ id, or the run_ id of the recording it was calculated from — as investigate and scenario_show print them.",
+    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",
@@ -185,13 +196,22 @@ function flag(args, key, name) {
         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. Read a step here before changing it.",
+            "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 },
@@ -266,9 +286,11 @@ const SCENARIO_TOOLS = [
         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 scenario_show printed) so a plan that changed meanwhile is not overwritten. " +
+            "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. Every save can be undone with scenario_undo.",
+            "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: {
@@ -289,7 +311,7 @@ const SCENARIO_TOOLS = [
                 revision: {
                     type: "integer",
                     minimum: 1,
-                    description: "The chainRevision the change was made against; the save is refused if the plan moved on.",
+                    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"],
@@ -307,11 +329,7 @@ const SCENARIO_TOOLS = [
                 ...flag(a, "unfreeze", "--unfreeze"),
                 ...flag(a, "force", "--force"),
             ];
-            if (a.note !== undefined && a.note !== null) {
-                if (typeof a.note !== "string")
-                    throw new BadArguments("`note` must be a string");
-                argv.push("--note", a.note);
-            }
+            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");
@@ -324,13 +342,24 @@ const SCENARIO_TOOLS = [
     {
         name: "scenario_undo",
         changes: true,
-        description: "Put one step of a calculated scenario back as it was before its newest hand edit — without `edit`, the newest " +
-            "edit that can be undone. The undo is itself an edit, so undoing it again redoes the change.",
+        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." },
+                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,
@@ -341,8 +370,12 @@ const SCENARIO_TOOLS = [
                 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 };
         },
     },
@@ -372,7 +405,36 @@ function listTools(cwd) {
 function birPath() {
     return resolvePath(dirname(fileURLToPath(import.meta.url)), "bir.js");
 }
-function runBir(argv, cwd) {
+/** 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,
@@ -381,6 +443,8 @@ function runBir(argv, cwd) {
             stdio: ["ignore", "pipe", "pipe"],
             windowsHide: true,
         });
+        if (flight)
+            flight.child = child;
         let stdout = "";
         let stderr = "";
         let timedOut = false;
@@ -412,9 +476,11 @@ 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.
+ * 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) {
+async function callScenarioTool(tool, args, cwd, flight = { tool: tool.name, cancelled: false }) {
     let plan;
     try {
         plan = tool.plan(args);
@@ -422,11 +488,11 @@ async function callScenarioTool(tool, args, cwd) {
     catch (err) {
         return failed(`invalid arguments for ${tool.name}: ${errText(err)}`);
     }
-    let dir;
     try {
         const argv = [...plan.argv];
         if (plan.inputLogic !== undefined || plan.outputLogic !== undefined) {
-            dir = mkdtempSync(join(tmpdir(), "bir-logic-"));
+            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 });
@@ -439,7 +505,11 @@ async function callScenarioTool(tool, args, cwd) {
             }
         }
         argv.push("--json");
-        const run = await runBir(argv, cwd);
+        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();
@@ -454,18 +524,46 @@ async function callScenarioTool(tool, args, cwd) {
         return failed(`could not run bir: ${errText(err)}`);
     }
     finally {
-        if (dir)
-            rmSync(dir, { recursive: true, force: true });
+        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);
@@ -503,7 +601,12 @@ function main() {
                         return;
                     }
                     logDetail("scenario.tool", { cwd, tool: name });
-                    void callScenarioTool(scenarioTool, paramsObject(params.arguments), cwd).then((result) => {
+                    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 });
                     });
@@ -529,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,9 +12,9 @@
  *   bir login | logout
  *   bir --version
  *
- *   bir scenario list | show <runId|scnId> [--step <n>] | calc <runId> [--force [--discard-edits]]
+ *   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>]
+ *   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

package/dist/bin/bir.js

@@ -12,9 +12,9 @@
  *   bir login | logout
  *   bir --version
  *
- *   bir scenario list | show <runId|scnId> [--step <n>] | calc <runId> [--force [--discard-edits]]
+ *   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>]
+ *   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
@@ -72,16 +72,18 @@ Commands:
   scenario list                     recorded runs and their calculated scenarios
   scenario show <runId|scnId> [--step <n>]
                                     a scenario: intent, params, steps (--step: just that one)
-  scenario calc <runId> [--force [--discard-edits]]
-                                    calculate (or re-derive) a run's scenario
+  scenario calc <runId|scnId> [--force [--discard-edits]]
+                                    calculate (or re-derive) a run's scenario; a scn_ id
+                                    (a sub-task's too) is recalculated in place, with --force
   scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze]
                                     try a change to one step against the recording; saves nothing
   scenario edit <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
                 [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>]
                                     the same check, and save the change if it passes
   scenario edits <runId|scnId>      a scenario's hand edits, newest first
-  scenario undo <runId|scnId> [--edit <sedit_id>]
-                                    put a step back as it was before its newest edit
+  scenario undo <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
+                                    take back the newest edit (of step n); run it again to go
+                                    one further back; undo an undo's sedit_ id to redo
   scenario editing on|off|status    whether this project's bir MCP server offers the tools
                                     that change a scenario (restart Claude Code after)
   scenario replay <scnId> --prompt "…" [--dry]
@@ -111,14 +113,15 @@ Options:
   --dry             replay against recorded outputs only; run no real tools
   --force           scenario calc: recalculate in place · scenario edit: save although
                     the check refused it (needs --note; only for a recording that was wrong)
-  --step <n>        scenario show|check|edit: the step, by the stepIndex \`show\` prints
+                    · scenario undo: undo although a later step or the answer would break
+  --step <n>        scenario show|check|edit|undo: the step, by the stepIndex \`show\` prints
   --input-logic <file|->   scenario check|edit: the new input logic, from a file or stdin (-)
   --output-logic <file|->  scenario check|edit: the new output logic, from a file or stdin (-)
   --freeze          scenario edit: mark the step "needs a judgement" (runs hand over before it)
   --unfreeze        scenario check|edit: ask to remove that mark; the check decides
   --note <text>     scenario edit|undo: why, kept in the history (required with --force)
   --revision <n>    scenario edit|undo: only if the plan is still at this chainRevision
-  --edit <id>       scenario undo: the sedit_ id to undo (default: the newest that can be)
+  --edit <id>       scenario undo: the sedit_ id to undo (default: the newest edit that can be)
   --discard-edits   scenario calc --force: recalculate a plan with hand edits, replacing them
   --no-browser      login: print the link and code, open nothing (SSH, headless)
   --token <value>   login: redeem a one-time setup token from the console (no browser)

package/dist/bin/investigate.js

@@ -179,7 +179,7 @@ export const DECLINES = {
     },
     known_bad_first_step: {
         cause: "the chain's first step is parked after repeated failures.",
-        fix: "wait: the service retries it once an hour for a day, then repairs the plan from the next run of the prompt. To repair now: `bir scenario calc <runId> --force`.",
+        fix: "wait: the service retries it once an hour for a day, then repairs the plan from the next run of the prompt — unless the plan has steps edited by hand, or is a sub-task, which it does not repair on its own. To repair now: `bir scenario calc <scnId> --force` (add --discard-edits to drop hand edits), or fix the step: `bir scenario edit <scnId> --step 0 --input-logic <file>`. `bir investigate <scnId>` names the scenario id.",
     },
     nondeterministic_first_step: {
         cause: "the chain's first step needs a judgement the calculation could not write code for, so the plan cannot start.",

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

@@ -7,8 +7,8 @@
  *   bir scenario edit  <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
  *                      [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>]
  *   bir scenario edits <runId|scnId>
- *   bir scenario undo  <runId|scnId> [--edit <sedit_id>]
- *   bir scenario calc  <runId> [--force [--discard-edits]]
+ *   bir scenario undo  <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
+ *   bir scenario calc  <runId|scnId> [--force [--discard-edits]]
  *   bir scenario editing on|off|status
  *
  * WHY THIS IS A CLIENT AND NOTHING MORE. Whether a change may be saved is
@@ -70,6 +70,10 @@ export interface EditReport {
         before: MarkState;
         after: MarkState;
     };
+    /** The logic and mark asked for are what the step already has (rule 10). */
+    noChange?: boolean;
+    /** The check stopped at the service's sandbox-time budget: *too costly to check* (rule 11). */
+    budgetExceeded?: boolean;
     problems: string[];
 }
 interface MarkState {
@@ -131,7 +135,7 @@ export interface ScenarioEditArgs {
     freeze: boolean;
     unfreeze: boolean;
     note?: string;
-    /** `undo --edit`: the `sedit_` id to put back. */
+    /** `undo --edit`: the `sedit_` id to put back. `undo --step` is {@link step}. */
     edit?: string;
     /** `--revision`: save only if the plan is still at this `chainRevision`. */
     revision?: number;
@@ -155,19 +159,42 @@ export declare function decodeLogic(bytes: Buffer): string;
  * The report in the lines editSteps.md "What a person sees" shows:
  * `input`, `output` (when the output logic changed), `later`, `answer` (when
  * the final answer read anything before) and `mark`.
+ *
+ * `check` prints every line: it is where a person explores a change, and "step
+ * 5 still reproduces" is an answer there. `edit` and `undo` are acts, and print
+ * `brief`ly — what changed and what went wrong: `input` always, `output` when
+ * it changed, `later` only for a step that broke, `answer` only when it lost its
+ * values, `mark` only when it moves. The report is the same one either way (D11);
+ * only the lines that say "nothing to see" are left out.
+ *
+ * An `undo` does not judge the step itself — its code and mark go back exactly
+ * as they were (editSteps.md, "Undo") — so its report's input status is
+ * `not_checked` by design, and printing the usual reason for that ("the
+ * recorded call is plain text") would be false. It says what happened instead.
  */
-export declare function renderReport(out: (line?: string) => void, r: EditReport): void;
+export declare function renderReport(out: (line?: string) => void, r: EditReport, opts?: {
+    brief?: boolean;
+    undo?: boolean;
+}): void;
 /**
  * About {@link CONTEXT} characters either side of `at`. A text already that
  * short — a window the service cut itself, or a small call — is printed whole.
  */
 export declare function around(text: string, at: number): string;
 /**
- * Undo puts one step back as it was before its newest edit (D9). Without
- * `--edit`, that is the newest entry nothing has put back and no
- * recalculation replaced — which is by construction the newest of its step.
- * An undo is itself such an entry, so a second `undo` redoes.
+ * What `undo` without `--edit` takes back (D9): the newest **edit** — never an
+ * undo entry — that nothing has put back and no recalculation replaced; of
+ * step `step` when it is given.
+ *
+ * Undo entries are skipped on purpose. They used to be picked like any other,
+ * so a second `undo` redid the first one, and a step edited twice toggled
+ * between its two edits for ever and never got back to the calculation's code
+ * (C12). Now a second `undo` goes one further back; a redo is asked for by
+ * name, `--edit <the undo's id>`, which the undo prints.
+ *
+ * Whether the step is still exactly as that edit left it is the service's
+ * question, not this list's: it answers `not_latest_edit` when it is not.
  */
-export declare function newestUndoable(edits: EditEntry[]): EditEntry | undefined;
+export declare function newestUndoable(edits: EditEntry[], step?: number): EditEntry | undefined;
 export {};
 //# sourceMappingURL=scenario-edit.d.ts.map