@basein/runner 0.3.25 → 0.3.27

package/dist/bin/bir.js

@@ -46,9 +46,9 @@ import { ControlClient } from "../control/client.js";
 import { pidAlive, readDiscovery } from "../control/discovery.js";
 import * as daemonApi from "../control/daemon.js";
 import { activeSessions, daemonStatus, ensureDaemon, probeHealth, readPortProblem, stopDaemon, } from "../control/daemon.js";
-import { configDir, controlDir, controlKey, discoveryPath, installedPath, normalizePath } from "../control/paths.js";
+import { configDir, controlDir, controlKey, DEFAULT_CONTROL_PORT, discoveryPath, installedPath, normalizePath } from "../control/paths.js";
 import { offFlagPath, offSource, projectOffFlagPath, setRunnerOff } from "../util/off-switch.js";
-import { allocateFreeProjectPort, backupIsCreation, backupOriginalText, configSha, envProxyHint, exemptLoopbackFromProxy, isNpxEntry, isScenarioServer, isWrapped, nodeFlagsToCarry, normaliseRecordKeys, npxHookInvocation, protectBackupText, recordKey, sameServerConfig, PACKAGE_NAME, projectRecord, readSidecar, redactSecrets, restoreSecrets, remoteWrapBlocker, scenarioEntry, editingEnabled, setProjectRecord, settleEditing, settleReplaySwitch, sidecarKey, unwrapEntry, UPSTREAM_HEADERS_ENV, wrapEntry, writeSidecar, SCENARIO_SERVER_KEY, } from "../config/generate.js";
+import { allocateFreeProjectPort, backupIsCreation, backupOriginalText, configSha, envProxyHint, exemptLoopbackFromProxy, isNpxEntry, isScenarioServer, isWrapped, nodeFlagsToCarry, normaliseRecordKeys, npxHookInvocation, protectBackupText, recordKey, sameServerConfig, PACKAGE_NAME, projectRecord, readSidecar, redactSecrets, restoreSecrets, remoteWrapBlocker, scenarioEntry, editingEnabled, setProjectRecord, settleEditing, settleReplaySwitch, sidecarKey, sidecarReadError, stashStands, unwrapEntry, UPSTREAM_HEADERS_ENV, wrapEntry, writeSidecar, SCENARIO_SERVER_KEY, } from "../config/generate.js";
 import { chooseNodePath } from "../config/node-path.js";
 import { claudeUserSettingsPath, managedMcpPolicyBlocker, mcpjsonApprovals } from "../config/mcp-approval.js";
 import { checkOverrides, recordServerName } from "../config/overrides.js";
@@ -56,11 +56,10 @@ import { awaitWithin, isUnhealthyStatus, serviceHealth, serviceTimeoutMs, timeou
 import { runSetup } from "./setup.js";
 import { runUpdate } from "./update.js";
 import { claudeConfigHome, claudeProjectKey, claudeProjectRoot, isRemote, linkedWorktrees, parseJsonFile, projectKeyFor, projectKeysFor, projectScope, resolveServers, } from "../config/resolve.js";
-import { addAllowRules, allowRules, assertEditableJson, BIR_TOOLS_RULE, buildHooksBlock, claudeCodePaths, claudeCodeSetUp, disableMcpjsonServers, enableMcpjsonServers, ENSURE_ARG, ensureGitExcludeLine, hasBirHooks, installHooks, isBirHook, LOCAL_SETTINGS_EXCLUDE, otherHosts, readTextOrNull, removeAllowRules, removeGitExclude, setLocalEntries, setServerEntry, sha256, uninstallHooks, } from "../config/adapters/claude-code.js";
+import { addAllowRules, allowRules, assertEditableJson, BIR_TOOLS_RULE, buildHooksBlock, claudeCodePaths, claudeCodeSetUp, disableMcpjsonServers, enableMcpjsonServers, ENSURE_ARG, ensureGitExcludeLine, hasBirHooks, installHooks, isBirHook, LOCAL_SETTINGS_EXCLUDE, otherHosts, readJsonOrUndefined, readTextOrNull, removeAllowRules, removeGitExclude, setLocalEntries, setServerEntry, sha256, uninstallHooks, UnreadableFileError, } from "../config/adapters/claude-code.js";
 import { writeFileAtomic } from "../util/atomic-write.js";
 import { readGenericServers, setGenericServerEntry } from "../config/adapters/generic.js";
 import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, clearCredentials, deviceLogin, describeAuthService, inspectAuthService, legacyPasswordLogin, tokenLogin, normalizeAuthUrl, rememberAuthUrl, resolveAuthUrl, } from "../auth/client.js";
