@basein/runner 0.2.10 → 0.2.12

package/dist/bin/scenario-edit.js

@@ -0,0 +1,950 @@
+/**
+ * scenario-edit — read, check, change and undo one step of a calculated
+ * scenario (editSteps.md in the BaseIn repository; docs/calculatedReplayGuide.md §9.2).
+ *
+ *   bir scenario show  <runId|scnId> [--step <n>]
+ *   bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze]
+ *   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> | --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
+ * decided on the service, against the recording, by the calculation's own
+ * check (D3) — and `check` and `edit` are the same function there (D11). A
+ * runner-side pre-check would be a second opinion that can disagree with the
+ * one that counts, so this module reads logic from files, sends it, and says
+ * in words what the service answered. `--json` prints the answer unchanged,
+ * which is what the `bir` MCP server hands the model.
+ *
+ * Logic never comes from the command line itself. A JavaScript body is full
+ * of quotes, braces and `$`, and every shell mangles a different subset of
+ * them; a file, or stdin with `-`, arrives byte for byte.
+ *
+ * Everything the commands touch is injected ({@link ScenarioEditDeps}), as in
+ * `investigate.ts`, so all of it is tested in-process against a fake service.
+ * The exception is `editing`, which writes the install sidecar — tests point
+ * `BIR_HOME` at a temporary directory for that.
+ */
+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";
+/** The `bir scenario` words this module answers; `list` and `replay` stay in bir.ts. */
+export const SCENARIO_EDIT_SUBCOMMANDS = new Set([
+    "show",
+    "check",
+    "edit",
+    "edits",
+    "undo",
+    "calc",
+    "editing",
+]);
+/** The `bir` MCP server's tools that only read: always offered (D2). */
+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"];
+const USAGE = {
+    show: "usage: bir scenario show <runId|scnId> [--step <n>]",
+    check: "usage: bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze] [--json]",
+    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> | --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) {
+    switch (args.positionals[0] ?? "") {
+        case "show":
+            return show(args, deps);
+        case "check":
+            return checkOrEdit(args, deps, false);
+        case "edit":
+            return checkOrEdit(args, deps, true);
+        case "edits":
+            return listEdits(args, deps);
+        case "undo":
+            return undo(args, deps);
+        case "calc":
+            return calc(args, deps);
+        case "editing":
+            return editing(args, deps);
+        default:
+            deps.out("usage: bir scenario <list|show|calc|check|edit|edits|undo|editing|replay> …");
+            return 2;
+    }
+}
+/**
+ * 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,
+ * 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;
+    const target = args.positionals[1];
+    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`);
+    if ("error" in reply || reply.status !== 200) {
+        return explain(reply, args, deps, {
+            verb: "Could not read the scenario",
+            target,
+            notFound: byScenario
+                ? `No such scenario, or it is not yours: ${target}.`
+                : "No scenario for that run yet — `bir scenario calc <runId>` first.",
+        });
+    }
+    if (args.step === undefined) {
+        out(JSON.stringify(reply.body, null, 2));
+        return 0;
+    }
+    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;
+    }
+    const step = scenario.steps.find((s) => s.stepIndex === args.step);
+    if (!step) {
+        const indexes = scenario.steps.map((s) => s.stepIndex).filter((n) => typeof n === "number");
+        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({ scenarioId: scenario.id ?? null, chainRevision: scenario.chainRevision ?? null, ...step }, null, 2));
+    return 0;
+}
+/**
+ * `check` and `edit` share everything up to the request, on purpose: the
+ * service runs the same function for both (D11), so the same flags must build
+ * the same body. `check` asks and writes nothing; `edit` writes only what the
+ * check approves — or, with `--force` and a note, what it did not.
+ */
+async function checkOrEdit(args, deps, save) {
+    const sub = save ? "edit" : "check";
+    const { out } = deps;
+    const target = args.positionals[1];
+    if (!target)
+        return usageError(deps, sub);
+    if (args.step === undefined) {
+        return usageError(deps, sub, "Which step? Give --step <n>, the stepIndex `bir scenario show` prints.");
+    }
+    if (!save && (args.freeze || args.force)) {
+        return usageError(deps, sub, "`check` never saves, so --freeze and --force belong to `bir scenario edit`.");
+    }
+    if (args.freeze && args.unfreeze) {
+        return usageError(deps, sub, "--freeze and --unfreeze ask for opposite things; give one of them.");
+    }
+    const note = args.note?.trim() ? args.note : undefined;
+    if (save && args.force && !note) {
+        // Before any request: a forced save is the one kind the check did not
+        // approve, and the note is the only record of why somebody wanted it.
+        return usageError(deps, sub, '--force needs --note "why" (note_required): a change saved on purpose says why, and the history keeps it.');
+    }
+    if (!args.inputLogic && !args.outputLogic && !args.unfreeze && !(save && args.freeze)) {
+        return usageError(deps, sub, save
+            ? "Nothing to change: give --input-logic <file>, --output-logic <file>, --freeze or --unfreeze."
+            : "Nothing to check: give --input-logic <file>, --output-logic <file> or --unfreeze.");
+    }
+    if (args.inputLogic === "-" && args.outputLogic === "-") {
+        return usageError(deps, sub, "Only one of --input-logic and --output-logic can read stdin (-); put the other in a file.");
+    }
+    // Read the files before any request, so a typo in a path costs nothing.
+    const body = {};
+    const sources = [
+        [args.inputLogic, "input logic", "toolInputLogic"],
+        [args.outputLogic, "output logic", "toolOutputLogic"],
+    ];
+    for (const [spec, what, key] of sources) {
+        if (spec === undefined)
+            continue;
+        const read = await readLogic(spec, what, deps);
+        if ("problem" in read)
+            return usageError(deps, sub, read.problem);
+        body[key] = read.text;
+    }
+    const resolved = await resolveTarget(target, args, deps);
+    if ("code" in resolved)
+        return resolved.code;
+    const path = `/scenarios/${seg(resolved.id)}/steps/${args.step}`;
+    const explained = { target, step: args.step };
+    if (!save) {
+        if (args.unfreeze)
+            body.unfreeze = true;
+        const reply = await deps.service("POST", `${path}/check`, body);
+        if ("error" in reply || reply.status !== 200)
+            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 || 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, "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)
+        body.freeze = true;
+    else if (args.unfreeze)
+        body.freeze = false;
+    if (args.force)
+        body.force = true;
+    if (note)
+        body.note = note;
+    if (args.revision !== undefined)
+        body.expectedRevision = args.revision;
+    const reply = await deps.service("PATCH", path, body);
+    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 saved", ...explained });
+    }
+    if (args.json) {
+        out(JSON.stringify(reply.body, null, 2));
+        return refused ? 1 : 0;
+    }
+    if (answer?.report)
+        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;
+    const revision = answer?.chainRevision ?? edit?.chainRevisionAfter;
+    out(`Saved as ${edit?.id ?? "(no id)"} (revision ${revision ?? "?"}).` +
+        (edit?.id ? ` Undo: bir scenario undo ${target} --edit ${edit.id}` : ""));
+    if (edit?.forced) {
+        out("  Saved on purpose (--force): `bir investigate` keeps reporting it as forced.");
+        for (const p of answer?.report?.problems ?? [])
+            out(`  The check said: ${sentence(p)}`);
+    }
+    return 0;
+}
+/** What `check` printed, turned into the `edit` that would save it. */
+function editCommand(target, args) {
+    const parts = ["bir scenario edit", target, "--step", String(args.step)];
+    if (args.inputLogic)
+        parts.push("--input-logic", quoteArg(args.inputLogic));
+    if (args.outputLogic)
+        parts.push("--output-logic", quoteArg(args.outputLogic));
+    if (args.unfreeze)
+        parts.push("--unfreeze");
+    return parts.join(" ");
+}
+function quoteArg(value) {
+    return /\s/.test(value) ? `"${value}"` : value;
+}
+/**
+ * A logic file's text. UTF-8, with a byte-order mark dropped — and UTF-16 with
+ * its mark decoded, because that is what `"…" > step.js` writes in Windows
+ * PowerShell 5.1, and a service answering "SyntaxError" to a file that looks
+ * fine in every editor is a riddle nobody should have to solve.
+ */
+export function decodeLogic(bytes) {
+    if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe)
+        return bytes.subarray(2).toString("utf16le");
+    const text = bytes.toString("utf8");
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+async function readLogic(spec, what, deps) {
+    const from = spec === "-" ? "stdin" : spec;
+    let text;
+    try {
+        text = decodeLogic(spec === "-" ? await deps.readStdin() : deps.readFile(spec));
+    }
+    catch (err) {
+        return { problem: `Could not read the ${what} from ${from}: ${errText(err)}` };
+    }
+    // Trailing whitespace is a file's last newline, not code; the history reads
+    // better without it, and `check` and `edit` trim it the same way.
+    text = text.replace(/\s+$/, "");
+    if (!text)
+        return { problem: `The ${what} from ${from} is empty.` };
+    return { text };
+}
+// ── rendering the report ──────────────────────────────────────────────────────
+/** Characters of context shown on either side of the first difference. */
+const CONTEXT = 40;
+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, 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 (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) {
+            out(`           computed  ${around(d.computed, d.at)}`);
+            out(`           recorded  ${around(d.recorded, d.at)}`);
+        }
+    }
+    else if (i.after === "throws") {
+        out(label("input", `throws: ${i.error ?? "(no message)"}${unchanged}`));
+    }
+    else {
+        out(label("input", `${inputPhrase(i.after, r.verifiable)}${unchanged}`));
+    }
+    if (r.output?.changed) {
+        const o = r.output;
+        out(label("output", o.status === "runs"
+            ? `runs; keeps ${o.emittedKeys?.length ? o.emittedKeys.join(", ") : "nothing"}`
+            : o.status === "throws"
+                ? `throws: ${o.error ?? "(no message)"}`
+                : o.status === "not_object"
+                    ? "does not return an object"
+                    : "unchanged"));
+    }
+    const later = r.later ?? [];
+    const regressed = later.filter((l) => l.regressed);
+    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);
+        out(label("later", still.length === 0
+            ? "no later step reproduced before, so none can break"
+            : still.length === 1
+                ? `step ${still[0]} still reproduces`
+                : `steps ${still.join(", ")} still reproduce`));
+    }
+    else {
+        for (const l of regressed) {
+            out(label("later", `step ${l.stepIndex} (${l.toolName ?? "?"}) reproduced before; now it ${laterPhrase(l.after)}`));
+        }
+    }
+    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;
+        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) {
+    switch (status) {
+        case "reproduces":
+            return "reproduces the recorded call";
+        case "copy":
+            return "is a copy: it returns the recorded call whatever the parameters say";
+        case "not_checked":
+            return verifiable
+                ? "not checked: the recorded call is plain text, not an object"
+                : "not checked: the step comes after a sub-task call, whose outputs the check cannot rebuild";
+        case "differs":
+            return "differs from the recorded call";
+        case "throws":
+            return "throws";
+        default:
+            return String(status);
+    }
+}
+function laterPhrase(status) {
+    switch (status) {
+        case "differs":
+            return "differs from its recorded call";
+        case "throws":
+            return "throws";
+        case "copy":
+            return "is a copy of its recorded call";
+        case "not_checked":
+            return "cannot be checked";
+        default:
+            return status;
+    }
+}
+/** A report's `MarkState` or a history entry's `StepState`, in the words the report uses. */
+const markWord = (m) => (m.marked ?? m.nondeterministic)
+    ? `needs a judgement (${m.why ?? m.nondeterministicWhy ?? "?"})`
+    : "runs by itself";
+/**
+ * The report's `firstDifference`, or the same computed here from `computed` and
+ * `recorded` when the service sent only those: whitespace-squashed JSON text,
+ * as the service compares it.
+ */
+function firstDifference(computed, recorded) {
+    if (computed === undefined || recorded === undefined)
+        return undefined;
+    const squash = (v) => (JSON.stringify(v) ?? String(v)).replace(/\s+/g, " ");
+    const a = squash(computed);
+    const b = squash(recorded);
+    let at = 0;
+    while (at < a.length && at < b.length && a[at] === b[at])
+        at += 1;
+    return { at, computed: a, recorded: b };
+}
+/**
+ * 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 function around(text, at) {
+    if (text.length <= 2 * CONTEXT + 2)
+        return text;
+    const from = Math.max(0, Math.min(at, text.length) - CONTEXT);
+    const to = Math.min(text.length, from + 2 * CONTEXT);
+    return `${from > 0 ? "…" : ""}${text.slice(from, to)}${to < text.length ? "…" : ""}`;
+}
+/** One problem sentence, continuing a line that already opened with "Not saved:". */
+function sentence(problem) {
+    const text = problem.trim();
+    const lowered = /^[A-Z][a-z]/.test(text) ? text[0].toLowerCase() + text.slice(1) : text;
+    return /[.!?]$/.test(lowered) ? lowered : `${lowered}.`;
+}
+/**
+ * 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])}`);
+    }
+    else {
+        out(`${opening}:`);
+        for (const p of list)
+            out(`  - ${sentence(p)}`);
+    }
+    out(hint);
+}
+// ── edits / undo ──────────────────────────────────────────────────────────────
+async function fetchEdits(scenarioId, deps) {
+    const reply = await deps.service("GET", `/scenarios/${seg(scenarioId)}/edits`);
+    if ("error" in reply || reply.status !== 200)
+        return { reply };
+    const edits = reply.body?.edits;
+    return { edits: Array.isArray(edits) ? edits : [] };
+}
+async function listEdits(args, deps) {
+    const { out } = deps;
+    const target = args.positionals[1];
+    if (!target)
+        return usageError(deps, "edits");
+    const resolved = await resolveTarget(target, args, deps);
+    if ("code" in resolved)
+        return resolved.code;
+    const reply = await 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));
+        return 0;
+    }
+    const edits = reply.body?.edits ?? [];
+    if (edits.length === 0) {
+        out(`No hand edits of ${target}.`);
+        return 0;
+    }
+    // Ids are printed whole: they are what `undo --edit` takes. The detail line
+    // is indented rather than aligned under the date, which a 42-character id
+    // would push past most terminals' width.
+    for (const e of edits) {
+        const note = e.note ? `  "${e.note.replace(/\s+/g, " ")}"` : "";
+        out(`${e.id}  ${when(e.createdAt)}  step ${e.stepIndex}  ${String(e.kind).padEnd(7)} revision ${e.chainRevisionBefore} → ${e.chainRevisionAfter}${note}`);
+        out(`    ${editSummary(e)}`);
+    }
+    return 0;
+}
+/** The second line of an `edits` entry: what the edit changed, and what became of it. */
+function editSummary(e) {
+    const parts = [];
+    if (e.kind === "revert" && e.revertsEditId)
+        parts.push(`undoes ${e.revertsEditId}`);
+    const b = e.before;
+    const a = e.after;
+    if (b && a) {
+        if ((b.toolInputLogic ?? null) !== (a.toolInputLogic ?? null))
+            parts.push("input logic changed");
+        if ((b.toolOutputLogic ?? null) !== (a.toolOutputLogic ?? null))
+            parts.push("output logic changed");
+        if (Boolean(b.nondeterministic) !== Boolean(a.nondeterministic) || (b.nondeterministicWhy ?? null) !== (a.nondeterministicWhy ?? null)) {
+            parts.push(`${markWord(b)} → ${markWord(a)}`);
+        }
+    }
+    if (e.forced)
+        parts.push("saved on purpose (--force)");
+    if (e.revertedAt)
+        parts.push(`undone ${when(e.revertedAt)}`);
+    if (e.replacedAt)
+        parts.push(`replaced by a recalculation ${when(e.replacedAt)}`);
+    return parts.length ? parts.join("; ") : "no change to the code or the mark";
+}
+/**
+ * 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, 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.kind !== "revert" &&
+        !e.revertedAt &&
+        !e.replacedAt &&
+        (step === undefined || e.stepIndex === step));
+}
+async function undo(args, deps) {
+    const { out } = deps;
+    const target = args.positionals[1];
+    if (!target)
+        return usageError(deps, "undo");
+    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;
+    let editId = args.edit;
+    if (!editId) {
+        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, args.step);
+        if (!pick) {
+            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 (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);
+    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 refused ? 1 : 0;
+    }
+    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 ──────────────────────────────────────────────────────────────────────
+/**
+ * `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;
+    const target = args.positionals[1];
+    if (!target)
+        return usageError(deps, "calc");
+    if (args.discardEdits && !args.force) {
+        return usageError(deps, "calc", "--discard-edits only means something with --force (a recalculation in place).");
+    }
+    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));
+        return reply.status === 202 ? 0 : 1;
+    }
+    const { status, body } = reply;
+    const code = body?.error;
+    if (status === 202) {
+        const b = body;
+        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) : [];
+        const which = list.length === 0 ? "some steps were" : list.length === 1 ? `step ${list[0]} was` : `steps ${list.join(", ")} were`;
+        out(`Not recalculated: ${which} edited by hand, and a recalculation rebuilds every step.`);
+        out(`  To recalculate anyway and discard the edits: bir scenario calc ${target} --force --discard-edits`);
+        out("  (the edits stay in `bir scenario edits`, marked replaced)");
+        return 1;
+    }
+    if (status === 409 && code === "calculation_in_flight") {
+        out("Another calculation of yours is running, and the service calculates one at a time. Try again when it is ready.");
+        return 1;
+    }
+    // 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 && 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}${code ? `, ${code}` : ""}): ${JSON.stringify(body)}`);
+    return 1;
+}
+// ── editing on|off|status ─────────────────────────────────────────────────────
+/**
+ * Which tools this project's `bir` MCP server offers (D2). Stored in the
+ * project's record in `installed.json`, next to the replay switches, so a
+ * server Claude Code starts with its own environment reads the same answer.
+ * The server reads it when the session lists its tools, hence the restart.
+ */
+function editing(args, deps) {
+    const { out, cwd } = deps;
+    const word = args.positionals[1];
+    if (word !== "on" && word !== "off" && word !== "status")
+        return usageError(deps, "editing");
+    const sidecar = readSidecar();
+    if (word !== "status") {
+        if (!setEditing(sidecar, cwd, word === "on")) {
+            out("This directory has not been installed — run `bir setup` (or `bir install --replay`) here first.");
+            return 1;
+        }
+        writeSidecar(sidecar);
+    }
+    describeEditing(out, sidecar, cwd);
+    if (word !== "status")
+        out("Restart Claude Code in this project: a running session does not see the change.");
+    return 0;
+}
+function describeEditing(out, sidecar, cwd) {
+    const on = editingEnabled(sidecar, cwd);
+    out(`Scenario editing for ${cwd}: ${on ? "on" : "off"}`);
+    if (!projectRecord(sidecar, cwd)) {
+        out("  (this directory has not been installed — `bir setup` here first)");
+        return;
+    }
+    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)
+        out(`                        and  ${EDIT_TOOLS.join(", ")}  (they change a scenario)`);
+    else
+        out(`  \`bir scenario editing on\` adds ${EDIT_TOOLS.join(", ")}  (they change a scenario)`);
+    out("  The `bir scenario` commands work either way: this switch decides only the MCP tools.");
+}
+function hasScenarioServer(sidecar, cwd) {
+    const here = normalizePath(cwd);
+    return Object.entries(sidecar.servers ?? {}).some(([key, record]) => key.endsWith(`::${SCENARIO_SERVER_KEY}`) && normalizePath(record.cwd) === here);
+}
+// ── shared ────────────────────────────────────────────────────────────────────
+const seg = (id) => encodeURIComponent(id);
+const when = (iso) => iso ? iso.replace("T", " ").replace(/\.\d+Z$/, "Z") : "—";
+function usageError(deps, sub, why) {
+    if (why)
+        deps.out(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 (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 `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_"))
+        return { id: target };
+    const reply = await deps.service("GET", `/recordings/runs/${seg(target)}/scenario`);
+    if ("error" in reply || reply.status !== 200) {
+        return {
+            code: explain(reply, args, deps, {
+                verb: "Could not find the scenario",
+                target,
+                notFound: `No scenario for ${target}: it is not a run of yours, or nothing was calculated from it yet (\`bir scenario calc ${target}\`).`,
+            }),
+        };
+    }
+    const served = reply.body;
+    const id = served?.scenario?.id;
+    if (typeof id !== "string")
+        return { code: noWholeRunScenario(target, served?.segments, args, deps) };
+    return { id };
+}
+/**
+ * Every answer that is not the one asked for, in words — with the service's
+ * error code in brackets, because that is what the guide's troubleshooting
+ * table is keyed on. `--json` gets the service's body unchanged.
+ */
+function explain(reply, args, deps, e) {
+    const { out } = deps;
+    if ("error" in reply) {
+        if (args.json)
+            out(JSON.stringify({ error: "service_unreachable", details: reply.error }, null, 2));
+        else
+            out(`Could not reach the service: ${reply.error}`);
+        return 1;
+    }
+    if (args.json) {
+        out(JSON.stringify(reply.body ?? null, null, 2));
+        return 1;
+    }
+    const body = (reply.body && typeof reply.body === "object" ? reply.body : {});
+    const code = typeof body.error === "string" ? body.error : "";
+    const target = e.target ?? "<id>";
+    const stepFlag = e.step !== undefined ? ` --step ${e.step}` : "";
+    if (reply.status === 404) {
+        out(e.notFound ??
+            `${e.verb} (not_found): no such scenario, step or edit — or it is not yours. Only a scenario's owner can see or change it.`);
+        return 1;
+    }
+    if (reply.status === 401) {
+        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);
+            out(`${e.verb} (invalid_input): the service found the request invalid${details ? ` — ${details}` : ""}.`);
+            return 1;
+        }
+        case "not_a_tool_step":
+            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":
+            // 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".`);
+            return 1;
+        case "not_ready":
+        case "scenario_calculating":
+            out(`${e.verb} (${code}): the scenario is not ready, or a recalculation of it is running. Wait for it to finish (\`bir scenario show ${target}\`), then try again.`);
+            return 1;
+        case "revision_changed": {
+            const now = typeof body.chainRevision === "number" ? ` — it is at revision ${body.chainRevision} now` : "";
+            out(`${e.verb} (revision_changed): the plan changed since it was read${now}. Show it again (\`bir scenario show ${target}${stepFlag}\`), check again, then save again.`);
+            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): 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":
+            out(`${e.verb} (edit_replaced): a recalculation replaced the plan after that edit. It stays in \`bir scenario edits\`, but there is nothing left to undo.`);
+            return 1;
+        case "rate_limited": {
+            const ms = typeof body.retryAfterMs === "number" ? body.retryAfterMs : undefined;
+            out(`${e.verb} (rate_limited): too many checks, edits and undos in a minute. Try again${ms !== undefined ? ` in ${Math.ceil(ms / 1000)} s` : " in a minute"}.`);
+            return 1;
+        }
+        default: {
+            const details = brief(body.details);
+            out(`${e.verb} (HTTP ${reply.status}${code ? `, ${code}` : ""})${details ? `: ${details}` : ""}.`);
+            return 1;
+        }
+    }
+}
+/** A service's `details`, short enough for one line. */
+function brief(details) {
+    if (details === undefined || details === null)
+        return "";
+    const text = typeof details === "string" ? details : JSON.stringify(details);
+    return text.length > 300 ? `${text.slice(0, 300)}…` : text;
+}
+//# sourceMappingURL=scenario-edit.js.map