@basein/runner 0.2.11 → 0.2.12

package/docs/calculatedReplay.md

@@ -176,7 +176,7 @@ Three additions to the v1 topology, and nothing else moves:
 |---|---|---|
 | `bir-hooks` control server | extended | Holds the `ScenarioReplayPlan` on `RunState`. Arms it, pins inputs, threads outputs, dispatches direct steps, redeems the ticket |
 | `bir-proxy` | extended | Long-polls for work; executes a `tools/call` on the upstream it already owns |
-| `bir-scenario` | **new**, ~120 lines | A stdio MCP server exposing one tool, `run_scenario`. The delivery channel for direct mode (§6) |
+| `bir-scenario` | **new**, ~120 lines | A stdio MCP server exposing one tool, `run_scenario`. The delivery channel for direct mode (§6). It later gained the scenario tools of §16.5 |
 
 ---
 
@@ -815,7 +815,7 @@ If that is not enough for a deployment, the mitigation is a real one and is out
 evaluate the logic in a `node:vm` context with a frozen, minimal global. Filed as §20 question 3.
 
 **A hand-edited step is the same code, and runs the same way.** Since 2026-09-25 (the service's
-`editSteps.md`, not yet released) the owner — or Claude working for them — can change a step's
+`editSteps.md`; built, not yet released) the owner — or Claude working for them — can change a step's
 logic with `bir scenario edit`. The service checks the change against the recording before it saves
 it, but that check is about *what the code computes*. Once saved, the step arrives in the same
 payload and runs here unattended, with `new Function`, next to the same credentials, exactly like
@@ -823,13 +823,39 @@ calculated code. The provenance argument still holds: only the owner can edit, o
 and anyone else — an admin included — gets `404`. What changes is that *"the model wrote it"* is no
 longer always true.
 
-The service now sandboxes its own evaluation of every logic body: one worker thread with an empty
-environment and a memory cap, a fresh `node:vm` context per evaluation with a time limit and nothing
-but JavaScript's own built-ins, values in and out as JSON text only. It had to: there, one account's
-code runs in the process that holds every account's data and the service's secrets. **The runner
-still does not sandbox.** Here the code runs on the owner's machine, for the owner's account. One
-consequence to know: code that uses `fetch`, `process` or a timer throws in the service's check, so
-it cannot be saved without `--force`; a forced step would run here with all of them.
+The service sandboxes its own evaluation of every logic body (built with the same service change;
+not yet released). It had to: there, one account's code runs next to every account's data and the
+service's secrets. How it is built:
+
+- **A fresh `node:vm` context for each evaluation**, with a time limit (`LOGIC_TIMEOUT_MS`). Only
+  JavaScript's own built-ins are in it, less `ArrayBuffer`, `SharedArrayBuffer`, `DataView`, the
+  typed arrays, `Atomics`, `WebAssembly` and `FinalizationRegistry`; `Symbol.for` and
+  `Symbol.keyFor` are removed too. No `require`, `process`, `fetch`, `Buffer` or timers. Values go
+  in and come out as JSON text only.
+- **That context lives in a separate evaluator process**, not in the service: an empty
+  environment, `--permission` (no files, no child processes), `--disallow-code-generation-from-strings`,
+  `--frozen-intrinsics`, and a heap of `LOGIC_MEMORY_MB`.
+- **A relay worker thread of the service drives that process.** No logic runs in the relay. It
+  kills the evaluator when a body runs too long, and the next job starts a new one; a body that
+  runs out of memory takes down only the evaluator, and is run once more on a fresh one before it
+  is blamed. The relay also replaces the evaluator when its heap stays above half of
+  `LOGIC_MEMORY_MB` after a job, and after 2,000 jobs. A body that overran its time or memory, or
+  took the evaluator down twice, is refused at once, with the same message, for the next 10
+  minutes.
+- **The hand-edit check runs in a check worker thread of its own**, with its own relay and
+  evaluator process, under a sandbox-time budget
+  (`EDIT_CHECK_BUDGET_MS`, 5000 ms by default; past it, *too costly to check*), so a slow check
+  never holds up the service's other requests.
+
+**The runner still does not sandbox.** Here the code runs on the owner's machine, for the owner's
+account, with `new Function`. One consequence to know: **the service's check only judges what a
+body returns for the recording's values.** Code that calls `fetch`, `process` or a timer on that
+path, and does not catch the error, throws in the check, so it cannot be saved without `--force`.
+But a call behind a `typeof` guard (`if (typeof fetch === "function") …`), or on a branch the
+recording's values never take, is never reached in the check; one inside a `try` fails there
+quietly. Such code passes, it is saved like any other change, and here it runs with `fetch`,
+`process` and timers all present. The service's sandbox protects the service; it proves
+nothing about what a body does on the runner. Read every hand edit before it is saved.
 
 ### 13.2 Replay bypasses permission prompts
 
