@basein/runner 0.2.10 → 0.2.12

package/docs/calculatedReplayGuide.md

@@ -148,7 +148,14 @@ Calculation is a background job. Poll `show` until `state` leaves `calculating`:
 | `failed` | see the `error` field | fix and recalculate with `--force` |
 
 `409 scenario_exists` means this run already has one. Re-derive it in place — keeping the id and its
-replay history — with `bir scenario calc run_… --force`.
+replay history — with `bir scenario calc run_… --force`. A `run_` id reaches only the run's
+whole-run scenario. From the next version (not yet released), `bir scenario calc scn_… --force`
+does the same by the scenario's own id, a sub-task scenario included; it is the only way to
+recalculate a sub-task scenario from `bir`.
+
+To change one step instead, without recalculating, see §9.2. A plan with steps edited by hand is
+not rebuilt unless you add `--discard-edits`, which replaces those edits. They stay in
+`bir scenario edits`, marked replaced, and can no longer be undone.
 
 ### 3.1 Check the scenario before you trust it
 
@@ -248,17 +255,23 @@ nothing. `bir install --replay` does exactly two things beyond a normal install,
 `bir uninstall --replay` takes the scenario server out again and leaves everything else as it is:
 
 - registers a first-party MCP server under the key **`bir`** in the project's `.mcp.json` (never
-  `~/.claude.json`), exposing one tool, `mcp__bir__run_scenario` — the channel a fully-wrapped
-  scenario's results come back through;
+  `~/.claude.json`), exposing `mcp__bir__run_scenario` — the channel a fully-wrapped scenario's
+  results come back through. It also offers three tools that only read a scenario
+  (`scenario_show`, `scenario_edits`, `investigate`) and, only after `bir scenario editing on`,
+  three for changing one (`scenario_check` tries a change, `scenario_edit` saves it,
+  `scenario_undo` takes it back). §9.2 lists them with their arguments; the editing it describes
+  is built but not yet released. From the next version, a call to any of them except
+  `run_scenario` is never recorded;
 - pre-approves that server in `.claude/settings.local.json` (`enabledMcpjsonServers`), because a
   "No" to Claude Code's approval dialog leaves a direct replay with nowhere to deliver its results.
 
 The `UserPromptSubmit` hook's 15 s timeout, which the match round trip needs, is not one of them:
 every install writes it, replay or not.
 
-The `bir` tool is visible to the model in every session in this project. That is a real cost — one
-more tool in the list, a little context per turn — and it is why replay is a separate flag rather
-than part of `bir install`.
+The `bir` tools are visible to the model in every session in this project. That is a real cost — a
+few more tools in the list, a little context per turn — and it is why replay is a separate flag
+rather than part of `bir install`. The tools that change a scenario are not among them until you
+run `bir scenario editing on` (§9.2).
 
 Confirm:
 
@@ -465,8 +478,8 @@ first prompt that states the task plainly.
 | `run_scenario` returns "no scenario is armed" | The model called it on a turn with no plan | Harmless. It happens when the model remembers the tool from an earlier turn |
 | `recorder.send_failed … error="HTTP 409 … invalid_ticket"` | The execution report's ticket was already redeemed, or belongs to another scenario | Harmless if the body says `duplicate: true`. Otherwise a rollover raced `SessionEnd`; the server books once |
 | `savedUsd` looks impossible | Pricing drift between the runner's table and the server's | Compare `PRICING_VERSION` on both sides. Design §11.3 documents a known live drift between two existing copies |
