@basein/runner 0.3.25 → 0.3.26

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.js

@@ -241,6 +241,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.",

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 ?? "?"})`

package/dist/config/adapters/claude-code.d.ts

@@ -126,13 +126,44 @@ export declare function otherHostOnly(cwd: string, sidecar: InstalledSidecar): b
 /** Which file holds a given scope's `mcpServers` for this cwd. */
 export declare function fileForScope(scope: Scope, paths: ClaudeCodePaths): string;
 export declare function sha256(text: string): string;
-/** Read a file's text, or null when it does not exist. */
+/**
+ * A config file that is there and cannot be read: its permissions, or a lock
+ * another program holds on it. Its own class so an install can give the advice
+ * that fits it ("make it readable", not "remove the comments").
+ */
+export declare class UnreadableFileError extends Error {
+    constructor(message: string);
+}
+/**
+ * Read a file's text; null when there is no such file, and only then.
+ *
+ * A file that is there and cannot be read throws {@link UnreadableFileError}.
+ * It used to answer null as well, which {@link editJson} takes for "no file":
+ * it built a new one from `{}` plus its own edit and renamed that over the
+ * real one. A settings file that could not be read for a moment was replaced
+ * by one holding nothing but our hooks, exit 0, and its backup said "created
+ * by install".
+ */
 export declare function readTextOrNull(path: string): string | null;
+/**
+ * A JSON file's value for a change to it, or to undo one: undefined when there
+ * is no such file, and only then. One that is there and cannot be read throws
+ * ({@link readTextOrNull}), and so does one that is not JSON.
+ *
+ * parseJsonFile answers undefined for an unreadable file too, which is right
+ * for reading a config and wrong for undoing one: `bir uninstall` read a locked
+ * `~/.claude.json` as one with no entry of ours, said the entry was "changed
+ * since install", dropped its record and ended "Uninstalled." with the entry
+ * still wrapped.
+ */
+export declare function readJsonOrUndefined(path: string): unknown;
 /**
  * Read-modify-write one JSON file, safely:
  *
  *   - a file that is not plain JSON (comments, trailing commas, a torn write)
  *     is REFUSED with an error naming it, never rewritten from a guess;
+ *   - so is one that is there and cannot be read ({@link readTextOrNull}):
+ *     only a file that does not exist is created;
  *   - the file is re-read just before the write, and the edit is applied again
  *     to the fresh text when somebody else changed it in between (Claude Code
  *     rewrites `~/.claude.json` constantly, and a lost update there loses a
@@ -141,13 +172,18 @@ export declare function readTextOrNull(path: string): string | null;
  *     reads a half-written config, and a symlinked file stays a symlink.
  *
  * `mutate` gets a fresh parse each attempt and must not keep state between
- * calls. Returns the text written, for the sidecar's hash.
+ * calls. `opts.mode` is for a file the edit puts a credential in: created
+ * with those permission bits, and set to them when it is already there
+ * (POSIX). Returns the text written, for the sidecar's hash.
  */
-export declare function editJson(path: string, mutate: (parsed: Record<string, unknown>) => void): string;
+export declare function editJson(path: string, mutate: (parsed: Record<string, unknown>) => void, opts?: {
+    mode?: number;
+}): string;
 /**
- * Throw (naming the file) when `path` exists and is not a plain JSON object —
- * so an install can refuse up front, before it has written anything, instead
- * of stopping halfway through with some files changed and others not.
+ * Throw (naming the file) when `path` exists and is not a plain JSON object,
+ * or cannot be read at all — so an install can refuse up front, before it has
+ * written anything, instead of stopping halfway through with some files
+ * changed and others not.
  */
 export declare function assertEditableJson(path: string): void;
 /**
@@ -267,7 +303,9 @@ export declare function buildHooksBlock(controlUrl: string, token: string, opts?
  *   HTTP: a loopback URL (127.0.0.1 / localhost / [::1]) whose path is exactly
  *         one of our routes, AND either our kind of bearer token or a port in
  *         the range `bir` allocates (the token-less 0.2.8 shape). A hook to
- *         `https://hooks.example.com/session/end` is somebody else's.
+ *         `https://hooks.example.com/session/end` is somebody else's. One
+ *         whose URL is no URL (`http://127.0.0.1:NaN/tool/pre`, from a
+ *         `--port` that was not a number) needs the token as well as the route.
  *   exec: our self-starting SessionStart hook — `bir-hooks.js ensure`, or the
  *         npx form `… -p @basein/runner@<v> bir-hooks ensure`.
  */
@@ -277,6 +315,12 @@ export declare function isBirHook(entry: unknown): boolean;
  * the new text. Our own entries are replaced rather than appended, so repeated
  * installs stay idempotent — hook by hook: a user's own hook that happens to
  * share a matcher group with one of ours stays exactly where it is.
+ *
+ * The file is left readable by its owner only (0600). The block carries the
+ * recorder's bearer token, which is enough to make the recorder run a
+ * scenario, and its two other copies (the discovery file, installed.json) are
+ * 0600 already: at the default 0644 any other account on the machine could
+ * read it here.
  */
 export declare function installHooks(settingsPath: string, block: HooksBlock): string;
 /** Remove only our hook entries, and drop events left empty. */