@basein/runner 0.2.11 → 0.3.0

package/dist/bin/scenario-edit.js

@@ -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
@@ -31,6 +31,7 @@
 import { normalizePath } from "../control/paths.js";
 import { SCENARIO_SERVER_KEY, editingEnabled, projectRecord, readSidecar, setEditing, writeSidecar, } from "../config/generate.js";
 import { errText } from "../util/log.js";
+import { ReadClock, jsonText, readWithin, serviceProblem } from "./service-read.js";
 /** The `bir scenario` words this module answers; `list` and `replay` stay in bir.ts. */
 export const SCENARIO_EDIT_SUBCOMMANDS = new Set([
     "show",
@@ -41,7 +42,13 @@ export const SCENARIO_EDIT_SUBCOMMANDS = new Set([
     "calc",
     "editing",
 ]);
-/** The `bir` MCP server's tools that only read: always offered (D2). */
+/**
+ * The `bir` MCP server's tools that only read. Offered with scenario editing
+ * on, or where the server's environment has `BIR_SCENARIO_TOOLS=read` — no
+ * longer in every session: their definitions ride along with every request a
+ * session makes, and only somebody working on a scenario ever calls them (the
+ * same answers are `bir scenario show` and `bir investigate` in a terminal).
+ */
 export const READ_TOOLS = ["scenario_show", "scenario_edits", "investigate"];
 /** The ones that change a scenario: offered only after `bir scenario editing on` (D2). */
 export const EDIT_TOOLS = ["scenario_check", "scenario_edit", "scenario_undo"];
@@ -51,8 +58,8 @@ const USAGE = {
     edit: "usage: bir scenario edit <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]\n" +
         '                          [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>] [--json]',
     edits: "usage: bir scenario edits <runId|scnId> [--json]",
-    undo: "usage: bir scenario undo <runId|scnId> [--edit <sedit_id>] [--json]",
-    calc: "usage: bir scenario calc <runId> [--force [--discard-edits]]",
+    undo: 'usage: bir scenario undo <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"] [--json]',
+    calc: "usage: bir scenario calc <runId|scnId> [--force [--discard-edits]]",
     editing: "usage: bir scenario editing on|off|status",
 };
 export async function scenarioEditCommand(args, deps) {
@@ -79,7 +86,11 @@ export async function scenarioEditCommand(args, deps) {
 /**
  * The raw JSON, as it always was — scripts and the guide read it. A `scn_` id
  * goes to `GET /scenarios/:id`, which also serves sub-task scenarios (they have
- * no run of their own); `--step` narrows the print to that one step object.
+ * no run of their own); `--step` narrows the print to that one step object,
+ * with the scenario's id and `chainRevision` put in front of it. The revision
+ * is a scenario's, not a step's, and it is what `edit --revision` (and the MCP
+ * `scenario_edit`'s `revision`) takes: a step printed without it sent the model
+ * that had just read the step off to guess one (C20).
  */
 async function show(args, deps) {
     const { out } = deps;
@@ -87,7 +98,7 @@ async function show(args, deps) {
     if (!target)
         return usageError(deps, "show");
     const byScenario = target.startsWith("scn_");
-    const reply = await deps.service("GET", byScenario ? `/scenarios/${seg(target)}` : `/recordings/runs/${seg(target)}/scenario`);
+    const reply = await readWithin(deps.service("GET", byScenario ? `/scenarios/${seg(target)}` : `/recordings/runs/${seg(target)}/scenario`));
     if ("error" in reply || reply.status !== 200) {
         return explain(reply, args, deps, {
             verb: "Could not read the scenario",
@@ -98,14 +109,13 @@ async function show(args, deps) {
         });
     }
     if (args.step === undefined) {
-        out(JSON.stringify(reply.body, null, 2));
+        out(jsonText(reply.body));
         return 0;
     }
-    const scenario = reply.body?.scenario;
-    if (!scenario) {
-        out(`${target} has no calculated scenario yet — \`bir scenario calc ${target}\` first.`);
-        return 1;
-    }
+    const served = reply.body;
+    const scenario = served?.scenario;
+    if (!scenario)
+        return noWholeRunScenario(target, served?.segments, args, deps);
     if (!Array.isArray(scenario.steps)) {
         out(`${scenario.id ?? target} is ${scenario.state ?? "not ready"}, so it has no steps to show yet.`);
         return 1;
@@ -116,7 +126,7 @@ async function show(args, deps) {
         out(`${scenario.id ?? target} has no step ${args.step}${indexes.length ? ` (its steps are ${Math.min(...indexes)}–${Math.max(...indexes)})` : " (it has no steps)"}.`);
         return 1;
     }
-    out(JSON.stringify(step, null, 2));
+    out(jsonText({ scenarioId: scenario.id ?? null, chainRevision: scenario.chainRevision ?? null, ...step }));
     return 0;
 }
 /**
@@ -181,19 +191,28 @@ async function checkOrEdit(args, deps, save) {
             return explain(reply, args, deps, { verb: "Not checked", ...explained });
         const report = reply.body?.report;
         if (args.json) {
-            out(JSON.stringify(reply.body, null, 2));
-            return report?.ok ? 0 : 1;
+            out(jsonText(reply.body));
+            return report?.ok || report?.noChange ? 0 : 1;
         }
         if (!report) {
             out("The service answered the check without a report.");
             return 1;
         }
         renderReport(out, report);
+        // Before `ok`: a change that is already the step's would pass the check and
+        // then be answered `nothing_to_change` by `edit` — so `check` says so
+        // itself, instead of printing an `edit` command that cannot save (C15).
+        if (report.noChange) {
+            out("Nothing would change: the step already has this code and mark.");
+            return 0;
+        }
         if (report.ok) {
             out(`Nothing saved. To save: ${editCommand(target, args)}`);
             return 0;
         }
-        refusal(out, report.problems ?? [], "Nothing saved, and `bir scenario edit` would refuse it", '  Fix the code and check again. If the recording itself was wrong, edit can save it on purpose: add --force --note "why".');
+        refusal(out, report, "Nothing saved, and `bir scenario edit` would refuse it", report.budgetExceeded
+            ? '  Make the code cheaper to run and check again. If the recording itself was wrong, edit can save it on purpose: add --force --note "why".'
+            : '  Fix the code and check again. If the recording itself was wrong, edit can save it on purpose: add --force --note "why".');
         return 1;
     }
     if (args.freeze)
@@ -213,13 +232,15 @@ async function checkOrEdit(args, deps, save) {
         return explain(reply, args, deps, { verb: "Not saved", ...explained });
     }
     if (args.json) {
-        out(JSON.stringify(reply.body, null, 2));
+        out(jsonText(reply.body));
         return refused ? 1 : 0;
     }
     if (answer?.report)
-        renderReport(out, answer.report);
-    if (refused) {
-        refusal(out, answer?.report?.problems ?? [], "Not saved", '  Fix the code and try again, or save it on purpose: add --force --note "why".');
+        renderReport(out, answer.report, { brief: true });
+    if (refused && answer?.report) {
+        refusal(out, answer.report, "Not saved", answer.report.budgetExceeded
+            ? '  Make the code cheaper to run and try again, or save it on purpose: add --force --note "why".'
+            : '  Fix the code and try again, or save it on purpose: add --force --note "why".');
         return 1;
     }
     const edit = answer?.edit;
@@ -283,12 +304,28 @@ const label = (name, text) => `  ${name.padEnd(9)}${text}`;
  * 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 function renderReport(out, r) {
+export function renderReport(out, r, opts = {}) {
+    const brief = opts.brief === true;
     out(`Step ${r.stepIndex} (${r.toolName ?? "?"}) — checked against ${r.sourceRunId}`);
     const i = r.input ?? { changed: false, before: "not_checked", after: "not_checked" };
     const unchanged = i.changed ? "" : " (input logic unchanged)";
-    if (i.after === "differs") {
+    if (opts.undo) {
+        out(label("input", i.changed ? "back as it was before that edit" : "unchanged"));
+    }
+    else if (i.after === "differs") {
         const d = i.firstDifference ?? firstDifference(i.computed, i.recorded);
         out(label("input", `differs from the recorded call${d ? ` at character ${d.at}` : ""}${unchanged}`));
         if (d) {
@@ -314,8 +351,18 @@ export function renderReport(out, r) {
     }
     const later = r.later ?? [];
     const regressed = later.filter((l) => l.regressed);
-    if (later.length === 0) {
-        out(label("later", "no later steps"));
+    if (brief && regressed.length === 0) {
+        // Nothing broke: an act has nothing to say about later steps.
+    }
+    else if (later.length === 0) {
+        // The service judges later steps only when what they read can change: an
+        // input-only change (or a mark) leaves them alone, and marked or
+        // unverifiable later steps are never judged (editSteps.md rule 6).
+        out(label("later", r.output?.changed
+            ? "none to check"
+            : r.input?.changed
+                ? "not affected: only the input logic changed"
+                : "not affected: the code did not change"));
     }
     else if (regressed.length === 0) {
         const still = later.filter((l) => l.after === "reproduces").map((l) => l.stepIndex);
@@ -330,18 +377,21 @@ export function renderReport(out, r) {
             out(label("later", `step ${l.stepIndex} (${l.toolName ?? "?"}) reproduced before; now it ${laterPhrase(l.after)}`));
         }
     }
-    if (r.answer?.informativeBefore) {
+    if (r.answer?.informativeBefore && !(brief && r.answer.informativeAfter)) {
         out(label("answer", r.answer.informativeAfter
             ? "still gets its values"
             : "no longer gets its values: the final answer's logic stops finding what it reads"));
     }
     if (r.mark?.before && r.mark.after) {
         const { before, after } = r.mark;
-        out(label("mark", before.marked === after.marked && before.why === after.why
-            ? before.marked
-                ? `${markWord(before)} → stays marked`
-                : "runs by itself"
-            : `${markWord(before)} → ${markWord(after)}`));
+        const moves = before.marked !== after.marked || before.why !== after.why;
+        if (moves || !brief) {
+            out(label("mark", moves
+                ? `${markWord(before)} → ${markWord(after)}`
+                : before.marked
+                    ? `${markWord(before)} → stays marked`
+                    : "runs by itself"));
+        }
     }
 }
 function inputPhrase(status, verifiable) {
@@ -413,8 +463,27 @@ function sentence(problem) {
     const lowered = /^[A-Z][a-z]/.test(text) ? text[0].toLowerCase() + text.slice(1) : text;
     return /[.!?]$/.test(lowered) ? lowered : `${lowered}.`;
 }
-function refusal(out, problems, opening, hint) {
-    const list = problems.length ? problems : ["the check did not pass"];
+/**
+ * The verdict under a refused report. When the one thing wrong is that the
+ * changed input logic does not compute the recorded call, the `input` line
+ * above has already said where it parts, and the verdict says it in the words
+ * editSteps.md shows: "the change does not reproduce the recording". Anything
+ * else — a copy, a later step, the answer, the mark, *too costly to check* —
+ * is the service's own sentence, one per problem.
+ */
+function refusal(out, report, opening, hint) {
+    const problems = report.problems ?? [];
+    const inputOnly = problems.length === 1 &&
+        report.input?.changed === true &&
+        (report.input.after === "differs" || report.input.after === "throws") &&
+        !report.budgetExceeded &&
+        !(report.later ?? []).some((l) => l.regressed) &&
+        !(report.answer?.informativeBefore && !report.answer.informativeAfter);
+    const list = inputOnly
+        ? ["the change does not reproduce the recording"]
+        : problems.length
+            ? problems
+            : ["the check did not pass"];
     if (list.length === 1) {
         out(`${opening}: ${sentence(list[0])}`);
     }
@@ -427,7 +496,7 @@ function refusal(out, problems, opening, hint) {
 }
 // ── edits / undo ──────────────────────────────────────────────────────────────
 async function fetchEdits(scenarioId, deps) {
-    const reply = await deps.service("GET", `/scenarios/${seg(scenarioId)}/edits`);
+    const reply = await readWithin(deps.service("GET", `/scenarios/${seg(scenarioId)}/edits`));
     if ("error" in reply || reply.status !== 200)
         return { reply };
     const edits = reply.body?.edits;
@@ -438,15 +507,18 @@ async function listEdits(args, deps) {
     const target = args.positionals[1];
     if (!target)
         return usageError(deps, "edits");
-    const resolved = await resolveTarget(target, args, deps);
+    // A `run_` id is two reads — which scenario, then its history — inside one
+    // bound: the `bir` MCP server gives a reading tool one read's worth of time.
+    const clock = new ReadClock();
+    const resolved = await resolveTarget(target, args, deps, clock);
     if ("code" in resolved)
         return resolved.code;
-    const reply = await deps.service("GET", `/scenarios/${seg(resolved.id)}/edits`);
+    const reply = await clock.within(deps.service("GET", `/scenarios/${seg(resolved.id)}/edits`));
     if ("error" in reply || reply.status !== 200) {
         return explain(reply, args, deps, { verb: "Could not read the history", target });
     }
     if (args.json) {
-        out(JSON.stringify(reply.body, null, 2));
+        out(jsonText(reply.body));
         return 0;
     }
     const edits = reply.body?.edits ?? [];
@@ -489,17 +561,28 @@ function editSummary(e) {
     return parts.length ? parts.join("; ") : "no change to the code or the mark";
 }
 /**
- * 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 function newestUndoable(edits) {
+export function newestUndoable(edits, step) {
     // Newest first, as the service lists them; sorted again so a reordering
     // there cannot make this undo the wrong one.
     return [...edits]
         .sort((x, y) => (x.createdAt < y.createdAt ? 1 : x.createdAt > y.createdAt ? -1 : 0))
-        .find((e) => !e.revertedAt && !e.replacedAt);
+        .find((e) => e.kind !== "revert" &&
+        !e.revertedAt &&
+        !e.replacedAt &&
+        (step === undefined || e.stepIndex === step));
 }
 async function undo(args, deps) {
     const { out } = deps;
@@ -509,6 +592,15 @@ async function undo(args, deps) {
     if (args.edit !== undefined && !/^sedit_[\w-]+$/.test(args.edit)) {
         return usageError(deps, "undo", `--edit takes a sedit_… id, as \`bir scenario edits\` prints it; got ${args.edit}.`);
     }
+    if (args.edit !== undefined && args.step !== undefined) {
+        return usageError(deps, "undo", "--edit names one entry and --step picks one; give one of them.");
+    }
+    const note = args.note?.trim() ? args.note : undefined;
+    if (args.force && !note) {
+        // As for `edit`: an undo the check refused is taken back only on purpose,
+        // and the note is the only record of why.
+        return usageError(deps, "undo", '--force needs --note "why" (note_required): an undo made on purpose says why, and the history keeps it.');
+    }
     const resolved = await resolveTarget(target, args, deps);
     if ("code" in resolved)
         return resolved.code;
@@ -517,34 +609,61 @@ async function undo(args, deps) {
         const listed = await fetchEdits(resolved.id, deps);
         if ("reply" in listed)
             return explain(listed.reply, args, deps, { verb: "Could not read the history", target });
-        const pick = newestUndoable(listed.edits);
+        const pick = newestUndoable(listed.edits, args.step);
         if (!pick) {
-            return localFailure(args, deps, "nothing_to_undo", `Nothing to undo: ${target} has no hand edit that can be undone.`);
+            return localFailure(args, deps, "nothing_to_undo", args.step === undefined
+                ? `Nothing to undo: ${target} has no hand edit that can be undone.`
+                : `Nothing to undo: step ${args.step} of ${target} has no hand edit that can be undone.`);
         }
         editId = pick.id;
     }
     const body = {};
-    if (args.note?.trim())
-        body.note = args.note;
+    if (note)
+        body.note = note;
+    if (args.force)
+        body.force = true;
     if (args.revision !== undefined)
         body.expectedRevision = args.revision;
     const reply = await deps.service("POST", `/scenarios/${seg(resolved.id)}/edits/${seg(editId)}/revert`, body);
-    if ("error" in reply || reply.status !== 200) {
+    const answer = ("error" in reply ? undefined : reply.body);
+    const refused = !("error" in reply) && reply.status === 422 && Boolean(answer?.report);
+    if ("error" in reply || (reply.status !== 200 && !refused)) {
         return explain(reply, args, deps, {
             verb: "Not undone",
             target,
+            editId,
             notFound: `Not undone (not_found): ${target} has no edit ${editId}, or it is not yours.`,
         });
     }
     if (args.json) {
-        out(JSON.stringify(reply.body, null, 2));
-        return 0;
+        out(jsonText(reply.body));
+        return refused ? 1 : 0;
     }
-    const b = reply.body;
-    const entry = b?.edit;
-    const revision = b?.chainRevision ?? entry?.chainRevisionAfter;
+    if (answer?.report)
+        renderReport(out, answer.report, { brief: true, undo: true });
+    if (refused && answer?.report) {
+        // The undo would break a later step or the answer (D9): the same check a
+        // save runs, and the same way past it.
+        refusal(out, answer.report, "Not undone", '  To undo it anyway, on purpose: add --force --note "why".');
+        return 1;
+    }
+    const entry = answer?.edit;
+    const revision = answer?.chainRevision ?? entry?.chainRevisionAfter;
     out(`Step ${entry?.stepIndex ?? "?"} is back as it was before ${entry?.revertsEditId ?? editId} (revision ${revision ?? "?"}).` +
         (entry?.id ? ` Redo: bir scenario undo ${target} --edit ${entry.id}` : ""));
+    // Undo walks back (D9): the same command again goes one further. An undo
+    // asked for by id names its step, so "further back" stays on that step.
+    const further = args.step !== undefined
+        ? ` --step ${args.step}`
+        : args.edit !== undefined && typeof entry?.stepIndex === "number"
+            ? ` --step ${entry.stepIndex}`
+            : "";
+    out(`  One further back: bir scenario undo ${target}${further}`);
+    if (entry?.forced) {
+        out("  Undone on purpose (--force), although the check refused it.");
+        for (const p of answer?.report?.problems ?? [])
+            out(`  The check said: ${sentence(p)}`);
+    }
     return 0;
 }
 // ── calc ──────────────────────────────────────────────────────────────────────
@@ -552,6 +671,13 @@ async function undo(args, deps) {
  * `calc` lives here because of one answer: a recalculation rebuilds every
  * step from the recording, so the service refuses `--force` on a plan with
  * hand edits (D4) unless `--discard-edits` says to throw them away.
+ *
+ * A `run_` id posts `/recordings/runs/:id/calculate`, which reaches only the
+ * run's **whole-run** scenario. A `scn_` id posts `/scenarios/:id/recalculate`
+ * — the only way to recalculate a sub-task (segment) scenario from here, and
+ * so the only way to take a segment's hand edits back once undo cannot (C12).
+ * A scenario id always names one that exists, so it is always a
+ * recalculation in place, and asks for `--force` as the run form does.
  */
 async function calc(args, deps) {
     const { out } = deps;
@@ -561,20 +687,30 @@ async function calc(args, deps) {
     if (args.discardEdits && !args.force) {
         return usageError(deps, "calc", "--discard-edits only means something with --force (a recalculation in place).");
     }
-    const reply = await deps.service("POST", `/recordings/runs/${seg(target)}/calculate`, args.force ? { force: true, ...(args.discardEdits ? { discardEdits: true } : {}) } : {});
+    const byScenario = target.startsWith("scn_");
+    if (byScenario && !args.force) {
+        return usageError(deps, "calc", `${target} is a scenario already, so calculating it means recalculating it in place: add --force (and --discard-edits to replace steps edited by hand).`);
+    }
+    const reply = byScenario
+        ? await deps.service("POST", `/scenarios/${seg(target)}/recalculate`, args.discardEdits ? { discardEdits: true } : {})
+        : await deps.service("POST", `/recordings/runs/${seg(target)}/calculate`, args.force ? { force: true, ...(args.discardEdits ? { discardEdits: true } : {}) } : {});
     if ("error" in reply)
         return explain(reply, args, deps, { verb: "Could not start calculation", target });
     if (args.json) {
-        out(JSON.stringify(reply.body ?? null, null, 2));
+        out(jsonText(reply.body ?? null));
         return reply.status === 202 ? 0 : 1;
     }
     const { status, body } = reply;
     const code = body?.error;
     if (status === 202) {
         const b = body;
-        out(`Calculating ${b.scenarioId ?? ""} — poll with \`bir scenario show ${target}\`.`);
+        out(`${byScenario ? "Recalculating" : "Calculating"} ${b.scenarioId ?? target} — poll with \`bir scenario show ${target}\`.`);
         return 0;
     }
+    if (status === 404) {
+        out(byScenario ? `No such scenario, or it is not yours: ${target}.` : `No such run, or it is not yours: ${target}.`);
+        return 1;
+    }
     if (status === 409 && code === "scenario_has_edits") {
         const steps = body.editedSteps;
         const list = Array.isArray(steps) ? steps.map(String) : [];
@@ -588,15 +724,26 @@ async function calc(args, deps) {
         out("Another calculation of yours is running, and the service calculates one at a time. Try again when it is ready.");
         return 1;
     }
-    if (status === 409) {
+    // With --force the run route answers `scenario_exists` for one reason only:
+    // that scenario is being calculated right now. `scenario_calculating` is the
+    // scenario route's word for the same thing (C16).
+    if (status === 409 && (code === "scenario_calculating" || (code === "scenario_exists" && args.force))) {
+        out(`A calculation of ${target} is already running. Wait for it to finish (\`bir scenario show ${target}\`).`);
+        return 1;
+    }
+    if (status === 409 && code === "scenario_exists") {
         out("That run already has a scenario. Re-derive it in place with --force.");
         return 1;
     }
-    if (status === 503) {
+    if (status === 503 && code === "calculation_paused_today") {
+        out("Calculation is paused for today: the service has reached its daily calculation budget. Try again tomorrow.");
+        return 1;
+    }
+    if (status === 503 && code === "anthropic_not_configured") {
         out("The service has no Anthropic configuration, so it cannot calculate scenarios.");
         return 1;
     }
-    out(`Could not start calculation (HTTP ${status}): ${JSON.stringify(body)}`);
+    out(`Could not start calculation (HTTP ${status}${code ? `, ${code}` : ""}): ${JSON.stringify(body)}`);
     return 1;
 }
 // ── editing on|off|status ─────────────────────────────────────────────────────
@@ -634,11 +781,19 @@ function describeEditing(out, sidecar, cwd) {
     if (!hasScenarioServer(sidecar, cwd)) {
         out("  (no `bir` MCP server is installed here, so no tool is offered at all — `bir install --replay` adds it)");
     }
-    out(`  the bir MCP server offers  ${READ_TOOLS.join(", ")}  (they read)`);
-    if (on)
+    // The reading tools come with the switch too: they are for whoever is
+    // working on a scenario, and every other session would pay for their
+    // definitions on every request without ever calling them.
+    if (on) {
+        out(`  the bir MCP server offers  run_scenario, ${READ_TOOLS.join(", ")}  (they read)`);
         out(`                        and  ${EDIT_TOOLS.join(", ")}  (they change a scenario)`);
-    else
+    }
+    else {
+        out("  the bir MCP server offers  run_scenario");
         out(`  \`bir scenario editing on\` adds ${EDIT_TOOLS.join(", ")}  (they change a scenario)`);
+        out(`                        and  ${READ_TOOLS.join(", ")}  (they read)`);
+        out("  (BIR_SCENARIO_TOOLS=read in the server's environment offers the reading ones alone)");
+    }
     out("  The `bir scenario` commands work either way: this switch decides only the MCP tools.");
 }
 function hasScenarioServer(sidecar, cwd) {
@@ -654,20 +809,41 @@ function usageError(deps, sub, why) {
     deps.out(USAGE[sub] ?? "usage: bir scenario …");
     return 2;
 }
-/** A failure this side decided on; `--json` still gets JSON, in the service's `{error, details}` shape. */
-function localFailure(args, deps, code, text) {
-    deps.out(args.json ? JSON.stringify({ error: code, details: text }, null, 2) : text);
+/**
+ * A failure this side decided on; `--json` still gets JSON, in the service's
+ * `{error, details}` shape (with `extra` beside them when there is more to say).
+ */
+function localFailure(args, deps, code, text, extra = {}) {
+    deps.out(args.json ? jsonText({ error: code, details: text, ...extra }) : text);
     return 1;
 }
+/**
+ * A run with no whole-run scenario. When sub-task (segment) scenarios were
+ * calculated from it, they are listed with their `scn_` ids — the only ids
+ * they have — instead of suggesting a calculation, which would start a new
+ * whole-run plan beside them rather than reach the one the person meant (C21).
+ */
+function noWholeRunScenario(target, segments, args, deps) {
+    const listed = (Array.isArray(segments) ? segments : []).filter((s) => typeof s?.id === "string");
+    if (listed.length === 0) {
+        return localFailure(args, deps, "no_scenario", `${target} has no calculated scenario yet — \`bir scenario calc ${target}\` first.`);
+    }
+    const range = (s) => typeof s.stepFrom === "number" && typeof s.stepTo === "number" ? `  steps ${s.stepFrom}–${s.stepTo} of the recording` : "";
+    const text = [
+        `${target} has no whole-run scenario, only sub-task scenarios — and a sub-task scenario is addressed by its own scn_ id:`,
+        ...listed.map((s) => `  ${s.id}${range(s)}`),
+    ].join("\n");
+    return localFailure(args, deps, "no_whole_run_scenario", text, { segments: listed.map((s) => s.id) });
+}
 /**
  * A `run_` id is the recording's; the routes that change a scenario take its
- * `scn_` id (D7). A `scn_` id is used as it is — sub-task scenarios have
- * nothing else.
+ * `scn_` id (D7). A `run_` id reaches only the run's **whole-run** scenario; a
+ * `scn_` id is used as it is — sub-task scenarios have nothing else.
  */
-async function resolveTarget(target, args, deps) {
+async function resolveTarget(target, args, deps, clock = new ReadClock()) {
     if (target.startsWith("scn_"))
         return { id: target };
-    const reply = await deps.service("GET", `/recordings/runs/${seg(target)}/scenario`);
+    const reply = await clock.within(deps.service("GET", `/recordings/runs/${seg(target)}/scenario`));
     if ("error" in reply || reply.status !== 200) {
         return {
             code: explain(reply, args, deps, {
@@ -677,12 +853,10 @@ async function resolveTarget(target, args, deps) {
             }),
         };
     }
-    const id = reply.body?.scenario?.id;
-    if (typeof id !== "string") {
-        return {
-            code: localFailure(args, deps, "no_scenario", `${target} has no calculated scenario yet — \`bir scenario calc ${target}\` first.`),
-        };
-    }
+    const served = reply.body;
+    const id = served?.scenario?.id;
+    if (typeof id !== "string")
+        return { code: noWholeRunScenario(target, served?.segments, args, deps) };
     return { id };
 }
 /**
@@ -693,14 +867,18 @@ async function resolveTarget(target, args, deps) {
 function explain(reply, args, deps, e) {
     const { out } = deps;
     if ("error" in reply) {
+        // In words, not the transport's ("fetch failed"): this is what reaches a
+        // model through the `bir` MCP server. A person at a terminal also gets the
+        // raw reason in brackets, for a bug report.
+        const words = serviceProblem(reply.error);
         if (args.json)
-            out(JSON.stringify({ error: "service_unreachable", details: reply.error }, null, 2));
+            out(jsonText({ error: "service_unreachable", details: words }));
         else
-            out(`Could not reach the service: ${reply.error}`);
+            out(`Could not reach the service: ${words}${words === reply.error ? "" : ` (${reply.error})`}`);
         return 1;
     }
     if (args.json) {
-        out(JSON.stringify(reply.body ?? null, null, 2));
+        out(jsonText(reply.body ?? null));
         return 1;
     }
     const body = (reply.body && typeof reply.body === "object" ? reply.body : {});
@@ -716,6 +894,12 @@ function explain(reply, args, deps, e) {
         out(`${e.verb}: the service did not accept this machine's session (HTTP 401) — run \`bir login\`.`);
         return 1;
     }
+    if (reply.status === 413) {
+        // By status, not code: a proxy in front of the service answers 413 with a
+        // page of its own, and the cause is the same.
+        out(`${e.verb} (payload_too_large): the request is larger than the service accepts. A logic body may be at most 20 000 characters, and a note 500.`);
+        return 1;
+    }
     switch (code) {
         case "invalid_input": {
             const details = brief(body.details);
@@ -726,7 +910,14 @@ function explain(reply, args, deps, e) {
             out(`${e.verb} (not_a_tool_step): step ${e.step ?? "?"} is a sub-task call row, not a tool step. Call rows belong to the service; only tool steps can be edited.`);
             return 1;
         case "nothing_to_change":
-            out(`${e.verb} (nothing_to_change): give --input-logic, --output-logic, --freeze or --unfreeze.`);
+            // The empty command is refused on this side before any request, so a
+            // service `nothing_to_change` always means the change is already the
+            // step's — naming the flags again would tell the person to repeat
+            // themselves (C15, C27).
+            out("Nothing to change: the step already has this code and this mark.");
+            return 1;
+        case "logic_sandbox_unavailable":
+            out(`${e.verb} (logic_sandbox_unavailable): the service could not run step code just now, so nothing was checked, saved or undone. Try again in a minute.`);
             return 1;
         case "note_required":
             out(`${e.verb} (note_required): --force needs --note "why".`);
@@ -741,9 +932,19 @@ function explain(reply, args, deps, e) {
             return 1;
         }
         case "not_latest_edit": {
+            // Undo walks back (D9), so this is a real way through now: undoing the
+            // newer entry puts the step back as this one left it, and then this one
+            // can be undone. It used to loop, when undo only toggled (C23).
             const latest = typeof body.latestEditId === "string" ? body.latestEditId : "<the newer edit>";
-            out(`${e.verb} (not_latest_edit): a newer edit of the same step follows it. Undo that one first:`);
+            out(`${e.verb} (not_latest_edit): the step has changed since that edit — ${latest} changed it after. Undo the newer one first, then this one:`);
             out(`  bir scenario undo ${target} --edit ${latest}`);
+            out(`  bir scenario undo ${target} --edit ${e.editId ?? "<this edit>"}`);
+            return 1;
+        }
+        case "already_undone": {
+            const by = typeof body.revertedById === "string" ? body.revertedById : undefined;
+            out(`${e.verb} (already_undone): ${e.editId ?? "that edit"} was undone already${by ? `, by ${by}` : ""}. To redo it, undo that undo:`);
+            out(`  bir scenario undo ${target} --edit ${by ?? "<the undo's sedit_ id, from bir scenario edits>"}`);
             return 1;
         }
         case "edit_replaced":