@basein/runner 0.3.26 → 0.3.28

package/dist/replay/plan.js

@@ -132,6 +132,47 @@ function clipReasoning(reasoning) {
     const first = (reasoning ?? "").trim().split(/\r?\n/, 1)[0]?.trim() ?? "";
     return first.length > MAX_REASONING_CHARS ? `${first.slice(0, MAX_REASONING_CHARS)}…` : first;
 }
+// ── the recording's values in a directive's text (B2 is11.md) ────────────────
+/**
+ * A recorded value as a text may name it: a string or a number at least this
+ * long — a one-character sample ("5", "a") is found in too many words — and
+ * no longer than a name or a title is.
+ */
+const RECORDED_VALUE_MIN = 2;
+const RECORDED_VALUE_MAX = 200;
+/** One of this request's values, as a directive shows it: this long at most. */
+const SHOWN_VALUE_MAX = 60;
+/** This many of this request's values at most on a direct directive's values line… */
+const SHOWN_VALUES = 4;
+/** …and this long at most, all of them. */
+const SHOWN_VALUES_CHARS = 200;
+/** The recorded value `value` as a text may name it, or undefined. */
+function recordedText(value) {
+    const text = typeof value === "number" && Number.isFinite(value)
+        ? String(value)
+        : typeof value === "string"
+            ? value.trim()
+            : undefined;
+    return text !== undefined && text.length >= RECORDED_VALUE_MIN && text.length <= RECORDED_VALUE_MAX ? text : undefined;
+}
+/** A value of this request's as plain text — never a mark — or undefined. */
+function valueText(value) {
+    let text;
+    if (typeof value === "boolean")
+        text = String(value);
+    else if (typeof value === "number" && Number.isFinite(value))
+        text = String(value);
+    else if (typeof value === "string")
+        text = value.replace(/\s+/g, " ").trim();
+    if (!text || markedKey(text) !== undefined)
+        return undefined;
+    return text;
+}
+const clipValue = (text) => text.length > SHOWN_VALUE_MAX ? `${text.slice(0, SHOWN_VALUE_MAX)}…` : text;
+const sameText = (a, b) => a.toLowerCase() === b.toLowerCase();
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** A parameter's role, for a value a text must not name: `assignee_name` → `<assignee name>`. */
+const roleOf = (key) => `<${key.replace(/[_-]+/g, " ").trim() || key}>`;
 /** A step's computed arguments, as a steer directive shows them: this long at most. */
 const MAX_DIRECTIVE_ARGS_CHARS = 240;
 /**
@@ -854,6 +895,120 @@ export class ScenarioReplayPlan {
         }
         return out;
     }
+    /**
+     * This request's value of `key`, as a directive may show it, or undefined
+     * (B2 is11.md): once the reading has settled, a plain value the reading
+     * took from the request — never a mark, and never a value a step works out
+     * (`from: "step"`): before the run nobody has that one, and the recorded one
+     * is another request's (issue 1212).
+     */
+    shownValueOf(key, p) {
+        if (!this.paramsSettled || p?.from === "step")
+            return undefined;
+        return valueText(this.derivedParams[key]);
+    }
+    /**
+     * A text written from the recording — the intent, a step's reasoning — put
+     * right for this request, for a directive to show (B2 is11.md).
+     *
+     * Both name the recording's values: "set Olga up", "moves each lead to
+     * Olga". Shown beside a request for Carlos, the name tells the model the
+     * plan is for someone else. A careful model then checks before it runs
+     * anything, and a direct plan's first call that was not `run_scenario`
+     * retired it — so the replay was lost on exactly the turn replay is for: the
+     * same task with a new value. The steps never read the text: they take
+     * Carlos from the request.
+     *
+     * Each recorded value of a parameter found in the text, as a whole word, is
+     * replaced by this request's own value where the plan has one it may show
+     * ({@link shownValueOf}), and else by the parameter's role (`<assignee
+     * name>`): a target the request did not name, a value a step works out, or
+     * any value while the reading has not settled. A value the same as the
+     * recorded one stays as it is. One pass, longest value first, so nothing put
+     * in is replaced again.
+     */
+    forThisRequest(text) {
+        return this.rewriter()(text);
+    }
+    /** {@link forThisRequest} as one function, built once for a directive's many texts. */
+    rewriter() {
+        const schema = this.scenario.paramsObject;
+        if (!schema || typeof schema !== "object")
+            return (text) => text;
+        /** Recorded value (lower case) → what goes in its place; null where it stays. */
+        const swaps = new Map();
+        for (const [key, p] of Object.entries(schema)) {
+            const recorded = recordedText(p?.sampleValue);
+            if (!recorded)
+                continue;
+            const now = this.shownValueOf(key, p);
+            const swap = now !== undefined && sameText(now, recorded) ? null : now !== undefined ? clipValue(now) : roleOf(key);
+            const k = recorded.toLowerCase();
+            // Two parameters recorded with one value: a change wins over "stays".
+            if (!swaps.has(k) || swaps.get(k) === null)
+                swaps.set(k, swap);
+        }
+        const found = [...swaps.entries()].filter(([, swap]) => swap !== null).map(([k]) => k);
+        if (found.length === 0)
+            return (text) => text;
+        found.sort((a, b) => b.length - a.length);
+        let pattern;
+        try {
+            pattern = new RegExp(`(?<![\\p{L}\\p{N}_])(?:${found.map(escapeRegExp).join("|")})(?![\\p{L}\\p{N}_])`, "giu");
+        }
+        catch {
+            return (text) => text;
+        }
+        return (text) => (text ? text.replace(pattern, (m) => swaps.get(m.toLowerCase()) ?? m) : text);
+    }
+    /**
+     * This request's own values, for the direct directive's line that says the
+     * steps take them (B2 is11.md): what the reading took from the request.
+     * The values the request names in words come first — a name, a title: what
+     * a reader holds the note against — those unlike the recording's first;
+     * then the values worked out from the day ("tomorrow" as a date). Targets
+     * only: never a setting, never a value a step works out, never a mark.
+     * Undefined until the reading has settled, or when it named none.
+     */
+    requestValues() {
+        if (!this.paramsSettled)
+            return undefined;
+        const schema = this.scenario.paramsObject;
+        if (!schema || typeof schema !== "object")
+            return undefined;
+        const items = [];
+        let order = 0;
+        for (const [key, p] of Object.entries(schema)) {
+            order += 1;
+            if (p?.kind === "setting")
+                continue;
+            const now = this.shownValueOf(key, p);
+            if (now === undefined)
+                continue;
+            const recorded = recordedText(p?.sampleValue);
+            items.push({
+                key,
+                text: clipValue(now),
+                // Named in the request's own words; an older service sends no `from`.
+                said: p?.from === undefined || p.from === "prompt",
+                differs: recorded !== undefined && !sameText(now, recorded),
+                order,
+            });
+        }
+        items.sort((a, b) => Number(b.said) - Number(a.said) || Number(b.differs) - Number(a.differs) || a.order - b.order);
+        const parts = [];
+        let chars = 0;
+        for (const item of items) {
+            if (parts.length >= SHOWN_VALUES)
+                break;
+            const part = `${item.key} ${JSON.stringify(item.text)}`;
+            if (parts.length > 0 && chars + part.length > SHOWN_VALUES_CHARS)
+                break;
+            parts.push(part);
+            chars += part.length + 2;
+        }
+        return parts.length > 0 ? parts.join(", ") : undefined;
+    }
     /**
      * The directive injected via `UserPromptSubmit`'s `additionalContext`.
      *
@@ -880,9 +1035,14 @@ export class ScenarioReplayPlan {
         // A sub-task plan (armed mid-task) never tells the agent to stop calling
         // tools: the steps below are a part of the task it is already doing.
         const subTask = opts?.subTask ?? this.subTask;
+        // The intent and each step's reasoning were written from the recording,
+        // so they name its values ("set Olga up"); shown here, they say this
+        // request's — or the value's role — never another request's (B2 is11.md).
+        const fix = this.rewriter();
         // The intent is a paragraph the analyser wrote; it is context, not an
         // instruction, so it is clipped rather than dumped whole into the prompt.
-        const intent = this.intent.length > 240 ? `${this.intent.slice(0, 240)}…` : this.intent;
+        const written = fix(this.intent);
+        const intent = written.length > 240 ? `${written.slice(0, 240)}…` : written;
         if (this.mode === "direct") {
             // The steps are not listed. The model does not call them, and what the
             // tool returns names every call and says whether the run was whole or
@@ -890,9 +1050,17 @@ export class ScenarioReplayPlan {
             // cost the agent up to 2,000 characters in the first call of every turn
             // a plan was armed for (docs/calculatedReplay.md, "How a bundle reads"),
             // and the tool's result shows an operator watching the session what ran.
+            //
+            // One line says where the steps' values come from, with this request's
+            // own: a model that met another request's value in the note used to
+            // stop to check, and its check retired the plan (B2 is11.md).
+            const values = this.requestValues();
             return [
                 "[BaseInstRunner calculated replay] A known-good tool sequence was recorded",
-                `for this request${intent ? ` (intent: ${intent})` : ""}.`,
+                `for a request like this one${intent ? ` (intent: ${intent})` : ""}.`,
+                values
+                    ? `Its steps take this request's values, not the recording's: ${values}.`
+                    : "Its steps take this request's values, not the recording's.",
                 "",
                 `Call ${directToolName} once, with no arguments, before any other tool. It runs the`,
                 "sequence and returns what each call did.",
@@ -924,7 +1092,7 @@ export class ScenarioReplayPlan {
             return ` (only when ${t.text ?? "this request needs it"})`;
         };
         const listing = (withWhy, argsBefore) => planned.map((s, i) => {
-            const why = withWhy ? clipReasoning(s.reasoning) : "";
+            const why = withWhy ? clipReasoning(fix(s.reasoning ?? "")) : "";
             const head = `  ${i + 1}. ${s.toolName}${onlyWhen(i)}${why ? ` — ${why}` : ""}`;
             const shown = i < argsBefore ? args[i] : undefined;
             return shown ? `${head}\n     ${shown}` : head;

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

@@ -0,0 +1,48 @@
+/**
+ * reads-only — whether one call of the agent's only looks, and changes nothing.
+ *
+ * WHY THE RUNNER ASKS (B2 is11.md, 2026-11-11). A direct plan is announced
+ * with "call run_scenario before any other tool", and a first call that is
+ * not `run_scenario` used to retire it on the spot (control/server.ts). The
+ * rule is there for one danger: a model that has no `run_scenario` makes its
+ * own calls, and a divergence would then run every step, writes included,
+ * inside a hook nobody approves. But the call that retired the plan in is11
+ * was the agent reading its own notes file: it had seen another person's name
+ * in the note (Olga, the recording's; the request said Carlos) and checked
+ * first. The plan would have done the task right — its steps take the person
+ * from the request — and the turn cost a full agent run.
+ *
+ * So a call that only looks no longer retires a direct plan: it runs as the
+ * agent wrote it, and the plan waits, still announced, for `run_scenario`.
+ * The first call that may change something still retires it, running nothing
+ * (and nothing ever runs in a hook in its place): a plan run after the agent
+ * changed something itself could do the same work twice.
+ *
+ * WHEN IN DOUBT, IT IS A CHANGE. A call judged "only looks" that does change
+ * something leaves a plan armed that could then repeat that change; a change
+ * judged a change only ends a replay early, as every call did before. So:
+ *
+ *  - Claude Code's built-ins by name: the reading ones only look, every other
+ *    built-in (a sub-agent, an edit, an unknown new tool) is a change;
+ *  - `Bash` by its command ({@link commandReadsOnly}), and `PowerShell` never;
+ *  - an MCP tool by what its own server says of it (`annotations`), else by
+ *    its name: a reading word and no writing word.
+ *
+ * The same rule as the service's `readsOnly` (correctionCheck.ts, AC13), kept
+ * in step by hand, stricter where a wrong "only looks" costs more here: a
+ * command substitution, a process substitution or an `awk` `system(` makes a
+ * command a change.
+ */
+import type { ToolAnnotations } from "../record/recorder.js";
+/**
+ * Whether this call only looks. `toolInput` is the hook's `tool_input` (only a
+ * `Bash` call's `command` is read from it); `hints` is what the tool's own
+ * server listed for it, when it listed anything.
+ */
+export declare function readsOnlyCall(toolName: string, toolInput?: unknown, hints?: ToolAnnotations): boolean;
+/**
+ * Whether a shell command only looks: every part of it is a looking command,
+ * nothing is written to a file, and nothing runs code it does not show.
+ */
+export declare function commandReadsOnly(command: string): boolean;
+//# sourceMappingURL=reads-only.d.ts.map