@@ -901,7 +927,7 @@ src/
 │  ├─ source-run.ts              # lazy GET /recordings/runs/:id → recorded outputs by tool (§8.1)
 │  └─ types.ts                   # SerializedScenario, SerializedScenarioStep
 ├─ bin/
-│  ├─ bir-scenario.ts            ← new: the one-tool MCP server (§6.3)
+│  ├─ bir-scenario.ts            ← new: the `bir` MCP server — `run_scenario` (§6.3), later the scenario tools (§16.5)
 │  └─ bir.ts                     # + `--replay`, `bir scenario …`, `bir replay` (§16.5)
 ├─ control/
 │  ├─ server.ts                  # + arm / pin / thread / dispatch / report
@@ -1046,8 +1072,8 @@ and a session with no BaseIn credentials still replays (it just books nothing).
 
 ### 16.5 CLI surface
 
-`bir` gains one flag and one command group. Everything here is a thin client over endpoints that
-already exist server-side, except `bir replay`, which drives §16.2's executor directly.
+`bir` gains one flag and one command group. Everything here is a thin client over service
+endpoints, except `bir replay`, which drives §16.2's executor directly.
 
 ```
 bir install --replay          register the `bir` MCP server; raise the prompt-hook timeout to 15 s
@@ -1056,43 +1082,77 @@ bir uninstall --replay        reverse exactly that, leaving the rest of the inst
 bir scenario list             GET  /recordings/runs               runs, iterations, scenario state
 bir scenario show <runId>     GET  /recordings/runs/:id/scenario  intent, params, steps, logic
 bir scenario show <scnId>     GET  /scenarios/:id                 the same, by scenario id (segments too)
-                                   [--step <n>: one step]
+                                   [--step <n>: one step, with scenarioId and chainRevision first]
 bir scenario calc <runId>     POST /recordings/runs/:id/calculate     [--force to re-derive in place]
                                    [--force --discard-edits: re-derive a plan with hand edits]
+bir scenario calc <scnId> --force
+                              POST /scenarios/:id/recalculate    recalculate in place (segments too)
+                                   [--discard-edits: sends {discardEdits: true}]
 bir scenario replay <scnId> --prompt "…" [--dry]
 
 bir scenario check <id> --step <n>    POST  /scenarios/:id/steps/:n/check        try a change; writes nothing
 bir scenario edit  <id> --step <n>    PATCH /scenarios/:id/steps/:n              the same check, then save
 bir scenario edits <id>               GET   /scenarios/:id/edits                 the history, newest first
-bir scenario undo  <id> [--edit <e>]  POST  /scenarios/:id/edits/:e/revert       put one step back
+bir scenario undo  <id> [--edit <e> | --step <n>]
+                                      POST  /scenarios/:id/edits/:e/revert       take back the newest edit (of step n)
 bir scenario editing on|off|status    (no route) ~/.baseinstrunner/installed.json  which `bir` MCP tools are offered
 
 bir replay --scenario <scnId> --prompt "…" [--dry]     alias; the Tier 2 / debugging path (§12.1)
 ```
 
-The second group, and `show <scnId>`, `--step` and `--discard-edits`, were added on 2026-09-25 by
-the service's `editSteps.md` and are not yet released; their routes are new on the service. They
-are the one place `bir` changes a scenario, so the rules are strict:
+The second group, and `show <scnId>`, `--step`, `calc <scnId>` and `--discard-edits`, were added
+on 2026-09-25 by the service's `editSteps.md`. They are built and tested, and not yet released in
+the form described here (version 0.2.11 on npm has an early form): they need the next
+`@basein/runner` version and a service deploy, because their routes are new on the service. They
+are where `bir` changes a scenario by hand, so the rules are strict:
 
 - **Owner only.** Anyone else, an admin included, gets `404`, never `403`.
 - **A change is saved only if it reproduces the recording and is not a copy**, or on purpose with
-  `--force --note "<why>"`. `check` and `edit` run the same check; `check` never writes.
+  `--force --note "<why>"`. `check` and `edit` run the same check; `check` never writes. When the
+  check had any problem, a forced save is recorded as forced, and `bir investigate` keeps saying so.
 - `<id>` is a `run_` id, resolved to its whole-run scenario with `GET /recordings/runs/:id/scenario`,
