@basein/runner 0.3.18 → 0.3.20

package/dist/replay/plan.d.ts

@@ -469,6 +469,12 @@ export declare class ScenarioReplayPlan {
     stopStep(): SerializedScenarioStep | undefined;
     /** The entry the plan stops in front of, with the frame that owns it. */
     stopEntry(): FlatEntry | undefined;
+    /**
+     * The flat position of the chain's decision stop (the service's
+     * segmentsbreakdown.md SB-18), or -1 when it has none. The steps from there
+     * on are the half the recording took, whatever stops the plan first.
+     */
+    decisionIndex(): number;
     /** Every entry in order — for the report, and for the owning scenario ids. */
     allEntries(): readonly FlatEntry[];
     /** The entry awaiting execution, or undefined when the plan is done. */
@@ -539,11 +545,12 @@ export declare class ScenarioReplayPlan {
         text: string | null;
     } | undefined;
     /**
-     * The tool names of the steps from flat position `from` to the end, each
-     * that runs only under a test marked so — for a hand-over note's "remaining
-     * planned steps", which must not read as steps this request needs.
+     * The tool names of the steps from flat position `from` to the end (or to
+     * `until`, not included), each that runs only under a test marked so — for a
+     * hand-over note's "remaining planned steps", which must not read as steps
+     * this request needs.
      */
-    remainingFrom(from: number): string[];
+    remainingFrom(from: number, until?: number): string[];
     /** The steps the plan's own cursor has left out so far, in order (AC5). */
     leftOut(): readonly LeftOut[];
     /** Whether any planned step runs only under a test. */

package/dist/replay/plan.js

@@ -700,6 +700,14 @@ export class ScenarioReplayPlan {
     stopEntry() {
         return this.stopsEarly() ? this.entries[this.stopAt] : undefined;
     }
+    /**
+     * The flat position of the chain's decision stop (the service's
+     * segmentsbreakdown.md SB-18), or -1 when it has none. The steps from there
+     * on are the half the recording took, whatever stops the plan first.
+     */
+    decisionIndex() {
+        return this.entries.findIndex((e) => e.step.stop?.kind === "decision");
+    }
     /** Every entry in order — for the report, and for the owning scenario ids. */
     allEntries() {
         return this.entries;
@@ -853,12 +861,13 @@ export class ScenarioReplayPlan {
         return undefined;
     }
     /**
-     * The tool names of the steps from flat position `from` to the end, each
-     * that runs only under a test marked so — for a hand-over note's "remaining
-     * planned steps", which must not read as steps this request needs.
+     * The tool names of the steps from flat position `from` to the end (or to
+     * `until`, not included), each that runs only under a test marked so — for a
+     * hand-over note's "remaining planned steps", which must not read as steps
+     * this request needs.
      */
-    remainingFrom(from) {
-        return this.entries.slice(Math.max(0, from)).map((e) => {
+    remainingFrom(from, until) {
+        return this.entries.slice(Math.max(0, from), until).map((e) => {
             const name = e.step.toolName ?? "";
             const t = this.onlyWhen(e);
             return t ? `${name} (only when ${t.text ?? "a request needs it"})` : name;
@@ -1279,10 +1288,21 @@ export class ScenarioReplayPlan {
             break;
         }
         const anyArgs = args.slice(0, argsShown).some((a) => a !== undefined);
+        // A plan whose chain holds a decision (the service's segmentsbreakdown.md
+        // SB-18) never shows its intent, even when it stops earlier for another
+        // reason: the intent names the recorded task, the half the recording took
+        // included, and which way applies is the agent's choice.
+        const atDecision = this.stopStep()?.stop?.kind === "decision";
+        const shownIntent = this.decisionIndex() >= 0 ? "" : intent;
         // A parked step (fallbk.md D3): the model is told up front that the plan is
         // partial, so the hand-over that follows is expected rather than a surprise.
         const tail = this.stopsEarly()
-            ? ["", "The system will then hand the rest of the task back to you."]
+            ? [
+                "",
+                atDecision
+                    ? "The system will then hand the task back to you at a decision."
+                    : "The system will then hand the rest of the task back to you.",
+            ]
             : [];
         if (this.mode === "direct") {
             // The sequence is listed even though the model does not call it itself:
@@ -1291,7 +1311,7 @@ export class ScenarioReplayPlan {
             // place an operator watching the session can see what a replay is doing.
             return [
                 "[BaseInstRunner calculated replay] A known-good tool sequence was recorded",
-                `for this request${intent ? ` (intent: ${intent})` : ""}.`,
+                `for this request${shownIntent ? ` (intent: ${shownIntent})` : ""}.`,
                 "",
                 anyTest
                     ? 'It runs these tools, in order, and returns their results. A step marked "only when" runs only when this request needs it, and the results say which ones did not:'
@@ -1313,7 +1333,7 @@ export class ScenarioReplayPlan {
             "recorded for this request. Call exactly these tools, in order, one at a time:",
             "",
             ...lines,
-            ...(intent ? ["", `Context: ${intent}`] : []),
+            ...(shownIntent ? ["", `Context: ${shownIntent}`] : []),
             ...(anyTest
                 ? [
                     "",

package/dist/replay/reads-only.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Whether a tool call may change something, judged by its name alone — the
+ * runner's copy of the service's own rule (BaseIn src/scenarios/correctionCheck.ts,
+ * `readsOnly`, `commandReadsOnly`, `callMayChange`), kept word for word so the
+ * two never disagree about the same call.
+ *
+ * Used where a call after a plan's decision is the agent starting a way of its
+ * own (the service's offer1.md O7), and where a plan started after a call
+ * would make it a second time (O8). When in doubt, a call is a change: that
+ * only ends a set of scenarios early or keeps a plan from starting, never lets
+ * a second write through.
+ */
+/**
+ * A tool that only reads: Claude Code's read-only tools, then the name — a
+ * reading word and no writing word (`calendar_search_events`, `getJiraIssue`;
+ * `run_sql` no: `run` writes). A name with both (`get_or_create_contact`)
+ * changes something.
+ */
+export declare function readsOnly(toolName: string): boolean;
+/** Whether a shell command only looks: every part of it is a looking command, and nothing is written to a file. */
+export declare function commandReadsOnly(command: string): boolean;
+/**
+ * Whether one call may change something. A Bash call changes nothing only
+ * when its command is there and only looks; any other tool is a change unless
+ * {@link readsOnly} says it only reads — a tool it cannot tell about counts as
+ * a change. `input` is the call's arguments, as an object or as JSON text.
+ */
+export declare function callMayChange(toolName: string, input: unknown): boolean;
+//# sourceMappingURL=reads-only.d.ts.map

package/dist/replay/reads-only.js

@@ -0,0 +1,261 @@
+/**
+ * Whether a tool call may change something, judged by its name alone — the
+ * runner's copy of the service's own rule (BaseIn src/scenarios/correctionCheck.ts,
+ * `readsOnly`, `commandReadsOnly`, `callMayChange`), kept word for word so the
+ * two never disagree about the same call.
+ *
+ * Used where a call after a plan's decision is the agent starting a way of its
+ * own (the service's offer1.md O7), and where a plan started after a call
+ * would make it a second time (O8). When in doubt, a call is a change: that
+ * only ends a set of scenarios early or keeps a plan from starting, never lets
+ * a second write through.
+ */
+/** Built-in tools that only read (Claude Code's). */
+const READ_TOOLS = new Set([
+    "Read",
+    "Grep",
+    "Glob",
+    "LS",
+    "WebFetch",
+    "WebSearch",
+    "NotebookRead",
+    "TodoWrite",
+    "TaskOutput",
+    "BashOutput",
+]);
+/** Built-in tools that change files or run commands (Claude Code's). */
+const CHANGING_BUILTINS = new Set([
+    "Write",
+    "Edit",
+    "MultiEdit",
+    "NotebookEdit",
+    "Bash",
+    "KillShell",
+]);
+// Not `query`, `select` or `check`: a database query, a selected option, a
+// check-in can change something.
+const READ_WORDS = new Set([
+    "list",
+    "get",
+    "search",
+    "find",
+    "read",
+    "fetch",
+    "lookup",
+    "count",
+    "view",
+    "show",
+    "describe",
+    "retrieve",
+    "browse",
+    "peek",
+    "inspect",
+    "snapshot",
+]);
+/**
+ * A word that may change something: a name holding one writes, whatever else
+ * it says (`get_or_create_contact`, `find_and_replace`).
+ */
+const WRITE_WORDS = new Set([
+    "create",
+    "add",
+    "set",
+    "update",
+    "upsert",
+    "insert",
+    "put",
+    "post",
+    "send",
+    "delete",
+    "remove",
+    "mark",
+    "replace",
+    "archive",
+    "move",
+    "assign",
+    "book",
+    "cancel",
+    "write",
+    "edit",
+    "modify",
+    "save",
+    "submit",
+    "approve",
+    "reject",
+    "close",
+    "open",
+    "merge",
+    "push",
+    "publish",
+    "upload",
+    "invite",
+    "schedule",
+    "reply",
+    "forward",
+    "transfer",
+    "pay",
+    "refund",
+    "notify",
+    "run",
+    "execute",
+    "exec",
+    "apply",
+    "reset",
+    "start",
+    "stop",
+    "kill",
+    "enable",
+    "disable",
+    "grant",
+    "revoke",
+    "rename",
+    "tag",
+    "label",
+    "comment",
+]);
+/** A tool name's words: `getJiraIssue` → get, jira, issue; `calendar_search_events` → calendar, search, events. */
+function nameWords(name) {
+    return name
+        .replace(/([a-z\d])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z\d]+/)
+        .filter(Boolean);
+}
+/**
+ * A tool that only reads: Claude Code's read-only tools, then the name — a
+ * reading word and no writing word (`calendar_search_events`, `getJiraIssue`;
+ * `run_sql` no: `run` writes). A name with both (`get_or_create_contact`)
+ * changes something.
+ */
+export function readsOnly(toolName) {
+    if (READ_TOOLS.has(toolName))
+        return true;
+    if (CHANGING_BUILTINS.has(toolName))
+        return false;
+    const words = nameWords(toolName.replace(/^mcp__.+?__/, ""));
+    if (words.some((w) => WRITE_WORDS.has(w)))
+        return false;
+    return words.some((w) => READ_WORDS.has(w));
+}
+/** Commands that only look (`ls`, `git status`, `grep …`). */
+const READ_COMMANDS = new Set([
+    "ls",
+    "dir",
+    "cat",
+    "type",
+    "head",
+    "tail",
+    "less",
+    "more",
+    "grep",
+    "rg",
+    "egrep",
+    "fgrep",
+    "find",
+    "wc",
+    "pwd",
+    "echo",
+    "printf",
+    "date",
+    "whoami",
+    "which",
+    "where",
+    "env",
+    "printenv",
+    "stat",
+    "file",
+    "du",
+    "df",
+    "tree",
+    "jq",
+    "sort",
+    "uniq",
+    "cut",
+    "awk",
+    "diff",
+    "cmp",
+    "basename",
+    "dirname",
+    "realpath",
+    "readlink",
+    "true",
+    "false",
+    "test",
+    "sleep",
+    "ps",
+    "uname",
+    "hostname",
+    "id",
+    "nproc",
+    "free",
+    "uptime",
+    "node --version",
+    "npm --version",
+]);
+const READ_GIT = new Set([
+    "status",
+    "log",
+    "diff",
+    "show",
+    "branch",
+    "rev-parse",
+    "ls-files",
+    "blame",
+    "remote",
+    "describe",
+    "config --get",
+    "grep",
+    "shortlog",
+    "tag --list",
+]);
+/** Whether a shell command only looks: every part of it is a looking command, and nothing is written to a file. */
+export function commandReadsOnly(command) {
+    const text = command.trim();
+    if (!text)
+        return true;
+    // A redirect into a file (not into /dev/null, not 2>&1), tee, or an in-place edit changes something.
+    if (/(^|[^0-9&])>{1,2}\s*(?!&|\/dev\/null)\S/.test(text) || /\btee\b/.test(text) || /\bsed\b[^|;&]*\s-i\b/.test(text)) {
+        return false;
+    }
+    if (/\bfind\b[^|;&]*\s-(delete|exec|execdir|ok)\b/.test(text))
+        return false;
+    const parts = text
+        .split(/\|\||&&|[|;\n]/)
+        .map((p) => p.trim())
+        .filter(Boolean);
+    return parts.every((part) => {
+        const words = part.replace(/^(\w+=\S+\s+)+/, "").split(/\s+/);
+        const cmd = (words[0] ?? "").replace(/^.*[\\/]/, "");
+        if (cmd === "git")
+            return READ_GIT.has(words[1] ?? "") || READ_GIT.has(`${words[1] ?? ""} ${words[2] ?? ""}`);
+        if (cmd === "sed" || cmd === "awk")
+            return !/\s-i\b/.test(part);
+        return READ_COMMANDS.has(cmd) || READ_COMMANDS.has(`${cmd} ${words[1] ?? ""}`);
+    });
+}
+/**
+ * Whether one call may change something. A Bash call changes nothing only
+ * when its command is there and only looks; any other tool is a change unless
+ * {@link readsOnly} says it only reads — a tool it cannot tell about counts as
+ * a change. `input` is the call's arguments, as an object or as JSON text.
+ */
+export function callMayChange(toolName, input) {
+    if (toolName === "Bash") {
+        let value = input;
+        if (typeof value === "string") {
+            try {
+                value = JSON.parse(value);
+            }
+            catch {
+                value = undefined;
+            }
+        }
+        const command = value && typeof value === "object" && typeof value.command === "string"
+            ? value.command
+            : "";
+        return command.trim() === "" || !commandReadsOnly(command);
+    }
+    return !readsOnly(toolName);
+}
+//# sourceMappingURL=reads-only.js.map

package/dist/replay/types.d.ts

@@ -47,9 +47,18 @@ export interface StepStop {
      * `parked`: the step has failed too often and its retry is not due, or its
      * grace has ended. `nondeterministic`: the calculation could not write code
      * that computes this step's input — a judgement — so the agent makes it.
+     * `decision`: the task has an "if … otherwise" here (the service's
+     * segmentsbreakdown.md SB-6). The plan runs only the steps before it and
+     * hands the task back, and the agent decides which way applies. Not a
+     * failure: it counts nothing against the step. Runners up to 0.3.18 read it
+     * as an unknown kind and stop here too, as `known_bad_step`.
+     */
+    kind: "parked" | "nondeterministic" | "decision";
+    /**
+     * For `nondeterministic`: which check the step failed at calculation. For
+     * `decision`: the condition in words. It holds the recorded run's values,
+     * so it is never shown to the agent (it would hint at the recorded half).
      */
-    kind: "parked" | "nondeterministic";
-    /** For `nondeterministic`: which check the step failed at calculation. */
     why?: string;
     /** For `parked` inside its grace: when the step may be tried again. */
     retryAt?: string;
@@ -252,7 +261,14 @@ export type FallbackKind =
  * (autocorrect.md AC5): this request is the other half of an "if …
  * otherwise", and the agent does it. No fault of the plan; counts nothing.
  */
- | "other_branch";
+ | "other_branch"
+/**
+ * The plan ran the steps before its decision and stopped in front of it
+ * (the service's segmentsbreakdown.md SB-17): the agent decides which way
+ * applies and does the rest. No fault of the plan; it counts nothing, and
+ * the plan is billed only up to the stop (SB-26).
+ */
+ | "decision";
 /**
  * Upgrade order. `not_steered` is the floor — the control group, and the safe
  * answer if a turn dies mid-flight — and each later decision point can only move

package/docs/calculatedReplay.md

@@ -748,6 +748,30 @@ about it:
 It ends with the remaining planned steps and the parameters derived for this request, within 4 000
 characters.
 
+**A plan's decision (0.3.19)** has a note of its own. The service serves a step with
+`stop: {kind: "decision"}` where the task has an "if … otherwise" (its segmentsbreakdown.md). The
+plan runs only the steps before it, in steer and direct mode and when a divergence's bundle runs up
+to it, and hands the task back. The note opens *"[BaseInstRunner calculated replay] The calculated
+scenario for this request ran the steps before a decision, and stopped there."*, says which steps
+ran as above, and ends *"This request asks for a decision: “…”. Decide from the results above
+which way applies, then continue the task, calling tools as needed."* (*below* in a direct run's
+answer, *above and below* after a divergence; *"This task has a decision to make here."* when the
+request has no such sentence). The quote is the live request's own sentences with a word for a
+condition, found with the service's word list (`if`, `otherwise`, `else`, `unless`, `only when`,
+`only if`, `in case`, `whether`, and the Hebrew ones), at most 600 characters
+([`condition-words.ts`](../src/replay/condition-words.ts)). The note has no intent line, no
+remaining planned steps and no parameters, and never the condition the service keeps (`stop.why`):
+each names, or hints at, the half the recording took. The directive at the prompt leaves the intent
+out for the same reason, and says the task comes back *"at a decision"*. The report is `fell_back`
+(`failed` when no step ran) with `fallbackKind: "decision"`; the decision step has no verdict, so
+nothing counts against it. A runner up to 0.3.18 reads the unknown kind as `known_bad_step`.
+
+A plan whose chain has a decision keeps these protections when it stops *earlier* for another
+reason — a parked or failed step, a judgement, the budget. Its note is the ordinary one above, but
+with no intent line and no parameters, and its remaining planned steps end before the decision. Its
+directive leaves the intent out too. An agent sent on to the recorded half's steps would start that
+half's segment, and the plan would have decided after all.
+
 With `BIR_REPLAY_RECORDED_OUTPUTS=1`, a step that could not be *sent* (a built-in, no proxy, off the
 allowlist) is served its **recorded output** instead (§8.1), marked `(recorded)` in the bundle so the
 model is never told a stale result is fresh. A timeout or an upstream error never is.
@@ -1010,10 +1034,16 @@ note replaces the call, in direct mode `run_scenario` answers with it). The deri
 itself times out after max(`BIR_SERVICE_TIMEOUT_MS`, `BIR_DERIVE_BUDGET_MS`). None of these waits
 happens while the service is cooling down after a failure: the turn simply runs normally.
 
-**Intent arming mid-turn is opt-in.** An intent probe is sent from `PreToolUse` for hit counting and
-is never waited on, unless `BIR_INTENT_ARM=1` or `BIR_SEGMENT_ARM=1` lets it arm a plan in that
-call's place; then it waits at most `BIR_INTENT_ARM_BUDGET_MS` (**500**) for the probe and 1.5 s for
-arming. `BIR_INTENT_ARM=0` never waits.
+**Intent arming mid-turn is on by default from 0.3.19.** An intent probe is sent from `PreToolUse`
+for hit counting. While arming is on — `BIR_SEGMENT_ARM` unset or `1`, the recorder's default from
+0.3.19, or `BIR_INTENT_ARM=1` — the probe may arm a plan in that call's place, and the hook waits at
+most `BIR_INTENT_ARM_BUDGET_MS` (**500**) for it and 1.5 s more for arming. With `BIR_SEGMENT_ARM=0`
+(and no `BIR_INTENT_ARM=1`), or `BIR_INTENT_ARM=0`, it is never waited on. Up to 0.3.18 arming was
+opt-in: a segment runs only mid-task, and a plan that stops at its decision hands the rest of the
+task to segments of its halves, so 0.3.19 turns it on. A probe asks the service to hand segments out
+(`acceptSegments`) only where one can arm: segment and intent arming on, in Claude Code. Any other
+probe — `BIR_INTENT_ARM=0`, or a session of another host — gets what would have armed instead, and
+it is logged (`replay.segment_would_arm`).
 
 `UserPromptSubmit` must stay non-`async`: an async hook is fire-and-forget and cannot return
 `additionalContext` at all.
@@ -1045,7 +1075,8 @@ stopped at a step that broke (a logic failure, a tool error, a call sent and nev
 recorded stand-in (`BIR_REPLAY_RECORDED_OUTPUTS=1`) is never work done: it counts toward neither
 `stepsPinned` nor the upgrade, and a direct run that used one is `diverged` at best. A call that ran
 beside a pinned one hands over as `fell_back` or `failed` (§7), and so does a divergence whose
-bundle stops in front of the other half of an "if … otherwise" (§9.2). A direct run cancelled by its caller
+bundle stops in front of the other half of an "if … otherwise" (§9.2), or in front of the plan's
+decision (§8). A direct run cancelled by its caller
 (Esc, or `bir-scenario`'s own timeout) books `fell_back` or `failed` with `measured: false`, never
 `diverged`: that turn's cost says nothing about what the task costs.
 
@@ -1256,6 +1287,15 @@ tokens and every model in the list has a price; with no usage at all, the line s
 `why="the host sent no usage"`. Such a host hands over one number for the whole run, so with more
 than one plan in one run none of them is measured.
 
+**A plan stopped at its decision is billed up to the stop (0.3.19).** When a step of it ran, its
+hand-over takes a usage mark, and its report's window ends there: the agent's decision and the half
+it took are the agent's own, not the plan's (the service's segmentsbreakdown.md SB-26). This holds
+for a plan the prompt started, which gets a way to take a mark only when its stop is a decision, and
+for one an intent match started, whose window already ended at its own retire. Every other plan
+keeps its window — a plan of the prompt is billed for the whole turn up to the next plan, so the
+answer it was asked for stays on its bill — and every other hand-over still takes no mark. A
+decision reached before any step ran takes no mark either: its report is a sample of the whole turn.
+
 ---
 
 ## 12. What the replayed turn records

package/docs/calculatedReplayGuide.md

@@ -327,7 +327,7 @@ Recording         : yes
   · the recorder runs in the background (pid 41820); its audit log is ~/.baseinstrunner/logs/<key>.log
   · the BaseIn service last answered the recorder 12 s ago
   · wrapped MCP calls are not approved by the runner: Claude Code asks as it would without it. For headless runs (`claude -p`) allow them in permissions.allow or --allowedTools, or set BIR_CORRELATION_DECISION=allow where the recorder starts
-  · recurring sub-tasks are observed only — nothing is replaced (BIR_SEGMENT_ARM unset)
+  · segments run mid-task — recurring sub-tasks, and the halves after a plan's decision — and so may whole plans (the default; BIR_SEGMENT_ARM=0 turns this off)
 
 No problems found.
 ```
@@ -370,7 +370,8 @@ so there is exactly one switch and it cannot get out of step with itself.
 | `BIR_REPLAY_RECORDED_OUTPUTS` | *(unset)* | `1` lets a step that could not be sent (a built-in off `BIR_BUILTIN_TOOLS`, no proxy, a server off the allowlist) stand on its recorded output instead of stopping the plan. Never for a timeout or an upstream error |
 | `BIR_BUILTIN_TOOLS` | `Read,Glob,Grep,Edit,Write,Bash` | Built-ins the runner executes itself during a replay, in the session's own project directory and confined to it. A chain whose only non-MCP steps are on this list arms `direct`. A runner-side step never reaches the host's permission prompts, so leave off any tool you want the model to call itself; `Read,Glob,Grep` is the read-only set (the default up to 0.3.7). `none`: every built-in step is steered in the session. Claude Code sessions only: in a LangChain application a tool with one of these names is the application's own, and the runner runs none (§6.5) |
 | `BIR_BASH_ALLOW` | *(unset: any command)* | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset means any command; `none` means no command, and `Bash` steps are steered in the session. A plan's Bash steps share a working directory, exactly as the host's own Bash tool does — variables and functions do not persist, also as the host's. A call with `run_in_background`, or with its own `timeout` longer than the step's clock (`BIR_STEP_TIMEOUT_MS`), is never started on the runner: the plan hands over in front of it |
-| `BIR_INTENT_ARM` | *(unset)* | `1` lets a match found mid-turn arm a plan in the calling tool's place, which means waiting for it (`BIR_INTENT_ARM_BUDGET_MS`, 500); `0` never waits; unset follows `BIR_SEGMENT_ARM` |
+| `BIR_SEGMENT_ARM` | *(unset: on, from 0.3.19)* | A segment the service hands out runs mid-task: a recurring sub-task, or a half of a task after a plan's decision. `0` is observe-only: what would have armed is logged (`replay.segment_would_arm`) and nothing is replaced. Up to 0.3.18 observe-only was the default. A recorder started before an update keeps its old default until `bir up --restart` |
+| `BIR_INTENT_ARM` | *(unset)* | `1` lets a match found mid-turn arm a plan in the calling tool's place, which means waiting for it (`BIR_INTENT_ARM_BUDGET_MS`, 500); `0` never waits, and then nothing starts mid-task, segments included: what would have armed is logged; unset follows `BIR_SEGMENT_ARM`, so from 0.3.19 it is on unless `BIR_SEGMENT_ARM=0` |
 | `BIR_VERBOSE` | *(unset)* | `1` adds per-step `replay.*` detail lines |
 
 The `bir` server reads its own, from the environment Claude Code starts it with:
@@ -493,7 +494,11 @@ Everything replay decides is one line. `grep` for these:
 | `replay.step` | One direct step executed |
 | `replay.step_not_taken` | A step's test said this request does not need it, and nothing was sent for it ([calculatedReplay.md](calculatedReplay.md) §9.2). `plan.armed … tests=` lists the tested steps by their place in the plan: `4:hand_over,11:skip` |
 | `replay.diverge` / `replay.compose` | Off-script, and the recovery |
-| `replay.handover` | The plan stopped and handed the rest of the task to the model; `kind=` and `step=` say where |
+| `replay.handover` | The plan stopped and handed the rest of the task to the model; `kind=` and `step=` say where. `kind=decision` (0.3.19) is a plan that ran the steps before its decision and stopped there, as planned (`via=divergence` when a divergence's bundle ran up to it) |
+| `run.fragment … decision=true` / `run.fragment_dropped` | After a plan's decision: the agent's own work from its next call is recorded as a fragment, from which the service makes a calculated scenario of that way / a plan the intent check armed, or a next scenario, took that call instead, so nothing is recorded as the agent's own |
+| `replay.next_ready` / `replay.next_hit` / `replay.next_miss` | 0.3.20: the calculated scenarios that can follow a plan's decision, armed while the agent decided / the agent's call was one's first step, value for value, so it runs in the call's place / none was used: `reason=other_values` (the same first tool with other values), `own_way` (a call that may change something and starts none of them), `not_ready` (the one that starts with that tool was not armed in time), `calls_limit` (5 calls started none), `turn_ended`. A call that only reads ends nothing |
+| `run.fragment_closed` | 0.3.20: a scenario that follows the decision took over after the agent's own looks had opened the fragment; the fragment ends there, with what the agent did itself |
+| `replay.decision … code=would_repeat` | 0.3.20: a plan an intent match armed after the agent's call would have made that call again (the same tool that may change something, or for a shell the same command), so it was not started (never twice) |
 | `replay.vetoed` | A direct plan retired without running anything: `run_scenario` was not the first call, or never arrived |
 | `replay.run_ambiguous` | Two sessions had `run_scenario` pending and the request named neither; nothing ran |
 | `replay.cancelled` / `replay.note_kept` | A direct run's caller went away (Esc); no further step started, and the note is kept for the model's next call |
@@ -578,6 +583,11 @@ A recorded output that stood in for a step (`BIR_REPLAY_RECORDED_OUTPUTS=1`) is
 work done. A direct run you cancel (Esc) is booked `fell_back` or `failed` with `measured: false`:
 a turn cut short says nothing about what the task costs.
 
+A plan that stops at its decision (runner 0.3.19 or newer) is booked `fell_back` with
+`fallbackKind: decision`, or `failed` when no step ran. Nothing is counted against its steps, and
+when a step ran its cost ends at the stop: the agent's decision and the half it took are not on the
+plan's bill.
+
 A turn's cost is **measured** only when its tokens were found and every model of the turn has a
 price in the runner's table. A model with no price used to count as $0, and that zero was called
 measured. Now such a turn is not measured, in Claude Code as in any host, and a `run.unmeasured`
@@ -656,6 +666,8 @@ Code's pool, as before.
 | `run_scenario` answers "The prepared results are not available for this request. Do the task normally with your tools." | The plan could not be delivered — a recorder that does not answer, a timeout, an HTTP error — and the model does the task itself | The `scenario.answered` line on the `bir` server's stderr has the real reason. `BIR_SCENARIO_DEBUG=1` in that server's environment hands the raw reason to the model as an error, for debugging |
 | A hand-over note says a step "was sent but did not answer … may or may not have completed" | The step timed out, or its upstream went away mid-call; nothing after it ran | Check whether its work happened before running it again — the model is told the same. Repeats: look at that upstream, or raise `BIR_STEP_TIMEOUT_MS` |
 | A hand-over note says "a step never runs on another session's upstream" | Two Claude Code sessions are open in the project, and this one has not yet made a call of its own to that server, so bir cannot tell its proxy from the other session's. A direct plan is told apart by the process that started both the `bir` server and the session's proxies, so for one this means an older proxy or `bir` server (restart the session after an update), or a server started through a wrapper such as a shell or `npx` | Expected: the model calls the tool itself. Once the session's own call to the server has gone through, later replays use its proxy |
+| A hand-over note says the plan "ran the steps before a decision, and stopped there" | The service split the plan at its "if … otherwise" (runner 0.3.19 or newer): the plan runs the steps both ways need, then the agent decides which way applies. The note quotes the request's own sentences with the condition | Expected. The agent's next step may start a segment of the way it chose (`replay.intent_armed … kind=segment`); with `BIR_SEGMENT_ARM=0` it does that part itself. `bir investigate` shows the run as `fell_back · decision` |
+| A hand-over note says a step "did not run: it has failed before", and the step never failed | A runner up to 0.3.18 met a plan's decision, a stop it does not know. It stops there too, but its note names a failure and lists the remaining steps | Update the runner (`bir update`, then `bir up --restart`) |
 | A hand-over note says a step "was not run by the host", or "ran with arguments a person chose, not the scenario's" | A LangChain application (§6.5). A person said no to the step, or answered in the tool's place, or a call limit blocked the call (`host_rejected`); or a person changed the call before it ran (`host_edited`) | Expected, and no fault of the plan: the step is booked `skipped`, the plan stops there and the model takes over. It is told not to run the step again — after a refusal, unless the user asks. §7 has what the report says |
 | `recorder.send_failed … error="HTTP 409 … invalid_ticket"` | The execution report's ticket was already redeemed, or belongs to another scenario. Or the report came more than an hour after its plan was handed out | Harmless if the body says `duplicate: true`. Otherwise a rollover raced `SessionEnd`; the server books once. A report that came too late is not booked; the service as built (not deployed yet) takes a report for 24 hours |
 | `recorder.send_failed … error="HTTP 429 …"` | The account is over one of the service's limits, and the answer is `429` with `Retry-After`. The limits are built on the service and not deployed yet; each is a setting there. By default: 120 runs a minute · 3,000 steps a minute (a tool call is two steps) · 10 title requests a minute · 20 requests in any one hour for Calculate, Prefer and Recalculate together (`bir scenario calc` then prints a line that begins `Could not start calculation (HTTP 429`) | What it costs: a create, a step or a report is sent once more, at most 2 s later, then dropped. A dropped step is a hole in its recording. A run whose create got the 429 runs without its plan. A 429 that the second try did not cure counts as the service being unwell: for 5 to 60 seconds no prompt of that recorder waits for a match. An intent probe over its own limit (1,500 a minute) is answered with no match, never with `429` |
@@ -1337,7 +1349,7 @@ Parameter database: target → setting (revision 4). Undo: bir scenario undo scn
 | `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. For a correction: the plan has changed since it | `bir` prints two commands: undo the newer one first, then yours |
+| `not_latest_edit` | The step has changed since the edit you named: a newer entry changed it. For a correction: the plan has changed since it. When the newer entry is an `ssplit_…` id, the plan was split at its decision after the correction, and a correction cannot be taken back while the split is in use | `bir` prints two commands: undo the newer one first, then yours. For a split, `bir` says to press Undo on the Split card of the plan's recording page first, and prints the command for 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 |

package/package.json

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