@basein/runner 0.2.10 → 0.2.11

package/dist/config/generate.d.ts

@@ -157,6 +157,18 @@ export interface ProjectRecord {
      * a fleet's absolute paths into pinned-npx entries.
      */
     invocation?: Invocation;
+    /**
+     * `bir scenario editing on|off` (editSteps.md D2, in the BaseIn repository):
+     * whether this project's `bir` MCP server also offers the tools that CHANGE
+     * a calculated scenario — `scenario_check`, `scenario_edit`, `scenario_undo`.
+     * Absent means off. The read tools are offered either way.
+     *
+     * Per project, and off by default, because the `bir` server runs in every
+     * session of every installed project — a fleet included — and a plan must
+     * not change because some agent there decided it should. The `bir scenario`
+     * commands ignore it: a person in a terminal is asked before each one.
+     */
+    editing?: boolean;
 }
 export interface InstalledSidecar {
     version: 1;
@@ -216,4 +228,13 @@ export declare function allocateFreeProjectPort(sidecar: InstalledSidecar, cwd:
 export declare function setProjectRecord(sidecar: InstalledSidecar, cwd: string, patch: Partial<ProjectRecord> & Pick<ProjectRecord, "port">): ProjectRecord;
 /** The bearer token this project's hooks and control server share. */
 export declare function projectToken(sidecar: InstalledSidecar, cwd: string): string | undefined;
+/** Whether `bir scenario editing on` was run for `cwd`; see {@link ProjectRecord.editing}. */
+export declare function editingEnabled(sidecar: InstalledSidecar, cwd: string): boolean;
+/**
+ * Store `bir scenario editing on|off` for `cwd`, under the same normalised key
+ * as the replay switches. `undefined` when the directory has no record: it was
+ * never installed, so there is no `bir` server here to offer anything, and
+ * inventing a record would invent a port the hooks do not use.
+ */
+export declare function setEditing(sidecar: InstalledSidecar, cwd: string, on: boolean): ProjectRecord | undefined;
 //# sourceMappingURL=generate.d.ts.map

package/dist/config/generate.js

@@ -198,4 +198,20 @@ export function setProjectRecord(sidecar, cwd, patch) {
 export function projectToken(sidecar, cwd) {
     return projectRecord(sidecar, cwd)?.token ?? sidecar.token;
 }
+/** Whether `bir scenario editing on` was run for `cwd`; see {@link ProjectRecord.editing}. */
+export function editingEnabled(sidecar, cwd) {
+    return projectRecord(sidecar, cwd)?.editing === true;
+}
+/**
+ * Store `bir scenario editing on|off` for `cwd`, under the same normalised key
+ * as the replay switches. `undefined` when the directory has no record: it was
+ * never installed, so there is no `bir` server here to offer anything, and
+ * inventing a record would invent a port the hooks do not use.
+ */
+export function setEditing(sidecar, cwd, on) {
+    const record = projectRecord(sidecar, cwd);
+    if (!record)
+        return undefined;
+    return setProjectRecord(sidecar, cwd, { port: record.port, editing: on });
+}
 //# sourceMappingURL=generate.js.map

package/docs/calculatedReplay.md

@@ -814,6 +814,23 @@ What actually constrains it:
 If that is not enough for a deployment, the mitigation is a real one and is out of scope here:
 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
+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
+calculated code. The provenance argument still holds: only the owner can edit, over their own token,
+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.
+
 ### 13.2 Replay bypasses permission prompts
 
 This is the sharpest edge in the whole design, and it must not be buried.
@@ -1038,12 +1055,46 @@ 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]
 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 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 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:
+
+- **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.
+- `<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`.
+- `calc --force` answers `409 scenario_has_edits` on a plan with hand edits, unless
+  `--discard-edits` is given.
+- 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
+[calculatedReplayGuide.md](calculatedReplayGuide.md) §9.2.
+
 `--dry` maps to BaseIn's `POST /scenarios/:id/replay`, which evaluates the stored logic against the
 source run's *recorded* outputs — no real tools, no side effects, one Haiku call. Without `--dry`,
 `bir replay` runs the same plan through the same executor against the live proxies. `bir doctor`

package/docs/calculatedReplayGuide.md

@@ -148,7 +148,9 @@ 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`. To change one step instead, without
+recalculating, see §9.2; a plan with steps edited by hand needs `--force --discard-edits` to be
+rebuilt.
 
 ### 3.1 Check the scenario before you trust it
 
@@ -248,17 +250,19 @@ 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 — and three tools that only read a scenario (`scenario_show`,
+  `scenario_edits`, `investigate`; §9.2, not yet released);
 - 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 +469,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). 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` |
 | `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,6 +510,312 @@ 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* the
+> service deploy that adds the `/scenarios/:id/steps/…` routes. The design is `editSteps.md` in the
+> BaseIn repository.
+
+`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>]
+bir scenario calc  <runId> [--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.
+
+#### 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 |
+
+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.
+
+**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.
+
+**1. Read the step.**
+
+```bash
+bir scenario show scn_4a17a126-… --step 4
+```
+
+```
+{
+  "stepIndex": 4,
+  "toolName": "mcp__postgres__execute_sql",
+  "toolInputLogic": "return {\"sql\":\"SELECT * FROM employees.hiring_year_summary ORDER BY hire_year;\"};",
+  "nondeterministic": true,
+  "nondeterministicWhy": "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.
+
+**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    no later steps
+  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?
+- `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_7c1e… (revision 4). Undo: bir scenario undo scn_4a17a126-… --edit sedit_7c1e…
+```
+
+**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? 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 |
+
+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:
+
+```bash
+bir scenario edit 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 14
+           computed  …FROM employees.employees.hiring_year_summary ORDER…
+           recorded  …FROM employees.hiring_year_summary ORDER BY hire_…
+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`.
+
+#### `--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`.
+- 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.
+  `bir scenario check … --unfreeze` asks the same question without saving.
+
+#### The history, and undo
+
+```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
+```
+
+```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…
+```
+
+- `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.
+
+#### 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). 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)
+```
+
+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`).
+
+#### What `bir investigate` says
+
+It names the fix, and it reports edits. Here, after step 4 was saved and before step 3 was:
+
+```
+  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.
+```
+
+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
+```
+
+| 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.
+
+**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 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.*
+
+#### 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` and timers do not exist in the check |
+| 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 |
+| `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 |
+| `edit_replaced` | A recalculation replaced the plan after that edit | Nothing to undo; the edit is history now |
+| `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

package/docs/quickstart.md

@@ -255,7 +255,9 @@ 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 with `bir scenario edit` (not yet released) — see
+[calculatedReplayGuide.md](calculatedReplayGuide.md) §9.2.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "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",