-  or a `scn_` id, used as it is. Logic goes in with `--input-logic` / `--output-logic` from a file,
-  or `-` for stdin — never inline, because shell quoting mangles JavaScript. `edit` also takes
-  `--freeze`, `--unfreeze`, `--note` and `--revision <n>` (the `expectedRevision` of the body).
-- `undo` without `--edit` undoes the newest edit that can be undone. Every save and every undo bumps
-  the scenario's `chainRevision`.
+  or a `scn_` id, used as it is. A sub-task scenario has only its `scn_` id; for a run with only
+  sub-task scenarios, `bir` lists their `scn_` ids. Logic goes in with `--input-logic` /
+  `--output-logic` from a file, or `-` for stdin — never inline, because shell quoting mangles
+  JavaScript. `edit` also takes `--freeze`, `--unfreeze`, `--note` and `--revision <n>` (the
+  `expectedRevision` of the body).
+- `show --step <n>` prints the step object with `scenarioId` and `chainRevision` first. The revision
+  is the scenario's, and is what `--revision` takes.
+- **`undo` walks back.** Without `--edit` it takes back the newest edit (never an undo entry) that
+  can be undone; with `--step <n>`, the newest edit of step `n`. Run again, it goes one further
+  back. `--edit` and `--step` cannot be given together. To redo, undo the undo entry by its
+  `sedit_` id; the undo prints that command. The service checks an undo like a save, for the later
+  steps and the final answer (so only when it changes output logic), and answers
+  `422 undo_refused` when it would break them, unless `--force --note "<why>"` is given. Every
+  save and every undo bumps the scenario's `chainRevision`.
+- A save lifts a mark made by hand (`--freeze`, `by_hand`) only with `--unfreeze`; undoing the
+  freeze, or `calc --force --discard-edits`, also removes it. A forced save lifts only a mark the
+  calculation set.
 - `calc --force` answers `409 scenario_has_edits` on a plan with hand edits, unless
-  `--discard-edits` is given.
+  `--discard-edits` is given. `calc <scnId>` without `--force` is a usage error: nothing is sent.
+- Answers `bir` puts in words: `400 nothing_to_change` (the code and mark asked for are the step's
+  already), `413 payload_too_large`, `503 logic_sandbox_unavailable` (nothing was checked, saved or
+  undone), and a check report with `noChange: true` (`check` then says nothing would change, and
+  exits `0`).
 - Exit codes: `0` checked OK, saved or undone; `1` refused, not found, or a service error; `2`
   usage. `--json` prints the service's body unchanged.
 
-The same commands are tools on the `bir` MCP server. `scenario_show`, `scenario_edits` and
-`investigate` only read, and are always offered. `scenario_check`, `scenario_edit` and
-`scenario_undo` are offered only in a project where `bir scenario editing on` was run, because that
-server runs in every session of every installed project. Each tool runs the installed `bir … --json`;
-a refusal comes back as an MCP error result carrying the report. The operator's walk-through is
+The same commands are tools on the `bir` MCP server. `scenario_show` (`target`, `step`),
+`scenario_edits` (`target`) and `investigate` (`id`) only read, and are always offered.
+`scenario_check` (`target`, `step`, `inputLogic`, `outputLogic`, `unfreeze`), `scenario_edit` (the
+same, plus `freeze`, `force`, `note`, `revision`) and `scenario_undo` (`target`, `edit` or `step`,
+`force`, `note`) are offered only in a project where `bir scenario editing on` was run, because that
+server runs in every session of every installed project. Each tool runs this package's own
+`bir … --json`, with logic bodies passed through temporary files; a refusal comes back as an MCP
+error result carrying the report. A call the host cancels, or leaves behind when it exits, has its
+`bir` stopped and its files removed.
+
+**`bir`'s own calls are never recorded** (the service's `editSteps.md` D13; not yet released). The
+`bir` server's tools other than `run_scenario`, and a `Bash` or `PowerShell` command made only of
+`bir` invocations (and a plain `cd`), are host housekeeping, like `ToolSearch`
+([housekeeping.ts](../src/record/housekeeping.ts)). They are never recorded as steps, and never
+count as divergence from a plan. A session that fixes a plan must not become a plan that edits
+plans when it is replayed. The operator's walk-through is
 [calculatedReplayGuide.md](calculatedReplayGuide.md) §9.2.
 
 `--dry` maps to BaseIn's `POST /scenarios/:id/replay`, which evaluates the stored logic against the