package/dist/replay/reads-only.js

@@ -0,0 +1,161 @@
+/**
+ * reads-only — whether one call of the agent's only looks, and changes nothing.
+ *
+ * WHY THE RUNNER ASKS (B2 is11.md, 2026-11-11). A direct plan is announced
+ * with "call run_scenario before any other tool", and a first call that is
+ * not `run_scenario` used to retire it on the spot (control/server.ts). The
+ * rule is there for one danger: a model that has no `run_scenario` makes its
+ * own calls, and a divergence would then run every step, writes included,
+ * inside a hook nobody approves. But the call that retired the plan in is11
+ * was the agent reading its own notes file: it had seen another person's name
+ * in the note (Olga, the recording's; the request said Carlos) and checked
+ * first. The plan would have done the task right — its steps take the person
+ * from the request — and the turn cost a full agent run.
+ *
+ * So a call that only looks no longer retires a direct plan: it runs as the
+ * agent wrote it, and the plan waits, still announced, for `run_scenario`.
+ * The first call that may change something still retires it, running nothing
+ * (and nothing ever runs in a hook in its place): a plan run after the agent
+ * changed something itself could do the same work twice.
+ *
+ * WHEN IN DOUBT, IT IS A CHANGE. A call judged "only looks" that does change
+ * something leaves a plan armed that could then repeat that change; a change
+ * judged a change only ends a replay early, as every call did before. So:
+ *
+ *  - Claude Code's built-ins by name: the reading ones only look, every other
+ *    built-in (a sub-agent, an edit, an unknown new tool) is a change;
+ *  - `Bash` by its command ({@link commandReadsOnly}), and `PowerShell` never;
+ *  - an MCP tool by what its own server says of it (`annotations`), else by
+ *    its name: a reading word and no writing word.
+ *
+ * The same rule as the service's `readsOnly` (correctionCheck.ts, AC13), kept
+ * in step by hand, stricter where a wrong "only looks" costs more here: a
+ * command substitution, a process substitution or an `awk` `system(` makes a
+ * command a change.
+ */
+/** Claude Code's built-ins that only read. `ToolSearch` and `TodoWrite` are housekeeping (record/housekeeping.ts). */
+const READ_BUILTINS = new Set([
+    "Read",
+    "Grep",
+    "Glob",
+    "LS",
+    "WebFetch",
+    "WebSearch",
+    "NotebookRead",
+    "TaskOutput",
+    "BashOutput",
+    // The conversation's own: a question to the person, plan mode in or out.
+    // Nothing outside the conversation changes, and the plan may still be
+    // what the person says yes to.
+    "AskUserQuestion",
+    "EnterPlanMode",
+    "ExitPlanMode",
+]);
+// 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`). Some are nouns too
+ * (`get_schedule`): such a look is then taken for a change, which only ends a
+ * replay early, never lets a change through.
+ */
+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);
+}
+/**
+ * Whether this call only looks. `toolInput` is the hook's `tool_input` (only a
+ * `Bash` call's `command` is read from it); `hints` is what the tool's own
+ * server listed for it, when it listed anything.
+ */
+export function readsOnlyCall(toolName, toolInput, hints) {
+    if (toolName === "Bash") {
+        const command = toolInput?.command;
+        return typeof command === "string" && commandReadsOnly(command);
+    }
+    if (READ_BUILTINS.has(toolName))
+        return true;
+    // Every other built-in — Write, Edit, PowerShell, a sub-agent, one added
+    // after this list was written — may change something.
+    if (!toolName.startsWith("mcp__"))
+        return false;
+    // A server's word beats any guess from the name.
+    if (hints?.readOnlyHint === false || hints?.destructiveHint === true)
+        return false;
+    if (hints?.readOnlyHint === true)
+        return true;
+    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`, `cat`, `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", "stat", "file",
+    "du", "df", "tree", "jq", "sort", "uniq", "cut", "awk", "diff", "cmp", "basename", "dirname",
+    "realpath", "readlink", "true", "false", "test", "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,
+ * nothing is written to a file, and nothing runs code it does not show.
+ */
+export function commandReadsOnly(command) {
+    const text = command.trim();
+    if (!text)
+        return false;
+    // Code that runs out of sight: a substitution (`$(…)`, backticks), a
+    // process substitution, awk's `system(`.
+    if (/`|\$\(|<\(|>\(|\bsystem\s*\(/.test(text))
+        return false;
+    // 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) ||
+        /&>{1,2}\s*(?!\/dev\/null)\S/.test(text) ||
+        /\btee\b/.test(text) ||
+        /\bsed\b[^|;&]*\s(-i|--in-place)/.test(text)) {
+        return false;
+    }
+    if (/\bfind\b[^|;&]*\s-(delete|exec|execdir|ok|okdir|fprint|fprintf|fls)\b/.test(text))
+        return false;
+    // A job sent to the background (`cmd &`): not something this reads.
+    if (/(?<![>&])&(?![>&])/.test(text.replace(/&&/g, "")))
+        return false;
+    const parts = text
+        .split(/\|\||&&|[|;\n]/)
+        .map((p) => p.trim())
+        .filter(Boolean);
+    if (parts.length === 0)
+        return false;
+    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")
+            return !/\s(-i|--in-place)/.test(part);
+        return READ_COMMANDS.has(cmd) || READ_COMMANDS.has(`${cmd} ${words[1] ?? ""}`);
+    });
+}
+//# sourceMappingURL=reads-only.js.map

package/docs/calculatedReplayGuide.md

@@ -784,8 +784,9 @@ bir scenario edit  <runId|scnId> --step <n> [--input-logic <file|->] [--output-l
                    [--freeze | --unfreeze] [--note "<why>"] [--force --note "<why>"] [--revision <n>]
 bir scenario edit  <runId|scnId> --param <name> --kind target|setting [--note "<why>"] [--revision <n>]
 bir scenario edits <runId|scnId>
-bir scenario undo  <runId|scnId> [--edit <sedit_id|pedit_id|scor_id> | --step <n> | --param <name>] [--force --note "<why>"]
+bir scenario undo  <runId|scnId> [--edit <sedit_id|pedit_id|scor_id|simp_id> | --step <n> | --param <name>] [--force --note "<why>"]
 bir scenario calc  <runId|scnId> [--force [--discard-edits]]
+bir scenario learning <runId|scnId> [--runs <n>] [--stop] [--again]     (§9.3)
 bir scenario editing on|off|status
 ```
 
@@ -1128,6 +1129,10 @@ How undo works:
   `bir scenario undo` takes back a correction in use when it is the newest change. `--step` never
   picks one: a correction changes the whole plan. A recalculation is refused on a corrected plan
   as on an edited one (`Not recalculated: the plan carries correction scor_…`).
+- **A change of the plan's learning phase** (built 2026-11-13, not yet released; §9.3).
+  `bir scenario edits` lists it under its `simp_` id, and `bir scenario undo <id> --edit simp_…`
+  puts back the whole plan from before it. Only by its id: a plain `bir scenario undo` never takes
+  one back, and when nothing else can be undone it names the change in use and the command.
 
 #### What a save changes
 
@@ -1346,6 +1351,73 @@ Parameter database: target → setting (revision 4). Undo: bir scenario undo scn
 | Claude Code asks before each `bir` tool | No `mcp__bir` in `permissions.allow`: the project was wired by `bir install`, or the rule was taken out | `bir setup` here adds it (`bir doctor` says when it is missing) |
 | The `bir` server lists no tools at all | The runner is off here (`bir off`, `bir off --here`, or `BIR_OFF=1` where Claude Code started) | `bir on` (or `bir on --here`), and the server tells the open session its list changed. For `BIR_OFF=1`, start Claude Code without it |
 
+### 9.3 The learning phase — `bir scenario learning`
+
+> Built 2026-11-13, **not yet released**: it needs the next `@basein/runner` version and a service
+> deploy. The design is `learningPhase.md` in the BaseIn repository (LP9, LP11).
+
+A new plan is in its **learning phase** from the moment it is calculated until 10 of its runs were
+evaluated. You can change the number for each plan, from 1 to 50. In that time the service scores
+every run, looks for what to improve, and tries one change at a time. It keeps a change only when
+the plan got better by the three measures — successful runs first, then cost, then speed — and
+otherwise takes it back exactly.
+
+**Do this**
+
+```
+bir scenario learning <runId|scnId>                        # where the learning phase stands
+bir scenario learning <runId|scnId> --runs <n>             # it lasts n evaluated runs (1–50)
+bir scenario learning <runId|scnId> --stop                 # end it now
+bir scenario learning <runId|scnId> --again [--runs <n>]   # start a new one
+```
+
+**You should see**
+
+```
+Learning: 4 of 10 runs evaluated · change 2 on trial (1 of 2 runs)
+  Revision 7: Successful 4 of 6 · cost 40% under the original · time 35% under the original
+  Found in the last run:
+    P3  The summary reads 2 values no step makes (task_id, due_date). (step 4)
+  Changes:
+    simp_0b6f…  kept         cost       The summary emits only the values the answer reads. — Kept: cost 0.62 → 0.41 of the original over 2 runs, every run successful.
+    simp_7d2e…  trial        speed      The owner's lookup is left out: nothing reads it.
+```
+
+- The first line is the phase: `Learning: 4 of 10 runs evaluated`, `Learning done after 10 runs`,
+  `Learning stopped after 4 runs`, or `No learning phase`. A change on trial says how many of its
+  runs are in.
+- The second line is the three measures of the revision the plan is at now. A measure that is not
+  known yet is left out.
+- `Found in the last run` is what the service's rules found in the newest evaluated run, one
+  problem per line (P1 to P10).
+- `Changes` is the phase's changes, oldest first: the id, the state (`proposed`, `trial`, `kept`,
+  `taken_back`, `failed_check`, `dismissed`, `replaced`), what it aims at, what it changed, and the
+  decision with its numbers. A `proposed` change waits for you: **Use** on the recording page tries
+  it.
+- `bir scenario show <id>` ends with the first line (not with `--json`: scripts read that as JSON,
+  and it carries the same facts as `learning`). `bir scenario edits <id>` lists the changes beside
+  your hand edits, and `bir scenario undo <id> --edit simp_…` takes one back (§9.2).
+- `--json` prints the service's answer unchanged. The exit codes are those of §9.2.
+
+The runner also tells the service more about each run, for the learning phase's rules about cost
+and time: the execution report's `turn` says whether the plan ran direct or steered, the turn's
+model calls and tokens, how many characters the plan handed the agent to read, whether that was
+the brief bundle, how long the agent's answer was, and, on a hand-over, where the step stood and
+why it stopped. An older service ignores it.
+
+**If it goes wrong**
+
+| What `bir` says | Why | What to do |
+|---|---|---|
+| `Not changed (builtin)` | Update bir and Remove bir have no learning phase | Nothing |
+| `Not changed (learning_off)` | The service runs with `SCENARIO_LEARNING=off` | Ask whoever runs the service |
+| `Not changed (not_ready)` | The plan is not ready, or a calculation of it is running | Wait for it, then try again |
+| `Not changed (invalid_input)` | The service did not take the request; `bir` prints its details | `--runs` takes 1 to 50 |
+| `the service does not know the learning phase yet` | The service is older than this runner | Wait for the service deploy |
+| `No learning phase` | The plan was in use before the learning phase existed — or it has none at first: a fragment, or another host's plan | For a plan in use from before: `bir scenario learning <id> --again` starts one |
+| `Not undone (not_latest_change)` | A later change of the plan stands on that one | Take back the newer one first: `bir` prints both commands when the service names it, and `bir scenario edits <id>` lists the changes, newest first |
+| `Not undone (not_used)` | The change was never used: it is proposed, dismissed, or failed its check | Nothing to take back |
+
 ---
 
 ## 10. What is built
@@ -1368,6 +1440,7 @@ part of it is not deployed yet.
 | **§6.5** *(the package is not on PyPI; the service's part is not deployed)* | A plan stepped through by the adapter of a host that is not Claude Code: the declines `host_records_only` and `host_tool_missing`, the stops `host_rejected` and `host_edited`, the cost from the adapter's `usage` | [control/server.ts](../src/control/server.ts), [controller.ts](../src/replay/controller.ts), [handover.ts](../src/replay/handover.ts), [safety.ts](../src/replay/safety.ts), [bin/investigate.ts](../src/bin/investigate.ts); the proof: `examples/langchain-proof/` in the repository (not in the npm package) |
 | **Redo and corrections** *(not yet released; the service's autocorrect.md)* | The report's `redoneBy`; a redone repeat opens with the plan's own calls, whole and marked `byPlan`; steps that run only when (contract 2); `scor_` corrections in `bir scenario edits` and `undo`; `bir investigate`'s repeat, verdict, hold and correction lines | [control/server.ts](../src/control/server.ts), [controller.ts](../src/replay/controller.ts), [plan.ts](../src/replay/plan.ts), [scenario-edit.ts](../src/bin/scenario-edit.ts), [investigate.ts](../src/bin/investigate.ts); tests: [step-tests.test.ts](../test/step-tests.test.ts), [newest-run.test.ts](../test/newest-run.test.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) |
+| **§9.3** *(not yet released; the service's learningPhase.md)* | `bir scenario learning`, the learning line in `show`, `simp_` changes in `edits` and `undo`; the report's `turn` (LP11) | [bin/scenario-edit.ts](../src/bin/scenario-edit.ts), [controller.ts](../src/replay/controller.ts), [control/server.ts](../src/control/server.ts), [control/transcript.ts](../src/control/transcript.ts), [remote-recorder.ts](../src/record/remote-recorder.ts); tests: [scenario-learning.test.ts](../test/scenario-learning.test.ts), [learning-turn.test.ts](../test/learning-turn.test.ts) |
 
 ```bash
 npm test                                                # ~1,000 tests, incl. test/replay.test.ts and test/replay-server.test.ts

package/package.json

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