@basein/runner 0.3.25 → 0.3.27

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. */

package/dist/config/adapters/claude-code.js

@@ -21,12 +21,12 @@
  * clone, and never the user scope, which applies to every project.
  */
 import { createHash } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, parse as parsePath, resolve as resolvePath } from "node:path";
 import { normalizePath } from "../../control/paths.js";
 import { writeFileAtomic } from "../../util/atomic-write.js";
 import { FIRST_PROJECT_PORT, PACKAGE_NAME, SCENARIO_SERVER_KEY, projectRecord, } from "../generate.js";
-import { claudeJsonPath, parseJsonFile, parseJsonText, projectKeyFor, } from "../resolve.js";
+import { claudeJsonPath, parseJsonFile, parseJsonText, projectKeyFor, readFailure, } from "../resolve.js";
 export function claudeCodePaths(cwd, claudeJsonOverride) {
     return {
         claudeJson: claudeJsonPath(claudeJsonOverride),
@@ -162,7 +162,7 @@ export function enableMcpjsonServers(settingsPath, names) {
 }
 /** Undo {@link enableMcpjsonServers} for `names`; drops the key when empty. */
 export function disableMcpjsonServers(settingsPath, names) {
-    const parsed = parseJsonFile(settingsPath);
+    const parsed = readJsonOrUndefined(settingsPath);
     if (!parsed || !Array.isArray(parsed.enabledMcpjsonServers))
         return undefined;
     if (!parsed.enabledMcpjsonServers.map(String).some((n) => names.includes(n)))
@@ -300,13 +300,70 @@ export function fileForScope(scope, paths) {
 export function sha256(text) {
     return createHash("sha256").update(text).digest("hex");
 }
-/** 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 class UnreadableFileError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnreadableFileError";
+    }
+}
+/**
+ * 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 function readTextOrNull(path) {
     try {
-        return existsSync(path) ? readFileSync(path, "utf8") : null;
+        return readFileSync(path, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        // ENOTDIR: a folder on the way is a file, so nothing can be there either.
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return null;
+        throw new UnreadableFileError(`${path} exists but cannot be read (${readFailure(err)})`);
+    }
+}
+/**
+ * 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 function readJsonOrUndefined(path) {
+    const text = readTextOrNull(path);
+    return text === null ? undefined : parseJsonText(text, path);
+}
+/**
+ * Set a file's permission bits before it is written again. The write keeps
+ * the mode a file already has (util/atomic-write.ts), so one created 0644
+ * would stay readable by everybody with a token in it; changed first, the new
+ * text never exists under the old mode. POSIX only, and best effort: a file
+ * that is not there yet is created with the mode instead, and one whose mode
+ * is not ours to change is written all the same.
+ */
+function restrictMode(path, mode) {
+    if (process.platform === "win32")
+        return;
+    try {
+        chmodSync(path, mode);
     }
     catch {
-        return null;
+        /* not there yet, or somebody else's: never a failed install */
     }
 }
 /**
@@ -314,6 +371,8 @@ export function readTextOrNull(path) {
  *
  *   - 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
@@ -322,9 +381,11 @@ export function readTextOrNull(path) {
  *     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 function editJson(path, mutate) {
+export function editJson(path, mutate, opts = {}) {
     for (let attempt = 0;; attempt += 1) {
         const before = readTextOrNull(path);
         const value = before === null ? {} : parseJsonText(before, path);
@@ -337,14 +398,22 @@ export function editJson(path, mutate) {
         if (attempt < 3 && readTextOrNull(path) !== before)
             continue;
         mkdirSync(dirname(path), { recursive: true });
-        writeFileAtomic(path, text);
+        if (opts.mode === undefined)
+            writeFileAtomic(path, text);
+        else {
+            restrictMode(path, opts.mode);
+            // The mode wins over the old file's even when that chmod was refused:
+            // what is written now is ours, and holds the token.
+            writeFileAtomic(path, text, { mode: opts.mode, replaceMode: true });
+        }
         return text;
     }
 }
 /**
- * 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 function assertEditableJson(path) {
     const text = readTextOrNull(path);
@@ -535,26 +604,36 @@ const OUR_TOKEN = /^Bearer [0-9a-f]{64}$/i;
  *   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`.
  */
 export function isBirHook(entry) {
     const e = (entry ?? {});
     if (typeof e.url === "string" && e.url) {
+        const auth = e.headers?.Authorization;
+        const ourToken = typeof auth === "string" && OUR_TOKEN.test(auth);
         let url;
         try {
             url = new URL(e.url);
         }
         catch {
-            return false;
+            // `bir install --port abc`, or `--port` with its value forgotten, once
+            // wrote http://127.0.0.1:NaN/<route>. No parser reads that, so it was
+            // nobody's hook, and neither install nor uninstall ever took it out.
+            // Ours all the same — but only as all three together: the address
+            // install writes, one of our routes, our kind of token. There is no
+            // port here to vouch for it, and no query or fragment is ever ours.
+            const broken = /^http:\/\/127\.0\.0\.1:[^/?#]*(\/[^?#]*)$/.exec(e.url);
+            return broken !== null && ourToken && HOOK_ROUTES.some(({ route }) => broken[1] === route);
         }
         if (!["127.0.0.1", "localhost", "[::1]"].includes(url.hostname))
             return false;
         if (!HOOK_ROUTES.some(({ route }) => url.pathname === route))
             return false;
-        const auth = e.headers?.Authorization;
-        if (typeof auth === "string" && OUR_TOKEN.test(auth))
+        if (ourToken)
             return true;
         const port = Number(url.port);
         return port >= FIRST_PROJECT_PORT && port < FIRST_PROJECT_PORT + 200;
@@ -574,6 +653,12 @@ export function isBirHook(entry) {
  * 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 function installHooks(settingsPath, block) {
     return editJson(settingsPath, (parsed) => {
@@ -585,11 +670,13 @@ export function installHooks(settingsPath, block) {
             hooks[event] = [...existing, ...matchers];
         }
         parsed.hooks = hooks;
-    });
+    }, { mode: 0o600 });
 }
 /** Remove only our hook entries, and drop events left empty. */
 export function uninstallHooks(settingsPath) {
-    const parsed = parseJsonFile(settingsPath);
+    // Strict: a file that cannot be read throws, so the caller says the hooks
+    // may still be there, rather than nothing at all.
+    const parsed = readJsonOrUndefined(settingsPath);
     if (!parsed?.hooks)
         return undefined;
     return editJson(settingsPath, (fresh) => {

package/dist/config/generate.d.ts

@@ -262,6 +262,27 @@ export declare function redactSecrets(config: McpServerConfig): {
  * would break it, so the caller leaves the entry alone instead.
  */
 export declare function restoreSecrets(stash: McpServerConfig, wrapped: McpServerConfig | undefined): McpServerConfig | undefined;
+/**
+ * True while a wrapped entry still says what its stash says. `unwrapped` is
+ * the entry read back ({@link unwrapEntry}), `stash` the original an install
+ * kept for it, values included. They agree when the entry starts the same
+ * program with the same arguments and env (or names the same URL, transport
+ * and headers), and every other field it carries has the stash's value.
+ *
+ * False means somebody changed the server inside its wrapped entry — another
+ * script after `--`, a rotated key, a `disabled` the client switched — and the
+ * stash describes a server that is no longer there.
+ *
+ * The stash is compared as a wrap of it reads back, not as it is written: a
+ * wrapped entry cannot carry `oauth`, `headersHelper` or `type: "stdio"` at
+ * all ({@link REGENERATED_FIELDS}), so set beside the stash itself it would
+ * always look changed. For the same reason a field only the stash has is no
+ * disagreement: an entry a runner before 0.3.0 wrote carries none of the
+ * client's own fields (`disabled`, `timeout`, …). Counted as changes, all of
+ * these would be dropped from the stash by the next install, and from the
+ * server by uninstall.
+ */
+export declare function stashStands(stash: McpServerConfig, unwrapped: McpServerConfig): boolean;
 /**
  * The entry for the scenario server itself. Not a proxy: it wraps nothing and
  * spawns nothing, it just forwards one call to the control server.
@@ -343,14 +364,16 @@ export interface FileBackup {
     stale?: boolean;
     /**
      * A `.mcp.json` whose servers carry env or header VALUES (API keys, bearer
-     * tokens) is not kept verbatim — that would be a second long-lived copy of
-     * them under ~/.baseinstrunner. Its text is kept with each value's literal
-     * replaced by a placeholder, and {@link FileBackup.originalText} stays null;
-     * uninstall reads the values back from the entries in the file (wrapped or
-     * not) and restores the file byte-for-byte only when the result hashes to
-     * `sha`, the original's. See {@link protectBackupText}. A runner older than
-     * this field (0.2.12) reads the backup as a file install created, and never
-     * writes it back whole.
+     * tokens), or a Claude Code settings file with an `env` block of its own
+     * (`{"env":{"ANTHROPIC_API_KEY":"sk-…"}}`), is not kept verbatim — that
+     * would be a second long-lived copy of them under ~/.baseinstrunner. Its
+     * text is kept with each value's literal replaced by a placeholder, and
+     * {@link FileBackup.originalText} stays null; uninstall reads the values
+     * back from the file as it is then (its servers' entries, wrapped or not,
+     * and its own `env`) and restores the file byte-for-byte only when the
+     * result hashes to `sha`, the original's. See {@link protectBackupText}. A
+     * runner older than this field (0.2.12) reads the backup as a file install
+     * created, and never writes it back whole.
      */
     redacted?: RedactedText;
 }
@@ -360,9 +383,14 @@ export interface RedactedText {
     text: string;
     /** sha256 of the original text: a restore is used only when it matches. */
     sha: string;
-    /** Placeholder `i` is the value of `mcpServers[server][field][key]`. */
+    /**
+     * Placeholder `i` is the value of `mcpServers[server][field][key]` — or,
+     * with no `server`, of the file's own top-level `env[key]`. A runner that
+     * predates the second kind looks for it under `mcpServers`, finds nothing,
+     * cannot fill the placeholder, and repairs the file entry by entry instead.
+     */
     secrets: Array<{
-        server: string;
+        server?: string;
         field: "env" | "headers";
         key: string;
     }>;
@@ -380,9 +408,10 @@ export declare function protectBackupText(text: string): FileBackup;
 /**
  * The text a backup restores: its verbatim original, or the redacted one with
  * every value read back from `currentText` — the file as it is now, whose
- * entries (wrapped by us, or left as they were) carry those values. Null for a
- * file install created; undefined when the original cannot be rebuilt exactly
- * (a value is gone, or the result does not hash to the original's).
+ * entries (wrapped by us, or left as they were) and own `env` block carry
+ * those values. Null for a file install created; undefined when the original
+ * cannot be rebuilt exactly (a value is gone, or the result does not hash to
+ * the original's).
  */
 export declare function backupOriginalText(backup: FileBackup, currentText: string | null): string | null | undefined;
 /** True when a backup says the file did not exist before install (nothing to restore). */
@@ -526,7 +555,23 @@ export interface InstalledSidecar {
     /** Settings files whose `hooks` block we added, for a clean uninstall. */
     hookFiles?: string[];
 }
+/**
+ * installed.json, or an empty sidecar when there is none, or none that can be
+ * used. A file that does not parse reads as empty and is copied aside before
+ * the next write replaces it ({@link writeSidecar}).
+ *
+ * One that is there and cannot be READ (its permissions, a lock another
+ * program holds) reads as empty too, so a recorder or `bir status` goes on —
+ * but that sidecar is never written back. Saved, it replaced every project's
+ * originals, ports and tokens with whatever one command had just added.
+ * {@link sidecarReadError} lets a command that is about to write say so first.
+ */
 export declare function readSidecar(): InstalledSidecar;
+/**
+ * Why installed.json could not be read when `sidecar` was made from it
+ * ({@link readSidecar}); undefined when it was read, or is not there.
+ */
+export declare function sidecarReadError(sidecar: InstalledSidecar): string | undefined;
 /**
  * The prefix of the key a record is kept under when its stash has its
  * secrets blanked ({@link InstalledRecord.secretsRedacted}).
@@ -560,6 +605,9 @@ export declare function normaliseRecordKeys(servers: Record<string, InstalledRec
  * ports with nothing. Before that happens the unreadable file is copied aside
  * as `installed.json.corrupt-<time>`, where a person (or support) can get the
  * originals back.
+ *
+ * A sidecar made up for a file that could not be read at all is refused: there
+ * is nothing to copy aside, and it knows nothing of what the file holds.
  */
 export declare function writeSidecar(sidecar: InstalledSidecar): void;
 export declare function sidecarKey(cwd: string, serverName: string): string;

package/dist/config/generate.js

@@ -17,7 +17,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { createServer } from "node:net";
 import { configDir, ensureDir, installedPath, normalizePath } from "../control/paths.js";
 import { writeFileAtomic } from "../util/atomic-write.js";
-import { isRemote } from "./resolve.js";
+import { isRemote, readFailure } from "./resolve.js";
 /** npm package name, as it appears in a generated `npx -p` invocation. */
 export const PACKAGE_NAME = "@basein/runner";
 /**
@@ -462,6 +462,38 @@ export function restoreSecrets(stash, wrapped) {
     }
     return { ...stash, env };
 }
+/**
+ * True while a wrapped entry still says what its stash says. `unwrapped` is
+ * the entry read back ({@link unwrapEntry}), `stash` the original an install
+ * kept for it, values included. They agree when the entry starts the same
+ * program with the same arguments and env (or names the same URL, transport
+ * and headers), and every other field it carries has the stash's value.
+ *
+ * False means somebody changed the server inside its wrapped entry — another
+ * script after `--`, a rotated key, a `disabled` the client switched — and the
+ * stash describes a server that is no longer there.
+ *
+ * The stash is compared as a wrap of it reads back, not as it is written: a
+ * wrapped entry cannot carry `oauth`, `headersHelper` or `type: "stdio"` at
+ * all ({@link REGENERATED_FIELDS}), so set beside the stash itself it would
+ * always look changed. For the same reason a field only the stash has is no
+ * disagreement: an entry a runner before 0.3.0 wrote carries none of the
+ * client's own fields (`disabled`, `timeout`, …). Counted as changes, all of
+ * these would be dropped from the stash by the next install, and from the
+ * server by uninstall.
+ */
+export function stashStands(stash, unwrapped) {
+    const again = unwrapEntry(wrapEntry(stash, { serverName: "stash" }));
+    if (!again || isRemote(again) !== isRemote(unwrapped))
+        return false;
+    // `?? null`: an entry with no command at all (a client's `{ "url": … }`
+    // with no `type` is read as stdio) comes back from its wrap as `command: null`.
+    const said = (c) => isRemote(c) ? [c.type, c.url, c.headers ?? {}] : [c.command ?? null, c.args ?? [], c.env ?? {}];
+    if (!sameServerConfig(said(again), said(unwrapped)))
+        return false;
+    const kept = again;
+    return Object.entries(unwrapped).every(([field, value]) => REGENERATED_FIELDS.has(field) || sameServerConfig(value, kept[field]));
+}
 /**
  * The entry for the scenario server itself. Not a proxy: it wraps nothing and
  * spawns nothing, it just forwards one call to the control server.
@@ -485,24 +517,32 @@ export function isScenarioServer(config) {
 function secretPlaceholder(i) {
     return `"@@bir-secret-${i}@@"`;
 }
-/** The env and header values of every server in a parsed `{ mcpServers }` file, in order. */
+/**
+ * The values a parsed config file holds that are credentials more often than
+ * not, in order: its own top-level `env` (a Claude Code settings file's), then
+ * the env and headers of every server under `mcpServers`.
+ */
 function secretValues(parsed) {
-    const servers = parsed?.mcpServers;
-    if (!servers || typeof servers !== "object" || Array.isArray(servers))
-        return [];
     const found = [];
+    const collect = (values, where) => {
+        if (!values || typeof values !== "object" || Array.isArray(values))
+            return;
+        for (const [key, value] of Object.entries(values)) {
+            if (typeof value === "string" && value !== "")
+                found.push({ ...where, key, value });
+        }
+    };
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return found;
+    collect(parsed.env, { field: "env" });
+    const servers = parsed.mcpServers;
+    if (!servers || typeof servers !== "object" || Array.isArray(servers))
+        return found;
     for (const [server, config] of Object.entries(servers)) {
         if (!config || typeof config !== "object")
             continue;
-        for (const field of ["env", "headers"]) {
-            const values = config[field];
-            if (!values || typeof values !== "object" || Array.isArray(values))
-                continue;
-            for (const [key, value] of Object.entries(values)) {
-                if (typeof value === "string" && value !== "")
-                    found.push({ server, field, key, value });
-            }
-        }
+        for (const field of ["env", "headers"])
+            collect(config[field], { server, field });
     }
     return found;
 }
@@ -569,9 +609,10 @@ function fillSecrets(redacted, values) {
 /**
  * The text a backup restores: its verbatim original, or the redacted one with
  * every value read back from `currentText` — the file as it is now, whose
- * entries (wrapped by us, or left as they were) carry those values. Null for a
- * file install created; undefined when the original cannot be rebuilt exactly
- * (a value is gone, or the result does not hash to the original's).
+ * entries (wrapped by us, or left as they were) and own `env` block carry
+ * those values. Null for a file install created; undefined when the original
+ * cannot be rebuilt exactly (a value is gone, or the result does not hash to
+ * the original's).
  */
 export function backupOriginalText(backup, currentText) {
     if (backup.originalText !== null)
@@ -588,6 +629,12 @@ export function backupOriginalText(backup, currentText) {
     }
     const servers = (parsed?.mcpServers ?? {});
     const values = redacted.secrets.map(({ server, field, key }) => {
+        if (server === undefined) {
+            // The file's own `env` block, which nothing of ours rewrites.
+            const own = parsed?.env;
+            const value = own && typeof own === "object" ? own[key] : undefined;
+            return typeof value === "string" ? value : undefined;
+        }
         const entry = servers[server];
         if (!entry || typeof entry !== "object")
             return undefined;
@@ -603,12 +650,40 @@ export function backupOriginalText(backup, currentText) {
 export function backupIsCreation(backup) {
     return backup.originalText === null && !backup.redacted;
 }
+/**
+ * The sidecars {@link readSidecar} had to make up because installed.json is
+ * there and could not be read, and why — so that {@link writeSidecar} refuses
+ * exactly those.
+ */
+const unreadSidecars = new WeakMap();
+/**
+ * installed.json, or an empty sidecar when there is none, or none that can be
+ * used. A file that does not parse reads as empty and is copied aside before
+ * the next write replaces it ({@link writeSidecar}).
+ *
+ * One that is there and cannot be READ (its permissions, a lock another
+ * program holds) reads as empty too, so a recorder or `bir status` goes on —
+ * but that sidecar is never written back. Saved, it replaced every project's
+ * originals, ports and tokens with whatever one command had just added.
+ * {@link sidecarReadError} lets a command that is about to write say so first.
+ */
 export function readSidecar() {
     const path = installedPath();
-    if (!existsSync(path))
-        return { version: 1, servers: {} };
+    let text;
     try {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        text = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        const empty = { version: 1, servers: {} };
+        const code = err.code;
+        // Not there (ENOTDIR: nor could it be) is a machine nothing was installed on.
+        if (code !== "ENOENT" && code !== "ENOTDIR") {
+            unreadSidecars.set(empty, `${path} exists but cannot be read (${readFailure(err)})`);
+        }
+        return empty;
+    }
+    try {
+        const parsed = JSON.parse(text);
         const sidecar = { version: 1, servers: parsed.servers ?? {}, ...parsed };
         sidecar.servers ??= {};
         normaliseRecordKeys(sidecar.servers);
@@ -618,6 +693,13 @@ export function readSidecar() {
         return { version: 1, servers: {} };
     }
 }
+/**
+ * Why installed.json could not be read when `sidecar` was made from it
+ * ({@link readSidecar}); undefined when it was read, or is not there.
+ */
+export function sidecarReadError(sidecar) {
+    return unreadSidecars.get(sidecar);
+}
 /**
  * The prefix of the key a record is kept under when its stash has its
  * secrets blanked ({@link InstalledRecord.secretsRedacted}).
@@ -685,8 +767,14 @@ export function normaliseRecordKeys(servers) {
  * ports with nothing. Before that happens the unreadable file is copied aside
  * as `installed.json.corrupt-<time>`, where a person (or support) can get the
  * originals back.
+ *
+ * A sidecar made up for a file that could not be read at all is refused: there
+ * is nothing to copy aside, and it knows nothing of what the file holds.
  */
 export function writeSidecar(sidecar) {
+    const unread = unreadSidecars.get(sidecar);
+    if (unread)
+        throw new Error(`${unread}; it is not written over`);
     // Whoever built the record, it lands under the key its stash calls for.
     normaliseRecordKeys((sidecar.servers ??= {}));
     ensureDir(configDir());

package/dist/config/resolve.d.ts

@@ -59,6 +59,11 @@ export interface ResolveOptions {
 export declare function isRemote(config: McpServerConfig): config is RemoteServerConfig;
 /** Parse a JSON file. `undefined` if absent; throws if present but malformed. */
 export declare function parseJsonFile(path: string): unknown;
+/**
+ * Why a file could not be read, as one phrase: Node's own text without the
+ * `, open '<path>'` it ends in, since the caller names the file itself.
+ */
+export declare function readFailure(err: unknown): string;
 /**
  * Parse the text of a JSON file (BOM tolerated). Throws, naming `path`, when
  * it is not JSON — a file with comments (JSONC) included, which is exactly the

package/dist/config/resolve.js

@@ -51,6 +51,13 @@ export function parseJsonFile(path) {
     }
     return parseJsonText(raw, path);
 }
+/**
+ * Why a file could not be read, as one phrase: Node's own text without the
+ * `, open '<path>'` it ends in, since the caller names the file itself.
+ */
+export function readFailure(err) {
+    return (err instanceof Error ? err.message : String(err)).replace(/, \w+ '.*'$/, "");
+}
 /**
  * Parse the text of a JSON file (BOM tolerated). Throws, naming `path`, when
  * it is not JSON — a file with comments (JSONC) included, which is exactly the