@basein/runner 0.2.11 → 0.2.12

package/docs/calculatedReplayGuide.md

@@ -148,9 +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`. To change one step instead, without
-recalculating, see §9.2; a plan with steps edited by hand needs `--force --discard-edits` to be
-rebuilt.
+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
 
@@ -251,8 +256,12 @@ nothing. `bir install --replay` does exactly two things beyond a normal install,
 
 - registers a first-party MCP server under the key **`bir`** in the project's `.mcp.json` (never
   `~/.claude.json`), exposing `mcp__bir__run_scenario` — the channel a fully-wrapped scenario's
-  results come back through — and three tools that only read a scenario (`scenario_show`,
-  `scenario_edits`, `investigate`; §9.2, not yet released);
+  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.
 
@@ -469,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). `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). 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`. 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. Fix the step (§9.2), or add `--discard-edits` |
+| 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 |
@@ -512,9 +521,13 @@ You see your own data. An admin of the service sees everyone's and may pass
 
 ### 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* the
-> service deploy that adds the `/scenarios/:id/steps/…` routes. The design is `editSteps.md` in the
-> BaseIn repository.
+> 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
@@ -530,17 +543,18 @@ bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-l
 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
 ```
 
-A `run_` id finds the run's scenario; a `scn_` id (what `bir investigate` prints) is used as it is.
-A sub-task scenario has only a `scn_` id. `--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` that
-`show` printed). `--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.
+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
 
@@ -551,17 +565,29 @@ Each logic is the *body* of a JavaScript function. It must end in `return { …
 | 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 |
 
-When the service runs it, only JavaScript itself is there: `JSON`, `Math`, `Date`, `RegExp` and the
-like. There is no `require`, `process`, `fetch` or timer, and code that uses one fails the check.
+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 were marked *needs a judgement*. Their code
-wrote `schema + '.' + summary_table`, but the table name already carried its schema. Step 4 is shown
-here; step 3 is the same.
+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.**
 
@@ -569,21 +595,35 @@ here; step 3 is the same.
 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;\"}",
   …
 }
 ```
 
-The stored input logic is a copy of the recorded call. 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.
+`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.**
 
@@ -607,13 +647,14 @@ 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    no later steps
+  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?
+- `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.
 
@@ -628,9 +669,12 @@ bir scenario edit scn_4a17a126-… --step 4 --input-logic step4.js --note "summa
 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_7c1e… (revision 4). Undo: bir scenario undo scn_4a17a126-… --edit sedit_7c1e…
+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.
@@ -642,40 +686,96 @@ parameter values, and with what the earlier steps kept from their recorded answe
 
 | It asks | It refuses when |
 |---|---|
-| Does the code give the recorded call? Spaces inside strings 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 | the call never moves: the code returns the recorded call whatever the request says |
-| Do the later steps still give their calls? | a later step that gave its recorded call before does not any more |
-| Does the final answer still get its values? | it did before, and does not after |
+| 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`.
 
-A refused change says where it differs:
+**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 edit scn_4a17a126-… --step 4 --input-logic wrong.js
+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 14
-           computed  …FROM employees.employees.hiring_year_summary ORDER…
-           recorded  …FROM employees.hiring_year_summary ORDER BY hire_…
+  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 the same way:
-`input  is a copy: it returns the recorded call whatever the parameters say`.
+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: `note_required`.
-- A forced save removes the mark, unless you also pass `--freeze`.
-- It is saved as *forced*, and `bir investigate` keeps saying so, as a `warn`.
+- `--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.
 
@@ -683,33 +783,98 @@ call with a mistake you do not want repeated. Then no correct code can reproduce
 
 - `--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.
+- `--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_7c1e…  2026-09-25 09:12:04Z  step 4  edit    revision 3 → 4  "summary_table already carries its schema"
-             input logic changed; needs a judgement (input_mismatch) → runs by itself
+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 4 is back as it was before sedit_7c1e… (revision 5). Redo: bir scenario undo scn_4a17a126-… --edit sedit_9a02…
+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-…
 ```
 
-- `undo` puts **one step** back as it was before its newest edit: its code and its mark. Without
-  `--edit` it undoes the newest edit that can be undone.
-- The undo is a new line in the history. Undo the undo to redo.
-- Only the newest edit of a step can be undone. For an older one you get `not_latest_edit` and the
-  id of the newer edit: undo that one first.
+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
 
@@ -717,8 +882,9 @@ Step 4 is back as it was before sedit_7c1e… (revision 5). Redo: bir scenario u
   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). Read your change as
-  carefully as you read a calculated plan, and dry-replay it (§3.1).
+- **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:
 
@@ -732,22 +898,31 @@ Not recalculated: steps 3, 4 were edited by hand, and a recalculation rebuilds e
   (the edits stay in `bir scenario edits`, marked replaced)
 ```
 
-The console's *Recalculate* is refused too. 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, and `bir investigate` says
-so. After `--discard-edits` the old edits stay readable, but they cannot be undone
-(`edit_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 names the fix, and it reports edits. Here, after step 4 was saved and before step 3 was:
+It reports every edited step, and names the command that takes it back. After both steps were
+saved, its service findings began like this:
 
 ```
-  1. [warn] Step 3 (mcp__postgres__execute_sql) needs a judgement, so runs hand over in front of it.
-     fix:  Recalculate once (`bir scenario calc run_… --force`) … Or fix it yourself: read it with
-           `bir scenario show scn_… --step 3`, write the input logic to a file, and run
-           `bir scenario edit scn_… --step 3 --input-logic <file>`; the service checks it against the recording.
-  2. [info] Step 4 (mcp__postgres__execute_sql) was edited by hand on 2026-09-25 (revision 4).
-     fix:  To see or undo it: `bir scenario edits scn_…`. A recalculation keeps it unless you pass --discard-edits.
+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.
@@ -769,20 +944,43 @@ bir scenario editing off      # back to the tools that only read
 bir scenario editing status   # what is stored for this project
 ```
 
-| Tool (`mcp__bir__…`) | Offered | Runs |
-|---|---|---|
-| `scenario_show` | always | `bir scenario show` |
-| `scenario_edits` | always | `bir scenario edits` |
-| `investigate` | always | `bir investigate` |
-| `scenario_check` | after `bir scenario editing on` | `bir scenario check` |
-| `scenario_edit` | after `bir scenario editing on` | `bir scenario edit` |
-| `scenario_undo` | after `bir scenario editing on` | `bir scenario undo` |
-
-Why it 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. **Restart the
-Claude Code session after you switch it** — a running session does not see the change.
+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:
 
@@ -794,9 +992,9 @@ 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 was marked because its code added the
-schema twice; the new code builds the query from `summary_table`; the check says it reproduces the
-recording, and the step will run by itself.*
+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
 
@@ -804,14 +1002,22 @@ recording, and the step will run by itself.*
 |---|---|---|
 | `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` and timers do not exist in the check |
+| `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 |
-| `not_latest_edit` | A newer edit of the same step follows the one you named | Undo the newer one first; the answer names it |
+| `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 |
@@ -821,7 +1027,8 @@ recording, and the step will run by itself.*
 ## 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 |
 |---|---|---|
@@ -833,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
 ```