-| The hand-over note says a step "did not run: its input needs a judgement" | The service marked the step non-deterministic when it calculated the plan: the generated logic could not compute its input from the prompt or from earlier outputs, so the recorded value was a copy (the service's plan-services design, D8 kind 3 — it lives in the BaseIn repository, not this one) | Nothing on the runner. The agent makes that choice and finishes the task; a model step for such judgements is planned (W3.1). The journal's `plan.armed` line lists it under `stops=` |
-| A parked step ran again after an hour, or a plan was recalculated by itself | The service's grace period (D8): a parked step is served with `stop: null` once an hour for a day and a success clears its count; if it keeps failing, or its tool is gone, the next repeat of the prompt is recorded in full and the plan is calculated again from it | Nothing: that is the repair. `bir investigate` says which it is — a step still being retried, a parked step whose repair is due, or a plan being calculated again. To repair now by hand: `bir scenario calc <runId> --force` |
+| The hand-over note says a step "did not run: its input needs a judgement" | The service marked the step non-deterministic when it calculated the plan: the generated logic could not compute its input from the prompt or from earlier outputs, so the recorded value was a copy (the service's plan-services design, D8 kind 3 — it lives in the BaseIn repository, not this one). `nondeterministicWhy: by_hand` means someone marked it with `bir scenario edit --freeze` | If the code only has a slip, fix the step yourself: `bir scenario show scn_… --step <n>`, write the input logic to a file, then `bir scenario edit scn_… --step <n> --input-logic <file>` — the service checks it against the recording before it saves it (§9.2, not yet released). Of the edits, only `--unfreeze` lifts a mark made by hand (`by_hand`); a code edit, even a forced one, leaves it in place. A real judgement — a choice with no fixed rule — cannot be written as code: the agent makes that choice and finishes the task; a model step for it is planned (W3.1). The journal's `plan.armed` line lists the step under `stops=` |
+| A parked step ran again after an hour, or a plan was recalculated by itself | The service's grace period (D8): a parked step is served with `stop: null` once an hour for a day and a success clears its count; if it keeps failing, or its tool is gone, the next repeat of the prompt is recorded in full and the plan is calculated again from it | Nothing: that is the repair. `bir investigate` says which it is — a step still being retried, a parked step whose repair is due, or a plan being calculated again. To repair now by hand: `bir scenario calc <runId> --force` for a whole-run plan; from the next version, `bir scenario calc <scnId> --force` works for any plan, a sub-task one included. A plan with steps edited by hand is not repaired by itself: the parked step stays parked, and `bir investigate` says the repair was skipped. Then fix the step (§9.2); or take the edits back with `bir scenario undo`, once per edit, and it is repaired as usual; or recalculate now and drop the edits: `bir scenario calc <scnId> --force --discard-edits` |
 | `sessionCostUsd` grows every prompt in a session | The per-run usage watermark is missing or not taken | Design §11.4. Reports without a mark must carry `measured: false` |
 | Everything works, nothing is saved | A replayed turn is deliberately not recorded (design §12) | Correct. The matched run stays canonical and its `iterations` is bumped |
 | `bir doctor`: the SessionStart hook points at a Node that is gone | The hook names Node by absolute path. That Node was uninstalled, moved, or was a version manager's per-shell copy; the hook then fails on every session, no recorder is started, and runs record Tier 2 | `bir setup` here again — it rewrites the hook to the Node that runs it |
@@ -506,12 +519,516 @@ fix*. The three questions it answers:
 You see your own data. An admin of the service sees everyone's and may pass
 `--user` to `executions`. `--json` on any form prints the raw merge.
 
+### 9.2 Fix a step — `bir scenario check`, `edit`, `edits`, `undo`
+
+> Built 2026-09-25, **not yet released**. It needs the next `@basein/runner` version *and* a
+> service deploy: the `/scenarios/:id/steps/…` routes and the sandbox the service runs step code
+> in. Version 0.2.11 on npm has an early form of these commands. It is not what this section
+> describes. The design is `editSteps.md` in the BaseIn repository.
+>
+> The hiring-year outputs below were printed by the real `bir`, against the real service, on the
+> real recording. Only the ids are shortened, with `…`.
+
+`bir investigate` says *what* is wrong. This section is how you fix it. A calculated step is code:
+its **input logic** says what to send to the tool, and its **output logic** says what to keep from
+the answer. When that code is wrong, you do not have to recalculate and hope any more. You change
+the step, and the service checks your change against the recording before it saves it.
+
+**A change is saved only if it reproduces the recording and is not a copy — or on purpose, with
+`--force --note "why"`.**
+
+```
+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
+```
+
+A `run_` id finds the run's whole-run scenario. A `scn_` id (what `bir investigate` prints) is used
+as it is. A sub-task scenario has only a `scn_` id. When a run has only sub-task scenarios, `bir`
+lists their `scn_` ids instead of guessing. `--step` is the `stepIndex` that `show` prints; it
+starts at 0. `--revision <n>` saves only if the plan is still at revision `n`: the `chainRevision`
+at the top of `show --step`. `--json` on `check`, `edit`, `edits` or `undo` prints the service's
+answer unchanged. Exit codes: `0` checked OK, saved or undone · `1` refused, not found, or a
+service error · `2` a wrong command line.
+
+#### What the code is
+
+Each logic is the *body* of a JavaScript function. It must end in `return { … }`.
+
+| Logic | Reads | Returns |
+|---|---|---|
+| input logic (`toolInputLogic`) | `parameters` — this request's values · `respParams` — what earlier steps kept · `intent` | the tool's input, as an object |
+| output logic (`toolOutputLogic`) | `toolOutput` — the tool's answer, as text · and the same three | the values to keep for later steps, as an object |
+
+The service runs your code in a sandbox (design §13.1). In the sandbox only JavaScript itself
+exists: `JSON`, `Math`, `Date`, `RegExp` and the like. There is no `require`, `process`, `fetch`,
+`Buffer` or timer. A few built-ins are taken away too: `ArrayBuffer`, the typed arrays such as
+`Uint8Array`, `Atomics`, `WebAssembly`, `FinalizationRegistry` and `Symbol.for`. Code that uses
+one of them with the recording's values throws in the check.
+
+**But the check only judges what your code returns for the recording's values.** A `fetch` behind
+a `typeof` guard (`if (typeof fetch === "function") …`), or on a branch the recording's values
+never take, is never reached in the check. A `fetch` inside a `try` fails in the check, but the
+`catch` hides the error. Either way the code passes. On your machine the runner runs the same
+code with `new Function`, where `fetch` and `process` do exist. So read every change before it is
+saved — yours and Claude's.
+
+**Only a step's code and its mark can be changed.** Not the parameters, not their sample values, not
+the logic that builds the final answer. Only tool steps: a sub-task call row belongs to the service.
+
+#### The fix, step by step
+
+On 2026-09-25 two SQL steps of the hiring-year scenario, 3 and 4, were marked *needs a judgement*.
+Step 4 is shown here; step 3 was fixed the same way. The calculation's code for step 4 wrote
+`schema + '.' + summary_table`, but the table name already carried its schema, so the code did not
+give the recorded call. The calculation then put a copy of the recorded call in its place, and
+marked the step.
+
+**1. Read the step.**
+
+```bash
+bir scenario show scn_4a17a126-… --step 4
+```
+
+You should see this (shortened: each `…` line stands for lines left out):
+
+```
+{
+  "scenarioId": "scn_4a17a126-…",
+  "chainRevision": 1,
+  "stepIndex": 4,
+  "kind": "tool",
+  "toolName": "mcp__postgres__execute_sql",
+  "toolInputLogic": "return {\"sql\":\"SELECT * FROM employees.hiring_year_summary ORDER BY hire_year;\"};",
+  …
+  "nondeterministic": true,
+  "nondeterministicWhy": "input_mismatch",
+  "editedAt": null,
+  "editForced": false,
+  "stop": {
+    "kind": "nondeterministic",
+    "why": "input_mismatch"
+  },
+  "sampleInput": "{\"sql\":\"SELECT * FROM employees.hiring_year_summary ORDER BY hire_year;\"}",
+  …
+}
+```
+
+`scenarioId` and `chainRevision` come first. They belong to the whole scenario, and
+`chainRevision` is the number `edit --revision` takes. The rest is the step. Its input logic is
+that copy: compare it with `sampleInput`. A copy does the old job, on the old table, whatever the
+new request says. That is why the step is marked (`nondeterministic: true`), and why runs hand over
+to the agent in front of it.
+
+**2. Write the new code to a file.**
+
+```bash
+cat step4.js
+```
+
+```
+return { sql: "SELECT * FROM " + parameters.summary_table + " ORDER BY hire_year;" };
+```
+
+Code always goes in from a file, or from stdin with `-`. Never on the command line: the shell's
+quoting breaks JavaScript.
+
+**3. Check it.** Nothing is saved.
+
+```bash
+bir scenario check scn_4a17a126-… --step 4 --input-logic step4.js
+```
+
+```
+Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
+  input    reproduces the recorded call
+  later    not affected: only the input logic changed
+  mark     needs a judgement (input_mismatch) → runs by itself
+Nothing saved. To save: bir scenario edit scn_4a17a126-… --step 4 --input-logic step4.js
+```
+
+- `input` — does the code give the recorded call?
+- `later` — do the steps after it still give theirs? Here only the input logic changed. Nothing a
+  later step reads has changed, so no later step was judged.
+- `mark` — what happens to the *needs a judgement* mark. `→ runs by itself` means the mark goes
+  when you save, and runs stop handing over in front of this step.
+
+**4. Save it.** `edit` runs the same check, and saves only what the check approved. Add a `--note`
+that says why; the history keeps it.
+
+```bash
+bir scenario edit scn_4a17a126-… --step 4 --input-logic step4.js --note "summary_table already carries its schema"
+```
+
+```
+Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
+  input    reproduces the recorded call
+  mark     needs a judgement (input_mismatch) → runs by itself
+Saved as sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda (revision 2). Undo: bir scenario undo scn_4a17a126-… --edit sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda
+```
+
+`edit` prints fewer lines than `check`. It always prints `input`, and the other lines only when
+something moved or broke. Step 3 was then saved the same way, as revision 3.
+
+**5. Try it without real tools.** A dry replay (§3.1) runs the new code over the recorded outputs:
+`bir scenario replay scn_4a17a126-… --prompt "…" --dry`. The next real prompt uses the new code.
+There is nothing to restart.
+
+#### How the check decides
+
+The service runs your code the way the recorded run would have run it: with the recording's
+parameter values, and with what the earlier steps kept from their recorded answers.
+
+| It asks | It refuses when |
+|---|---|
+| Does the code give the recorded call? Extra spaces inside strings, and the order of keys, do not count | it gives something else (`differs`), or it crashes (`throws`) |
+| Is it a copy? It changes one parameter, or one earlier output, at a time — only the ones the code reads | the call never moves: the code returns the recorded call whatever the request says |
+| Do the later steps still give their calls? Asked only when the **output** logic changed, and only of later steps that are not marked and can be checked | a later step that gave its recorded call before does not any more |
+| Does the final answer still get its values? Asked only when the **output** logic changed | it did before, and does not after |
+| Can the mark go? | you asked to unmark the step (`--unfreeze`), and its input does not reproduce |
+
+A recorded input of `{}` is never a copy. A recorded input that is plain text, not an object, is
+`not_checked`.
+
+**The check is kept small.** On the service it runs in a worker thread of its own, never in the
+thread that answers requests. By default it may use 5 seconds of sandbox time
+(`EDIT_CHECK_BUDGET_MS`, 5000 ms). Past that it stops, and the change is refused as *too costly to
+check*. The reason `bir` prints is the service's own sentence:
+
+```
+too costly to check: the check used up its 5000 ms of sandbox time (EDIT_CHECK_BUDGET_MS) before it finished.
+```
+
+One run of your code may take 1 second (`LOGIC_TIMEOUT_MS`) and 64 MB of memory
+(`LOGIC_MEMORY_MB`), by default. Code that ran out of time or memory, or stopped the sandbox twice,
+is held back for 10 minutes: every run of that same code fails at once, with the same message.
+
+A refused change says where it differs. Here `wrong.js` adds the schema a second time:
+
+```bash
+bir scenario check scn_4a17a126-… --step 4 --input-logic wrong.js
+```
+
+```
+Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
+  input    differs from the recorded call at character 32
+           computed  … FROM employees.employees.hiring_year_summary ORDER BY h…
+           recorded  … FROM employees.hiring_year_summary ORDER BY hire_year;"…
+  later    not affected: only the input logic changed
+  mark     needs a judgement (input_mismatch) → stays marked
+Nothing saved, and `bir scenario edit` would refuse it: the change does not reproduce the recording.
+  Fix the code and check again. If the recording itself was wrong, edit can save it on purpose: add --force --note "why".
+```
+
+`bir scenario edit` with the same file refuses it, and saves nothing:
+
+```
+Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
+  input    differs from the recorded call at character 32
+           computed  … FROM employees.employees.hiring_year_summary ORDER BY h…
+           recorded  … FROM employees.hiring_year_summary ORDER BY hire_year;"…
+Not saved: the change does not reproduce the recording.
+  Fix the code and try again, or save it on purpose: add --force --note "why".
+```
+
+A pasted value is refused as a copy. Here `pasted.js` returns the recorded SQL as fixed text:
+
+```bash
+bir scenario check scn_4a17a126-… --step 4 --input-logic pasted.js
+```
+
+```
+Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
+  input    is a copy: it returns the recorded call whatever the parameters say
+  later    not affected: only the input logic changed
+  mark     needs a judgement (input_mismatch) → stays marked
+Nothing saved, and `bir scenario edit` would refuse it: the input logic is a copy: it returns the recorded call whatever the parameters and earlier outputs say.
+  Fix the code and check again. If the recording itself was wrong, edit can save it on purpose: add --force --note "why".
+```
+
+Any other refusal prints the service's own reason, one line for each problem.
+
+Code and a mark the step already has change nothing. `check` then says
+`Nothing would change: the step already has this code and mark.` (exit 0), and `edit` refuses:
+
+```bash
+bir scenario edit scn_4a17a126-… --step 4 --input-logic step4.js
+```
+
+```
+Nothing to change: the step already has this code and this mark.
+```
+
+#### `--force --note`: save it on purpose
+
+**Use `--force` only when the recording itself was wrong** — for example, the recorded run sent a
+call with a mistake you do not want repeated. Then no correct code can reproduce it.
+
+- `--force` needs a `--note` that says why (500 characters at most). Without one, `bir` stops
+  before it sends anything (`note_required`).
+- **When the check found any problem, a forced save is recorded as forced.** `bir` says so under
+  the `Saved as …` line and repeats what the check said. `bir investigate` keeps reporting the step
+  as a `warn`.
+- A forced save removes a mark **the calculation** set, unless you also pass `--freeze`. A mark
+  made **by hand** (`--freeze`) stays. A save lifts it only with `--unfreeze`.
+- A step after a sub-task call row can only be saved with `--force`: the check cannot rebuild the
+  outputs that step reads.
+
+#### Mark or unmark a step by hand
+
+- `--freeze` marks the step *needs a judgement* (`nondeterministicWhy: by_hand`). Runs then hand
+  over to the agent in front of it. No check blocks this: a mark only makes replay more careful.
+- `--unfreeze` asks to remove a mark. The check decides: the step's input must reproduce. With
+  `--force --note "why"` the mark goes anyway, and the edit is recorded as forced.
+  `bir scenario check … --unfreeze` asks the same question without saving.
+- **A mark made by hand is lifted only when someone asks.** A code edit does not lift it, even one
+  that reproduces the recording, and neither does a forced save. What lifts it: `--unfreeze`,
+  undoing the edit that made it, or `bir scenario calc … --force --discard-edits`.
+
+#### The history, and undo
+
+After both steps were saved:
+
+```bash
+bir scenario edits scn_4a17a126-…
+```
+
+```
+sedit_02cb1210-1938-4902-9395-5a82b321276d  2026-09-25 11:10:59Z  step 3  edit    revision 2 → 3  "use the settings, not the recorded names"
+    input logic changed; needs a judgement (input_mismatch) → runs by itself
+sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda  2026-09-25 11:10:59Z  step 4  edit    revision 1 → 2  "summary_table already carries its schema"
+    input logic changed; needs a judgement (input_mismatch) → runs by itself
+```
+
+The newest entry is first. Each id is printed in full, because it is what `undo --edit` takes.
+
+Take back the newest edit:
+
+```bash
+bir scenario undo scn_4a17a126-…
+```
+
+```
+Step 3 (mcp__postgres__execute_sql) — checked against run_67afb010-…
+  input    back as it was before that edit
+  mark     runs by itself → needs a judgement (input_mismatch)
+Step 3 is back as it was before sedit_02cb1210-1938-4902-9395-5a82b321276d (revision 4). Redo: bir scenario undo scn_4a17a126-… --edit sedit_1bcba735-a526-4a1c-a890-261addf2d82b
+  One further back: bir scenario undo scn_4a17a126-…
+```
+
+The same command again goes one further back:
+
+```bash
+bir scenario undo scn_4a17a126-…
+```
+
+```
+Step 4 (mcp__postgres__execute_sql) — checked against run_67afb010-…
+  input    back as it was before that edit
+  mark     runs by itself → needs a judgement (input_mismatch)
+Step 4 is back as it was before sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda (revision 5). Redo: bir scenario undo scn_4a17a126-… --edit sedit_8d3da392-1d96-4b2e-8c5d-34f8ab668b53
+  One further back: bir scenario undo scn_4a17a126-…
+```
+
+Now the history shows the two undos, and both edits as undone:
+
+```bash
+bir scenario edits scn_4a17a126-…
+```
+
+```
+sedit_8d3da392-1d96-4b2e-8c5d-34f8ab668b53  2026-09-25 11:11:00Z  step 4  revert  revision 4 → 5
+    undoes sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda; input logic changed; runs by itself → needs a judgement (input_mismatch)
+sedit_1bcba735-a526-4a1c-a890-261addf2d82b  2026-09-25 11:11:00Z  step 3  revert  revision 3 → 4
+    undoes sedit_02cb1210-1938-4902-9395-5a82b321276d; input logic changed; runs by itself → needs a judgement (input_mismatch)
+sedit_02cb1210-1938-4902-9395-5a82b321276d  2026-09-25 11:10:59Z  step 3  edit    revision 2 → 3  "use the settings, not the recorded names"
+    input logic changed; needs a judgement (input_mismatch) → runs by itself; undone 2026-09-25 11:11:00Z
+sedit_633dba0d-bbbe-4517-ac29-74cc85a3abda  2026-09-25 11:10:59Z  step 4  edit    revision 1 → 2  "summary_table already carries its schema"
+    input logic changed; needs a judgement (input_mismatch) → runs by itself; undone 2026-09-25 11:11:00Z
+```
+
+Step 4 is the calculation's code again: `bir scenario show scn_4a17a126-… --step 4` now prints
+`"chainRevision": 5`, `"editedAt": null` and the mark `"nondeterministicWhy": "input_mismatch"`.
+
+How undo works:
+
+- **Undo walks back.** `bir scenario undo <id>` takes back the newest edit that can be undone. Its
+  step goes back as it was before that edit: its code and its mark. Run it again to go one further
+  back. Keep going, and each step gets back to the calculation's code, unless an undo is refused
+  (below).
+- **`--step <n>` limits it to one step.** `bir scenario undo scn_… --step 4` takes back step 4's
+  newest edit, and nothing else.
+- `--edit <sedit_id>` takes back that one entry.
+- An undo is a new line in the history (`revert`). **To redo, undo the undo** by its id. The undo
+  prints that command after `Redo:`.
+- **An undo is checked too:** for the later steps and for the final answer, like a save (so only
+  when the undo changes the step's output logic). The step itself is not judged: it goes back
+  exactly as it was. If the undo would break a later step or the answer, it is refused
+  (`undo_refused`). `bir` prints `Not undone:` with the reason, then
+  `To undo it anyway, on purpose: add --force --note "why".` An undo forced past a refusal is
+  recorded as forced.
+- Once every hand edit of a plan is taken back, the service repairs and rebuilds it as usual again.
+  An undo forced past a refusal is the exception: it leaves its step counted as edited and
+  forced, so `bir investigate` keeps warning about it.
+
+#### What a save changes
+
+- **The next prompt uses the new code.** The service hands out the plan fresh on every prompt. A
+  turn that is already running keeps the old plan until it ends.
+- **The revision goes up by one, and the step's failure count is cleared.** Reports from turns that
+  started before the change do not count against the new code. An undo does the same.
+- **A saved step runs unattended, exactly like calculated code** (§5.1), on this machine, with
+  `new Function`. The service's sandbox does not protect this machine. Read your change as carefully
+  as you read a calculated plan, and dry-replay it (§3.1).
+- **Edits are protected.** A recalculation rebuilds every step from the recording, and would throw
+  your fix away. So `calc --force` refuses:
+
+```bash
+bir scenario calc run_67afb010-… --force
+```
+
+```
+Not recalculated: steps 3, 4 were edited by hand, and a recalculation rebuilds every step.
+  To recalculate anyway and discard the edits: bir scenario calc run_67afb010-… --force --discard-edits
+  (the edits stay in `bir scenario edits`, marked replaced)
+```
+
+A `run_` id reaches only the run's whole-run scenario. `bir scenario calc <scnId> --force`
+recalculates any scenario in place, by its own id, a sub-task scenario included. Add
+`--discard-edits` when it has hand edits. A `scn_` id without `--force` is refused before anything
+is sent: a scenario that exists can only be recalculated.
+
+The console's *Recalculate* button (on a sub-task's scenario) is refused too while a plan has hand
+edits; the console does not discard them. The service's own rebuilds — the repair of a parked step
+(§9) and the adoption of a sub-task — skip a plan with hand edits. `bir investigate` says that the
+service does not rebuild the plan on its own, and warns when it skipped a repair
+(`repair_skipped_edits`). After `--discard-edits` the old edits stay readable, but they cannot be
+undone (`edit_replaced`).
+
+#### What `bir investigate` says
+
+It reports every edited step, and names the command that takes it back. After both steps were
+saved, its service findings began like this:
+
+```
+Service findings
+  1. [info] Step 3 (mcp__postgres__execute_sql) was edited by hand on 2026-09-25; the chain is at revision 3.
+     why:  Its code or its mark was changed by hand rather than by the calculation, and the change was checked against the recording before it was saved. The service does not rebuild a plan with hand edits on its own.
+     fix:  To see it: `bir scenario edits scn_4a17a126-…`; to take it back: `bir scenario undo scn_4a17a126-… --step 3`. A recalculation will not replace it unless you pass --discard-edits.
+  2. [info] Step 4 (mcp__postgres__execute_sql) was edited by hand on 2026-09-25; the chain is at revision 3.
+     why:  Its code or its mark was changed by hand rather than by the calculation, and the change was checked against the recording before it was saved. The service does not rebuild a plan with hand edits on its own.
+     fix:  To see it: `bir scenario edits scn_4a17a126-…`; to take it back: `bir scenario undo scn_4a17a126-… --step 4`. A recalculation will not replace it unless you pass --discard-edits.
+```
+
+A forced edit is a `warn`, not an `info`. So is a repair the service skipped because of hand edits.
+
+#### Let Claude do it
+
+Claude Code can do all of this for you, in two ways. Both use the same service routes and the same
+check.
+
+1. **In its terminal.** Claude runs `bir scenario …` like any other command. You see each command,
+   and Claude Code asks you before it runs one, unless you allowed it. This works in every project.
+2. **As tools on the `bir` MCP server** — the server `bir setup` or `bir install --replay` adds
+   (§5.2). This is smoother for the model. **Reading is always offered. Changing is off until you
+   turn it on, per project:**
+
+```bash
+bir scenario editing on       # this project's `bir` server also offers the tools that change a scenario
+bir scenario editing off      # back to the tools that only read
+bir scenario editing status   # what is stored for this project
+```
+
+The tools, as the `bir` server defines them. **Bold** arguments are required.
+
+| Tool (`mcp__bir__…`) | Offered | Arguments | Runs |
+|---|---|---|---|
+| `run_scenario` | always | none | the plan armed for this turn (§6.1) |
+| `scenario_show` | always | **`target`**, `step` | `bir scenario show` |
+| `scenario_edits` | always | **`target`** | `bir scenario edits` |
+| `investigate` | always | `id` — a `run_`, `scn_` or `sexec_` id; without it, the newest turn here | `bir investigate` |
+| `scenario_check` | after `bir scenario editing on` | **`target`**, **`step`**, `inputLogic`, `outputLogic`, `unfreeze` | `bir scenario check` |
+| `scenario_edit` | after `bir scenario editing on` | **`target`**, **`step`**, `inputLogic`, `outputLogic`, `freeze`, `unfreeze`, `force`, `note`, `revision` | `bir scenario edit` |
+| `scenario_undo` | after `bir scenario editing on` | **`target`**, `edit` or `step` (not both), `force`, `note` | `bir scenario undo` |
+
+- `target` is a `scn_` id, or the `run_` id of a whole-run scenario. `step` is the `stepIndex`.
+- `inputLogic` and `outputLogic` are the code itself, as text. The server writes them to temporary
+  files for `bir`, and removes the files afterwards.
+- `revision` is the `chainRevision` at the top of `scenario_show` with `step`.
+- `force` needs `note`, as on the command line.
+- Each tool runs this package's own `bir` with `--json`. A refusal comes back as an error result
+  that carries the check's report, so the model can read why.
+- When the session ends, or you press Esc during a call, that call's `bir` is stopped and its
+  temporary files are removed. A request the service had already received may still finish there;
+  `bir scenario edits` shows it.
+
+Why changing is off by default: the `bir` server runs in every session of every project it is
+installed in, a fleet included. A plan must not change because some agent there decided to change
+it. The switch is kept in `~/.baseinstrunner/installed.json`, next to the replay switches. It only
+decides which tools the `bir` server offers; the `bir scenario` commands work everywhere. The server
+reads the switch when Claude Code lists its tools, and again on every call. **Restart the Claude
+Code session after you switch it** — a running session does not see the change.
+
+**`bir`'s own calls are never recorded.** A session that fixes a plan must not become a plan that
+edits plans when it is replayed. So these calls are never recorded as steps, and never count as the
+model leaving a plan: the `bir` server's tools other than `run_scenario`, and a `Bash` or
+`PowerShell` command made only of `bir` commands (a plain `cd` may come with them).
+`npm test && bir investigate` is still recorded: the `npm test` half is real work. So is writing
+the code file, which is an ordinary step. Under `BIR_VERBOSE=1` a skipped call shows as
+`tool.pre.skipped … why="host housekeeping"`.
+
+**Do this.** In the Claude Code session, in the project folder, paste:
+
+```
+Run `bir investigate` in this folder. If a step needs a judgement or its code
+is wrong, read it with `bir scenario show`, write the corrected code to a file,
+and test it with `bir scenario check`. Show me the check and explain it in plain
+words. Do not save anything until I say yes. Then save it with
+`bir scenario edit` and a --note that says why. Never use --force.
+```
+
+For the hiring-year case, Claude's report would be: *step 4's code is a copy of the recorded query,
+so it was marked; the new code builds the query from `summary_table`; the check says it reproduces
+the recording, and the step will run by itself.*
+
+#### When it does not work
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `input differs from the recorded call at character N` | The code gives a different call from the recorded one | Read the `computed` and `recorded` lines, fix the code, check again |
+| `input is a copy` | The code returns the recorded call whatever the request says — usually a pasted value | Build the call from `parameters.…` or `respParams.…` |
+| `input throws` | The code crashed; the message is shown | Fix it. `require`, `process`, `fetch`, `Buffer`, timers, `ArrayBuffer`, the typed arrays and `Symbol.for` do not exist in the check |
+| `… did not finish in N ms`, `… ran out of memory (the limit is N MB)`, or `… stopped the logic sandbox before it finished` | The code went past the sandbox's time or memory limit (`LOGIC_TIMEOUT_MS`, `LOGIC_MEMORY_MB` on the service), or stopped the sandbox twice. That same code is then refused at once for 10 minutes | Fix the loop or the size. Changed code is new code, and is checked again |
+| A `later` step no longer reproduces | The change broke a step after it — usually output logic that stopped keeping a value a later step reads | Keep every key the later steps read |
+| `too costly to check` | The check used up its 5 seconds of sandbox time (`EDIT_CHECK_BUDGET_MS`). Usually code that reads or keeps a great many values, so the check has to run it very many times | Make the code cheaper to run, then check again |
+| `Nothing to change: the step already has this code and this mark.` | The code and the mark you gave are what the step already has (`nothing_to_change`) | Nothing to do. `check` says `Nothing would change` for the same case |
+| `not_a_tool_step` | The index is a sub-task call row, not a tool step | Call rows cannot be edited; the service writes them |
+| `note_required` | `--force` without `--note` | Add `--note "why"` |
+| `revision_changed` | The plan changed since you read it: another edit, or a recalculation | `show` it again, check again, save again |
+| `not_ready` or `scenario_calculating` | The scenario is not `ready`, or a recalculation is running | Wait for it to finish |
+| `undo_refused` | The undo would stop a later step from giving its recorded call, or leave the final answer without its values | Fix that later step first. Or undo it on purpose: `--force --note "why"` |
+| `not_latest_edit` | The step has changed since the edit you named: a newer entry changed it | `bir` prints two commands: undo the newer one first, then yours |
+| `already_undone` | That edit was undone already | To redo it, undo the undo. `bir` prints the command |
+| `edit_replaced` | A recalculation replaced the plan after that edit | Nothing to undo; the edit is history now |
+| `logic_sandbox_unavailable` | The service could not run step code just now (HTTP 503). Nothing was checked, saved or undone | Try again in a minute |
+| `invalid_input` | The service found the request invalid; `bir` prints its details. For example, a logic body longer than 20 000 characters, or a note longer than 500 | Shorten it |
+| `payload_too_large` | The whole request is larger than the service accepts (HTTP 413, over 256 kB) | A logic body may be at most 20 000 characters, and a note 500 |
+| `rate_limited` | More checks, edits and undos in a minute than the service allows (`SCENARIO_EDITS_PER_MINUTE`, 30 by default) | Wait a minute |
+| `not found` for a scenario you can see | It is not yours. **Only the owner can change a scenario** — an admin gets `not found` too | Ask the owner |
+| The `scenario_check`, `scenario_edit` and `scenario_undo` tools are missing | `bir scenario editing on` was not run in this project, or the session started before it | Run it here, then restart the session |
+
 ---
 
 ## 10. What is built
 
 All of it. Phases R0–R7 of [calculatedReplay.md](calculatedReplay.md) §17 are implemented and
-tested; everything this guide describes is code you can run.
+tested; everything this guide describes is code you can run. §9.2 is built and tested too, but not
+yet released.
 
 | Phase | What landed | Where |
 |---|---|---|
@@ -523,9 +1040,10 @@ tested; everything this guide describes is code you can run.
 | **R5** | The `bir` MCP server, `/scenario/run`, `--replay` | [bin/bir-scenario.ts](../src/bin/bir-scenario.ts), [bin/bir.ts](../src/bin/bir.ts) |
 | **R6** | Divergence, source-run fallback, `bir replay` | `diverge()` in [controller.ts](../src/replay/controller.ts), [source-run.ts](../src/replay/source-run.ts) |
 | **R7** | Usage watermark, reporting, ticket, doctor | [control/transcript.ts](../src/control/transcript.ts), [remote-recorder.ts](../src/record/remote-recorder.ts) |
+| **§9.2** *(not yet released)* | `bir scenario show/check/edit/edits/undo/calc/editing`, the `bir` server's scenario tools, `bir` calls never recorded (`editSteps.md` D13) | [bin/scenario-edit.ts](../src/bin/scenario-edit.ts), [bin/bir-scenario.ts](../src/bin/bir-scenario.ts), [record/housekeeping.ts](../src/record/housekeeping.ts); tests: [scenario-edit.test.ts](../test/scenario-edit.test.ts), [bir-scenario.test.ts](../test/bir-scenario.test.ts), [housekeeping.test.ts](../test/housekeeping.test.ts), [replay-server.test.ts](../test/replay-server.test.ts) |
 
 ```bash
-npm test                                                # ~400 tests, incl. test/replay.test.ts and test/replay-server.test.ts
+npm test                                                # ~450 tests, incl. test/replay.test.ts and test/replay-server.test.ts
 npm run build && npm run pretest && npm run test:smoke  # the smoke test needs the test build too
 ```
 

package/docs/quickstart.md

@@ -168,7 +168,7 @@ its prompt, its tool calls and its final answer.
 |---|---|
 | `~/.baseinstrunner/config.json` | the service address; `BIR_AUTH_URL` in the environment overrides it, and `bir setup` warns when the two differ |
 | `~/.baseinstrunner/credentials.json` | the cached session, bound to the service that issued it |
-| `~/.baseinstrunner/installed.json` | the original text of every file it rewrote, and each project's port, token and replay switches |
+| `~/.baseinstrunner/installed.json` | the original text of every file it rewrote, and each project's port, token and replay switches, and whether Claude's `bir` tools may change scenarios there (`bir scenario editing on`) |
 | `~/.baseinstrunner/logs/<key>.log` | the recorder's audit log, one file per project |
 | `~/.baseinstrunner/node/` | a private Node, only if the machine had no usable one; not on PATH |
 | `~/.baseinstrunner/npm/` | the runner package |
@@ -255,7 +255,49 @@ answer. Then:
 
 For a turn that did not do what you expected — a scenario that did not run, a
 saving that was not made — `bir investigate` reads the journal and the service
-and says why.
+and says why. When it names a step whose code is wrong, you can fix that step
+yourself: see the next section.
+
+---
+
+## Fixing a step (not yet released)
+
+Built 2026-09-25. It needs the next `@basein/runner` version and a service
+deploy, so it does not work yet. The full guide, with real output, is
+[calculatedReplayGuide.md](calculatedReplayGuide.md) §9.2.
+
+A calculated step is code. When `bir investigate` says a step's code is wrong,
+you can change that step. The service checks your change against the
+recording. It saves it only if it gives the same call the recording made, and
+is not a pasted copy of that call. Only the owner of a scenario can change it.
+
+1. **Read the step.** `bir scenario show scn_… --step 4` (the `scn_` id and the
+   step number are the ones `bir investigate` printed).
+2. **Write the new code to a file,** for example `step4.js`. Never on the
+   command line: the shell breaks JavaScript.
+3. **Check it.** `bir scenario check scn_… --step 4 --input-logic step4.js`.
+   Nothing is saved. You should see `input    reproduces the recorded call`.
+4. **Save it.** `bir scenario edit scn_… --step 4 --input-logic step4.js --note "why"`.
+   You should see a line that starts `Saved as sedit_…`.
+5. **Changed your mind?** `bir scenario undo scn_…` takes back the newest
+   change. Run it again to go one further back. With `--step 4` it takes
+   back only step 4's changes, newest first. An undo that would break a later
+   step or the final answer is refused (`undo_refused`).
+
+If the check refuses your change, it says why. For example, the `input` line
+says where your call differs from the recorded one. Fix the code and check
+again. `--force --note "why"` saves it anyway, but use it only when the
+recording itself was wrong.
+
+The saved code runs on your machine without asking you, like the code the
+calculation wrote. The check only tests what it sends for the recording's
+values. So read the code before it is saved, yours or Claude's.
+
+Claude can do this for you. Ask it in the session; it runs the same commands,
+and Claude Code asks you before each one, unless you allowed it. Or run
+`bir scenario editing on` in the project folder and restart Claude Code: the
+`bir` server then also offers tools that change a scenario. These `bir` calls
+are never recorded as part of your task.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "A recording MCP proxy: sits between any MCP client and its MCP servers, executes each call on the client's behalf, and records the run as a reusable BaseIn scenario.",
   "type": "module",
   "license": "MIT",