@basein/runner 0.2.11 → 0.2.12

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
@@ -51,8 +51,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 +79,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;
@@ -101,11 +105,10 @@ async function show(args, deps) {
         out(JSON.stringify(reply.body, null, 2));
         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 +119,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(JSON.stringify({ scenarioId: scenario.id ?? null, chainRevision: scenario.chainRevision ?? null, ...step }, null, 2));
     return 0;
 }
 /**
@@ -182,18 +185,27 @@ async function checkOrEdit(args, deps, save) {
         const report = reply.body?.report;
         if (args.json) {
             out(JSON.stringify(reply.body, null, 2));
-            return report?.ok ? 0 : 1;
+            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)
@@ -217,9 +229,11 @@ async function checkOrEdit(args, deps, save) {
         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 +297,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 +344,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 +370,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 +456,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])}`);
     }
@@ -489,17 +551,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 +582,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 +599,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;
+        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 +661,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,7 +677,13 @@ 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) {
@@ -572,9 +694,13 @@ async function calc(args, deps) {
     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 +714,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 ─────────────────────────────────────────────────────
@@ -654,15 +791,36 @@ 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 ? JSON.stringify({ error: code, details: text, ...extra }, null, 2) : 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) {
     if (target.startsWith("scn_"))
@@ -677,12 +835,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 };
 }
 /**
@@ -716,6 +872,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 +888,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 +910,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":

package/dist/control/server.js

@@ -28,7 +28,7 @@ import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { FINGERPRINT_WINDOW_MS, fingerprint, newCallId, parseQualifiedName, qualifyToolName, } from "./correlation.js";
 import { StepIndexAllocator } from "./ordering.js";
 import { contextForToolUse, intentForToolUse, markTranscriptUsage, recentToolResults, settledLastAssistantText, usageSince, } from "./transcript.js";
-import { isHousekeeping } from "../record/housekeeping.js";
+import { isHousekeepingCall } from "../record/housekeeping.js";
 import { redact } from "../record/redact.js";
 import { serializeCapped } from "../record/truncate.js";
 import { StepQueue } from "../record/queue.js";
@@ -732,7 +732,13 @@ export class ControlServer {
         // calculated scenario: its generated reasoning is injected into every
         // matched turn's steering directive, and because it is not an MCP tool it
         // drags the whole scenario out of `direct` mode. Observed in production.
-        if (isHousekeeping(toolName)) {
+        // The runner's own `bir` — its MCP tools and a Bash command that only runs
+        // it — is housekeeping too (D13): a session that fixes a plan must never
+        // become a scenario that edits plans when it is replayed. Returning here
+        // also keeps it out of intent matching, the fragment and the plan.
+        if (isHousekeepingCall(toolName, modelArgs)) {
+            if (toolUseId)
+                (run.housekeepingUses ??= new Set()).add(toolUseId);
             logDetail("tool.pre.skipped", { run: run.runId, tool: toolName, why: "host housekeeping" });
             return {};
         }
@@ -761,7 +767,7 @@ export class ControlServer {
         // Runs before anything else, because two of its four answers end the call.
         let pinned;
         if (run.replay?.plan && !run.replay.retired) {
-            const action = await this.replay.preTool(run.replay, toolName, toolUseId);
+            const action = await this.replay.preTool(run.replay, toolName, toolUseId, modelArgs);
             // A hand-over inside `preTool` (an input logic that threw) must still
             // schedule the fragment, even though this call ends here.
             this.noteHandover(run);
@@ -1266,8 +1272,15 @@ export class ControlServer {
         const toolUseId = payload.tool_use_id ?? "";
         const toolName = payload.tool_name ?? "unknown";
         // `onToolPre` opened no step for these, so closing one here would record a
-        // `tool_response` with no `tool_selected` before it.
-        if (isHousekeeping(toolName))
+        // `tool_response` with no `tool_selected` before it. The id it remembered
+        // decides first; the call itself is judged again only when no step was
+        // opened for it — a post whose pre never reached this server. A step the
+        // pre did open (a plan pinned the model's call to a command that happens
+        // to be `bir`) is closed as usual: its output is what the plan threads.
+        const skippedAtPre = toolUseId !== "" && run.housekeepingUses?.delete(toolUseId) === true;
+        if (skippedAtPre)
+            return {};
+        if (!run.builtIns.has(toolUseId) && isHousekeepingCall(toolName, payload.tool_input))
             return {};
         // Nor for an unarmed `run_scenario`. The plan may have retired since the
         // pre hook, so the test is whether that hook opened a step, not the plan.

package/dist/record/housekeeping.d.ts

@@ -27,8 +27,79 @@
  * possibly be the user's task. `Read`, `Bash` and `Grep` are NOT here: they do
  * real work, they belong in a recording, and reaching for one mid-replay
  * usually *is* the model doing the task another way.
+ *
+ * THE RUNNER'S OWN `bir` IS HOUSEKEEPING TOO (editSteps.md D13), and that is
+ * the one reason this file now looks at a call's input and not only its name.
+ * A session that fixes a plan — `bir investigate`, then `bir scenario edit`, or
+ * the same through the `bir` MCP server's `scenario_*` tools — is exactly the
+ * kind of session that gets recorded and calculated. Recorded, it becomes a
+ * scenario whose steps *edit plans*, and a steered or direct replay of it would
+ * then change a plan unattended, on a prompt nobody meant as "change the plan":
+ * the very thing D2 keeps the editing tools switched off in a fleet to prevent.
+ * And mid-replay, a model that stops to read `bir investigate` has not left the
+ * plan; it is reading about it.
+ *
+ * So two more kinds of call are housekeeping, and both are still narrow:
+ *
+ *   - every tool of the `bir` MCP server **except `run_scenario`**, which is
+ *     the direct plan's delivery vehicle and keeps its own handling (it is
+ *     recorded, tagged `pinnedBy`, while its plan is live);
+ *   - a `Bash` call whose command is **nothing but** `bir` invocations
+ *     ({@link isBirOnlyCommand}), and the same for a `PowerShell` call
+ *     ({@link isBirOnlyPowerShell}) — Claude Code on Windows reaches for its
+ *     PowerShell tool as readily as for Bash, and a `bir scenario edit` run
+ *     there is the same act. `npm test && bir investigate` is not: the
+ *     `npm test` half is real work, and hiding it from the recording would be
+ *     hiding the task. When in doubt the answer is "not housekeeping", because
+ *     a `bir` call recorded by mistake costs a noisy step, while real work
+ *     skipped by mistake is a plan with a hole in it.
  */
 /** Host tools that are never recorded as steps and never count as divergence. */
 export declare const HOUSEKEEPING_TOOLS: ReadonlySet<string>;