-import { DEFAULT_CONTROL_PORT } from "../control/server.js";
 import { errText, logLine } from "../util/log.js";
 import { journalPath, readJournal } from "../util/journal.js";
 import { investigateCommand } from "./investigate.js";
@@ -287,10 +286,19 @@ function parseArgs(argv) {
             case "--no-correlation":
                 args.noCorrelation = true;
                 break;
-            case "--port":
-                args.port = Number(argv[++i]);
+            case "--port": {
+                // Digits, and a port a URL can name. `Number("abc")` and a forgotten
+                // value are both NaN, and install then wrote every hook as
+                // http://127.0.0.1:NaN/… — no URL at all, so every hook failed, and
+                // none was recognised as ours to take out again (isBirHook).
+                const raw = argv[++i] ?? "";
+                const port = Number(raw);
+                if (!/^\d+$/.test(raw) || port < 1 || port > 65535)
+                    usage(2);
+                args.port = port;
                 args.portExplicit = true;
                 break;
+            }
             case "--auth-url":
                 args.authUrl = argv[++i];
                 if (!args.authUrl)
@@ -523,11 +531,16 @@ function isClaudeJson(file, claudeJson) {
  * a copy of it in installed.json was also a copy of every project's secrets.
  * Neither is a `--config` file (`entryOnly`), which is usually a client's one
  * global config, with every server's credentials in it. And a `.mcp.json`
- * (the `--mcp-json` shape) is kept without its env and header VALUES
- * (generate.ts, protectBackupText): uninstall reads them back from the file's
- * own entries, and restores it byte-for-byte only when that gives the original
- * exactly. A backup an older runner kept verbatim is converted the same way
- * the next time the file is touched.
+ * (the `--mcp-json` shape) is kept without its env and header VALUES, a
+ * settings file without the values of its own `env` block (generate.ts,
+ * protectBackupText): uninstall reads them back from the file as it is then,
+ * and restores it byte-for-byte only when that gives the original exactly. A
+ * backup an older runner kept verbatim is converted the same way the next
+ * time the file is touched.
+ *
+ * A file that is there and cannot be read throws (readTextOrNull). Taken for a
+ * missing one, it went on record as "created by install" — nothing to restore —
+ * while the write that followed replaced it.
  */
 function backupFile(sidecar, file, claudeJson, entryOnly = false) {
     sidecar.files ??= {};
@@ -616,6 +629,26 @@ function recordedOriginal(record, wrapped) {
         return record.original;
     return restoreSecrets(record.original, wrapped);
 }
+/**
+ * The server a wrapped entry stands for: the original its record stashed,
+ * while the entry still says what that stash says (generate.ts, stashStands);
+ * otherwise what the entry itself says now. `record`: the one that describes
+ * this entry, if there is one.
+ *
+ * The stash used to win for good. A server changed after its first install —
+ * another script after `--`, a key rotated in the entry's env — was then put
+ * back as its first-install self by the next `bir setup`, which re-wrapped the
+ * stash over it ("re-wrapping: its runner moved"), and by `bir uninstall`.
+ * Kept while it stands, it still supplies what a wrapped entry cannot carry
+ * (`oauth`, `headersHelper`, `type: "stdio"`).
+ */
+function wrappedOriginal(record, wrapped) {
+    const now = unwrapEntry(wrapped);
+    const stash = record ? recordedOriginal(record, wrapped) : undefined;
+    if (!stash || !now)
+        return stash ?? now;
+    return stashStands(stash, now) ? stash : now;
+}
 /** Why an existing wrapped entry is being written again, for the log line. */
 function rewrapReason(current, next) {
     if (!current || isRemote(current) || !isWrapped(current))
@@ -665,10 +698,32 @@ function scenarioServerHere(args, cwd) {
         return false;
     }
 }
+/**
+ * installed.json, for a command that is about to change what it describes —
+ * or a refusal. One that is there and cannot be read comes back empty
+ * (generate.ts, readSidecar): an install would then hand this project a new
+ * port and token and rewrite every hook and entry with them, an uninstall
+ * would find no record of anything, and neither could save what it had done.
+ * Both stop here instead, before their first write.
+ */
+function readSidecarOrRefuse() {
+    const sidecar = readSidecar();
+    const unread = sidecarReadError(sidecar);
+    if (unread) {
+        throw new UnreadableFileError(`${unread}; nothing was changed. Make it readable (its permissions, or the program that holds it open), then run this again.`);
+    }
+    return sidecar;
+}
 // ── install ────────────────────────────────────────────────────────────────
 async function install(args) {
     const cwd = process.cwd();
-    const sidecar = readSidecar();
+    // `--config` as a full path from here on. It goes on record, and `bir
+    // uninstall --all` reads that record from whichever directory it is run in:
+    // kept as typed, `client.json` was looked for there, reported as gone, and
+    // the real file stayed wrapped behind an "Uninstalled".
+    if (args.configPath)
+        args = { ...args, configPath: resolvePath(args.configPath) };
+    const sidecar = readSidecarOrRefuse();
     const before = projectRecord(sidecar, cwd);
     const invocation = resolveInvocation(args, before?.invocation, before?.invocationChosen);
     const flagged = args.local || args.global || args.npx;
@@ -696,7 +751,8 @@ async function install(args) {
     }
     // REFUSE BEFORE WRITING ANYTHING. A config with comments or a trailing comma
     // is not JSON; rewriting it would drop the comments (or, worse, the file).
-    // Checking every file up front means a refusal leaves nothing half-done.
+    // One that is there and cannot be read would be replaced outright. Checking
+    // every file up front means a refusal leaves nothing half-done.
     try {
         if (args.configPath)
             assertEditableJson(args.configPath);
@@ -708,8 +764,10 @@ async function install(args) {
         }
     }
     catch (err) {
-        process.stderr.write(`[bir] ${errText(err)}\n` +
-            "[bir] refusing to rewrite it: fix or remove the comments/trailing commas, then run this again. Nothing was changed.\n");
+        const fix = err instanceof UnreadableFileError
+            ? "make it readable (its permissions, or the program that holds it open)"
+            : "fix or remove the comments/trailing commas";
+        process.stderr.write(`[bir] ${errText(err)}\n[bir] refusing to rewrite it: ${fix}, then run this again. Nothing was changed.\n`);
         return 1;
     }
     // An uninstall that found this project's recorder still serving an open
@@ -951,7 +1009,7 @@ function installExplicit(args, cwd, sidecar, gen, named, claudeJson) {
         const found = findRecord(sidecar, cwd, name);
         let source = config;
         if (isWrapped(config)) {
-            source = (found ? recordedOriginal(found.record, config) : undefined) ?? unwrapEntry(config);
+            source = wrappedOriginal(found?.record, config);
             if (!source) {
                 out(`  = ${name} — already wrapped`);
                 continue;
@@ -982,7 +1040,9 @@ function installExplicit(args, cwd, sidecar, gen, named, claudeJson) {
         const reason = rewrapReason(config, proxied);
         backupFile(sidecar, file, claudeJson, true);
         noteWritten(sidecar, file, setGenericServerEntry(file, name, proxied), claudeJson, true);
-        const kept = redactSecrets(found?.record.original ?? source);
+        // What was just wrapped, never an earlier install's stash: the entry may
+        // have been replaced by another server since (see wrappedOriginal).
+        const kept = redactSecrets(source);
         putRecord(sidecar, cwd, name, found, {
             original: kept.config,
             scope: "explicit",
@@ -1133,26 +1193,42 @@ function installClaudeCode(args, cwd, sidecar, gen, named, paths, mcpJsonMode) {
         let source;
         let target;
         const unwrapped = (c) => c !== undefined && isWrapped(c) ? unwrapEntry(c) : c;
-        if (L !== undefined && isWrapped(L) && found?.record.override) {
+        // The record that describes the local entry, if one does: a record of
+        // another scope (an older install's, a `--config` file's) says nothing
+        // about it.
+        const own = found?.record.scope === "local" ? found.record : undefined;
+        // A wrapped local entry is a COPY of the server under it when its record
+        // says so — and, with no record of it (installed.json lost, or
+        // ~/.baseinstrunner deleted), when it still says exactly what that server
+        // says. Without the second half `bir setup` took a record-less copy for
+        // the person's own server and froze the team's definition into its stash:
+        // no later change to `.mcp.json` reached this project, and uninstall left
+        // a plain copy shadowing the team's entry for good. The same comparison
+        // uninstall makes for an entry no record explains (uninstallProject).
+        const copy = L !== undefined && isWrapped(L) && (own ? own.override !== undefined : sameServerConfig(unwrapEntry(L), unwrapped(P ?? U)));
+        if (copy) {
             source = unwrapped(P ?? U);
             target = { kind: "override", from: P !== undefined ? "project" : "user", keys: [...new Set([...overrideKeys, ...holders])] };
             if (source === undefined) {
                 // The server it overrode is gone from .mcp.json and the user scope.
                 setLocalEntries(claudeJson, target.keys, name, null, (cur) => cur !== undefined && isWrapped(cur));
-                delete sidecar.servers[found.key];
+                if (found)
+                    delete sidecar.servers[found.key];
                 out(`  - ${name} — its local copy is removed: the server is no longer configured anywhere else`);
                 continue;
             }
         }
         else if (L !== undefined) {
-            source = isWrapped(L)
-                ? (found?.record.scope === "local" ? recordedOriginal(found.record, L) : undefined) ?? unwrapEntry(L)
-                : L;
+            source = isWrapped(L) ? wrappedOriginal(own, L) : L;
             target = { kind: "inplace", keys: holders };
         }
+        else if (P !== undefined && mcpJsonMode) {
+            source = isWrapped(P) ? wrappedOriginal(found?.record.scope === "project" ? found.record : undefined, P) : P;
+            target = { kind: "mcpjson" };
+        }
         else if (P !== undefined) {
             source = unwrapped(P);
-            target = mcpJsonMode ? { kind: "mcpjson" } : { kind: "override", from: "project", keys: overrideKeys };
+            target = { kind: "override", from: "project", keys: overrideKeys };
         }
         else {
             source = unwrapped(U);
@@ -1247,7 +1323,9 @@ function installClaudeCode(args, cwd, sidecar, gen, named, paths, mcpJsonMode) {
             }
             backupFile(sidecar, paths.mcpJson, claudeJson);
             noteWritten(sidecar, paths.mcpJson, setServerEntry("project", cwd, name, proxied, paths).text, claudeJson);
-            const kept = redactSecrets((found?.record.scope === "project" ? found.record.original : undefined) ?? source);
+            // The stash is what was just wrapped (see wrappedOriginal), not what an
+            // earlier install found here.
+            const kept = redactSecrets(source);
             putRecord(sidecar, cwd, name, found, {
                 original: kept.config,
                 scope: "project",
@@ -1283,7 +1361,10 @@ function installClaudeCode(args, cwd, sidecar, gen, named, paths, mcpJsonMode) {
                 });
             }
             else {
-                const kept = redactSecrets((found?.record.scope === "local" ? found.record.original : undefined) ?? source);
+                // The stash is what is wrapped now. Kept from the first install for
+                // good, it was written back over a server the person had since
+                // replaced: by the next setup, and by uninstall (see wrappedOriginal).
+                const kept = redactSecrets(source);
                 putRecord(sidecar, cwd, name, found, {
                     original: kept.config,
                     scope: "local",
@@ -1607,7 +1688,9 @@ function runnerLeftovers(cwd, sidecar, configPath, otherClaude = []) {
     for (const { file, other } of claudeFiles) {
         let claude = {};
         try {
-            claude = parseJsonFile(file) ?? {};
+            // Strict: one that is there and cannot be read is listed as such, never
+            // read as a file with nothing of ours in it.
+            claude = readJsonOrUndefined(file) ?? {};
         }
         catch (err) {
             unreadable.push(`${file} (${errText(err)})`);
@@ -1634,7 +1717,7 @@ function runnerLeftovers(cwd, sidecar, configPath, otherClaude = []) {
         }
     }
     try {
-        const mcp = parseJsonFile(paths.mcpJson)?.mcpServers;
+        const mcp = readJsonOrUndefined(paths.mcpJson)?.mcpServers;
         for (const [name, config] of Object.entries(mcp ?? {})) {
             if (ourEntry(config))
                 found.push({ name, scope: "project", config, file: paths.mcpJson });
@@ -1690,6 +1773,14 @@ function uninstallProject(cwd, sidecar, opts) {
     const here = normalizePath(cwd);
     const narrow = opts.servers.length > 0;
     const wanted = (name) => !narrow || opts.servers.includes(name);
+    // A `--config` file that an install before this one recorded as it was
+    // typed: relative to the directory that install ran in, not to the one this
+    // runs in (`bir uninstall --all` runs anywhere).
+    for (const record of Object.values(sidecar.servers)) {
+        if (record.scope === "explicit" && typeof record.file === "string" && !isAbsolute(record.file)) {
+            record.file = resolvePath(record.cwd, record.file);
+        }
+    }
     const mine = Object.entries(sidecar.servers)
         .filter(([, record]) => normalizePath(record.cwd) === here)
         .map(([key, record]) => ({ key, record, name: recordName(key, record) }));
@@ -1705,7 +1796,10 @@ function uninstallProject(cwd, sidecar, opts) {
     const claudeFileOf = (record) => (record.scope === "local" || record.scope === "user") && typeof record.file === "string" && record.file
         ? record.file
         : claudeJson;
-    const readClaude = (file = claudeJson) => parseJsonFile(file) ?? {};
+    // Strict, as every read on the way to an undo: a file that is there and
+    // cannot be read throws, and the entry it holds is reported as left, not
+    // as "changed since install" with its record dropped.
+    const readClaude = (file = claudeJson) => readJsonOrUndefined(file) ?? {};
     const currentEntry = (record, name) => {
         if (record.scope === "explicit")
             return readGenericServers(record.file)[name];
@@ -1720,7 +1814,7 @@ function uninstallProject(cwd, sidecar, opts) {
         }
         if (record.scope === "user")
             return readClaude(claudeFileOf(record)).mcpServers?.[name];
-        return parseJsonFile(record.file)?.mcpServers?.[name];
+        return readJsonOrUndefined(record.file)?.mcpServers?.[name];
     };
     /** Put one entry back (or take it out), touching it only while it is still ours. */
     const repair = (record, name) => {
@@ -1736,9 +1830,11 @@ function uninstallProject(cwd, sidecar, opts) {
         const now = currentEntry(record, name);
         if (!ourEntry(now))
             return { what: `left as it is (changed since install)${where}`, done: true };
-        // The stash first; else the original rebuilt from the wrapped entry's own
-        // arguments. An entry left wrapped breaks the day the runner is removed.
-        const restored = record.original === null ? null : (recordedOriginal(record, now) ?? unwrapEntry(now));
+        // The stash, while the wrapped entry still says what it says; else the
+        // original rebuilt from the entry's own arguments (wrappedOriginal) — which
+        // is also what a server changed inside its wrapped entry comes back as.
+        // An entry left wrapped breaks the day the runner is removed.
+        const restored = record.original === null ? null : wrappedOriginal(record, now);
         if (restored === undefined)
             return { what: `left as it is (its original could not be rebuilt)${where}`, done: false };
         if (record.scope === "explicit")
@@ -1786,7 +1882,17 @@ function uninstallProject(cwd, sidecar, opts) {
         for (const [file, backup] of Object.entries(sidecar.files ?? {})) {
             if (isClaudeJson(file, claudeJson) || othersFiles.has(normalizePath(file)) || !ownsFile(file))
                 continue;
-            const current = readTextOrNull(file);
+            let current;
+            try {
+                current = readTextOrNull(file);
+            }
+            catch (err) {
+                // There and not readable: not restored, and not done. The steps below
+                // repair its entries if they can, and this keeps the snapshot and
+                // the records for the next run, which may find it readable.
+                remaining.set(`read:${file}`, `${file} could not be read, so it was not restored (${errText(err)})`);
+                continue;
+            }
             if (current === null || !backup.writtenSha || backup.stale || sha256(current) !== backup.writtenSha)
                 continue;
             if (backupIsCreation(backup)) {
@@ -1935,7 +2041,17 @@ function uninstallProject(cwd, sidecar, opts) {
     if (!narrow) {
         for (const file of [paths.settingsLocal, paths.settings]) {
             const key = `hooks:${normalizePath(file)}`;
-            if (hasBirHooks(file) && !remaining.has(key))
+            if (remaining.has(key))
+                continue;
+            try {
+                readTextOrNull(file);
+            }
+            catch (err) {
+                // hasBirHooks reads such a file as one without hooks.
+                remaining.set(key, `${file} could not be read, so hooks of ours may still be in it (${errText(err)})`);
+                continue;
+            }
+            if (hasBirHooks(file))
                 remaining.set(key, `hooks of ours are still in ${file}`);
         }
     }
@@ -2100,7 +2216,7 @@ async function uninstall(args) {
     if (args.all)
         return uninstallAll(args);
     const cwd = process.cwd();
-    const sidecar = readSidecar();
+    const sidecar = readSidecarOrRefuse();
     // `--replay` on its own is a narrow removal: take the scenario server out and
     // leave every proxy and the hooks exactly as they are. Somebody turning replay
     // off should not have to reinstall recording afterwards.
@@ -2365,7 +2481,7 @@ async function uninstallAll(args) {
         process.stderr.write("[bir] --all removes everything; it takes no --server, --replay or --config\n");
         return 2;
     }
-    const sidecar = readSidecar();
+    const sidecar = readSidecarOrRefuse();
     const paths = claudeCodePaths(process.cwd());
     const projects = installedProjects(sidecar);
     // Every `.claude.json` an install wrote to: this environment's, and any other
@@ -2830,7 +2946,7 @@ function hookFacts(paths) {
                                 facts.ports.push(port);
                         }
                         catch {
-                            /* isBirHook parsed it already */
+                            /* ours, and no URL (isBirHook: a `--port` that was not one): it names no port */
                         }
                     }
                 }

package/dist/bin/investigate.d.ts

@@ -102,6 +102,19 @@ export interface Turn {
         of?: string;
         reason?: string;
     };
+    /**
+     * The plan was retired before any step ran (`replay.vetoed`): the model
+     * changed something itself first, or its `run_scenario` never reached the
+     * runner. `code` from runners after 0.3.26; the reason text always.
+     */
+    vetoed?: {
+        why?: string;
+        code?: string;
+    };
+    /** A direct plan waited through a call that only reads (`replay.direct_waits`, B2 is11.md). */
+    waited?: {
+        tool?: string;
+    };
     /** `replay.*_failed`, `replay.arm_failed`, `replay.diverge`, `replay.handover` … */
     incidents: JournalEntry[];
     events: JournalEntry[];

package/dist/bin/investigate.js

@@ -164,6 +164,12 @@ export function turnsFromJournal(entries) {
             case "run.repeat":
                 turn.repeat = { runId: str(e.run), of: str(e.of), reason: str(e.reason) };
                 break;
+            case "replay.vetoed":
+                turn.vetoed ??= { why: str(e.why), code: str(e.code) };
+                break;
+            case "replay.direct_waits":
+                turn.waited ??= { tool: str(e.tool) };
+                break;
             case "run.finish":
                 turn.finishedAt = e.at;
                 turn.finish = {
@@ -241,6 +247,11 @@ export const DECLINES = {
         cause: "the plan was not ready before the hook that would have announced it had to answer: the prompt hook waits 7.5 s in all, match included, and a tool call that starts a plan mid-task waits 1.5 s. What arming waits for is the reading of the prompt's values (the derivation). A plan that was not announced is never run.",
         fix: "run the prompt again. If it keeps happening the reading is slow: the recorder's log (`bir status` names the file) shows when its `replay.derived` line landed, and a dry replay shows what the service's reading took, under `reading` (`bir scenario replay <scnId> --prompt \"…\" --dry --json`). BIR_HOOK_DERIVE_BUDGET_MS does not help here, because the hook's own limit was reached first. To read values on this machine instead of asking the service, set BIR_DERIVE_API_KEY where Claude Code starts.",
     },
+    // The control server's verdict too: the same plan was cancelled a moment ago.
+    after_cancel: {
+        cause: "the same plan was cancelled a few minutes earlier (Esc on run_scenario, or its caller timed out) after some of its steps had run, so it was not started again: those steps had done their work, and running them twice would add a second row or send a second mail. The agent was told which steps ran, and did the task.",
+        fix: "nothing to do. Ask again after ten minutes if you want the plan to run from its first step. The recorder's log shows the earlier run's `replay.cancelled` line.",
+    },
     // Nor is this one: the match itself was late, so nothing was armed at all.
     match_late: {
         cause: "the service's answer to the match landed too late: after the prompt hook had stopped waiting for it (3 s, BIR_MATCH_BUDGET_MS); while prompts were not waiting on the match at all — after one slow answer they stop waiting for a few minutes (`replay.match_gate state=holding`); or with the hook not waiting from the start, because a failure to reach the service was still on record (a `service.degraded` line, perhaps hours before, and no `service.recovered` until after this prompt) or the match request's first attempt failed. The agent did the task itself.",
@@ -335,6 +346,46 @@ function readingDecline(code, why) {
     }
     return undefined;
 }
+/**
+ * Why a plan that armed ran no step (`replay.vetoed`). The recording page
+ * once said "the runner did not say why" of such a turn, and guessed wrong
+ * (B2 is11.md): the runner had said, here, and only here.
+ */
+function vetoFinding(turn, v) {
+    const why = (v.why ?? "").replace(/ — the plan is retired without running any step$/, "");
+    const scenarioId = turn.plan?.scenarioId ?? turn.matched?.scenarioId ?? "<scnId>";
+    if (v.code === "run_refused" || (!v.code && /\brun_scenario (was called|failed|answered)\b/.test(why))) {
+        return {
+            code: "vetoed_run_refused",
+            severity: "info",
+            title: `The plan was not run: ${why}.`,
+            cause: "run_scenario was refused — by the person, or by a deny rule — or it failed before it reached the runner. Refused means refused: the plan ran no step, and the agent did the task.",
+            fix: "nothing, if it was refused on purpose. If it failed: `bir doctor` shows whether the bir server runs here, and `bir setup` lets Claude Code run it without asking.",
+            evidence: { code: v.code ?? null },
+        };
+    }
+    const tool = /\bfirst call (?:that may change something )?was (\S+), not run_scenario\b/.exec(why)?.[1];
+    if (!v.code) {
+        // Runners up to 0.3.26: any first call retired the plan, and no reason
+        // went with the report.
+        return {
+            code: "vetoed_first_call",
+            severity: "warn",
+            title: `The plan armed, and was not run: ${why}.`,
+            cause: "this runner retires a direct plan at the agent's first call that is not run_scenario, whatever it is — a file read included. A careful agent looks before it runs a plan that writes, the more so when the note names the recording's values where this request has others (another person, another date), and the replay is lost for it: the steps would have taken this request's values.",
+            fix: `update the runner when a version after 0.3.26 is out (\`bir update\`): it keeps the plan through calls that only read, and its note names this request's values in place of the recording's. \`bir scenario show ${scenarioId}\` shows which values the steps read from the request.`,
+            evidence: { tool: tool ?? null },
+        };
+    }
+    return {
+        code: "vetoed_changed_first",
+        severity: "warn",
+        title: `The plan armed, and was not run: ${why}.`,
+        cause: `the agent changed something itself (${tool ?? "a call"}) before it called run_scenario. Run after that, the plan could do the same work twice, so it ran no step and the agent did the task. Calls that only read before it would have kept the plan.`,
+        fix: `nothing is wrong with the plan. Why the agent went its own way is in its first lines of the turn; \`bir scenario show ${scenarioId}\` shows which values the steps read from the request.`,
+        evidence: { code: v.code, tool: tool ?? null },
+    };
+}
 export const LOW_SAVING_PCT = 0.3;
 const usd = (v) => `$${v.toFixed(4)}`;
 const pct = (v) => `${(v * 100).toFixed(1)}%`;
@@ -380,6 +431,17 @@ export function localFindings(turn) {
             fix: "Check the incidents below and `bir doctor`; the service section says whether the scenario is ready.",
         });
     }
+    if (turn.vetoed)
+        out.push(vetoFinding(turn, turn.vetoed));
+    else if (turn.waited) {
+        out.push({
+            code: "direct_waited",
+            severity: "info",
+            title: `The agent's first call only read (${turn.waited.tool ?? "a read"}), and the plan waited for run_scenario.`,
+            cause: "A call that only reads does not retire a direct plan: it ran as the agent wrote it, and the agent was told once that the plan was still ready.",
+            fix: "",
+        });
+    }
     if (turn.plan) {
         const coverage = turn.plan.coverage ?? [];
         const tools = turn.plan.tools ?? [];
@@ -414,10 +476,16 @@ export function localFindings(turn) {
             });
         }
         if (turn.plan.mode === "direct") {
+            const steps = turn.plan.steps ?? coverage.length;
+            // A plan that armed ran nothing when it was retired first, or the turn
+            // reported it not steered: "28 steps ran" of such a turn was false.
+            const ranNone = turn.vetoed !== undefined || turn.reported?.outcome === "not_steered";
             out.push({
                 code: "direct_mode",
                 severity: "info",
-                title: `The plan armed in direct mode: ${turn.plan.steps ?? coverage.length} steps ran on the proxies and the runner, no model in the loop.`,
+                title: ranNone
+                    ? `The plan armed in direct mode, ${steps} steps on the proxies and the runner, and none of them ran.`
+                    : `The plan armed in direct mode: ${steps} steps ran on the proxies and the runner, no model in the loop.`,
                 cause: "Every step is a wrapped MCP tool this session has a proxy for, or a built-in the runner runs itself.",
                 fix: "",
             });
@@ -809,7 +877,9 @@ export async function investigateCommand(args, deps) {
                 : t.decision?.verdict === "no-steer"
                     ? `declined ${t.decision.code ?? ""}`.trim()
                     : t.plan
-                        ? `${t.plan.mode} ${t.done?.outcome ?? t.reported?.outcome ?? "armed"}`
+                        ? `${t.plan.mode} ${t.done?.outcome ?? t.reported?.outcome ?? "armed"}${
+                        // Retired before any step ran: the reason, where the runner gave one.
+                        t.vetoed ? ` (${t.vetoed.code ?? "not run"})` : ""}`
                         : "matched";
             const p = savedPct(t);
             const saved = t.reported?.savedUsd != null ? `  saved ${usd(t.reported.savedUsd)}${p != null ? ` (${pct(p)})` : ""}` : "";

package/dist/bin/scenario-edit.d.ts

@@ -68,6 +68,11 @@ export interface EditReport {
         before: InputStatus;
         after: InputStatus;
         regressed: boolean;
+        /** Its test (autocorrect.md AC5) said yes over the recording and no longer does: then `after` is `not_checked`. */
+        test?: {
+            says: "no" | "throws" | "not_run";
+            error?: string;
+        };
     }>;
     answer: {
         informativeBefore: boolean;

package/dist/bin/scenario-edit.js

@@ -480,7 +480,10 @@ export function renderReport(out, r, opts = {}) {
     }
     else {
         for (const l of regressed) {
-            out(label("later", `step ${l.stepIndex} (${l.toolName ?? "?"}) reproduced before; now it ${laterPhrase(l.after)}`));
+            // A step stopped by its test was not run, so "reproduced before; now it
+            // cannot be checked" said neither what happened nor what was before.
+            const what = l.test ? laterTestPhrase(l.test) : `reproduced before; now it ${laterPhrase(l.after)}`;
+            out(label("later", `step ${l.stepIndex} (${l.toolName ?? "?"}) ${what}`));
         }
     }
     if (r.answer?.informativeBefore && !(brief && r.answer.informativeAfter)) {
@@ -532,6 +535,19 @@ function laterPhrase(status) {
             return status;
     }
 }
+/** What a later step's test says now, over what the changed step emits. */
+function laterTestPhrase(test) {
+    switch (test.says) {
+        case "no":
+            return "— its test said yes over the recording, and now says no";
+        case "throws":
+            return `— its test said yes over the recording, and now throws${test.error ? `: ${test.error}` : ""}`;
+        case "not_run":
+            return "— its test could not be run (it overran a few minutes ago and is held), so it is not known to pass";
+        default:
+            return `— its test now says ${test.says}`;
+    }
+}
 /** A report's `MarkState` or a history entry's `StepState`, in the words the report uses. */
 const markWord = (m) => (m.marked ?? m.nondeterministic)
     ? `needs a judgement (${m.why ?? m.nondeterministicWhy ?? "?"})`