@basein/runner 0.2.12 → 0.3.1

package/dist/config/generate.js

@@ -7,13 +7,16 @@
  * model-visible edit (a non-goal) as well as a broken scenario corpus.
  *
  * Reversibility is not an afterthought (Phase 7.4): the original entry is stashed
- * verbatim in `~/.baseinstrunner/installed.json` before anything is rewritten, so
- * `bir uninstall` restores exactly what was there — including fields
+ * in `~/.baseinstrunner/installed.json` before anything is rewritten — verbatim
+ * but for its env and header VALUES, which uninstall reads back from the wrapped
+ * entry — so `bir uninstall` restores exactly what was there, including fields
  * BaseInstRunner never understood.
  */
+import { createHash } from "node:crypto";
 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";
 /** npm package name, as it appears in a generated `npx -p` invocation. */
 export const PACKAGE_NAME = "@basein/runner";
@@ -32,15 +35,177 @@ export function packageSpec(version) {
  * model, and a collision would route that call somewhere else entirely.
  */
 export const SCENARIO_SERVER_KEY = "bir";
+/** The node flags `bir` knows how to carry into everything it sets up. */
+const CARRIED_FLAGS = ["--use-system-ca", "--use-env-proxy"];
+/** True when an HTTP(S) proxy is configured in `env` (either spelling). */
+export function proxyConfigured(env = process.env) {
+    return Boolean(env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy);
+}
+/**
+ * True when NO_PROXY (either spelling) sends 127.0.0.1 straight to the socket.
+ *
+ * `--use-env-proxy` sends EVERY request through HTTP(S)_PROXY — the runner's own
+ * loopback traffic too: the hooks' recorder, a proxy registering, `bir setup`
+ * waiting for the recorder — unless NO_PROXY exempts the address. Measured on
+ * Node 24: `127.0.0.1`, `*` and a suffix such as `.0.0.1` do; `localhost`,
+ * `127.0.0.0/8` and `127.*` do not. Node and undici disagree on which spelling
+ * wins when both are set, so every one that is set must exempt it.
+ */
+export function loopbackBypassesProxy(env = process.env) {
+    const values = [env.NO_PROXY, env.no_proxy].filter((v) => typeof v === "string" && v.trim() !== "");
+    if (values.length === 0)
+        return false;
+    return values.every((value) => value
+        .split(/[\s,]+/)
+        .map((e) => e.trim().toLowerCase())
+        .some((e) => e === "*" || e === "127.0.0.1" || (e.startsWith(".") && "127.0.0.1".endsWith(e))));
+}
+/** The addresses to add to NO_PROXY so the runner's loopback traffic skips the proxy. */
+export const LOOPBACK_NO_PROXY = "127.0.0.1,localhost,::1";
+/**
+ * What to tell a person whose proxy the runner will NOT use, or undefined. A
+ * proxy with a NO_PROXY that does not name 127.0.0.1 would swallow the runner's
+ * own loopback calls, so `--use-env-proxy` is left out rather than break every
+ * hook; the service is then reached directly, if at all.
+ */
+export function envProxyHint(env = process.env) {
+    if (!proxyConfigured(env) || loopbackBypassesProxy(asStarted(env)) || !nodeKnowsFlag("--use-env-proxy"))
+        return undefined;
+    return (`HTTPS_PROXY/HTTP_PROXY is set but NO_PROXY does not name 127.0.0.1, so the runner does not use the proxy ` +
+        `(it would swallow the runner's own loopback calls). Set NO_PROXY=${LOOPBACK_NO_PROXY} (plus your own entries) ` +
+        "and run `bir setup` again so the runner reaches the service through it");
+}
+/**
+ * Make THIS process's loopback fetches skip the proxy when it runs with
+ * `--use-env-proxy` and NO_PROXY does not already exempt them: a launcher
+ * written behind a proxy keeps the flag after the shell's NO_PROXY changes.
+ * undici re-reads NO_PROXY per request, so fetch honours the change; so does
+ * every process started from here (a recorder `bir up` launches). Returns true
+ * when it changed anything. The flags carried into the entries are decided
+ * from the environment as it was ({@link nodeFlagsToCarry}).
+ */
+export function exemptLoopbackFromProxy(env = process.env, execArgv = process.execArgv) {
+    if (!execArgv.includes("--use-env-proxy") || !proxyConfigured(env) || loopbackBypassesProxy(env))
+        return false;
+    if (env === process.env)
+        originalNoProxy ??= { NO_PROXY: env.NO_PROXY, no_proxy: env.no_proxy };
+    const add = (value) => (value && value.trim() ? `${value},${LOOPBACK_NO_PROXY}` : LOOPBACK_NO_PROXY);
+    const lower = env.no_proxy;
+    env.NO_PROXY = add(env.NO_PROXY);
+    // On Windows the two spellings are one variable; elsewhere both are fixed.
+    if (lower !== undefined && env.no_proxy === lower)
+        env.no_proxy = add(lower);
+    return true;
+}
+/** NO_PROXY as it was before {@link exemptLoopbackFromProxy} changed it. */
+let originalNoProxy;
+/**
+ * `env` as this process was started with it: the entries and hooks run in the
+ * user's environment, not in one this process has since exempted its own
+ * loopback in.
+ */
+function asStarted(env) {
+    return env === process.env && originalNoProxy ? { ...env, ...originalNoProxy } : env;
+}
+/** True when this Node knows `flag` (a cheap, spawn-free probe). */
+function nodeKnowsFlag(flag) {
+    try {
+        return process.allowedNodeEnvironmentFlags.has(flag);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The node flags this process was started with that everything it sets up
  * should share. The install scripts run `bir setup` with `--use-system-ca`
  * when the Node supports it; a hook, a proxy or a recorder started without it
  * would then fail the first TLS-inspected upload while the install itself
  * succeeded.
+ *
+ * `--use-env-proxy` is carried the same way, and added when HTTPS_PROXY or
+ * HTTP_PROXY is set and this Node knows the flag: Node's `fetch` ignores those
+ * variables otherwise, so behind a proxy-only network every service call waited
+ * out a connect timeout. A FLAG rather than `NODE_USE_ENV_PROXY=1` in the
+ * entries' env on purpose: `bir-proxy` hands its environment to the user's own
+ * MCP server, and that server's networking is not ours to change.
+ *
+ * ONLY WHEN NO_PROXY EXEMPTS 127.0.0.1 ({@link loopbackBypassesProxy}). With the
+ * flag, Node sends the runner's loopback calls to the proxy too, which refuses
+ * or swallows them: the SessionStart hook could not see its own recorder, the
+ * proxies could not register, and `bir setup` timed out — on a network where
+ * all of that worked without the flag. So without that exemption the flag is
+ * neither added nor carried, and {@link envProxyHint} says what to set.
+ */
+export function nodeFlagsToCarry(execArgv = process.execArgv, env = process.env) {
+    const envProxyOk = loopbackBypassesProxy(asStarted(env));
+    const flags = execArgv.filter((a) => CARRIED_FLAGS.includes(a) && (a !== "--use-env-proxy" || envProxyOk));
+    if (!flags.includes("--use-env-proxy") && envProxyOk && proxyConfigured(env) && nodeKnowsFlag("--use-env-proxy")) {
+        flags.push("--use-env-proxy");
+    }
+    return [...new Set(flags)];
+}
+/** Fields a wrapped entry regenerates, so they are never copied from the original. */
+const REGENERATED_FIELDS = new Set(["type", "url", "headers", "headersHelper", "oauth", "command", "args", "env"]);
+/**
+ * The env variable a wrapped REMOTE entry carries its upstream's static
+ * headers in: a JSON object, `{"Header-Name": "value", …}`. bir-proxy reads it
+ * (merged with any `--header K:V` arguments, which an entry an older runner
+ * wrote still has), and never hands it to a stdio upstream. In the env rather
+ * than on the command line because argv is visible to every local user
+ * (`ps`, /proc), and a header is usually a credential.
+ */
+export const UPSTREAM_HEADERS_ENV = "BIR_UPSTREAM_HEADERS";
+/**
+ * The headers in a wrapped entry's {@link UPSTREAM_HEADERS_ENV}, or none. Only
+ * string values count; anything unreadable is no headers rather than an error.
+ */
+export function upstreamHeadersFromEnv(env) {
+    const raw = env?.[UPSTREAM_HEADERS_ENV];
+    if (!raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        return Object.fromEntries(Object.entries(parsed).filter((e) => typeof e[1] === "string"));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * `npx … <bin>`, pinned and offline-first, for an MCP server entry.
+ *
+ * Plain `npx` on every platform, Windows included. Claude Code spawns MCP
+ * servers through cross-spawn, which resolves `npx` to `npx.cmd` and escapes
+ * each argument for cmd.exe the way cmd.exe reads it. Wrapping the entry in
+ * `cmd /c` instead hands cmd.exe a line it parses itself — and everything after
+ * `--` is the user's own server invocation: `?a=1&b=2` in a URL ran `b=2` as a
+ * command, `|` and `>` piped or redirected the proxy's stdout, `^1.2.0` lost its
+ * caret and `%VAR%` was expanded. `platform` is accepted and ignored.
+ */
+export function npxInvocation(bin, version, _platform = process.platform) {
+    return { command: "npx", args: [...(version ? ["--prefer-offline"] : []), "-y", "-p", packageSpec(version), bin] };
+}
+/**
+ * `npx … <bin>` for a COMMAND HOOK (the SessionStart `bir-hooks ensure`).
+ *
+ * Claude Code spawns a hook's exec form directly, without cross-spawn's
+ * `.cmd` resolution, so on native Windows it keeps `cmd /c` — safe there
+ * because every argument is ours: a pinned package spec, a bin name and
+ * fixed flags, never a user's text.
  */
-export function nodeFlagsToCarry(execArgv = process.execArgv) {
-    return execArgv.filter((a) => a === "--use-system-ca");
+export function npxHookInvocation(bin, version, platform = process.platform) {
+    const plain = npxInvocation(bin, version);
+    return platform === "win32" ? { command: "cmd", args: ["/c", "npx", ...plain.args] } : plain;
+}
+/** True when an entry is spawned through npx (with or without `cmd /c`). */
+export function isNpxEntry(config) {
+    if (isRemote(config))
+        return false;
+    const argv = config.args ?? [];
+    return config.command === "npx" || (/^cmd(\.exe)?$/i.test(config.command) && argv[0] === "/c" && argv[1] === "npx");
 }
 /** True when this entry already points at `bir-proxy` — makes install idempotent. */
 export function isWrapped(config) {
@@ -60,12 +225,6 @@ export function wrapEntry(config, opts) {
         proxyArgs.push("--no-correlation");
     if (isRemote(config)) {
         proxyArgs.push("--url", config.url, "--transport", config.type);
-        for (const [key, value] of Object.entries(config.headers ?? {})) {
-            // §9: the proxy holds the credential for a remote upstream, because the
-            // host's own OAuth now authenticates *us*. It is passed at spawn and never
-            // written to BaseInstRunner's own state.
-            proxyArgs.push("--header", `${key}:${value}`);
-        }
     }
     else {
         proxyArgs.push("--", config.command, ...(config.args ?? []));
@@ -73,26 +232,245 @@ export function wrapEntry(config, opts) {
     const env = {};
     if (opts.controlUrl)
         env.BIR_CONTROL_URL = opts.controlUrl;
-    if (!isRemote(config)) {
+    if (isRemote(config)) {
+        // §9: the proxy holds the credential for a remote upstream, because the
+        // host's own OAuth now authenticates *us*. It travels in the entry's env,
+        // not on the command line, where any local user's `ps` could read it.
+        // Values go in verbatim: Claude Code expands a `${VAR}` in an env value
+        // when it spawns the proxy. The install sidecar keeps the header NAMES
+        // only (see redactSecrets).
+        const headers = config.headers ?? {};
+        if (Object.keys(headers).length > 0)
+            env[UPSTREAM_HEADERS_ENV] = JSON.stringify(headers);
+    }
+    else {
         for (const [key, value] of Object.entries(config.env ?? {}))
             env[key] = value;
     }
     const invocation = opts.invocation ?? "npx";
-    const entry = invocation !== "npx" && opts.proxyPath
-        ? { command: process.execPath, args: [...(opts.nodeFlags ?? []), opts.proxyPath, ...proxyArgs] }
-        : { command: "npx", args: ["-y", "-p", packageSpec(opts.version), "bir-proxy", ...proxyArgs] };
+    const spawnAs = invocation !== "npx" && opts.proxyPath
+        ? { command: opts.node ?? process.execPath, args: [...(opts.nodeFlags ?? []), opts.proxyPath] }
+        : npxInvocation("bir-proxy", opts.version);
+    // Everything else the client understands about this server stays as it was:
+    // a `"disabled": true` server must not come back to life through the proxy,
+    // and a per-server auto-approve list must not quietly disappear.
+    const extra = {};
+    for (const [key, value] of Object.entries(config)) {
+        if (!REGENERATED_FIELDS.has(key))
+            extra[key] = value;
+    }
+    const entry = { ...extra, command: spawnAs.command, args: [...spawnAs.args, ...proxyArgs] };
     if (Object.keys(env).length > 0)
         entry.env = env;
     return entry;
 }
+/**
+ * Rebuild the original entry from a wrapped one — for an entry wrapped by an
+ * older runner or on another machine (nothing stashed here), and for remote
+ * header values, which the sidecar does not keep. `undefined` when `wrapped`
+ * is not an entry `wrapEntry` could have produced.
+ */
+export function unwrapEntry(wrapped) {
+    if (isRemote(wrapped) || !isWrapped(wrapped))
+        return undefined;
+    const argv = wrapped.args ?? [];
+    const at = argv.findIndex((a) => /(^|[\\/])bir-proxy(\.js)?$/.test(a));
+    if (at < 0)
+        return undefined;
+    const rest = argv.slice(at + 1);
+    let url;
+    let transport;
+    // A current entry carries its headers in its env; an older one as
+    // `--header K:V` arguments, read below.
+    const headers = upstreamHeadersFromEnv(wrapped.env);
+    let upstream;
+    for (let i = 0; i < rest.length; i += 1) {
+        const a = rest[i];
+        if (a === "--") {
+            upstream = rest.slice(i + 1);
+            break;
+        }
+        if (a === "--url")
+            url = rest[++i];
+        else if (a === "--transport")
+            transport = rest[++i];
+        else if (a === "--header") {
+            const raw = rest[++i] ?? "";
+            const sep = raw.indexOf(":");
+            if (sep > 0)
+                headers[raw.slice(0, sep)] = raw.slice(sep + 1);
+        }
+        else if (a === "--server-name")
+            i += 1;
+    }
+    const extra = {};
+    for (const [key, value] of Object.entries(wrapped)) {
+        if (!REGENERATED_FIELDS.has(key))
+            extra[key] = value;
+    }
+    if (url) {
+        const remote = { ...extra, type: transport === "sse" ? "sse" : "http", url };
+        if (Object.keys(headers).length > 0)
+            remote.headers = headers;
+        return remote;
+    }
+    if (!upstream || upstream.length === 0)
+        return undefined;
+    const stdio = { ...extra, command: upstream[0] };
+    if (upstream.length > 1)
+        stdio.args = upstream.slice(1);
+    const env = { ...(wrapped.env ?? {}) };
+    delete env.BIR_CONTROL_URL;
+    if (Object.keys(env).length > 0)
+        stdio.env = env;
+    return stdio;
+}
+/**
+ * The options `wrapEntry` was given for `wrapped`, read back from the entry:
+ * the interpreter, its flags and the proxy script (or the npx spec), the
+ * control URL and `--no-correlation`. What lets a local copy be re-generated
+ * over a changed source without knowing how `bir install` was run.
+ */
+export function wrapOptionsOf(wrapped) {
+    if (isRemote(wrapped) || !isWrapped(wrapped))
+        return undefined;
+    const argv = wrapped.args ?? [];
+    const at = argv.findIndex((a) => /(^|[\\/])bir-proxy(\.js)?$/.test(a));
+    if (at < 0)
+        return undefined;
+    const end = argv.indexOf("--", at + 1);
+    const proxyArgs = argv.slice(at + 1, end < 0 ? undefined : end);
+    const controlUrl = wrapped.env?.BIR_CONTROL_URL;
+    const common = { controlUrl, noCorrelation: proxyArgs.includes("--no-correlation") || undefined };
+    if (isNpxEntry(wrapped)) {
+        const spec = argv.find((a) => a.startsWith(`${PACKAGE_NAME}@`));
+        // No platform: an entry an unreleased build wrote as `cmd /c npx …` is
+        // re-generated in the plain shape, which is the point (npxInvocation).
+        return { ...common, invocation: "npx", version: spec ? spec.slice(PACKAGE_NAME.length + 1) : undefined };
+    }
+    return { ...common, invocation: "global", node: wrapped.command, nodeFlags: argv.slice(0, at), proxyPath: argv[at] };
+}
+/**
+ * An entry in the one shape two spellings of the same server share: keys
+ * sorted, `type: "stdio"` (optional in Claude Code's files) dropped, and empty
+ * `args` / `env` dropped (a wrapped entry cannot tell them from absent ones).
+ */
+function canonicalServer(config) {
+    const sort = (v) => Array.isArray(v)
+        ? v.map(sort)
+        : v && typeof v === "object"
+            ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sort(v[k])]))
+            : v;
+    if (!config || typeof config !== "object" || Array.isArray(config))
+        return sort(config);
+    const copy = { ...config };
+    if (copy.type === "stdio")
+        delete copy.type;
+    if (Array.isArray(copy.args) && copy.args.length === 0)
+        delete copy.args;
+    if (copy.env && typeof copy.env === "object" && Object.keys(copy.env).length === 0)
+        delete copy.env;
+    return sort(copy);
+}
+/** Two entries that say the same thing, whatever order or optional spelling they were written in. */
+export function sameServerConfig(a, b) {
+    return a !== undefined && b !== undefined && JSON.stringify(canonicalServer(a)) === JSON.stringify(canonicalServer(b));
+}
+/**
+ * A fingerprint of an entry (see {@link canonicalServer}), kept in an
+ * override's record so a later change to the entry it copied is noticed —
+ * without keeping the entry, whose env and headers are credentials.
+ */
+export function configSha(config) {
+    return createHash("sha256").update(JSON.stringify(canonicalServer(config))).digest("hex");
+}
+/** Header names that carry a credential. */
+const CREDENTIAL_HEADER = /authorization|api[-_]?key|token|secret|cookie|^x-.*key$/i;
+/**
+ * Whether a remote entry can be wrapped without breaking it.
+ *
+ * The proxy can only send what the entry spells out. A server Claude Code signs
+ * in itself — OAuth through `/mcp`, a `headersHelper` script, `${VAR}` headers
+ * Claude Code expands — would reach the upstream with no credentials, answer
+ * 401 on every call, and lose the "Authenticate" option in `/mcp` because the
+ * entry is now a stdio one. Those are left unwrapped: their calls are still
+ * recorded by the PreToolUse/PostToolUse hooks. Only an entry carrying a
+ * literal credential header is wrapped by default; `--server <name>` wraps
+ * any other one anyway.
+ */
+export function remoteWrapBlocker(config) {
+    if (config.oauth !== undefined)
+        return "it is signed in through Claude Code (an oauth block)";
+    if (config.headersHelper !== undefined)
+        return "its headers come from a headersHelper only Claude Code runs";
+    const headers = Object.entries(config.headers ?? {});
+    if (headers.length === 0)
+        return "it has no static credentials, so Claude Code signs it in (OAuth)";
+    if (headers.some(([, v]) => String(v).includes("${")))
+        return "its headers use ${VAR} expansion only Claude Code performs";
+    if (!headers.some(([k]) => CREDENTIAL_HEADER.test(k)))
+        return "it carries no credential header, so Claude Code signs it in (OAuth)";
+    return undefined;
+}
+/**
+ * `config` as the sidecar keeps it: a remote entry's header VALUES and a stdio
+ * entry's env VALUES are dropped — they are credentials more often than not
+ * (API keys, database URLs, bearer tokens), and a second long-lived copy of
+ * them in installed.json is exposure for nothing. The names stay; uninstall
+ * reads the values back from the wrapped entry, which carries them verbatim
+ * (and carries a key the user rotated since, which a stash would not).
+ */
+export function redactSecrets(config) {
+    const blank = (values) => Object.fromEntries(Object.keys(values).map((key) => [key, ""]));
+    if (isRemote(config)) {
+        if (!config.headers || Object.keys(config.headers).length === 0)
+            return { config, redacted: false };
+        return { config: { ...config, headers: blank(config.headers) }, redacted: true };
+    }
+    if (!config.env || Object.keys(config.env).length === 0)
+        return { config, redacted: false };
+    return { config: { ...config, env: blank(config.env) }, redacted: true };
+}
+/**
+ * Undo {@link redactSecrets}: the stash, with every redacted value read back
+ * from `wrapped`. Undefined when a value cannot be found there (the wrapped
+ * entry was changed or removed) — restoring an entry without its credentials
+ * would break it, so the caller leaves the entry alone instead.
+ */
+export function restoreSecrets(stash, wrapped) {
+    const back = wrapped ? unwrapEntry(wrapped) : undefined;
+    if (!back)
+        return undefined;
+    if (isRemote(stash)) {
+        if (!isRemote(back))
+            return undefined;
+        const headers = {};
+        for (const key of Object.keys(stash.headers ?? {})) {
+            if (back.headers?.[key] === undefined)
+                return undefined;
+            headers[key] = back.headers[key];
+        }
+        return { ...stash, headers };
+    }
+    if (isRemote(back))
+        return undefined;
+    const env = {};
+    for (const key of Object.keys(stash.env ?? {})) {
+        if (back.env?.[key] === undefined)
+            return undefined;
+        env[key] = back.env[key];
+    }
+    return { ...stash, env };
+}
 /**
  * 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.
  */
 export function scenarioEntry(opts) {
-    const entry = opts.invocation && opts.invocation !== "npx" && opts.scenarioPath
-        ? { command: process.execPath, args: [...(opts.nodeFlags ?? []), opts.scenarioPath] }
-        : { command: "npx", args: ["-y", "-p", packageSpec(opts.version), "bir-scenario"] };
+    const spawnAs = opts.invocation && opts.invocation !== "npx" && opts.scenarioPath
+        ? { command: opts.node ?? process.execPath, args: [...(opts.nodeFlags ?? []), opts.scenarioPath] }
+        : npxInvocation("bir-scenario", opts.version);
+    const entry = { command: spawnAs.command, args: spawnAs.args };
     if (opts.controlUrl)
         entry.env = { BIR_CONTROL_URL: opts.controlUrl };
     return entry;
@@ -103,21 +481,231 @@ export function isScenarioServer(config) {
         return false;
     return /\bbir-scenario\b/.test([config.command, ...(config.args ?? [])].join(" "));
 }
+/** The placeholder literal for secret `i` (with its JSON quotes). */
+function secretPlaceholder(i) {
+    return `"@@bir-secret-${i}@@"`;
+}
+/** The env and header values of every server in a parsed `{ mcpServers }` file, in order. */
+function secretValues(parsed) {
+    const servers = parsed?.mcpServers;
+    if (!servers || typeof servers !== "object" || Array.isArray(servers))
+        return [];
+    const 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 });
+            }
+        }
+    }
+    return found;
+}
+/**
+ * The backup of a project file's pre-install text, as installed.json keeps it
+ * (SEC-8): verbatim when it holds no env or header value; otherwise with every
+ * such value's literal replaced by a placeholder ({@link FileBackup.redacted}).
+ * When that cannot be done exactly — a value spelled with escapes, a text that
+ * does not parse, a placeholder already in the text — no text is kept at all
+ * and the file is repaired entry by entry on uninstall (`stale`), which loses
+ * the byte-for-byte restore and nothing else.
+ */
+export function protectBackupText(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+    }
+    catch {
+        return { originalText: text, writtenSha: "" };
+    }
+    const values = secretValues(parsed);
+    if (values.length === 0)
+        return { originalText: text, writtenSha: "" };
+    const unprotected = { originalText: null, writtenSha: "", stale: true };
+    if (text.includes("@@bir-secret-"))
+        return unprotected;
+    const secrets = [];
+    const byValue = new Map();
+    for (const v of values) {
+        if (byValue.has(v.value))
+            continue;
+        byValue.set(v.value, secrets.length);
+        secrets.push({ server: v.server, field: v.field, key: v.key });
+    }
+    // Longest first, so a short value cannot eat into a longer one's literal.
+    let redactedText = text;
+    for (const [value, i] of [...byValue].sort((a, b) => b[0].length - a[0].length)) {
+        const literal = JSON.stringify(value);
+        if (!redactedText.includes(literal))
+            return unprotected;
+        redactedText = redactedText.split(literal).join(secretPlaceholder(i));
+    }
+    const redacted = { text: redactedText, sha: sha256Hex(text), secrets };
+    // Proven now, not hoped for at uninstall: the values put back give the original, exactly.
+    const values_ = secrets.map((s) => values.find((v) => v.server === s.server && v.field === s.field && v.key === s.key)?.value);
+    if (fillSecrets(redacted, values_) !== text)
+        return unprotected;
+    return { originalText: null, writtenSha: "", redacted };
+}
+function sha256Hex(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/** The redacted text with each placeholder's value put back; undefined when a value is missing. */
+function fillSecrets(redacted, values) {
+    let text = redacted.text;
+    for (let i = 0; i < redacted.secrets.length; i += 1) {
+        const value = values[i];
+        if (value === undefined)
+            return undefined;
+        text = text.split(secretPlaceholder(i)).join(JSON.stringify(value));
+    }
+    return text;
+}
+/**
+ * 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).
+ */
+export function backupOriginalText(backup, currentText) {
+    if (backup.originalText !== null)
+        return backup.originalText;
+    const redacted = backup.redacted;
+    if (!redacted)
+        return null;
+    let parsed;
+    try {
+        parsed = currentText === null ? undefined : JSON.parse(currentText.charCodeAt(0) === 0xfeff ? currentText.slice(1) : currentText);
+    }
+    catch {
+        return undefined;
+    }
+    const servers = (parsed?.mcpServers ?? {});
+    const values = redacted.secrets.map(({ server, field, key }) => {
+        const entry = servers[server];
+        if (!entry || typeof entry !== "object")
+            return undefined;
+        const plain = isWrapped(entry) ? unwrapEntry(entry) : entry;
+        const bag = plain?.[field];
+        const value = bag?.[key];
+        return typeof value === "string" ? value : undefined;
+    });
+    const text = fillSecrets(redacted, values);
+    return text !== undefined && sha256Hex(text) === redacted.sha ? text : undefined;
+}
+/** True when a backup says the file did not exist before install (nothing to restore). */
+export function backupIsCreation(backup) {
+    return backup.originalText === null && !backup.redacted;
+}
 export function readSidecar() {
     const path = installedPath();
     if (!existsSync(path))
         return { version: 1, servers: {} };
     try {
         const parsed = JSON.parse(readFileSync(path, "utf8"));
-        return { version: 1, servers: parsed.servers ?? {}, ...parsed };
+        const sidecar = { version: 1, servers: parsed.servers ?? {}, ...parsed };
+        sidecar.servers ??= {};
+        normaliseRecordKeys(sidecar.servers);
+        return sidecar;
     }
     catch {
         return { version: 1, servers: {} };
     }
 }
+/**
+ * The prefix of the key a record is kept under when its stash has its
+ * secrets blanked ({@link InstalledRecord.secretsRedacted}).
+ *
+ * A runner older than redaction (0.2.12) finds its records by the exact key
+ * `<cwd>::<name>`, or by that prefix, and writes `original` back VERBATIM: on
+ * a rollback (`BIR_VERSION=0.2.12`, a second `bir` earlier on PATH, `npx
+ * @basein/runner@0.2.12`) its `bir uninstall` would put a server back with its
+ * API key blanked, the key's only copy — the wrapped entry — overwritten. Under
+ * this prefix it finds no record, says nothing to undo for that server, and
+ * leaves the wrapped entry, credentials and all, alone. Records it can restore
+ * correctly (no env, no headers, or an `original: null`) keep the old key.
+ */
+export const REDACTED_KEY_PREFIX = "v2|";
+/** The key a record for `serverName` in `cwd` belongs under, redacted or not. */
+export function recordKey(cwd, serverName, redacted = false) {
+    return `${redacted ? REDACTED_KEY_PREFIX : ""}${sidecarKey(cwd, serverName)}`;
+}
+/**
+ * Put every record under the key its stash calls for ({@link REDACTED_KEY_PREFIX}):
+ * a redacted record written under the plain key (by an earlier build, or by
+ * code that wrote the plain key) moves out of an older runner's sight, and
+ * two records for one server — one per key shape, left by installs of both
+ * versions — become the newer one. Returns true when anything moved.
+ */
+export function normaliseRecordKeys(servers) {
+    let changed = false;
+    for (const key of Object.keys(servers)) {
+        const record = servers[key];
+        if (!record || typeof record !== "object")
+            continue;
+        const redacted = key.startsWith(REDACTED_KEY_PREFIX);
+        const bare = redacted ? key.slice(REDACTED_KEY_PREFIX.length) : key;
+        const wanted = record.secretsRedacted === true ? `${REDACTED_KEY_PREFIX}${bare}` : bare;
+        if (wanted === key)
+            continue;
+        const other = servers[wanted];
+        if (!other || (record.installedAt ?? 0) >= (other.installedAt ?? 0))
+            servers[wanted] = record;
+        delete servers[key];
+        changed = true;
+    }
+    // One server under both shapes (a 0.2.12 install after a new one): the newer wins.
+    for (const key of Object.keys(servers)) {
+        if (!key.startsWith(REDACTED_KEY_PREFIX))
+            continue;
+        const bare = key.slice(REDACTED_KEY_PREFIX.length);
+        const plain = servers[bare];
+        if (!plain)
+            continue;
+        if ((plain.installedAt ?? 0) > (servers[key].installedAt ?? 0))
+            delete servers[key];
+        else
+            delete servers[bare];
+        changed = true;
+    }
+    return changed;
+}
+/**
+ * Write the sidecar so no reader ever sees half of it (a recorder that read a
+ * torn file used to start with a random token and refuse every hook).
+ *
+ * `readSidecar` answers an empty sidecar for a file it cannot parse, so the
+ * next write would silently replace every project's originals, tokens and
+ * 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.
+ */
 export function writeSidecar(sidecar) {
+    // Whoever built the record, it lands under the key its stash calls for.
+    normaliseRecordKeys((sidecar.servers ??= {}));
     ensureDir(configDir());
-    writeFileSync(installedPath(), JSON.stringify(sidecar, null, 2), { mode: 0o600 });
+    const path = installedPath();
+    try {
+        if (existsSync(path)) {
+            const current = readFileSync(path, "utf8");
+            try {
+                JSON.parse(current);
+            }
+            catch {
+                writeFileSync(`${path}.corrupt-${Date.now()}`, current, { mode: 0o600 });
+            }
+        }
+    }
+    catch {
+        /* unreadable: nothing to keep */
+    }
+    writeFileAtomic(path, JSON.stringify(sidecar, null, 2), { mode: 0o600 });
 }
 export function sidecarKey(cwd, serverName) {
     return `${cwd}::${serverName}`;
@@ -186,6 +774,27 @@ export async function allocateFreeProjectPort(sidecar, cwd) {
     }
     return allocateProjectPort(sidecar, cwd);
 }
+/**
+ * A new port for a project whose recorded one this machine will no longer let
+ * it bind (a Hyper-V/WSL/Docker exclusion that moved after a reboot, or another
+ * program). The lowest free one no other project holds, never `avoid`;
+ * `undefined` when none of the 200 is free. The caller rewrites the hooks and
+ * every wrapped entry's control URL — `bir setup` does, by re-running install.
+ */
+export async function allocateReplacementPort(sidecar, cwd, avoid) {
+    const key = normalizePath(cwd);
+    const taken = new Set(Object.entries(sidecar.projects ?? {})
+        .filter(([k]) => k !== key)
+        .map(([, r]) => r.port));
+    taken.add(avoid);
+    for (let port = FIRST_PROJECT_PORT; port < FIRST_PROJECT_PORT + 200; port += 1) {
+        if (taken.has(port))
+            continue;
+        if (await probeFreePort(port))
+            return port;
+    }
+    return undefined;
+}
 /** Merge `patch` into the record for `cwd`, creating it when absent. */
 export function setProjectRecord(sidecar, cwd, patch) {
     sidecar.projects ??= {};
@@ -214,4 +823,42 @@ export function setEditing(sidecar, cwd, on) {
         return undefined;
     return setProjectRecord(sidecar, cwd, { port: record.port, editing: on });
 }
+/**
+ * Keep this project's stored replay switch ({@link ReplayPolicy.enabled}) in
+ * line with what the person asked for, so the recorder never steers — or runs
+ * steps unattended — in a project that did not opt in. It used to default to
+ * on everywhere: `bir setup --no-replay` printed "replay not installed" while
+ * the recorder replayed matched prompts anyway, and a direct plan named a
+ * delivery tool the session did not have.
+ *
+ *   refused  → off, unless it is off already.
+ *   unasked  → off, but only while the switch was never set and no scenario
+ *              server is here (a project that has one keeps it — a plain
+ *              `bir install --server x` must not take replay away — and
+ *              `bir replay on|off` is the person's to keep).
+ *   wanted   → on again, but only when an install turned it off; a
+ *              `bir replay off` stays off.
+ *
+ * Returns what changed, or undefined. The caller writes the sidecar.
+ */
+export function settleReplaySwitch(sidecar, cwd, intent, scenarioServerHere) {
+    const record = projectRecord(sidecar, cwd);
+    if (!record)
+        return undefined;
+    const policy = { ...(record.replay ?? {}) };
+    if (intent === "wanted") {
+        if (policy.enabled !== false || policy.disabledBy !== "install")
+            return undefined;
+        delete policy.enabled;
+        delete policy.disabledBy;
+        setProjectRecord(sidecar, cwd, { port: record.port, replay: Object.keys(policy).length > 0 ? policy : undefined });
+        return "on";
+    }
+    if (policy.enabled === false)
+        return undefined;
+    if (intent === "unasked" && (policy.enabled !== undefined || scenarioServerHere))
+        return undefined;
+    setProjectRecord(sidecar, cwd, { port: record.port, replay: { ...policy, enabled: false, disabledBy: "install" } });
+    return "off";
+}
 //# sourceMappingURL=generate.js.map