+/** By name alone — the host's own bookkeeping tools. See {@link isHousekeepingCall} for the full rule. */
 export declare function isHousekeeping(toolName: string): boolean;
+/**
+ * The direct plan's delivery vehicle. Must equal `DIRECT_TOOL_NAME` in the
+ * replay controller (a test holds them together); spelled out here because
+ * the controller imports this file.
+ */
+export declare const RUN_SCENARIO_TOOL = "mcp__bir__run_scenario";
+/**
+ * Whether one call is host housekeeping: never recorded as a step, never a
+ * divergence from a plan. `toolInput` is what the hook saw (`tool_input`); only
+ * a `Bash` call's `command` is read from it.
+ */
+export declare function isHousekeepingCall(toolName: string, toolInput?: unknown): boolean;
+/**
+ * {@link isBirOnlyCommand} for PowerShell, whose rules differ enough that the
+ * Bash reader would get it wrong: a backslash is a path separator, not an
+ * escape; the escape is the backtick; `$(…)` runs code even inside double
+ * quotes; `&` at the start of a part is the call operator. Deliberately
+ * narrower than the Bash reader: parts split on `;`, `&&`, `||` and newlines
+ * (outside quotes); each is `bir …` (as {@link isBirInvocation} reads it, also
+ * after a leading `&`) or a plain `cd`/`Set-Location`/`Push-Location <dir>`.
+ * A pipe, a backtick, `$(` or `@(` anywhere, a brace or parenthesis outside
+ * quotes, an `@` starting a word, or a quote left open makes the answer false — for the same
+ * reason as there: when unsure, record it.
+ */
+export declare function isBirOnlyPowerShell(command: string): boolean;
+/**
+ * True when a shell command runs `bir` and nothing else: split on `&&`, `||`,
+ * `;`, `|`, `&` and newlines (outside quotes), every part is a `bir`
+ * invocation or a plain `cd <dir>`, and at least one is `bir`.
+ *
+ * A `bir` invocation is `bir` / `bir.cmd` / a path ending in `bir`, `bir.cmd`,
+ * `bir.js` or `bir.ps1`; `npx [-y] [-p @basein/runner…] [@basein/runner…] bir …`;
+ * or `node <path>/bir.js …` — each optionally after `NAME=value` assignments,
+ * which only set `bir`'s own environment. A heredoc is read as the data it is,
+ * because `bir scenario check … --input-logic - <<'EOF'` is the natural way to
+ * hand `bir` a logic body, and its lines are JavaScript, not commands.
+ *
+ * Anything that could run other code while looking like `bir` makes the answer
+ * false: a command substitution (`$(…)`, backticks) outside single quotes and
+ * quoted heredocs, and a subshell, group or process substitution (`(`, `{`).
+ * So does a quote or heredoc left open — a parse this side is not sure of is
+ * not one to hide a step on.
+ */
+export declare function isBirOnlyCommand(command: string): boolean;
 //# sourceMappingURL=housekeeping.d.ts.map