@basein/runner 0.2.11 → 0.3.0

package/dist/bin/bir.js

@@ -4,17 +4,18 @@
  *
  *   bir setup [--auth-url <url>] [--token <t>] [--project <dir>]   ← the one command
  *   bir up [--restart] | bir down
+ *   bir off [--here] | bir on [--here]   ← the kill switch: inert at once, nothing uninstalled
  *   bir install [--config <path>] [--server <name>]… [--local] [--no-hooks]
- *   bir uninstall [--config <path>]
+ *   bir uninstall [--config <path>] [--server <name>]… | bir uninstall --all
  *   bir status
- *   bir doctor
+ *   bir doctor [--quick]
  *   bir wrap --server-name <key> -- <command> [args…]
  *   bir login | logout
  *   bir --version
  *
- *   bir scenario list | show <runId|scnId> [--step <n>] | calc <runId> [--force [--discard-edits]]
+ *   bir scenario list | show <runId|scnId> [--step <n>] | calc <runId|scnId> [--force [--discard-edits]]
  *   bir scenario check|edit <runId|scnId> --step <n> --input-logic <file|-> …   ← fix one step
- *   bir scenario edits | undo <runId|scnId> [--edit <sedit_id>]
+ *   bir scenario edits | undo <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
  *   bir scenario editing on|off|status   ← may this project's `bir` MCP server change a scenario?
  *   bir scenario replay <scnId> --prompt "…" [--dry]  |  bir replay status|on|off|allow …
  *   bir investigate [<id>] | list | executions
@@ -22,115 +23,157 @@
  * The `scenario` words that read or change one step live in scenario-edit.ts
  * (editSteps.md in the BaseIn repository); `investigate` in investigate.ts.
  *
- * `bir install` is reversible by construction: every file it edits is stashed
- * verbatim first, so `bir uninstall` restores it byte-for-byte unless somebody
- * else edited it in the meantime (in which case it repairs the entries and says
- * so). `bir doctor` proves the install *works* by asking the control server which
+ * `bir install` is reversible by construction: every project file it edits is
+ * stashed verbatim first, so `bir uninstall` restores it byte-for-byte unless
+ * somebody else edited it in the meantime (in which case it repairs the entries
+ * and says so); `~/.claude.json` and a `--config` file are always repaired entry
+ * by entry. What install writes is chosen so it cannot break a working setup:
+ * wrapped copies go to this project's local scope (never the team's `.mcp.json`,
+ * never the user scope), a remote server Claude Code signs in itself is left
+ * alone, and a file that is not plain JSON is refused rather than rewritten.
+ * `bir doctor` proves the install *works* by asking the control server which
  * proxies actually registered — never by reading the config file back, and never
  * from `serverInfo`, which must stay the upstream's (Phase 3).
  */
 import { randomBytes } from "node:crypto";
-import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve as resolvePath } from "node:path";
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ControlClient } from "../control/client.js";
-import { readDiscovery } from "../control/discovery.js";
-import { ensureDaemon, stopDaemon } from "../control/daemon.js";
-import { configDir, discoveryPath, normalizePath } from "../control/paths.js";
-import { allocateFreeProjectPort, isScenarioServer, isWrapped, nodeFlagsToCarry, PACKAGE_NAME, packageSpec, projectRecord, readSidecar, scenarioEntry, setProjectRecord, sidecarKey, wrapEntry, writeSidecar, SCENARIO_SERVER_KEY, } from "../config/generate.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 { 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, setProjectRecord, settleReplaySwitch, sidecarKey, unwrapEntry, UPSTREAM_HEADERS_ENV, wrapEntry, writeSidecar, SCENARIO_SERVER_KEY, } from "../config/generate.js";
+import { chooseNodePath } from "../config/node-path.js";
+import { managedMcpPolicyBlocker, mcpjsonApprovals } from "../config/mcp-approval.js";
+import { checkOverrides, recordServerName } from "../config/overrides.js";
+import { awaitWithin, isUnhealthyStatus, serviceHealth, serviceTimeoutMs, timeoutSignal } from "../util/service-health.js";
 import { runSetup } from "./setup.js";
-import { isRemote, parseJsonFile, resolveServers } from "../config/resolve.js";
-import { buildHooksBlock, claudeCodePaths, disableMcpjsonServers, enableMcpjsonServers, ensureGitExclude, fileForScope, hasBirHooks, installHooks, isBirHook, LOCAL_SETTINGS_EXCLUDE, readTextOrNull, removeGitExclude, setServerEntry, sha256, uninstallHooks, } from "../config/adapters/claude-code.js";
+import { claudeConfigHome, claudeProjectKey, claudeProjectRoot, isRemote, linkedWorktrees, parseJsonFile, projectKeyFor, projectKeysFor, projectScope, resolveServers, } from "../config/resolve.js";
+import { assertEditableJson, buildHooksBlock, claudeCodePaths, disableMcpjsonServers, enableMcpjsonServers, ENSURE_ARG, ensureGitExcludeLine, hasBirHooks, installHooks, isBirHook, LOCAL_SETTINGS_EXCLUDE, readTextOrNull, removeGitExclude, setLocalEntries, setServerEntry, sha256, uninstallHooks, } 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, deviceLogin, describeAuthService, legacyPasswordLogin, tokenLogin, logout, normalizeAuthUrl, rememberAuthUrl, resolveAuthUrl, } from "../auth/client.js";
+import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, clearCredentials, deviceLogin, describeAuthService, legacyPasswordLogin, tokenLogin, normalizeAuthUrl, rememberAuthUrl, resolveAuthUrl, } from "../auth/client.js";
 import { DEFAULT_CONTROL_PORT } from "../control/server.js";
-import { errText } from "../util/log.js";
+import { errText, logLine } from "../util/log.js";
 import { journalPath, readJournal } from "../util/journal.js";
 import { investigateCommand } from "./investigate.js";
 import { SCENARIO_EDIT_SUBCOMMANDS, scenarioEditCommand } from "./scenario-edit.js";
 import { loadCredentials } from "../auth/client.js";
 import { packageVersion } from "../util/version.js";
 const VERSION = packageVersion();
+/**
+ * The npx SessionStart hook's own budget, passed as `ensure --budget-ms <n>`
+ * (bin/bir-hooks.ts, control/ensure-hook.ts). npx resolves the package — about
+ * a second cached, more when it has to look — before the hook's clock starts,
+ * and the host cancels the hook at ENSURE_TIMEOUT_S (15 s): the default 11 s
+ * budget plus its 0.5 s ceiling left npx under 3.5 s. 8 s leaves it 6.5.
+ */
+const NPX_ENSURE_BUDGET_ARGS = ["--budget-ms", "8000"];
 const out = (line = "") => {
     process.stdout.write(line + "\n");
 };
 function usage(code = 0) {
-    out(`bir ${VERSION} — a recording MCP proxy
-
-Commands:
-  setup       the one command: sign in, wire this project, start the recorder
-  up          start the recorder for this project in the background (--restart: replace it)
-  down        stop it
-  install     wrap this project's MCP servers and wire Claude Code's hooks
-  uninstall   restore everything install changed
-  status      what is installed for this directory
-  doctor      is it actually working right now?
-  wrap        print a proxied entry for one server (any MCP client)
-  login       sign in to the BaseIn service (opens your browser)
-  logout      revoke this machine's session and forget it
-
-  scenario list                     recorded runs and their calculated scenarios
-  scenario show <runId|scnId> [--step <n>]
-                                    a scenario: intent, params, steps (--step: just that one)
-  scenario calc <runId> [--force [--discard-edits]]
-                                    calculate (or re-derive) a run's scenario
-  scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze]
-                                    try a change to one step against the recording; saves nothing
-  scenario edit <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
-                [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>]
-                                    the same check, and save the change if it passes
-  scenario edits <runId|scnId>      a scenario's hand edits, newest first
-  scenario undo <runId|scnId> [--edit <sedit_id>]
-                                    put a step back as it was before its newest edit
-  scenario editing on|off|status    whether this project's bir MCP server offers the tools
-                                    that change a scenario (restart Claude Code after)
-  scenario replay <scnId> --prompt "…" [--dry]
-  replay --scenario <scnId> --prompt "…" [--dry]
-  replay status | on | off | allow <a,b> | allow all
-                                    this project's replay switches, kept for the background recorder
-
-  investigate [<id>]                why the newest turn here (or run_/scn_/sexec_ <id>) did what
-                                    it did, what it cost, what to fix — journal + service
-  investigate list [--limit <n>]    recent turns in this directory and their verdicts
-  investigate executions [--limit <n>] [--user <email|id>]
-                                    the ledger, newest first (--user: admins only)
-
-Options:
-  --config <path>   an explicit { "mcpServers": … } file, for clients with no adapter
-  --server <name>   restrict install/uninstall to one server (repeatable)
-  --local           invoke this checkout's bir-proxy instead of npx (development)
-  --global          invoke the installed package by absolute path instead of npx
-                    (no registry round trip, no PATH lookup — what a fleet wants)
-  --no-hooks        do not touch .claude/settings.local.json (Tier 2 recording only)
-  --no-correlation  never relax tool schemas; join steps on argument fingerprints
-  --replay          install/remove the scenario server, enabling calculated replay
-  --port <n>        install/setup: control-server port to write into the hook URLs
-                    (default: this project's, else the lowest free one from ${DEFAULT_CONTROL_PORT})
-  --json            machine-readable output for status / doctor / scenario / investigate
-                    (scenario check|edit|edits|undo: the service's answer, unchanged)
-  --dry             replay against recorded outputs only; run no real tools
-  --force           scenario calc: recalculate in place · scenario edit: save although
-                    the check refused it (needs --note; only for a recording that was wrong)
-  --step <n>        scenario show|check|edit: the step, by the stepIndex \`show\` prints
-  --input-logic <file|->   scenario check|edit: the new input logic, from a file or stdin (-)
-  --output-logic <file|->  scenario check|edit: the new output logic, from a file or stdin (-)
-  --freeze          scenario edit: mark the step "needs a judgement" (runs hand over before it)
-  --unfreeze        scenario check|edit: ask to remove that mark; the check decides
-  --note <text>     scenario edit|undo: why, kept in the history (required with --force)
-  --revision <n>    scenario edit|undo: only if the plan is still at this chainRevision
-  --edit <id>       scenario undo: the sedit_ id to undo (default: the newest that can be)
-  --discard-edits   scenario calc --force: recalculate a plan with hand edits, replacing them
-  --no-browser      login: print the link and code, open nothing (SSH, headless)
-  --token <value>   login: redeem a one-time setup token from the console (no browser)
-  --password        login: use the old email/password prompt (deprecated)
-  --user <ref>      investigate executions: another account, by email or id (admin)
-  --limit <n>       investigate: how many turns / executions to show
-  --auth-url <url>  setup: the BaseIn API address (else BIR_AUTH_URL, else the stored one)
-  --project <dir>   setup: the directory to record (default: this one)
-  --no-replay       setup: wire recording only; add no scenario server
-  --allow-servers <a,b>  setup: servers replay may call unattended (default: all wrapped)
-  --no-daemon       setup: wire everything, start nothing
-  --restart         up: replace a running recorder`);
+    out(`bir ${VERSION} — a recording MCP proxy
+
+Commands:
+  setup       the one command: sign in, wire this project, start the recorder
+  up          start the recorder for this project in the background (--restart: replace it)
+  down        stop it (open sessions here then show a hook error until they restart;
+              \`bir off --here\` is the quiet way to take it out of the way)
+  off         take the runner out of the way at once, uninstalling nothing: hooks answer
+              with nothing within a second, wrapped servers stop recording at once and run
+              as plain pipes from their next start, nothing is recorded or replayed
+              (--here: this project only)
+  on          undo \`bir off\` (without --here: every project on this machine)
+  install     wrap this project's MCP servers and wire Claude Code's hooks
+  uninstall   restore everything install changed here and stop this project's recorder
+              (--all: every project on this machine — run it before removing the package)
+  status      what is installed for this directory
+  doctor      is it actually working right now? (exits 1 only for what breaks a session;
+              --quick: no network)
+  wrap        print a proxied entry for one server (any MCP client)
+  login       sign in to the BaseIn service (opens your browser)
+  logout      revoke this machine's session and forget it
+
+  scenario list                     recorded runs and their calculated scenarios
+  scenario show <runId|scnId> [--step <n>]
+                                    a scenario: intent, params, steps (--step: just that one)
+  scenario calc <runId|scnId> [--force [--discard-edits]]
+                                    calculate (or re-derive) a run's scenario; a scn_ id
+                                    (a sub-task's too) is recalculated in place, with --force
+  scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze]
+                                    try a change to one step against the recording; saves nothing
+  scenario edit <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
+                [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>]
+                                    the same check, and save the change if it passes
+  scenario edits <runId|scnId>      a scenario's hand edits, newest first
+  scenario undo <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
+                                    take back the newest edit (of step n); run it again to go
+                                    one further back; undo an undo's sedit_ id to redo
+  scenario editing on|off|status    whether this project's bir MCP server offers the tools
+                                    that change a scenario (restart Claude Code after)
+  scenario replay <scnId> --prompt "…" [--dry]
+  replay --scenario <scnId> --prompt "…" [--dry]
+  replay status | on | off | allow <a,b> | allow all
+                                    this project's replay switches, kept for the background recorder
+
+  investigate [<id>]                why the newest turn here (or run_/scn_/sexec_ <id>) did what
+                                    it did, what it cost, what to fix — journal + service
+  investigate list [--limit <n>]    recent turns in this directory and their verdicts
+  investigate executions [--limit <n>] [--user <email|id>]
+                                    the ledger, newest first (--user: admins only)
+
+Options:
+  --config <path>   an explicit { "mcpServers": … } file, for clients with no adapter
+  --server <name>   restrict install/uninstall to one server (repeatable); also wraps a
+                    remote server Claude Code signs in itself (OAuth), which is
+                    otherwise left unwrapped — its calls are recorded by the hooks
+  --global          invoke the installed package by absolute path (the default when
+                    bir runs from an installed package: no registry, works offline)
+  --local           invoke this checkout's bir-proxy (development)
+  --npx             invoke a pinned npx package instead (~1 s more per server start)
+  --mcp-json        wrap .mcp.json servers in place and add the scenario server there
+                    (the old shape; never for a .mcp.json the team commits).
+                    Default: a local-scope copy in ~/.claude.json, for this project only
+  --no-hooks        do not touch .claude/settings.local.json (Tier 2 recording only)
+  --no-correlation  never relax tool schemas; join steps on argument fingerprints
+  --replay          install/remove the scenario server, enabling calculated replay
+  --port <n>        install/setup: control-server port to write into the hook URLs
+                    (default: this project's, else the lowest free one from ${DEFAULT_CONTROL_PORT})
+  --json            machine-readable output for status / doctor / scenario / investigate
+                    (scenario check|edit|edits|undo: the service's answer, unchanged)
+  --dry             replay against recorded outputs only; run no real tools
+  --force           scenario calc: recalculate in place · scenario edit: save although
+                    the check refused it (needs --note; only for a recording that was wrong)
+                    · scenario undo: undo although a later step or the answer would break
+  --step <n>        scenario show|check|edit|undo: the step, by the stepIndex \`show\` prints
+  --input-logic <file|->   scenario check|edit: the new input logic, from a file or stdin (-)
+  --output-logic <file|->  scenario check|edit: the new output logic, from a file or stdin (-)
+  --freeze          scenario edit: mark the step "needs a judgement" (runs hand over before it)
+  --unfreeze        scenario check|edit: ask to remove that mark; the check decides
+  --note <text>     scenario edit|undo: why, kept in the history (required with --force)
+  --revision <n>    scenario edit|undo: only if the plan is still at this chainRevision
+  --edit <id>       scenario undo: the sedit_ id to undo (default: the newest edit that can be)
+  --discard-edits   scenario calc --force: recalculate a plan with hand edits, replacing them
+  --no-browser      login: print the link and code, open nothing (SSH, headless)
+  --token <value>   login: redeem a one-time setup token from the console (no browser)
+  --password        login: use the old email/password prompt (deprecated)
+  --user <ref>      investigate executions: another account, by email or id (admin)
+  --limit <n>       investigate: how many turns / executions to show
+  --auth-url <url>  setup: the BaseIn API address (else BIR_AUTH_URL, else the stored one)
+  --project <dir>   setup: the directory to record (default: this one)
+  --no-replay       setup: wire recording only; add no scenario server
+  --allow-servers <a,b>  setup: servers replay may call unattended (default: all wrapped)
+  --no-daemon       setup: wire everything, start nothing
+  --restart         up: replace a running recorder
+  --here            off/on: this project only (the installed project this directory is in)
+  --all             uninstall: every project on this machine, every recorder, the user scope
+  --quick           doctor: local checks only, no network call to the service
+  --strict          doctor: exit 1 on warnings too (not recording, a proxy not registered, …)
+  --keep-recorder   uninstall: leave this project's recorder running`);
     process.exit(code);
 }
 function parseArgs(argv) {
@@ -139,6 +182,8 @@ function parseArgs(argv) {
         servers: [],
         local: false,
         global: false,
+        npx: false,
+        mcpJson: false,
         hooks: true,
         noCorrelation: false,
         port: DEFAULT_CONTROL_PORT,
@@ -156,6 +201,11 @@ function parseArgs(argv) {
         freeze: false,
         unfreeze: false,
         discardEdits: false,
+        here: false,
+        all: false,
+        quick: false,
+        strict: false,
+        keepRecorder: false,
     };
     for (let i = 1; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -203,6 +253,12 @@ function parseArgs(argv) {
             case "--global":
                 args.global = true;
                 break;
+            case "--npx":
+                args.npx = true;
+                break;
+            case "--mcp-json":
+                args.mcpJson = true;
+                break;
             case "--no-hooks":
                 args.hooks = false;
                 break;
@@ -299,6 +355,21 @@ function parseArgs(argv) {
             case "--discard-edits":
                 args.discardEdits = true;
                 break;
+            case "--here":
+                args.here = true;
+                break;
+            case "--all":
+                args.all = true;
+                break;
+            case "--quick":
+                args.quick = true;
+                break;
+            case "--strict":
+                args.strict = true;
+                break;
+            case "--keep-recorder":
+                args.keepRecorder = true;
+                break;
             default:
                 if (arg.startsWith("-"))
                     usage(2);
@@ -324,22 +395,26 @@ function localScenarioPath() {
 function localHooksPath() {
     return resolvePath(dirname(fileURLToPath(import.meta.url)), "bir-hooks.js");
 }
-/** True when this `bir` runs from an installed package rather than a checkout. */
+/**
+ * True when this `bir` runs from npx's cache (`…/_npx/<hash>/node_modules/…`):
+ * installed-looking, but npm cleans that cache whenever it likes, so an
+ * absolute path into it is a path that will one day be gone.
+ */
+function runsFromNpxCache() {
+    return /[\\/]_npx[\\/]/.test(localProxyPath());
+}
+/** True when this `bir` runs from an installed package rather than a checkout (or the npx cache). */
 function runsFromInstalledPackage() {
-    return /[\\/]node_modules[\\/]/.test(localProxyPath());
+    return /[\\/]node_modules[\\/]/.test(localProxyPath()) && !runsFromNpxCache();
 }
 /**
- * The node the SessionStart hook will run. The real path, not the one this
- * process was started through: a version manager's per-shell shim directory
- * is gone when that shell is, and a hook that names it fails every session.
+ * What a flag-less first install (and `bir setup`) generates: an installed
+ * package names itself by absolute path — no registry round trip, no ~1 s npx
+ * start per server, works offline, and gets the self-starting SessionStart
+ * hook. The npx cache and a checkout keep pinned npx, which is what they are.
  */
-function hookNodePath() {
-    try {
-        return realpathSync(process.execPath);
-    }
-    catch {
-        return process.execPath;
-    }
+function defaultInvocation() {
+    return runsFromInstalledPackage() ? "global" : "npx";
 }
 /**
  * Which invocation the generated entries use — and the guard that makes
@@ -354,49 +429,211 @@ function hookNodePath() {
  * that works today and breaks after a `git clean`. Hence the node_modules test:
  * it is the one cheap signal that says "somebody installed this".
  */
-function resolveInvocation(args, remembered) {
-    if (args.local && args.global) {
-        process.stderr.write("[bir] --local and --global are mutually exclusive\n");
+function resolveInvocation(args, remembered, rememberedChosen) {
+    if ([args.local, args.global, args.npx].filter(Boolean).length > 1) {
+        process.stderr.write("[bir] --local, --global and --npx are mutually exclusive\n");
         process.exit(2);
     }
-    // Neither flag: what this project was installed with last time. `bir setup`
+    if (args.forceInvocation)
+        return args.forceInvocation;
+    if (args.npx)
+        return "npx";
+    if (args.local)
+        return "local";
+    if (args.global) {
+        const proxy = localProxyPath();
+        if (!runsFromInstalledPackage()) {
+            process.stderr.write(`[bir] --global needs an installed package, but this bir runs from ${dirname(proxy)}` +
+                `${runsFromNpxCache() ? " (npx's cache, which npm cleans)" : ""}\n` +
+                `      install it first (npm install -g ${PACKAGE_NAME}@${VERSION}) and rerun,\n` +
+                `      or use --local to point at this checkout on purpose.\n`);
+            process.exit(2);
+        }
+        return "global";
+    }
+    // No flag: what this project was installed with last time. `bir setup`
     // installs with --global, and a later bare `bir install --replay` here must
-    // not quietly turn every entry into a pinned-npx one and drop the
-    // self-starting SessionStart hook with it.
-    if (!args.global && !args.local && remembered) {
+    // not quietly turn every entry into a pinned-npx one.
+    if (remembered) {
         if (remembered === "global" && !runsFromInstalledPackage())
-            return "local";
+            return runsFromNpxCache() ? "npx" : "local";
+        // A remembered npx nobody asked for is the old flag-less default; an
+        // installed `bir` replaces it with its absolute path (and the hook that
+        // starts the recorder), which is what it would pick today.
+        if (remembered === "npx" && !rememberedChosen && runsFromInstalledPackage())
+            return "global";
         return remembered;
     }
-    if (!args.global)
-        return args.local ? "local" : "npx";
-    const proxy = localProxyPath();
-    if (!/[\\/]node_modules[\\/]/.test(proxy)) {
-        process.stderr.write(`[bir] --global needs an installed package, but this bir runs from ${dirname(proxy)}\n` +
-            `      install it first (npm install -g ${PACKAGE_NAME}@${VERSION}) and rerun,\n` +
-            `      or use --local to point at this checkout on purpose.\n`);
-        process.exit(2);
-    }
-    return "global";
+    return defaultInvocation();
+}
+/** True when `file` is `~/.claude.json` (or whatever BIR_CLAUDE_JSON names). */
+function isClaudeJson(file, claudeJson) {
+    return normalizePath(file) === normalizePath(claudeJson);
 }
-/** Record a file's pre-install text once, so uninstall can restore it exactly. */
-function backupFile(sidecar, file) {
+/**
+ * Record a file's pre-install text once, so uninstall can restore it exactly —
+ * and notice when that snapshot has gone stale.
+ *
+ * The snapshot is taken at the FIRST install only. If somebody else changed
+ * the file after our last write (a server added by hand, Claude Code's own
+ * edits), a later install writes over their version, the file hashes to our
+ * write again, and a byte-for-byte restore would bring back the first-install
+ * text — deleting their change. So a changed file marks the snapshot stale, and
+ * uninstall repairs entries instead. `~/.claude.json` is never snapshotted: it
+ * is Claude Code's, rewritten constantly, and holds every project's settings;
+ * 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.
+ */
+function backupFile(sidecar, file, claudeJson, entryOnly = false) {
     sidecar.files ??= {};
-    if (sidecar.files[file])
+    if (entryOnly || isClaudeJson(file, claudeJson)) {
+        delete sidecar.files[file];
+        return;
+    }
+    const existing = sidecar.files[file];
+    if (existing) {
+        if (!existing.stale && existing.writtenSha) {
+            const current = readTextOrNull(file);
+            if (current === null || sha256(current) !== existing.writtenSha) {
+                sidecar.files[file] = { originalText: null, writtenSha: existing.writtenSha, stale: true };
+                return;
+            }
+        }
+        if (existing.originalText !== null && !existing.stale) {
+            const kept = protectBackupText(existing.originalText);
+            if (kept.originalText === null) {
+                sidecar.files[file] = { ...kept, writtenSha: existing.writtenSha };
+            }
+        }
+        return;
+    }
+    const text = readTextOrNull(file);
+    if (text !== null && holdsRunnerEntries(file, text)) {
+        // Not an original: an install that stopped halfway, an older runner, or a
+        // teammate's commit already put entries of ours here. Restoring this text
+        // "byte-for-byte" would put the runner back and report it gone, so the
+        // file is repaired entry by entry, always.
+        sidecar.files[file] = { originalText: null, writtenSha: "", stale: true };
         return;
-    sidecar.files[file] = { originalText: readTextOrNull(file), writtenSha: "" };
+    }
+    sidecar.files[file] = text === null ? { originalText: null, writtenSha: "" } : protectBackupText(text);
 }
-function noteWritten(sidecar, file, text) {
+/** True when a config file's text already carries a proxy, the scenario server or one of our hooks. */
+function holdsRunnerEntries(file, text) {
+    return /\bbir-(proxy|scenario|hooks)\b/.test(text) || hasBirHooks(file);
+}
+function noteWritten(sidecar, file, text, claudeJson, entryOnly = false) {
+    if (entryOnly || isClaudeJson(file, claudeJson))
+        return;
     sidecar.files ??= {};
     const backup = sidecar.files[file] ?? { originalText: null, writtenSha: "" };
     backup.writtenSha = sha256(text);
     sidecar.files[file] = backup;
 }
+/** The server name a sidecar key names, given the record's own cwd. */
+const recordName = recordServerName;
+/**
+ * Store `record` for `name`, replacing `found` (its earlier record, under
+ * whichever key and cwd spelling that had). A record whose stash is redacted
+ * goes under the key an older runner never reads (generate.ts,
+ * REDACTED_KEY_PREFIX): that runner would write the blanked values back.
+ */
+function putRecord(sidecar, cwd, name, found, record) {
+    if (found)
+        delete sidecar.servers[found.key];
+    sidecar.servers[recordKey(cwd, name, record.secretsRedacted === true)] = record;
+}
+/**
+ * This project's record for `name`: by the exact key, else by any key whose
+ * cwd is the same directory spelled differently (a lowercase drive letter).
+ */
+function findRecord(sidecar, cwd, name) {
+    const exact = sidecarKey(cwd, name);
+    if (sidecar.servers[exact])
+        return { key: exact, record: sidecar.servers[exact] };
+    const want = normalizePath(cwd);
+    for (const [key, record] of Object.entries(sidecar.servers)) {
+        if (normalizePath(record.cwd) === want && recordName(key, record) === name)
+            return { key, record };
+    }
+    return undefined;
+}
+/**
+ * The original entry a record stashed, with its header and env values read
+ * back from the wrapped entry (the sidecar keeps names only). Undefined when
+ * those values cannot be recovered — then the entry is left alone rather than
+ * restored without its credentials.
+ */
+function recordedOriginal(record, wrapped) {
+    if (!record.original)
+        return undefined;
+    if (!record.secretsRedacted)
+        return record.original;
+    return restoreSecrets(record.original, wrapped);
+}
+/** Why an existing wrapped entry is being written again, for the log line. */
+function rewrapReason(current, next) {
+    if (!current || isRemote(current) || !isWrapped(current))
+        return undefined;
+    const was = current.env?.BIR_CONTROL_URL;
+    const now = next.env?.BIR_CONTROL_URL;
+    if (was !== now)
+        return `its control URL was ${was ?? "unset"}, now ${now ?? "unset"}`;
+    const argv = current.args ?? [];
+    if (argv.includes("--header") && next.env?.[UPSTREAM_HEADERS_ENV] !== undefined) {
+        // An older runner passed a remote server's headers as `--header K:V`,
+        // readable by any local user through `ps`; they travel in the env now.
+        return "its headers move off the command line, into its env";
+    }
+    if (current.command !== next.command || argv.join("\u0000") !== next.args.slice(0, argv.length).join("\u0000")) {
+        const at = argv.findIndex((a) => /bir-proxy/.test(a));
+        return `its runner moved (was ${`${current.command} ${at >= 0 ? argv.slice(0, at + 1).join(" ") : argv[0] ?? ""}`.trim()})`;
+    }
+    return "its configuration changed";
+}
+function sameEntry(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Every `projects` key that holds `name` for this directory: the keys Claude
+ * Code reads, then legacy spellings of the directory itself (where an older
+ * install may have put an entry).
+ */
+function localHolders(claude, cwd, name) {
+    const projects = claude.projects ?? {};
+    const want = [normalizePath(claudeProjectKey(cwd)), normalizePath(cwd)];
+    return Object.keys(projects).filter((key) => want.includes(normalizePath(key)) && projects[key]?.mcpServers?.[name] !== undefined);
+}
+/**
+ * True when the servers this directory would use (or the `--config` file)
+ * include our scenario server — the delivery tool a direct replay needs.
+ * An unreadable configuration answers false: replay then stays off.
+ */
+function scenarioServerHere(args, cwd) {
+    try {
+        const servers = args.configPath
+            ? Object.entries(readGenericServers(args.configPath)).map(([name, config]) => ({ name, config }))
+            : resolveServers(cwd);
+        return servers.some((s) => s.name === SCENARIO_SERVER_KEY && isScenarioServer(s.config));
+    }
+    catch {
+        return false;
+    }
+}
 // ── install ────────────────────────────────────────────────────────────────
 async function install(args) {
     const cwd = process.cwd();
     const sidecar = readSidecar();
-    const invocation = resolveInvocation(args, projectRecord(sidecar, cwd)?.invocation);
+    const before = projectRecord(sidecar, cwd);
+    const invocation = resolveInvocation(args, before?.invocation, before?.invocationChosen);
+    const flagged = args.local || args.global || args.npx;
+    const invocationChosen = flagged || (before?.invocationChosen === true && before.invocation === invocation);
     sidecar.token ??= randomBytes(32).toString("hex");
     // One port per project (generate.ts): an explicit --port is honoured, else
     // the one this directory already has, else the lowest free one no other has.
@@ -404,336 +641,1952 @@ async function install(args) {
     sidecar.controlPort = port;
     // One token per project too: a token in this project's settings file opens
     // this project's recorder, not every recorder on the machine.
-    const token = projectRecord(sidecar, cwd)?.token ?? randomBytes(32).toString("hex");
-    setProjectRecord(sidecar, cwd, { port, token, invocation });
+    const token = before?.token ?? randomBytes(32).toString("hex");
+    setProjectRecord(sidecar, cwd, { port, token, invocation, invocationChosen: invocationChosen || undefined });
     const controlUrl = `http://127.0.0.1:${port}`;
-    const entries = args.configPath
-        ? Object.entries(readGenericServers(args.configPath)).map(([name, config]) => ({
-            name,
-            config,
-            scope: "explicit",
-            shadowed: [],
-        }))
-        : resolveServers(cwd);
-    const wanted = entries.filter((e) => args.servers.length === 0 || args.servers.includes(e.name));
-    if (wanted.length === 0 && (args.configPath || !args.hooks)) {
-        // An explicit config file, or proxies-only: with no server there is nothing
-        // this install could change.
-        out("No MCP servers found for this directory. Nothing to wrap.");
-        if (!args.configPath) {
-            out("  Looked in: ~/.claude.json (user + local scopes) and ./.mcp.json (project scope).");
+    const paths = claudeCodePaths(cwd);
+    const claudeJson = paths.claudeJson;
+    // The old shape, on request: wrap `.mcp.json` servers in place and put the
+    // scenario server there too. Only for a `.mcp.json` nobody commits.
+    const mcpJsonMode = args.mcpJson || process.env.BIR_WRAP_MCP_JSON === "1";
+    // A leftover snapshot of ~/.claude.json from an older install: never used
+    // again, and a full copy of every project's settings. Gone.
+    for (const file of Object.keys(sidecar.files ?? {})) {
+        if (isClaudeJson(file, claudeJson))
+            delete sidecar.files?.[file];
+    }
+    // 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.
+    try {
+        if (args.configPath)
+            assertEditableJson(args.configPath);
+        else {
+            assertEditableJson(claudeJson);
+            assertEditableJson(paths.mcpJson);
+            if (args.hooks)
+                assertEditableJson(paths.settingsLocal);
+        }
+    }
+    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");
+        return 1;
+    }
+    // An uninstall that found this project's recorder still serving an open
+    // session left the project switched off (see retireRecorder). Installing
+    // again is the end of that; a switch the person set with `bir off` is theirs.
+    if (clearUninstallMark(cwd))
+        out("  ~ the runner is on again here (an earlier uninstall had switched it off)");
+    try {
+        return await installWriting(args, cwd, sidecar, { before, invocation, port, token, controlUrl, paths, mcpJsonMode });
+    }
+    catch (err) {
+        // WRITE-AHEAD, the cheap way: whatever this run already changed is in
+        // `sidecar` — the originals it stashed, the files it snapshotted. Losing
+        // that to an EBUSY or a Ctrl-C halfway through left entries wrapped with
+        // no record, which `bir uninstall` then reported as nothing to undo.
+        try {
+            writeSidecar(sidecar);
         }
+        catch {
+            /* the original error is the one to report */
+        }
+        throw err;
+    }
+}
+/** Everything `install` writes, after every file it will touch was checked. */
+async function installWriting(args, cwd, sidecar, plan) {
+    const { before, invocation, port, token, controlUrl, paths, mcpJsonMode } = plan;
+    const claudeJson = paths.claudeJson;
+    const nodeFlags = nodeFlagsToCarry();
+    const nodeChoice = invocation === "npx" ? undefined : chooseNodePath();
+    const gen = {
+        controlUrl: args.hooks ? controlUrl : undefined,
+        noCorrelation: args.noCorrelation,
+        invocation,
+        proxyPath: invocation === "npx" ? undefined : localProxyPath(),
+        version: VERSION,
+        nodeFlags,
+        node: nodeChoice?.path,
+    };
+    const named = (name) => args.servers.includes(name);
+    let wrapped = 0;
+    const done = args.configPath
+        ? installExplicit(args, cwd, sidecar, gen, named, claudeJson)
+        : installClaudeCode(args, cwd, sidecar, gen, named, paths, mcpJsonMode);
+    if (done.nothing)
         return 0;
+    wrapped = done.wrapped;
+    // The scenario server (docs/calculatedReplay.md §6.3). Opt-in, and separate
+    // from the rest of install, because it is the one thing here the model can see:
+    // it adds `mcp__bir__run_scenario` to the tool list of every session in this
+    // project. That is a real cost, and it buys the delivery channel a fully
+    // wrapped scenario's results come back through.
+    installScenarioServer(args, cwd, sidecar, gen, paths, mcpJsonMode, done.theirBir, done.sharedKey);
+    if (!args.configPath) {
+        // An older install wrapped `.mcp.json` in place; the steps above put every
+        // entry back. Put the bytes back too, so git shows the team's file clean.
+        if (!mcpJsonMode)
+            restoreMcpJsonBytes(sidecar, paths);
+        // Which ~/.claude.json this install wrote to: CLAUDE_CONFIG_DIR moves it,
+        // and an uninstall from another environment must still find it.
+        const files = projectRecord(sidecar, cwd)?.claudeJsonFiles ?? [];
+        if (!files.some((f) => isClaudeJson(f, claudeJson))) {
+            setProjectRecord(sidecar, cwd, { port, claudeJsonFiles: [...files, claudeJson] });
+        }
+    }
+    // WHETHER REPLAY IS ON HERE — the switch the recorder reads at start
+    // (generate.ts, settleReplaySwitch). It used to be on in every installed
+    // project: `--no-replay` printed "not installed" while matched prompts were
+    // replayed anyway. Not asked for, it is off now; asked for, on — except
+    // where the person turned it off themselves.
+    const intent = args.replay ? "wanted" : args.noReplay ? "refused" : "unasked";
+    const replaySwitch = settleReplaySwitch(sidecar, cwd, intent, intent === "unasked" && scenarioServerHere(args, cwd));
+    if (replaySwitch === "on")
+        out("  ~ calculated replay is on again here (an earlier install had turned it off)");
+    else if (replaySwitch === "off") {
+        out(intent === "refused"
+            ? "  - calculated replay is off here (--no-replay); `bir replay on` turns it on"
+            : "  - calculated replay is off here: it was not asked for (`bir install --replay` adds it)");
+    }
+    // SessionStart starts the recorder itself when this directory has none
+    // (control/ensure-hook.ts). Every invocation gets it — an npx one through
+    // npx, once per session — because without it nothing starts the recorder,
+    // and every other hook fails against a port nobody listens on. The npx form
+    // asks for a smaller budget of its own: npx resolves the package before the
+    // hook's clock starts, and the two together must stay inside the host's
+    // ENSURE_TIMEOUT_S, or the session start shows the hook as timed out.
+    const ensure = invocation === "npx"
+        ? (() => {
+            const via = npxHookInvocation("bir-hooks", VERSION);
+            return { command: via.command, args: [...via.args, ENSURE_ARG, ...NPX_ENSURE_BUDGET_ARGS] };
+        })()
+        : { node: nodeChoice?.path ?? process.execPath, hooksScript: localHooksPath(), nodeFlags };
+    if (args.hooks && !args.configPath) {
+        // Hooks live in `.claude/settings.local.json` — the person's own file, the
+        // one Claude Code keeps out of git — not in the `settings.json` a team
+        // commits. They carry a bearer token and an absolute path to this machine's
+        // node; a teammate's clone wants neither. An older install put them in the
+        // shared file; take them out of there on the way.
+        if (hasBirHooks(paths.settings)) {
+            try {
+                backupFile(sidecar, paths.settings, claudeJson);
+                const cleaned = uninstallHooks(paths.settings);
+                if (cleaned !== undefined)
+                    noteWritten(sidecar, paths.settings, cleaned, claudeJson);
+                out(`  - hooks removed from ${paths.settings} (they live in settings.local.json now)`);
+            }
+            catch (err) {
+                out(`  ! ${paths.settings} still holds hooks of ours and could not be cleaned: ${errText(err)}`);
+            }
+        }
+        backupFile(sidecar, paths.settingsLocal, claudeJson);
+        let text = installHooks(paths.settingsLocal, buildHooksBlock(controlUrl, token, { ensure }));
+        if (args.replay && mcpJsonMode) {
+            // Pre-approve our own scenario server. Claude Code asks before it uses a
+            // server from `.mcp.json`, and a "No" there leaves a direct replay with
+            // nowhere to deliver its results — and nothing to say so.
+            text = enableMcpjsonServers(paths.settingsLocal, [SCENARIO_SERVER_KEY]);
+        }
+        else if (!mcpJsonMode) {
+            // The scenario server is a local-scope server now, which Claude Code
+            // never asks about; an older install's pre-approval has nothing to approve.
+            text = disableMcpjsonServers(paths.settingsLocal, [SCENARIO_SERVER_KEY]) ?? text;
+        }
+        noteWritten(sidecar, paths.settingsLocal, text, claudeJson);
+        sidecar.hookFiles = [...new Set([...(sidecar.hookFiles ?? []), paths.settingsLocal])];
+        out(`  + hooks → ${paths.settingsLocal} (control server on ${controlUrl}; the recorder starts itself with each session${invocation === "npx" ? ", through npx" : ""})`);
+        const exclude = ensureGitExcludeLine(cwd);
+        if (exclude) {
+            out(`  + ${LOCAL_SETTINGS_EXCLUDE} is listed in ${exclude.path}`);
+            // Remember whether the line is ours, so uninstall removes only that. An
+            // install older than this field is not asked (undefined: removed, as then).
+            const excludeAdded = exclude.added ? true : before && before.excludeAdded === undefined ? undefined : (before?.excludeAdded ?? false);
+            setProjectRecord(sidecar, cwd, { port, excludeAdded });
+        }
+    }
+    if (nodeChoice?.warning)
+        out(`  ! ${nodeChoice.warning}`);
+    const proxyHint = envProxyHint();
+    if (proxyHint)
+        out(`  ! ${proxyHint}`);
+    // THE UPGRADE NOTE ABOUT APPROVAL, said once per project. 0.2.12's recorder
+    // answered every wrapped MCP call's PreToolUse with "allow"; this one leaves
+    // the decision to Claude Code (no silent auto-approval). Sessions that
+    // relied on it — headless `claude -p` in a workspace whose permissions.allow
+    // is not read — start getting those calls denied, and nothing else says why.
+    const approvalNote = args.hooks && !args.configPath && before !== undefined && before.approvalNoteShown !== true && wrappedHere(cwd);
+    if (args.hooks && !args.configPath && projectRecord(sidecar, cwd)?.approvalNoteShown !== true) {
+        setProjectRecord(sidecar, cwd, { port, approvalNoteShown: true });
+    }
+    writeSidecar(sidecar);
+    out();
+    out(`Wrapped ${wrapped} server${wrapped === 1 ? "" : "s"}.`);
+    if (approvalNote) {
+        out("Note: the runner no longer approves wrapped MCP tool calls itself (0.2.12 answered every one \"allow\"):");
+        out("  Claude Code asks about them as it would without the runner. For headless runs (`claude -p`), allow");
+        out("  them in permissions.allow or with --allowedTools, or opt back in with BIR_CORRELATION_DECISION=allow");
+        out("  in the recorder's environment (then `bir up --restart`).");
+    }
+    if (args.hooks && !args.configPath) {
+        out("Next: start your session here as usual. The recorder starts itself with it;");
+        out("`bir up` starts it now, `bir off --here` takes it out of the way, `bir doctor` checks it.");
+    }
+    else {
+        out("Recording will be standalone (Tier 2): MCP calls only, no prompt or final answer.");
     }
+    const off = offSource(cwd);
+    if (off) {
+        out(`Note: the runner is OFF ${describeOff(off, cwd)}, so nothing is recorded or replayed until \`bir on\`.`);
+    }
+    if (args.replay && projectRecord(sidecar, cwd)?.replay?.enabled === false) {
+        out();
+        out("Calculated replay is INSTALLED but OFF here (`bir replay off`); `bir replay on` turns it on.");
+    }
+    else if (args.replay) {
+        out();
+        out("Calculated replay is INSTALLED and ON. `bir replay off` turns it off here, and");
+        out("`bir replay allow <servers>` narrows what it may call unattended — read");
+        out("docs/calculatedReplayGuide.md §5.1 first: a replayed step is auto-approved,");
+        out("and a directly executed one never reaches the permission system at all.");
+    }
+    return 0;
+}
+/** `--config <file>`: the file is the whole configuration, wrapped in place. */
+function installExplicit(args, cwd, sidecar, gen, named, claudeJson) {
+    const file = args.configPath;
+    const all = readGenericServers(file);
+    const wanted = Object.entries(all).filter(([name]) => args.servers.length === 0 || named(name));
     if (wanted.length === 0) {
+        out("No MCP servers found for this directory. Nothing to wrap.");
+        return { wrapped: 0, nothing: true };
+    }
+    let wrapped = 0;
+    let theirBir;
+    for (const [name, config] of wanted) {
+        if (name === SCENARIO_SERVER_KEY) {
+            if (isScenarioServer(config))
+                out(`  = ${name} — the scenario server (calculated replay)`);
+            else {
+                theirBir = file;
+                out(`  ! ${name} — reserved by BaseInstRunner; not wrapped. Rename it to record it`);
+            }
+            continue;
+        }
+        const found = findRecord(sidecar, cwd, name);
+        let source = config;
+        if (isWrapped(config)) {
+            source = (found ? recordedOriginal(found.record, config) : undefined) ?? unwrapEntry(config);
+            if (!source) {
+                out(`  = ${name} — already wrapped`);
+                continue;
+            }
+        }
+        const blocked = isRemote(source) ? remoteWrapBlocker(source) : undefined;
+        const optedIn = named(name) || found?.record.optedIn === true;
+        if (blocked && !optedIn) {
+            if (isWrapped(config)) {
+                backupFile(sidecar, file, claudeJson, true);
+                noteWritten(sidecar, file, setGenericServerEntry(file, name, source), claudeJson, true);
+                if (found)
+                    delete sidecar.servers[found.key];
+                out(`  ~ ${name} — un-wrapped: ${blocked}`);
+            }
+            else {
+                out(`  - ${name} — left unwrapped: ${blocked} (\`--server ${name}\` wraps it anyway)`);
+            }
+            continue;
+        }
+        if (blocked && named(name))
+            out(`  ! ${name} — wrapping it because --server names it, although ${blocked}`);
+        const proxied = wrapEntry(source, { ...gen, serverName: name });
+        if (sameEntry(config, proxied)) {
+            out(`  = ${name} — already wrapped`);
+            continue;
+        }
+        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);
+        putRecord(sidecar, cwd, name, found, {
+            original: kept.config,
+            scope: "explicit",
+            file,
+            cwd,
+            installedAt: Date.now(),
+            ...(kept.redacted ? { secretsRedacted: true } : {}),
+            ...(blocked ? { optedIn: true } : {}),
+        });
+        const kind = isRemote(source) ? `${source.type} ${source.url}` : source.command;
+        out(reason ? `  ~ ${name} — re-wrapping: ${reason}` : `  + ${name} → bir-proxy (upstream: ${kind})`);
+        wrapped += 1;
+    }
+    return { wrapped, theirBir };
+}
+/**
+ * Claude Code: every server this directory would use, wrapped as a LOCAL-scope
+ * entry of the same name.
+ *
+ * Local scope wins over project and user scope for this project only, and it
+ * lives in `~/.claude.json`, which nobody commits. So:
+ *
+ *   - a `.mcp.json` server is overridden, not rewritten — the team's file never
+ *     carries this machine's node path, runner path or control port, and a
+ *     teammate's clone keeps working;
+ *   - a user-scope server is overridden for this project only — it used to be
+ *     rewritten in place, which routed it through the proxy in EVERY project,
+ *     including ones never set up;
+ *   - a local-scope server is wrapped where it is.
+ *
+ * Entries an older install wrapped in `.mcp.json` or the user scope are put
+ * back first (from the stash, else rebuilt from the wrapped arguments).
+ */
+function installClaudeCode(args, cwd, sidecar, gen, named, paths, mcpJsonMode) {
+    const claudeJson = paths.claudeJson;
+    const readClaude = () => parseJsonFile(claudeJson) ?? {};
+    let claude = readClaude();
+    const projectServers = () => (parseJsonFile(paths.mcpJson)?.mcpServers ?? {});
+    const overrideKeys = projectKeysFor(claude.projects, cwd);
+    const names = [
+        ...new Set([
+            ...Object.keys(projectScope(claude.projects, cwd)),
+            ...Object.keys(projectServers()),
+            ...Object.keys(claude.mcpServers ?? {}),
+        ]),
+    ].filter((name) => args.servers.length === 0 || named(name));
+    const servers = names.filter((n) => n !== SCENARIO_SERVER_KEY);
+    // Named as Claude Code finds it: CLAUDE_CONFIG_DIR moves it out of the home directory.
+    const claudeLabel = claudeConfigHome() && !process.env.BIR_CLAUDE_JSON ? claudeJson : "~/.claude.json";
+    if (servers.length === 0 && !args.hooks) {
+        out("No MCP servers found for this directory. Nothing to wrap.");
+        out(`  Looked in: ${claudeLabel} (user + local scopes) and ./.mcp.json (project scope).`);
+        return { wrapped: 0, nothing: true };
+    }
+    if (servers.length === 0) {
         // Hooks alone are a recorder: built-in tools, the prompt and the answer are
         // all theirs, and a scenario over built-in steps steers a session the same
         // way. Stopping here used to leave such a project with nothing at all.
-        out("No MCP servers to wrap here (looked in ~/.claude.json and ./.mcp.json).");
+        out(`No MCP servers to wrap here (looked in ${claudeLabel} and ./.mcp.json).`);
         out("  Hooks are still wired: built-in tools and prompts are recorded.");
     }
-    const paths = claudeCodePaths(cwd);
-    /**
-     * Does a generated entry still name the runner that is running now? After
-     * an upgrade, a Node moved by a version manager, or a switch from the
-     * machine's npm prefix to the private one, the old absolute path (or the old
-     * pinned npx version) is what the host would keep spawning — and "already
-     * wrapped" is the last thing that should be printed about it.
-     */
-    const nodeFlags = nodeFlagsToCarry();
-    const stillCurrent = (config, scriptPath) => {
-        if (isRemote(config))
-            return false;
-        const argv = config.args ?? [];
-        if (invocation === "npx")
-            return config.command === "npx" && argv.includes(packageSpec(VERSION));
-        const at = argv.indexOf(scriptPath);
-        if (config.command !== process.execPath || at < 0)
-            return false;
-        // The node flags in front of the script must be the ones this run carries.
-        return argv.slice(0, at).join(" ") === nodeFlags.join(" ");
+    // A SHARED KEY. Claude Code keeps the local scope per repository — the
+    // canonical git root — so for a subdirectory or a linked worktree, a local
+    // copy written here would also apply to the root checkout and every other
+    // worktree: directories nobody set up, whose sessions would then be routed
+    // through this project's proxies and recorder. Those are left unwrapped (the
+    // hooks still record their calls) unless the old `.mcp.json` shape is asked for.
+    const root = claudeProjectRoot(cwd);
+    const sharedKey = !mcpJsonMode && normalizePath(root) !== normalizePath(cwd);
+    if (sharedKey && servers.length > 0) {
+        out(`  ! not wrapped here: Claude Code keeps local-scope servers per repository (${root}), so a ` +
+            "wrapped copy would also apply there and to its other worktrees. Their calls are still recorded " +
+            `by the hooks; \`bir setup\` in ${root} wraps them for the repository`);
+    }
+    // WHAT CLAUDE CODE ITSELF WOULD START WITHOUT ASKING (config/mcp-approval.ts).
+    // It asks before it starts a `.mcp.json` server, and never about a
+    // local-scope one — so a local copy of a server the person rejected, or was
+    // never asked about, would start silently. Only an approved one is copied.
+    const approval = mcpjsonApprovals(cwd, claude);
+    // An organisation's policy that matches servers by command: wrapping changes
+    // the command, so nothing is wrapped under it, `--server` or not.
+    const policy = managedMcpPolicyBlocker();
+    // Claude Code applies this project's local scope to its linked worktrees too.
+    const worktrees = sharedKey || mcpJsonMode ? [] : linkedWorktrees(root);
+    /** A worktree's own `.mcp.json` entry for `name`; null when that file is not plain JSON. */
+    const worktreeEntry = (dir, name) => {
+        try {
+            return parseJsonFile(join(dir, ".mcp.json"))?.mcpServers?.[name];
+        }
+        catch {
+            return null;
+        }
     };
+    let wroteLocal = false;
+    let theirBir;
+    const bir = projectScope(claude.projects, cwd)[SCENARIO_SERVER_KEY] ??
+        projectServers()[SCENARIO_SERVER_KEY] ??
+        claude.mcpServers?.[SCENARIO_SERVER_KEY];
+    if (bir && !isScenarioServer(bir)) {
+        // `mcp__bir__run_scenario` is how a direct replay's results reach the
+        // model. Wrapping somebody else's `bir` server would route that call to
+        // their server instead, silently — and shadowing it with ours would hide it.
+        theirBir = "yours";
+        out(`  ! ${SCENARIO_SERVER_KEY} — reserved by BaseInstRunner; not wrapped. Rename it to record it`);
+    }
     let wrapped = 0;
-    for (const entry of wanted) {
-        if (entry.name === SCENARIO_SERVER_KEY && isScenarioServer(entry.config)) {
-            if (!args.replay || stillCurrent(entry.config, localScenarioPath())) {
-                out(`  = ${entry.name} — the scenario server (calculated replay)`);
+    for (const name of servers) {
+        const found = findRecord(sidecar, cwd, name);
+        let P = projectServers()[name];
+        let U = claude.mcpServers?.[name];
+        // 1. MIGRATION: an older install rewrote the shared scopes in place.
+        if (P !== undefined && isWrapped(P) && !mcpJsonMode) {
+            const restored = found?.record.scope === "project" ? recordedOriginal(found.record, P) : undefined;
+            if (restored) {
+                backupFile(sidecar, paths.mcpJson, claudeJson);
+                noteWritten(sidecar, paths.mcpJson, setServerEntry("project", cwd, name, restored, paths).text, claudeJson);
+                delete sidecar.servers[found.key];
+                out(`  ~ ${name} — put back as it was in ${paths.mcpJson}: a file a team commits must not carry this machine's paths`);
+                P = restored;
+            }
+            else {
+                out(`  ! ${name} — ${paths.mcpJson} holds an entry wrapped by a runner, not by this install ` +
+                    "(another machine's, or an older copy): it is overridden here, but teammates without the runner need it put back");
+            }
+        }
+        if (U !== undefined && isWrapped(U)) {
+            const userRecords = Object.entries(sidecar.servers).filter(([key, r]) => r.scope === "user" && recordName(key, r) === name);
+            const mineFirst = [...userRecords].sort((a, b) => Number(normalizePath(b[1].cwd) === normalizePath(cwd)) - Number(normalizePath(a[1].cwd) === normalizePath(cwd)));
+            const restored = mineFirst.length ? recordedOriginal(mineFirst[0][1], U) ?? unwrapEntry(U) : undefined;
+            if (restored) {
+                setServerEntry("user", cwd, name, restored, paths);
+                const others = userRecords.map(([, r]) => r.cwd).filter((c) => normalizePath(c) !== normalizePath(cwd));
+                for (const [key] of userRecords)
+                    delete sidecar.servers[key];
+                out(`  ~ ${name} — put back as it was in your user scope, which applies to every project; recorded here through a local copy instead`);
+                if (others.length)
+                    out(`    (${[...new Set(others)].join(", ")} recorded it that way too — run \`bir setup\` there again)`);
+                U = restored;
+                claude = readClaude();
+            }
+            else {
+                out(`  ! ${name} — wrapped in your user scope (every project), not by this install; left as it is`);
+            }
+        }
+        // 2. SOURCE (what to wrap) and TARGET (where the wrapped entry goes).
+        const L = projectScope(claude.projects, cwd)[name];
+        const holders = localHolders(claude, cwd, name);
+        let source;
+        let target;
+        const unwrapped = (c) => c !== undefined && isWrapped(c) ? unwrapEntry(c) : c;
+        if (L !== undefined && isWrapped(L) && found?.record.override) {
+            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];
+                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;
+            target = { kind: "inplace", keys: holders };
+        }
+        else if (P !== undefined) {
+            source = unwrapped(P);
+            target = mcpJsonMode ? { kind: "mcpjson" } : { kind: "override", from: "project", keys: overrideKeys };
+        }
+        else {
+            source = unwrapped(U);
+            target = { kind: "override", from: "user", keys: overrideKeys };
+        }
+        if (source === undefined) {
+            out(`  = ${name} — already wrapped`);
+            continue;
+        }
+        const current = target.kind === "mcpjson" ? P : L;
+        if (sharedKey)
+            continue; // said once, above
+        // 3. Reasons to leave a server exactly as Claude Code would run it. Each
+        // one also TAKES BACK a wrap an earlier install made, so re-running
+        // `bir setup` is always the repair.
+        const src = source;
+        const tgt = target;
+        const leaveUnwrapped = (why, after) => {
+            if (current !== undefined && isWrapped(current)) {
+                if (tgt.kind === "override")
+                    setLocalEntries(claudeJson, tgt.keys, name, null, (cur) => cur !== undefined && isWrapped(cur));
+                else if (tgt.kind === "inplace")
+                    setLocalEntries(claudeJson, tgt.keys, name, src);
+                else {
+                    backupFile(sidecar, paths.mcpJson, claudeJson);
+                    noteWritten(sidecar, paths.mcpJson, setServerEntry("project", cwd, name, src, paths).text, claudeJson);
+                }
+                if (found)
+                    delete sidecar.servers[found.key];
+                claude = readClaude();
+                out(`  ~ ${name} — un-wrapped: ${why}. ${after.charAt(0).toUpperCase()}${after.slice(1)}`);
             }
             else {
-                out(`  ~ ${entry.name} — re-writing the scenario server: its runner moved`);
+                out(`  - ${name} — left unwrapped: ${why}; ${after}`);
             }
+        };
+        if (policy) {
+            leaveUnwrapped(policy, "its calls are still recorded by the hooks");
             continue;
         }
-        if (entry.name === SCENARIO_SERVER_KEY) {
-            // `mcp__bir__run_scenario` is how a direct replay's results reach the
-            // model. Wrapping somebody else's `bir` server would route that call to
-            // their server instead, silently.
-            out(`  ! ${entry.name} — reserved by BaseInstRunner; not wrapped. Rename it to record it`);
+        const optedIn = named(name) || found?.record.optedIn === true;
+        let pendingOptIn = false;
+        if (target.kind === "override" && target.from === "project") {
+            // 3a. Not approved in Claude Code: a local copy would skip its question.
+            const verdict = approval(name);
+            if (verdict.state === "rejected" || (verdict.state === "pending" && !optedIn)) {
+                leaveUnwrapped(verdict.why, verdict.state === "rejected"
+                    ? "a local copy would start it anyway, so none is made"
+                    : `the hooks record its calls once you approve it there; run \`bir setup\` again after approving to wrap it (\`--server ${name}\` wraps it now)`);
+                continue;
+            }
+            pendingOptIn = verdict.state === "pending";
+            // 3b. A linked worktree whose own `.mcp.json` says something else would
+            // run this checkout's copy instead of its own entry.
+            const differs = worktrees.filter((dir) => {
+                const theirs = worktreeEntry(dir, name);
+                if (theirs === undefined)
+                    return false;
+                return theirs === null || !sameServerConfig(isWrapped(theirs) ? unwrapEntry(theirs) : theirs, source);
+            });
+            if (differs.length > 0 && !named(name)) {
+                leaveUnwrapped(`the worktree${differs.length === 1 ? "" : "s"} ${differs.join(", ")} define${differs.length === 1 ? "s" : ""} it differently, ` +
+                    "and Claude Code would run this checkout's copy there too", `its calls are still recorded by the hooks (\`--server ${name}\` wraps it anyway)`);
+                continue;
+            }
+        }
+        // 3c. A remote server Claude Code signs in itself is never wrapped by default.
+        const blocked = isRemote(source) ? remoteWrapBlocker(source) : undefined;
+        if (blocked && !optedIn) {
+            // An older install may have wrapped it, which broke it: taken back.
+            leaveUnwrapped(blocked, `its calls are still recorded by the hooks (\`--server ${name}\` wraps it anyway)`);
             continue;
         }
-        if (isWrapped(entry.config)) {
-            // Already wrapped — but the control URL may have moved since (a second
-            // `install --port`). A stale `BIR_CONTROL_URL` is not cosmetic: discovery
-            // short-circuits on it, so the proxy would register with whatever is on
-            // the old port. If another project's control server is there, this
-            // project's MCP steps land in *its* run. Re-wrap from the stashed original
-            // so the entry is regenerated with the current URL.
-            // A wrapped entry is always a stdio entry (the proxy is what the host
-            // spawns), so `env` is present in practice; the cast is only to narrow the
-            // remote-or-stdio union.
-            const current = entry.config.env?.BIR_CONTROL_URL;
-            const urlStale = args.hooks && !args.configPath && current !== controlUrl;
-            const pathStale = !stillCurrent(entry.config, localProxyPath());
-            const stashed = sidecar.servers[sidecarKey(cwd, entry.name)]?.original;
-            if (!(urlStale || pathStale) || !stashed) {
-                out(`  = ${entry.name} — already wrapped`);
+        if (blocked && named(name)) {
+            out(`  ! ${name} — wrapping it because --server names it, although ${blocked}; if it answers 401, \`bir uninstall --server ${name}\``);
+        }
+        if (pendingOptIn && named(name)) {
+            out(`  ! ${name} — wrapping it because --server names it, although Claude Code has not been told to use it: ` +
+                "the local copy starts without asking");
+        }
+        const optIn = blocked || pendingOptIn ? { optedIn: true } : {};
+        // 4. Generate, and write only when it differs — which is what makes a
+        // re-run idempotent and catches every kind of staleness at once: a moved
+        // port, a moved runner or node, changed node flags, a changed upstream.
+        const proxied = wrapEntry(source, { ...gen, serverName: name });
+        const reason = rewrapReason(current, proxied);
+        const kind = isRemote(source) ? `${source.type} ${source.url}` : source.command;
+        if (target.kind === "mcpjson") {
+            if (current !== undefined && sameEntry(current, proxied)) {
+                out(`  = ${name} — already wrapped`);
                 continue;
             }
-            const was = `${entry.config.command} ${(entry.config.args ?? [])[0] ?? ""}`.trim();
-            entry.config = stashed;
-            out(urlStale
-                ? `  ~ ${entry.name} — re-wrapping: its control URL was ${current ?? "unset"}, now ${controlUrl}`
-                : `  ~ ${entry.name} — re-wrapping: its runner moved (was ${was})`);
-        }
-        // Phase 7.3: writing anywhere but the winning scope changes nothing.
-        if (entry.shadowed.length > 0) {
-            out(`  ! ${entry.name} — also defined in ${entry.shadowed.join(", ")} scope; ` +
-                `writing to ${entry.scope}, which is the one Claude Code uses`);
-        }
-        const proxied = wrapEntry(entry.config, {
-            serverName: entry.name,
-            controlUrl: args.hooks ? controlUrl : undefined,
-            noCorrelation: args.noCorrelation,
-            invocation,
-            proxyPath: invocation === "npx" ? undefined : localProxyPath(),
-            version: VERSION,
-            nodeFlags,
-        });
-        let file;
-        let text;
-        if (args.configPath) {
-            file = args.configPath;
-            backupFile(sidecar, file);
-            text = setGenericServerEntry(file, entry.name, proxied);
+            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);
+            putRecord(sidecar, cwd, name, found, {
+                original: kept.config,
+                scope: "project",
+                file: paths.mcpJson,
+                cwd,
+                installedAt: Date.now(),
+                ...(kept.redacted ? { secretsRedacted: true } : {}),
+                ...optIn,
+            });
         }
         else {
-            file = fileForScope(entry.scope, paths);
-            backupFile(sidecar, file);
-            const written = setServerEntry(entry.scope, cwd, entry.name, proxied, paths);
-            text = written.text;
-        }
-        noteWritten(sidecar, file, text);
-        sidecar.servers[sidecarKey(cwd, entry.name)] = {
-            original: entry.config,
-            scope: entry.scope,
-            file,
-            cwd,
-            installedAt: Date.now(),
-        };
-        const kind = isRemote(entry.config) ? `${entry.config.type} ${entry.config.url}` : entry.config.command;
-        out(`  + ${entry.name} → bir-proxy (${entry.scope} scope, upstream: ${kind})`);
+            // Never over a user's own entry under another spelling of this project.
+            const guard = target.kind === "override"
+                ? (cur) => cur === undefined || isWrapped(cur)
+                : (cur) => cur !== undefined;
+            const { keys } = setLocalEntries(claudeJson, target.keys, name, proxied, guard);
+            claude = readClaude();
+            wroteLocal = true;
+            const allKeys = [...new Set([...(found?.record.keys ?? []), ...keys, ...localHolders(claude, cwd, name)])];
+            if (target.kind === "override") {
+                putRecord(sidecar, cwd, name, found, {
+                    original: null,
+                    scope: "local",
+                    file: claudeJson,
+                    cwd,
+                    installedAt: Date.now(),
+                    override: { source: target.from },
+                    // What it copied, so `bir doctor` notices when that entry changes
+                    // (config/overrides.ts): the copy outranks it from now on.
+                    sourceSha: configSha(source),
+                    keys: allKeys,
+                    ...optIn,
+                });
+            }
+            else {
+                const kept = redactSecrets((found?.record.scope === "local" ? found.record.original : undefined) ?? source);
+                putRecord(sidecar, cwd, name, found, {
+                    original: kept.config,
+                    scope: "local",
+                    file: claudeJson,
+                    cwd,
+                    installedAt: Date.now(),
+                    keys: allKeys,
+                    ...(kept.redacted ? { secretsRedacted: true } : {}),
+                    ...optIn,
+                });
+            }
+            if (keys.length === 0) {
+                out(`  = ${name} — already wrapped`);
+                continue;
+            }
+        }
+        const where = target.kind === "override"
+            ? `local scope, over the ${target.from === "project" ? ".mcp.json" : "user-scope"} entry`
+            : target.kind === "mcpjson"
+                ? "project scope, in .mcp.json"
+                : "local scope";
+        out(reason ? `  ~ ${name} — re-wrapping: ${reason}` : `  + ${name} → bir-proxy (${where}; upstream: ${kind})`);
         wrapped += 1;
     }
-    // The scenario server (docs/calculatedReplay.md §6.3). Opt-in, and separate
-    // from the rest of install, because it is the one thing here the model can see:
-    // it adds `mcp__bir__run_scenario` to the tool list of every session in this
-    // project. That is a real cost, and it buys the delivery channel a fully
-    // wrapped scenario's results come back through.
-    if (args.replay) {
-        const entry = scenarioEntry({
-            invocation,
-            scenarioPath: invocation === "npx" ? undefined : localScenarioPath(),
-            version: VERSION,
-            controlUrl: args.hooks ? controlUrl : undefined,
-            nodeFlags,
-        });
-        // PROJECT SCOPE, NOT LOCAL — this was a bug worth the comment.
-        //
-        // The local scope lives in `~/.claude.json` under `projects[<path>]`, and
-        // Claude Code keys that map with FORWARD slashes, resolved to the project
-        // root. `process.cwd()` on Windows gives backslashes and the actual working
-        // directory, so an entry written from here lands under a key Claude Code
-        // never looks at: `bir status` shows the server, `/mcp` does not, and a
-        // direct replay has nowhere to deliver its results. Observed, not theorised
-        // — see `paths.ts`, which warns about exactly this trap for the proxy.
-        //
-        // `.mcp.json` has no such ambiguity: it is a file in this directory, read by
-        // path. It is also the file the proxies already go into, so the scenario
-        // server sits beside them and `bir uninstall` removes both the same way.
-        const scope = args.configPath ? "explicit" : "project";
-        let file;
-        let text;
-        if (args.configPath) {
-            file = args.configPath;
-            backupFile(sidecar, file);
-            text = setGenericServerEntry(file, SCENARIO_SERVER_KEY, entry);
-        }
-        else {
-            file = fileForScope(scope, paths);
-            backupFile(sidecar, file);
-            text = setServerEntry(scope, cwd, SCENARIO_SERVER_KEY, entry, paths).text;
+    if (wroteLocal && worktrees.length > 0) {
+        // Not a refusal — the main checkout is where `bir setup` was asked for —
+        // but sessions in those directories now run these entries too.
+        out(`  · Claude Code shares this local scope with the linked worktree${worktrees.length === 1 ? "" : "s"} ` +
+            `${worktrees.join(", ")}: sessions there run the wrapped servers too, recorded by this project's recorder ` +
+            "(`bir doctor` there says so)");
+    }
+    return { wrapped, theirBir, sharedKey };
+}
+/** The `bir` scenario server: local scope (or the explicit file, or `.mcp.json` on request). */
+function installScenarioServer(args, cwd, sidecar, gen, paths, mcpJsonMode, theirBir, sharedKey = false) {
+    const claudeJson = paths.claudeJson;
+    const found = findRecord(sidecar, cwd, SCENARIO_SERVER_KEY);
+    // Migration: an older install put it in `.mcp.json`, the file a team commits.
+    // A project that had it keeps it — a plain `bir install` (the by-hand path,
+    // or `--server x`) must not take direct replay's delivery tool away while
+    // saying it was moved — unless it cannot go to the local scope at all.
+    let migrated = false;
+    if (!args.configPath && !mcpJsonMode && found?.record.scope === "project") {
+        const inMcp = parseJsonFile(paths.mcpJson)?.mcpServers?.[SCENARIO_SERVER_KEY];
+        if (inMcp !== undefined && isScenarioServer(inMcp)) {
+            backupFile(sidecar, paths.mcpJson, claudeJson);
+            const text = setServerEntry("project", cwd, SCENARIO_SERVER_KEY, null, paths).text;
+            noteWritten(sidecar, paths.mcpJson, text, claudeJson);
+            removeIfOnlyOurs(sidecar, paths.mcpJson);
+            migrated = true;
+            const staysOut = sharedKey || Boolean(theirBir);
+            out(staysOut
+                ? `  ~ ${SCENARIO_SERVER_KEY} — removed from ${paths.mcpJson} (a file a team commits); it could not be put in the local scope (see below)`
+                : `  ~ ${SCENARIO_SERVER_KEY} — moved out of ${paths.mcpJson} (a file a team commits) into the local scope`);
         }
-        noteWritten(sidecar, file, text);
+        delete sidecar.servers[found.key];
+    }
+    if (!args.replay && !migrated) {
+        const present = args.configPath
+            ? readGenericServers(args.configPath)[SCENARIO_SERVER_KEY]
+            : projectScope((parseJsonFile(claudeJson) ?? {}).projects, cwd)[SCENARIO_SERVER_KEY];
+        if (present !== undefined && isScenarioServer(present))
+            out(`  = ${SCENARIO_SERVER_KEY} — the scenario server (calculated replay)`);
+        return;
+    }
+    if (sharedKey && !args.configPath && !mcpJsonMode) {
+        out(`  ! ${SCENARIO_SERVER_KEY} — the scenario server was not added: in the local scope it would apply to the whole repository (see above); replay steers without it`);
+        return;
+    }
+    if (theirBir) {
+        out(`  ! ${SCENARIO_SERVER_KEY} — the scenario server was not added: a server of yours is called ${SCENARIO_SERVER_KEY}`);
+        return;
+    }
+    const entry = scenarioEntry({
+        invocation: gen.invocation,
+        scenarioPath: gen.invocation === "npx" ? undefined : localScenarioPath(),
+        version: VERSION,
+        controlUrl: gen.controlUrl,
+        nodeFlags: gen.nodeFlags,
+        node: gen.node,
+    });
+    const record = (scope, file, keys) => {
         sidecar.servers[sidecarKey(cwd, SCENARIO_SERVER_KEY)] = {
             original: null, // it did not exist before; uninstall removes rather than restores
             scope,
             file,
             cwd,
             installedAt: Date.now(),
+            ...(keys ? { keys } : {}),
         };
-        out(`  + ${SCENARIO_SERVER_KEY} → bir-scenario (calculated replay; ${scope} scope)`);
+    };
+    let changed;
+    let current;
+    if (args.configPath) {
+        current = readGenericServers(args.configPath)[SCENARIO_SERVER_KEY];
+        changed = !sameEntry(current, entry);
+        if (changed) {
+            backupFile(sidecar, args.configPath, claudeJson, true);
+            noteWritten(sidecar, args.configPath, setGenericServerEntry(args.configPath, SCENARIO_SERVER_KEY, entry), claudeJson, true);
+        }
+        if (changed || !found)
+            record("explicit", args.configPath);
+    }
+    else if (mcpJsonMode) {
+        current = parseJsonFile(paths.mcpJson)?.mcpServers?.[SCENARIO_SERVER_KEY];
+        changed = !sameEntry(current, entry);
+        if (changed) {
+            backupFile(sidecar, paths.mcpJson, claudeJson);
+            noteWritten(sidecar, paths.mcpJson, setServerEntry("project", cwd, SCENARIO_SERVER_KEY, entry, paths).text, claudeJson);
+        }
+        record("project", paths.mcpJson);
+    }
+    else {
+        // LOCAL SCOPE, under the key Claude Code itself reads (resolve.ts,
+        // claudeProjectKey). An older runner wrote it under the raw working
+        // directory — backslashes on Windows — which Claude Code never reads, and
+        // moved it to `.mcp.json` to escape that; the key is right now, and
+        // `.mcp.json` is a file a team commits.
+        const claude = parseJsonFile(claudeJson) ?? {};
+        const keys = projectKeysFor(claude.projects, cwd);
+        current = projectScope(claude.projects, cwd)[SCENARIO_SERVER_KEY];
+        const written = setLocalEntries(claudeJson, keys, SCENARIO_SERVER_KEY, entry, (cur) => cur === undefined || isScenarioServer(cur));
+        changed = written.keys.length > 0;
+        record("local", claudeJson, [...new Set([...keys, ...(found?.record.keys ?? [])])]);
+    }
+    if (!changed)
+        out(`  = ${SCENARIO_SERVER_KEY} — the scenario server (calculated replay)`);
+    else if (current !== undefined && isScenarioServer(current))
+        out(`  ~ ${SCENARIO_SERVER_KEY} — re-writing the scenario server: its runner or control URL moved`);
+    else
+        out(`  + ${SCENARIO_SERVER_KEY} → bir-scenario (calculated replay; ${args.configPath ? "explicit" : mcpJsonMode ? "project" : "local"} scope)`);
+}
+/** True when a server this directory's sessions would start runs through the runner. */
+function wrappedHere(cwd) {
+    try {
+        return resolveServers(cwd).some((s) => s.name !== SCENARIO_SERVER_KEY && isWrapped(s.config));
+    }
+    catch {
+        return false;
+    }
+}
+/** A JSON value with every object's keys sorted, for comparing two texts by content. */
+function canonicalJson(value) {
+    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;
+    return JSON.stringify(sort(value));
+}
+/**
+ * After a migration took every runner entry an older install wrote into
+ * `.mcp.json` back out (each restored through a JSON edit, which re-indents
+ * the whole file), put the file's own bytes back when it now says exactly
+ * what it said before that install — so the team's committed file shows no
+ * diff at all, as "put back as it was" promises. Only from a backup nobody
+ * changed the file under (not stale), only once nothing of ours is left in
+ * it, and only when the content is equal; anything else is left as written.
+ */
+function restoreMcpJsonBytes(sidecar, paths) {
+    try {
+        const file = paths.mcpJson;
+        const backup = sidecar.files?.[file];
+        if (!backup || backup.stale || backupIsCreation(backup))
+            return;
+        const current = readTextOrNull(file);
+        if (current === null || holdsRunnerEntries(file, current))
+            return;
+        if (!backup.writtenSha || sha256(current) !== backup.writtenSha)
+            return;
+        const original = backupOriginalText(backup, current);
+        if (typeof original !== "string" || original === current)
+            return;
+        const strip = (t) => (t.charCodeAt(0) === 0xfeff ? t.slice(1) : t);
+        if (canonicalJson(JSON.parse(strip(current))) !== canonicalJson(JSON.parse(strip(original))))
+            return;
+        writeFileAtomic(file, original);
+        noteWritten(sidecar, file, original, paths.claudeJson);
+    }
+    catch {
+        /* left as the migration wrote it: same content, other whitespace */
+    }
+}
+/**
+ * Delete a `.mcp.json` that an install created and that now holds nothing but
+ * an empty `mcpServers` — what taking our entries out of it leaves behind.
+ */
+function removeIfOnlyOurs(sidecar, file) {
+    const backup = sidecar.files?.[file];
+    if (!backup || !backupIsCreation(backup) || backup.stale)
+        return;
+    const parsed = parseJsonFile(file);
+    if (!parsed)
+        return;
+    const keys = Object.keys(parsed);
+    const servers = parsed.mcpServers;
+    if (keys.length === 1 && keys[0] === "mcpServers" && servers && Object.keys(servers).length === 0) {
+        try {
+            rmSync(file, { force: true });
+            delete sidecar.files?.[file];
+        }
+        catch {
+            /* leave it */
+        }
+    }
+}
+// ── uninstall ──────────────────────────────────────────────────────────────
+/**
+ * The project directory a settings file or `.mcp.json` sits in (normalised),
+ * or undefined for any other file. What a file belongs to is decided by where
+ * it is, not by whether it is somewhere under the directory being uninstalled:
+ * a project nested inside another keeps its own settings, and uninstalling the
+ * outer one must not take the inner one's hooks with it.
+ */
+function fileProjectDir(file) {
+    const n = normalizePath(file);
+    return (/^(.*)\/\.claude\/settings(?:\.local)?\.json$/i.exec(n) ?? /^(.*)\/\.mcp\.json$/i.exec(n))?.[1];
+}
+/**
+ * Every directory an install on this machine touched: normalised → as
+ * spelled (a record's own spelling first, so messages name it as it was typed).
+ */
+function installedProjects(sidecar) {
+    const found = new Map();
+    const add = (dir) => {
+        if (!dir)
+            return;
+        const key = normalizePath(dir);
+        if (!found.has(key))
+            found.set(key, dir);
+    };
+    for (const record of Object.values(sidecar.servers))
+        add(record.cwd);
+    for (const file of sidecar.hookFiles ?? [])
+        add(dirname(dirname(file)));
+    for (const key of Object.keys(sidecar.projects ?? {}))
+        add(key);
+    return found;
+}
+/** The installed projects other than `cwd`, as spelled. */
+function otherProjects(sidecar, cwd) {
+    const here = normalizePath(cwd);
+    return [...installedProjects(sidecar)].filter(([key]) => key !== here).map(([, dir]) => dir);
+}
+/** A proxy or the scenario server: an entry that stops working when the runner is removed. */
+function ourEntry(e) {
+    return e !== undefined && (isWrapped(e) || isScenarioServer(e));
+}
+function leftoverWhere(e) {
+    const other = e.file ? ` of ${e.file}` : "";
+    if (e.scope === "local")
+        return `local scope${other}`;
+    if (e.scope === "user")
+        return `your user scope${other}, which every project uses`;
+    return e.file ?? e.scope;
+}
+/**
+ * The other `.claude.json` files this project's install wrote to — named by its
+ * records and its project record, and not the one this environment reads
+ * (claudeJsonPath follows CLAUDE_CONFIG_DIR). Only files that exist.
+ */
+function otherClaudeFiles(sidecar, cwd, claudeJson) {
+    const here = normalizePath(cwd);
+    const named = [
+        ...Object.values(sidecar.servers)
+            .filter((r) => normalizePath(r.cwd) === here && (r.scope === "local" || r.scope === "user"))
+            .map((r) => r.file),
+        ...(projectRecord(sidecar, cwd)?.claudeJsonFiles ?? []),
+    ];
+    const seen = new Set([normalizePath(claudeJson)]);
+    const found = [];
+    for (const file of named) {
+        if (typeof file !== "string" || !file || seen.has(normalizePath(file)))
+            continue;
+        seen.add(normalizePath(file));
+        if (existsSync(file))
+            found.push(file);
+    }
+    return found;
+}
+/**
+ * Every entry of ours this directory's sessions could still spawn, scope by
+ * scope — not only the winning one: taking a local copy out lets the
+ * `.mcp.json` or user-scope entry under it win, and that one may be wrapped too.
+ *
+ * The local scope is read under this directory's own spellings, and under the
+ * repository's key only when that repository is not an installed project of
+ * its own: a subdirectory shares its root's local scope, and what the root's
+ * install wrapped there is the root's to undo. A file that cannot be read is
+ * returned as such, so the caller reports it instead of calling it clean.
+ */
+function runnerLeftovers(cwd, sidecar, configPath, otherClaude = []) {
+    const unreadable = [];
+    const found = [];
+    if (configPath) {
+        try {
+            for (const [name, config] of Object.entries(readGenericServers(configPath))) {
+                if (ourEntry(config))
+                    found.push({ name, scope: "explicit", config, file: configPath });
+            }
+        }
+        catch (err) {
+            if (existsSync(configPath))
+                unreadable.push(`${configPath} (${errText(err)})`);
+        }
+        return { leftovers: found, unreadable };
+    }
+    const paths = claudeCodePaths(cwd);
+    const here = normalizePath(cwd);
+    const root = normalizePath(claudeProjectRoot(cwd));
+    const want = new Set([here]);
+    if (root === here || !installedProjects(sidecar).has(root))
+        want.add(normalizePath(claudeProjectKey(cwd)));
+    // This environment's `.claude.json` first, then any other one this project's
+    // install wrote to (another CLAUDE_CONFIG_DIR), named as such.
+    const claudeFiles = [
+        { file: paths.claudeJson, other: false },
+        ...otherClaude.filter((f) => !isClaudeJson(f, paths.claudeJson)).map((file) => ({ file, other: true })),
+    ];
+    const users = [];
+    for (const { file, other } of claudeFiles) {
+        let claude = {};
+        try {
+            claude = parseJsonFile(file) ?? {};
+        }
+        catch (err) {
+            unreadable.push(`${file} (${errText(err)})`);
+            continue;
+        }
+        const local = new Map();
+        for (const [key, project] of Object.entries(claude.projects ?? {})) {
+            if (!want.has(normalizePath(key)))
+                continue;
+            for (const [name, config] of Object.entries(project?.mcpServers ?? {})) {
+                if (!ourEntry(config))
+                    continue;
+                const seen = local.get(name);
+                if (seen)
+                    seen.keys?.push(key);
+                else
+                    local.set(name, { name, scope: "local", config, keys: [key], ...(other ? { file } : {}) });
+            }
+        }
+        found.push(...local.values());
+        for (const [name, config] of Object.entries(claude.mcpServers ?? {})) {
+            if (ourEntry(config))
+                users.push({ name, scope: "user", config, ...(other ? { file } : {}) });
+        }
+    }
+    try {
+        const mcp = parseJsonFile(paths.mcpJson)?.mcpServers;
+        for (const [name, config] of Object.entries(mcp ?? {})) {
+            if (ourEntry(config))
+                found.push({ name, scope: "project", config, file: paths.mcpJson });
+        }
+    }
+    catch (err) {
+        unreadable.push(`${paths.mcpJson} (${errText(err)})`);
+    }
+    found.push(...users);
+    return { leftovers: found, unreadable };
+}
+/**
+ * The `.mcp.json` or user-scope entry a local entry of `name` shadows, if any —
+ * unwrapped when an older runner wrapped it there, so it compares with what a
+ * local copy of it was made from. `claudeJson`: the file whose user scope is
+ * below (default: this environment's).
+ */
+function entryBelow(cwd, name, claudeJson) {
+    try {
+        const paths = claudeCodePaths(cwd, claudeJson);
+        const mcp = parseJsonFile(paths.mcpJson)?.mcpServers;
+        const below = mcp?.[name] ?? (parseJsonFile(paths.claudeJson)?.mcpServers ?? {})[name];
+        return below !== undefined && isWrapped(below) ? unwrapEntry(below) : below;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True when another installed project lives in the same repository, and so shares its exclude file. */
+function sharesRepository(cwd, sidecar) {
+    const root = normalizePath(claudeProjectRoot(cwd));
+    return otherProjects(sidecar, cwd).some((dir) => normalizePath(claudeProjectRoot(dir)) === root);
+}
+/**
+ * Undo `bir install` for ONE directory — the whole of it, or only
+ * `opts.servers` — and leave every other project exactly as it is.
+ *
+ * In order: the byte-for-byte restores (a project file we wrote and nobody
+ * touched since); the entries a record stashed; every entry of ours no record
+ * explains, rebuilt from the wrapped entry's own arguments (an install that
+ * stopped halfway, an older runner, a lost installed.json, a cwd spelled with
+ * another drive-letter case); then the hooks. Last it READS BACK what a
+ * session here would spawn, and reports anything of ours still there —
+ * "Uninstalled." followed by removing the package is exactly how a user's
+ * servers end up pointing at files that are gone.
+ *
+ * Bookkeeping is dropped only for what was undone, so running it again
+ * retries the rest. Writes the sidecar; never touches the recorder.
+ */
+function uninstallProject(cwd, sidecar, opts) {
+    const paths = claudeCodePaths(cwd);
+    const claudeJson = paths.claudeJson;
+    const here = normalizePath(cwd);
+    const narrow = opts.servers.length > 0;
+    const wanted = (name) => !narrow || opts.servers.includes(name);
+    const mine = Object.entries(sidecar.servers)
+        .filter(([, record]) => normalizePath(record.cwd) === here)
+        .map(([key, record]) => ({ key, record, name: recordName(key, record) }));
+    const remaining = new Map();
+    // Every `.claude.json` this project's install wrote to, besides this
+    // environment's: known now, before the records that name them are dropped.
+    const otherClaude = opts.configPath ? [] : otherClaudeFiles(sidecar, cwd, claudeJson);
+    /**
+     * The `.claude.json` a local- or user-scope record's entry is in: the file
+     * the install wrote, which CLAUDE_CONFIG_DIR may have made another one than
+     * this environment's — not whichever this shell happens to read.
+     */
+    const claudeFileOf = (record) => (record.scope === "local" || record.scope === "user") && typeof record.file === "string" && record.file
+        ? record.file
+        : claudeJson;
+    const readClaude = (file = claudeJson) => parseJsonFile(file) ?? {};
+    const currentEntry = (record, name) => {
+        if (record.scope === "explicit")
+            return readGenericServers(record.file)[name];
+        if (record.scope === "local") {
+            const claude = readClaude(claudeFileOf(record));
+            for (const key of record.keys ?? [projectKeyFor(claude.projects, record.cwd)]) {
+                const e = claude.projects?.[key]?.mcpServers?.[name];
+                if (e !== undefined)
+                    return e;
+            }
+            return undefined;
+        }
+        if (record.scope === "user")
+            return readClaude(claudeFileOf(record)).mcpServers?.[name];
+        return parseJsonFile(record.file)?.mcpServers?.[name];
+    };
+    /** Put one entry back (or take it out), touching it only while it is still ours. */
+    const repair = (record, name) => {
+        if (record.scope === "explicit" && !existsSync(record.file)) {
+            return { what: `its config file ${record.file} is gone; nothing to undo`, done: true };
+        }
+        const file = claudeFileOf(record);
+        const elsewhere = (record.scope === "local" || record.scope === "user") && !isClaudeJson(file, claudeJson);
+        if (elsewhere && !existsSync(file)) {
+            return { what: `its config file ${file} is gone; nothing to undo`, done: true };
+        }
+        const where = elsewhere ? ` in ${file}, not this environment's ${claudeJson}` : "";
+        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));
+        if (restored === undefined)
+            return { what: `left as it is (its original could not be rebuilt)${where}`, done: false };
+        if (record.scope === "explicit")
+            setGenericServerEntry(record.file, name, restored);
+        else if (record.scope === "local") {
+            const keys = record.keys ?? [projectKeyFor(readClaude(file).projects, record.cwd)];
+            setLocalEntries(file, keys, name, restored, ourEntry);
+        }
+        else if (record.scope === "user")
+            setServerEntry("user", record.cwd, name, restored, { ...paths, claudeJson: file });
+        else
+            setServerEntry(record.scope, record.cwd, name, restored, paths);
+        return { what: `${restored === null ? "removed" : "restored"}${where}`, done: true };
+    };
+    const myRecordFiles = new Set(mine.map((m) => normalizePath(m.record.file)));
+    const ownsFile = (file) => {
+        const dir = fileProjectDir(file);
+        if (dir !== undefined)
+            return dir === here;
+        return normalizePath(file).startsWith(`${here}/`) || myRecordFiles.has(normalizePath(file));
+    };
+    const myHookFiles = (sidecar.hookFiles ?? []).filter((f) => fileProjectDir(f) === here);
+    const hookedNow = [paths.settingsLocal, paths.settings].filter((f) => hasBirHooks(f));
+    const before = runnerLeftovers(cwd, sidecar, opts.configPath, otherClaude);
+    if (mine.length === 0 &&
+        myHookFiles.length === 0 &&
+        hookedNow.length === 0 &&
+        before.leftovers.length === 0 &&
+        before.unreadable.length === 0) {
+        return { nothing: true, remaining: [] };
+    }
+    // 1. Byte-for-byte: a project file we wrote, nobody touched since, and whose
+    // snapshot is not stale goes back exactly as it was. Never ~/.claude.json,
+    // and never a file another project's install also wrote.
+    const restoredWhole = new Set();
+    const othersFiles = new Set(Object.values(sidecar.servers)
+        .filter((r) => normalizePath(r.cwd) !== here)
+        .map((r) => normalizePath(r.file)));
+    if (!narrow) {
+        for (const [file, backup] of Object.entries(sidecar.files ?? {})) {
+            if (isClaudeJson(file, claudeJson) || othersFiles.has(normalizePath(file)) || !ownsFile(file))
+                continue;
+            const current = readTextOrNull(file);
+            if (current === null || !backup.writtenSha || backup.stale || sha256(current) !== backup.writtenSha)
+                continue;
+            if (backupIsCreation(backup)) {
+                out(`  - ${file} — created by install; leaving in place (now empty of our entries)`);
+                continue;
+            }
+            // Kept without its env and header values (generate.ts,
+            // protectBackupText): read back from the entries in the file as we left
+            // it, and used only when that gives the original exactly.
+            const original = backupOriginalText(backup, current);
+            if (typeof original !== "string") {
+                out(`  ~ ${file} — its entries are repaired one by one (the values in it could not all be read back)`);
+                continue;
+            }
+            try {
+                writeFileAtomic(file, original);
+            }
+            catch (err) {
+                out(`  ! ${file} — could not be restored whole (${errText(err)}); repairing its entries instead`);
+                continue;
+            }
+            restoredWhole.add(normalizePath(file));
+            out(`  ← ${file} — restored byte-for-byte`);
+        }
+    }
+    // 2. What the records stashed.
+    for (const { key, record, name } of mine) {
+        if (!wanted(name))
+            continue;
+        if (restoredWhole.has(normalizePath(record.file))) {
+            delete sidecar.servers[key];
+            continue;
+        }
+        // Repair the entry rather than clobbering the file, and say what happened.
+        let result;
+        try {
+            result = repair(record, name);
+        }
+        catch (err) {
+            result = { what: `left as it is (${errText(err)})`, done: false };
+        }
+        out(`  ← ${name} — ${result.what}`);
+        if (result.done)
+            delete sidecar.servers[key];
+        else
+            remaining.set(name, `${name} (${record.file}) — ${result.what}`);
+    }
+    // 3. Entries of ours that no record explains.
+    for (const stray of runnerLeftovers(cwd, sidecar, opts.configPath, otherClaude).leftovers) {
+        if (!wanted(stray.name) || remaining.has(stray.name))
+            continue;
+        if (stray.scope === "user" && !opts.all) {
+            // Every project uses the user scope. One that another project's install
+            // wrapped is that project's to undo.
+            const owner = Object.entries(sidecar.servers).find(([key, r]) => r.scope === "user" && recordName(key, r) === stray.name && normalizePath(r.cwd) !== here);
+            if (owner) {
+                remaining.set(stray.name, `${stray.name} — wrapped in your user scope (every project) by the install in ${owner[1].cwd}: ` +
+                    "`bir uninstall` there, or `bir uninstall --all`");
+                continue;
+            }
+        }
+        let back = isScenarioServer(stray.config) ? null : unwrapEntry(stray.config);
+        const where = leftoverWhere(stray);
+        // Local and user scope: the `.claude.json` it sits in (another profile's, named as such).
+        const strayClaude = stray.scope === "local" || stray.scope === "user" ? (stray.file ?? claudeJson) : claudeJson;
+        if (back && stray.scope === "local" && sameServerConfig(back, entryBelow(cwd, stray.name, strayClaude))) {
+            // An override (what install writes over a `.mcp.json` or user-scope
+            // server) whose record is lost: the entry under it is the original, so
+            // the copy goes rather than shadowing the team's entry from now on.
+            back = null;
+        }
+        if (back === undefined) {
+            remaining.set(stray.name, `${stray.name} (${where}) — its original could not be rebuilt from the wrapped entry; edit it by hand`);
+            continue;
+        }
+        try {
+            if (stray.scope === "explicit")
+                setGenericServerEntry(stray.file, stray.name, back);
+            else if (stray.scope === "local")
+                setLocalEntries(strayClaude, stray.keys ?? [], stray.name, back, ourEntry);
+            else
+                setServerEntry(stray.scope, cwd, stray.name, back, { ...paths, claudeJson: strayClaude });
+            const how = back !== null
+                ? `put back as the plain server in ${where} (no record of it here; rebuilt from the wrapped entry)`
+                : isScenarioServer(stray.config)
+                    ? `removed from ${where} (no record of it here)`
+                    : `its wrapped copy removed from ${where}; the entry under it is the original (no record of it here)`;
+            out(`  ← ${stray.name} — ${how}${stray.scope === "project" ? " — commit that if your team shares .mcp.json" : ""}`);
+        }
+        catch (err) {
+            remaining.set(stray.name, `${stray.name} (${where}) — ${errText(err)}`);
+        }
+    }
+    // 4. The hooks.
+    if (!narrow) {
+        const seen = new Set();
+        for (const settings of [...myHookFiles, ...hookedNow]) {
+            const norm = normalizePath(settings);
+            if (seen.has(norm))
+                continue;
+            seen.add(norm);
+            if (restoredWhole.has(norm) || !existsSync(settings))
+                continue;
+            try {
+                const had = hasBirHooks(settings);
+                uninstallHooks(settings);
+                // The scenario server's pre-approval lives beside the hooks in the
+                // person's own file; the team's settings.json never got one.
+                if (norm !== normalizePath(paths.settings) || myHookFiles.some((f) => normalizePath(f) === norm)) {
+                    disableMcpjsonServers(settings, [SCENARIO_SERVER_KEY]);
+                }
+                if (had)
+                    out(`  ← hooks removed from ${settings}`);
+            }
+            catch (err) {
+                remaining.set(`hooks:${norm}`, `the hooks in ${settings} — ${errText(err)}`);
+            }
+        }
+    }
+    // 5. Read it back: what would a session here spawn now — in this
+    // environment, and in any other profile the install wrote to?
+    const after = runnerLeftovers(cwd, sidecar, opts.configPath, otherClaude);
+    for (const e of after.leftovers) {
+        if (!wanted(e.name) || remaining.has(e.name))
+            continue;
+        remaining.set(e.name, `${e.name} (${leftoverWhere(e)}) still runs through the runner`);
+    }
+    for (const file of after.unreadable)
+        remaining.set(`read:${file}`, `${file} could not be read, so nothing in it was undone`);
+    if (!narrow) {
+        for (const file of [paths.settingsLocal, paths.settings]) {
+            const key = `hooks:${normalizePath(file)}`;
+            if (hasBirHooks(file) && !remaining.has(key))
+                remaining.set(key, `hooks of ours are still in ${file}`);
+        }
+    }
+    if (!opts.configPath) {
+        // Not ours to undo from here, but a session here still spawns them: the
+        // repository's install owns the local scope this subdirectory shares.
+        const listed = new Set(after.leftovers.map((e) => e.name));
+        let live = [];
+        try {
+            live = resolveServers(cwd);
+        }
+        catch {
+            /* reported above as unreadable */
+        }
+        const theirs = live.filter((s) => ourEntry(s.config) && !listed.has(s.name) && wanted(s.name)).map((s) => s.name);
+        if (theirs.length) {
+            out(`  · ${theirs.join(", ")} stay wrapped here: they belong to the install in ${claudeProjectRoot(cwd)} ` +
+                "(Claude Code shares the local scope per repository) — `bir uninstall` there");
+        }
+    }
+    // 6. The bookkeeping: only this project's, and only once nothing is left to
+    // retry — a second run needs the snapshots and records to finish the job.
+    if (!narrow) {
+        sidecar.hookFiles = (sidecar.hookFiles ?? []).filter((f) => fileProjectDir(f) !== here || remaining.has(`hooks:${normalizePath(f)}`));
+        if (remaining.size === 0) {
+            for (const file of Object.keys(sidecar.files ?? {})) {
+                if (isClaudeJson(file, claudeJson) || (ownsFile(file) && !othersFiles.has(normalizePath(file))))
+                    delete sidecar.files?.[file];
+            }
+            const record = projectRecord(sidecar, cwd);
+            if (sidecar.projects)
+                delete sidecar.projects[here];
+            if (record?.excludeAdded !== false && existsSync(cwd) && !sharesRepository(cwd, sidecar)) {
+                const exclude = removeGitExclude(cwd);
+                if (exclude)
+                    out(`  ← ${LOCAL_SETTINGS_EXCLUDE} removed from ${exclude}`);
+            }
+        }
+    }
+    writeSidecar(sidecar);
+    return { nothing: false, remaining: [...remaining.values()] };
+}
+/**
+ * True when a Claude Code session is using this recorder right now: a turn is
+ * mid-run, or a registered proxy — a session's own child process — is alive.
+ */
+function recorderInUse(health) {
+    if (activeSessions(health) > 0)
+        return true;
+    const proxies = health.registeredProxies ?? [];
+    return proxies.some((p) => typeof p.pid === "number" && p.pid > 0 && p.pid !== process.pid && pidAlive(p.pid));
+}
+/**
+ * Stop this project's recorder at the end of an uninstall — unless a Claude
+ * Code session here is still using it.
+ *
+ * An open session keeps the hooks it started with, and its MCP servers are
+ * already running. Stop the recorder under it and every prompt and tool call
+ * there shows a hook error until the session restarts. So a recorder that is
+ * serving one is left running with this project switched OFF — it answers
+ * those hooks with nothing at once and records nothing — and the person is
+ * told to restart the session, then `bir down`. `bir install` here again, or
+ * `bir on --here`, ends that switch.
+ */
+async function retireRecorder(cwd) {
+    // A recorder a reinstall on another port left serving an older window
+    // (LC-1): stopped when nothing uses it, else it stays for that window and
+    // is named — it is not reachable through the discovery file.
+    for (const record of await supersededRecorders(cwd)) {
+        const health = await supersededHealth(record);
+        if (health && recorderInUse(health)) {
+            out(`  · a superseded recorder (${describeSuperseded(record)}) still serves a Claude Code session opened before ` +
+                "the last reinstall; restart that session, then `bir down` here");
+            continue;
+        }
+        const result = await stopSuperseded(record);
+        if (result.stopped)
+            out(`  ← superseded recorder stopped (${describeSuperseded(record)})`);
+    }
+    const live = await daemonStatus(cwd);
+    if (!live) {
+        clearUninstallMark(cwd);
+        return;
+    }
+    if (recorderInUse(live.health)) {
+        try {
+            markOffForUninstall(cwd);
+            if (predatesOffSwitch(live.health)) {
+                // 0.2.12 or older: it has no off switch, so the mark changes nothing
+                // for it — it keeps recording that session, and approving its wrapped
+                // MCP calls, as before. Said as it is; stopping it instead would put a
+                // hook error on every prompt of a session the person is using.
+                out(`  · the recorder (pid ${live.info.pid}, ${recorderVersion(live.health, live.info) || "an older version"}) stays up for ` +
+                    "the Claude Code session open here. It predates the off switch, so it keeps recording that session " +
+                    "(and approving its wrapped MCP calls) until the session ends. Restart the session, then `bir down`");
+                return;
+            }
+            out(`  · the recorder (pid ${live.info.pid}) stays up for the Claude Code session open here, switched OFF: ` +
+                "it answers that session's hooks with nothing and records nothing. Restart the session, then `bir down`");
+            return;
+        }
+        catch {
+            /* no switch to leave it with: stop it after all */
+        }
+    }
+    const result = await stopDaemon(cwd);
+    if (result.stopped || result.stale) {
+        clearUninstallMark(cwd);
+        if (result.stopped)
+            out(`  ← recorder stopped (pid ${live.info.pid})`);
+    }
+    else {
+        out(`  ! the recorder (pid ${live.info.pid}) did not stop — \`bir down\` here`);
+    }
+}
+/**
+ * True when a recorder's `/health` has no `off` field: it is older than the
+ * off switch (0.2.12 and before) and ignores it — keeps recording, and
+ * approving wrapped MCP calls, whatever `bir off` or an uninstall's mark says.
+ */
+function predatesOffSwitch(health) {
+    return !("off" in health);
+}
+/** The version a recorder reports, or "". */
+function recorderVersion(health, info) {
+    const v = health.hooksVersion ?? info?.version;
+    return typeof v === "string" ? v : "";
+}
+/**
+ * A running recorder reads the replay switch once, when it starts
+ * (control/recorder-main.ts), so after the switch went off it would go on
+ * replaying until something restarted it. Restart one no session is using;
+ * leave one that serves an open session — stopping it would put a hook error
+ * on every prompt there — and say what is left to do.
+ */
+async function restartForReplaySwitch(cwd) {
+    const live = await daemonStatus(cwd);
+    const replay = live?.health.replay;
+    const want = projectRecord(readSidecar(), cwd)?.replay?.enabled !== false;
+    // `source: "env"`: BIR_REPLAY where it was started outranks the switch, and
+    // a restart from here would not carry that environment's answer.
+    if (!live || typeof replay?.enabled !== "boolean" || replay.enabled === want || replay.source === "env")
+        return;
+    if (recorderInUse(live.health)) {
+        out(`  · the recorder (pid ${live.info.pid}) keeps replay ${replay.enabled ? "on" : "off"} for the Claude Code session ` +
+            "open here — once it ends, `bir up --restart` applies the change");
+        return;
+    }
+    try {
+        await stopDaemon(cwd);
+        const { status } = await ensureDaemon(cwd, { hooksScript: localHooksPath() });
+        out(`  ~ recorder restarted (pid ${status.info.pid}) so the replay switch applies`);
+    }
+    catch (err) {
+        out(`  ! the recorder did not restart (${errText(err)}); the next session here starts it with the new switch`);
+    }
+}
+async function uninstall(args) {
+    if (args.all)
+        return uninstallAll(args);
+    const cwd = process.cwd();
+    const sidecar = readSidecar();
+    // `--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.
+    if (args.replay) {
+        const target = findRecord(sidecar, cwd, SCENARIO_SERVER_KEY);
+        // Switched off as well as taken out: without the switch the recorder kept
+        // replaying matched prompts — steering, or running steps unattended for a
+        // delivery tool that is no longer there. `bir replay on` turns it back on.
+        const switched = settleReplaySwitch(sidecar, cwd, "refused", false);
+        if (!target) {
+            if (switched)
+                writeSidecar(sidecar);
+            out(`Calculated replay is not installed for this directory${switched ? "; it is switched off here now" : ""}.`);
+            if (switched)
+                await restartForReplaySwitch(cwd);
+            return 0;
+        }
+        const result = uninstallProject(cwd, sidecar, { servers: [SCENARIO_SERVER_KEY], configPath: args.configPath });
+        await restartForReplaySwitch(cwd);
+        out();
+        if (result.remaining.length) {
+            for (const r of result.remaining)
+                out(`  ! ${r}`);
+            return 1;
+        }
+        out("Calculated replay is uninstalled and switched off here. Recording is unchanged.");
+        out("The prompt hook keeps its timeout; `bir install` rewrites it either way.");
+        return 0;
+    }
+    const narrow = args.servers.length > 0;
+    const result = uninstallProject(cwd, sidecar, { servers: args.servers, configPath: args.configPath });
+    if (result.nothing) {
+        out("Nothing installed for this directory.");
+        const others = otherProjects(sidecar, cwd);
+        if (others.length)
+            out(`(The runner is set up in ${others.join(", ")}; \`bir uninstall --all\` removes it everywhere.)`);
+        return 0;
+    }
+    if (!narrow && !args.keepRecorder)
+        await retireRecorder(cwd);
+    out();
+    if (result.remaining.length) {
+        out("Not everything could be undone. These still run through the runner here:");
+        for (const r of result.remaining)
+            out(`  ! ${r}`);
+        out("Fix what is named, then run `bir uninstall` again. Do not remove the runner before it says Uninstalled:");
+        out("these entries name its files, and would stop working without them.");
+        return 1;
+    }
+    out(narrow ? `Uninstalled ${args.servers.join(", ")}. Hooks and the other servers are unchanged.` : "Uninstalled.");
+    if (!narrow) {
+        const others = otherProjects(readSidecar(), cwd);
+        if (others.length) {
+            out(`The runner is still set up in ${others.length} other project${others.length === 1 ? "" : "s"}: ${others.join(", ")}.`);
+            out("`bir uninstall --all` removes it from every one — run that before removing the package.");
+        }
+    }
+    return 0;
+}
+/** Directories named in ~/.claude.json whose files hold something of ours, though no record here says so. */
+function projectsWithRunnerFiles(claude) {
+    const found = [];
+    for (const dir of Object.keys(claude.projects ?? {})) {
+        try {
+            if (!existsSync(dir))
+                continue;
+            const settings = claudeCodePaths(dir);
+            if (hasBirHooks(settings.settingsLocal) || hasBirHooks(settings.settings)) {
+                found.push(dir);
+                continue;
+            }
+            const mcp = parseJsonFile(settings.mcpJson)?.mcpServers;
+            if (Object.values(mcp ?? {}).some((c) => ourEntry(c)))
+                found.push(dir);
+        }
+        catch {
+            /* unreadable: not ours to guess at */
+        }
+    }
+    return found;
+}
+/**
+ * Put back every entry of ours left anywhere in ~/.claude.json: the user
+ * scope (every project) and the local scope of every project, including ones
+ * no record here knows — an older runner's, or a lost installed.json's.
+ */
+function sweepClaudeJson(claudeJson, remaining) {
+    let claude;
+    try {
+        claude = parseJsonFile(claudeJson) ?? {};
+    }
+    catch (err) {
+        remaining.push(`${claudeJson} could not be read (${errText(err)}), so nothing in it was undone`);
+        return 0;
+    }
+    let fixed = 0;
+    // This file, whichever profile it is: not this environment's by default.
+    const paths = claudeCodePaths(process.cwd(), claudeJson);
+    for (const [name, config] of Object.entries(claude.mcpServers ?? {})) {
+        if (!ourEntry(config))
+            continue;
+        const back = isScenarioServer(config) ? null : unwrapEntry(config);
+        if (back === undefined) {
+            remaining.push(`${name} in your user scope — its original could not be rebuilt; edit ${claudeJson} by hand`);
+            continue;
+        }
+        try {
+            setServerEntry("user", process.cwd(), name, back, paths);
+            out(`  ← ${name} — ${back === null ? "removed from" : "put back in"} your user scope`);
+            fixed += 1;
+        }
+        catch (err) {
+            remaining.push(`${name} in your user scope — ${errText(err)}`);
+        }
+    }
+    for (const [key, project] of Object.entries(claude.projects ?? {})) {
+        for (const [name, config] of Object.entries(project?.mcpServers ?? {})) {
+            if (!ourEntry(config))
+                continue;
+            let back = isScenarioServer(config) ? null : unwrapEntry(config);
+            if (back === undefined) {
+                remaining.push(`${name} in the local scope of ${key} — its original could not be rebuilt; edit ${claudeJson} by hand`);
+                continue;
+            }
+            // An override whose record is lost (what install writes over a
+            // `.mcp.json` or user-scope server): the entry under it is the original,
+            // so the copy goes. Rebuilt as a plain local entry instead, it would
+            // shadow that entry for good — every later change to it hidden.
+            let override = false;
+            if (back && sameServerConfig(back, entryBelow(key, name, claudeJson))) {
+                back = null;
+                override = true;
+            }
+            try {
+                setLocalEntries(claudeJson, [key], name, back, ourEntry);
+                out(`  ← ${name} — ${override ? "its wrapped copy removed; the entry under it is the original" : back === null ? "removed" : "put back"} (local scope of ${key})`);
+                fixed += 1;
+            }
+            catch (err) {
+                remaining.push(`${name} in the local scope of ${key} — ${errText(err)}`);
+            }
+        }
+    }
+    return fixed;
+}
+/**
+ * control/daemon.ts's `listSupersededRecorders` and `stopSupersededRecorder`,
+ * looked up at run time rather than imported by name: they arrive with the
+ * daemon's side of LC-1, and until they do there is nothing to list — which
+ * is exactly what a machine without that side has.
+ */
+const supersededApi = daemonApi;
+/** The superseded recorders of `cwd` (of every project, without it) that are still alive. Never throws. */
+async function supersededRecorders(cwd) {
+    try {
+        const list = supersededApi.listSupersededRecorders;
+        if (typeof list !== "function")
+            return [];
+        const found = await list(cwd);
+        return Array.isArray(found)
+            ? found.filter((r) => r && typeof r.pid === "number" && typeof r.url === "string" && typeof r.token === "string")
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Stop one superseded recorder the way stopDaemon stops the project's own:
+ * asked, and signalled only by the daemon's own code after it answered
+ * `/health` as that very pid — never by a pid alone, which may be recycled.
+ */
+async function stopSuperseded(record) {
+    try {
+        if (typeof supersededApi.stopSupersededRecorder === "function") {
+            return await supersededApi.stopSupersededRecorder(record);
+        }
+        const probe = await probeHealth(record.url, record.token);
+        if (probe.kind !== "ok" || probe.health.pid !== record.pid)
+            return { stopped: false, stale: probe.kind !== "timeout" };
+        const asked = await new ControlClient(record.url, record.token, 3_000).stop();
+        const deadline = Date.now() + 10_000;
+        while (asked && pidAlive(record.pid) && Date.now() < deadline)
+            await new Promise((r) => setTimeout(r, 100));
+        return { stopped: !pidAlive(record.pid) };
+    }
+    catch {
+        return { stopped: false };
+    }
+}
+/** `/health` of a superseded recorder, or undefined when it does not answer as itself. */
+async function supersededHealth(record) {
+    try {
+        const probe = await probeHealth(record.url, record.token);
+        return probe.kind === "ok" && probe.health.pid === record.pid ? probe.health : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One line naming a superseded recorder. */
+function describeSuperseded(record) {
+    return `pid ${record.pid} on ${record.url}${record.version ? `, version ${record.version}` : ""}${record.since ? `, superseded ${ago(record.since)}` : ""}`;
+}
+/** Stop every recorder this machine has a discovery file for, and every superseded one. */
+async function stopAllRecorders() {
+    let files = [];
+    try {
+        files = readdirSync(controlDir()).filter((f) => f.endsWith(".json"));
+    }
+    catch {
+        return 0;
+    }
+    let stopped = 0;
+    for (const file of files) {
+        let cwd;
+        try {
+            cwd = JSON.parse(readFileSync(join(controlDir(), file), "utf8")).cwd;
+        }
+        catch {
+            continue;
+        }
+        if (typeof cwd !== "string" || !readDiscovery(cwd))
+            continue;
+        // stopDaemon signals only a process that answers /health as the recorder
+        // with that file's pid: a recycled pid is never touched.
+        const result = await stopDaemon(cwd);
+        if (result.stopped) {
+            out(`  ← recorder stopped for ${cwd} (pid ${result.pid})`);
+            stopped += 1;
+        }
+        else if (!result.stale) {
+            out(`  ! the recorder for ${cwd} (pid ${result.pid}) did not stop — \`bir down\` there, or end that process`);
+        }
+    }
+    for (const record of await supersededRecorders()) {
+        const result = await stopSuperseded(record);
+        if (result.stopped) {
+            out(`  ← superseded recorder stopped for ${record.cwd} (${describeSuperseded(record)})`);
+            stopped += 1;
+        }
+        else if (!result.stale) {
+            out(`  ! a superseded recorder for ${record.cwd} (pid ${record.pid}) did not stop — end that process`);
+        }
+    }
+    return stopped;
+}
+/**
+ * `bir uninstall --all`: the runner out of every project on this machine,
+ * so that removing the package afterwards cannot break anything.
+ *
+ * Every installed project is uninstalled as `bir uninstall` would do it there
+ * (its hooks, its entries, its files); then everything of ours still in
+ * ~/.claude.json, for projects no record knows; then every recorder is
+ * stopped and every off switch removed. What could not be undone is listed,
+ * kept in installed.json for a second run, and the exit code says so — the
+ * one thing this must never do is say "safe to remove" while something still
+ * names the runner's files.
+ */
+async function uninstallAll(args) {
+    if (args.servers.length > 0 || args.replay || args.configPath) {
+        process.stderr.write("[bir] --all removes everything; it takes no --server, --replay or --config\n");
+        return 2;
+    }
+    const sidecar = readSidecar();
+    const paths = claudeCodePaths(process.cwd());
+    const projects = installedProjects(sidecar);
+    // Every `.claude.json` an install wrote to: this environment's, and any other
+    // profile's (CLAUDE_CONFIG_DIR) the records name — collected now, before the
+    // records that name them are dropped.
+    const claudeFiles = new Map([[normalizePath(paths.claudeJson), paths.claudeJson]]);
+    const noteFile = (file) => {
+        if (typeof file === "string" && file && !claudeFiles.has(normalizePath(file)) && existsSync(file)) {
+            claudeFiles.set(normalizePath(file), file);
+        }
+    };
+    for (const record of Object.values(sidecar.servers)) {
+        if (record && (record.scope === "local" || record.scope === "user"))
+            noteFile(record.file);
+    }
+    for (const project of Object.values(sidecar.projects ?? {}))
+        for (const file of project?.claudeJsonFiles ?? [])
+            noteFile(file);
+    for (const file of claudeFiles.values()) {
+        let claude = {};
+        try {
+            claude = parseJsonFile(file) ?? {};
+        }
+        catch {
+            /* sweepClaudeJson reports it */
+        }
+        for (const dir of projectsWithRunnerFiles(claude)) {
+            if (!projects.has(normalizePath(dir)))
+                projects.set(normalizePath(dir), dir);
+        }
+    }
+    out("Removing the runner from every project on this machine");
+    const remaining = [];
+    let count = 0;
+    for (const dir of [...projects.values()].sort()) {
+        out(`── ${dir}`);
+        try {
+            const result = uninstallProject(dir, sidecar, { servers: [], all: true });
+            if (result.nothing)
+                out("  (nothing of ours left here)");
+            else
+                count += 1;
+            remaining.push(...result.remaining.map((r) => `${dir}: ${r}`));
+        }
+        catch (err) {
+            remaining.push(`${dir}: ${errText(err)}`);
+        }
+    }
+    for (const file of claudeFiles.values()) {
+        out(isClaudeJson(file, paths.claudeJson)
+            ? `── ${file} (your user scope, and projects no install record names)`
+            : `── ${file} (another Claude Code profile an install wrote to: its user scope and projects)`);
+        if (sweepClaudeJson(file, remaining) === 0)
+            out("  (nothing of ours left)");
     }
-    // SessionStart starts the recorder itself when this directory has none
-    // (control/ensure-hook.ts) — but only when the binary can be named by an
-    // absolute path. A pinned-npx install keeps the HTTP hook: resolving a
-    // package inside a hook is too slow to start a recorder from.
-    const ensure = invocation === "npx" ? undefined : { node: hookNodePath(), hooksScript: localHooksPath(), nodeFlags };
-    if (args.hooks && !args.configPath) {
-        // Hooks live in `.claude/settings.local.json` — the person's own file, the
-        // one Claude Code keeps out of git — not in the `settings.json` a team
-        // commits. They carry a bearer token and an absolute path to this machine's
-        // node; a teammate's clone wants neither. An older install put them in the
-        // shared file; take them out of there on the way.
-        if (hasBirHooks(paths.settings)) {
-            backupFile(sidecar, paths.settings);
-            const cleaned = uninstallHooks(paths.settings);
-            if (cleaned !== undefined)
-                noteWritten(sidecar, paths.settings, cleaned);
-            out(`  - hooks removed from ${paths.settings} (they live in settings.local.json now)`);
+    out("── recorders");
+    if ((await stopAllRecorders()) === 0)
+        out("  (none running)");
+    if (remaining.length === 0) {
+        // The switches: a reinstall later must not start out switched off. Only
+        // once nothing of ours is left — a person who turned the runner off because
+        // it misbehaved, and whose uninstall could not undo everything, keeps the
+        // switch holding what is still wrapped inert.
+        try {
+            for (const flag of readdirSync(dirname(projectOffFlagPath(process.cwd())))) {
+                rmSync(join(dirname(projectOffFlagPath(process.cwd())), flag), { force: true });
+            }
         }
-        backupFile(sidecar, paths.settingsLocal);
-        let text = installHooks(paths.settingsLocal, buildHooksBlock(controlUrl, token, { ensure }));
-        if (args.replay) {
-            // Pre-approve our own scenario server. Claude Code asks before it uses a
-            // server from `.mcp.json`, and a "No" there leaves a direct replay with
-            // nowhere to deliver its results — and nothing to say so.
-            text = enableMcpjsonServers(paths.settingsLocal, [SCENARIO_SERVER_KEY]);
+        catch {
+            /* no per-project switches */
         }
-        noteWritten(sidecar, paths.settingsLocal, text);
-        sidecar.hookFiles = [...new Set([...(sidecar.hookFiles ?? []), paths.settingsLocal])];
-        out(`  + hooks → ${paths.settingsLocal} (control server on ${controlUrl}${ensure ? "; the recorder starts itself with each session" : ""})`);
-        const exclude = ensureGitExclude(cwd);
-        if (exclude)
-            out(`  + ${LOCAL_SETTINGS_EXCLUDE} is listed in ${exclude}`);
+        try {
+            setRunnerOff(false);
+        }
+        catch {
+            /* nothing to remove */
+        }
+        // Nothing left to retry: the bookkeeping goes too. The sign-in stays
+        // (`bir logout` revokes it) and so does the stored service address.
+        sidecar.servers = {};
+        sidecar.files = {};
+        sidecar.hookFiles = [];
+        sidecar.projects = {};
+        delete sidecar.controlPort;
+        delete sidecar.token;
     }
     writeSidecar(sidecar);
     out();
-    out(`Wrapped ${wrapped} server${wrapped === 1 ? "" : "s"}.`);
-    if (args.hooks && !args.configPath && ensure) {
-        out("Next: start your session here as usual. The recorder starts itself with it;");
-        out("`bir up` starts it now, `bir down` stops it, `bir doctor` checks it.");
+    if (remaining.length) {
+        out("Not everything could be undone:");
+        for (const r of remaining)
+            out(`  ! ${r}`);
+        out("Fix what is named, then run `bir uninstall --all` again. Do not remove the runner before it");
+        out("finishes cleanly: these entries name its files, and would stop working without them.");
+        if (offSource())
+            out("The off switch stays as you set it until then, so what is left stays inert.");
+        return 1;
     }
-    else if (args.hooks && !args.configPath) {
-        out("Next: run `bir-hooks` in this directory, then start your session.");
-        out("Without it, proxies record standalone (Tier 2): MCP calls only, no prompt.");
+    out(count === 0
+        ? "Nothing of the runner's was set up on this machine."
+        : `Uninstalled from ${count} project${count === 1 ? "" : "s"}. Nothing on this machine runs through the runner any more.`);
+    out("Restart any Claude Code session that is open now: until then it may show a hook error on each prompt.");
+    out(`You can now remove the runner: \`npm rm -g ${PACKAGE_NAME}\`, or delete ${configDir()}`);
+    out("(the install script's copy lives there). `bir logout` first revokes this machine's sign-in.");
+    return 0;
+}
+// ── off / on ───────────────────────────────────────────────────────────────
+/** The first word of a per-project off switch `bir uninstall` wrote (and `bir install` takes back). */
+const UNINSTALL_MARK = "set-by-uninstall";
+function markOffForUninstall(cwd) {
+    setRunnerOff(true, cwd);
+    writeFileSync(projectOffFlagPath(cwd), `${UNINSTALL_MARK} ${new Date().toISOString()}\n`, { mode: 0o600 });
+}
+function isUninstallMark(cwd) {
+    try {
+        return readFileSync(projectOffFlagPath(cwd), "utf8").startsWith(UNINSTALL_MARK);
     }
-    else {
-        out("Recording will be standalone (Tier 2): MCP calls only, no prompt or final answer.");
+    catch {
+        return false;
     }
-    if (args.replay) {
-        out();
-        out("Calculated replay is INSTALLED and ON. `bir replay off` turns it off here, and");
-        out("`bir replay allow <servers>` narrows what it may call unattended — read");
-        out("docs/calculatedReplayGuide.md §5.1 first: a replayed step is auto-approved,");
-        out("and a directly executed one never reaches the permission system at all.");
+}
+/** Remove this project's off switch when `bir uninstall` set it. True when it did. */
+function clearUninstallMark(cwd) {
+    if (!isUninstallMark(cwd))
+        return false;
+    try {
+        setRunnerOff(false, cwd);
+        return true;
+    }
+    catch {
+        return false;
     }
-    return 0;
 }
-// ── uninstall ──────────────────────────────────────────────────────────────
-function uninstall(args) {
-    const cwd = process.cwd();
+/** Why the runner is off, in words. */
+function describeOff(source, dir) {
+    if (source === "env")
+        return "(BIR_OFF=1 in this environment)";
+    if (source === "global")
+        return `everywhere on this machine (\`bir off\`: ${offFlagPath()})`;
+    return isUninstallMark(dir)
+        ? `for ${dir} (left by \`bir uninstall\` for a session still open there)`
+        : `for ${dir} (\`bir off --here\`)`;
+}
+/**
+ * The project directory `cwd` belongs to, as the recorder and the proxies key
+ * it: an installed project that is `cwd` or contains it, else `cwd`. The
+ * recorder runs where Claude Code was started — where `bir setup` ran — so a
+ * `bir off --here` typed in a subdirectory must name that directory, or it
+ * would switch off a project nothing runs in.
+ */
+function projectDirFor(cwd, sidecar = readSidecar()) {
+    const here = normalizePath(cwd);
+    let best;
+    for (const [key, dir] of installedProjects(sidecar)) {
+        if ((here === key || here.startsWith(`${key}/`)) && (!best || key.length > best[0].length))
+            best = [key, dir];
+    }
+    return !best || best[0] === here ? cwd : best[1];
+}
+/**
+ * After `bir off`: the live recorders among `dirs` that predate the switch
+ * (a 0.2.12 one left running across the upgrade), each replaced by a current
+ * one when no session is using it (ensureDaemon's skew restart, with the
+ * two-probe idle test for a recorder too old to say — control/daemon.ts), else
+ * reported. A directory with no discovery file is not asked at all.
+ */
+async function olderRecordersAfterOff(dirs) {
+    const found = [];
+    const seen = new Set();
+    for (const dir of dirs) {
+        const key = normalizePath(dir);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        try {
+            if (!readDiscovery(dir))
+                continue;
+            const live = await daemonStatus(dir);
+            if (!live || !predatesOffSwitch(live.health))
+                continue;
+            let replaced = false;
+            try {
+                const opts = {
+                    hooksScript: localHooksPath(),
+                    restartOnSkew: true,
+                    probeIdle: true,
+                };
+                const result = await ensureDaemon(dir, opts);
+                // Replaced means gone: one started beside it (another port) leaves it
+                // serving its sessions, still ignoring the switch.
+                replaced = !pidAlive(live.info.pid) && !predatesOffSwitch(result.status.health);
+            }
+            catch {
+                replaced = false;
+            }
+            found.push({ dir, pid: live.info.pid, version: recorderVersion(live.health, live.info), replaced });
+        }
+        catch {
+            /* nothing to say about a recorder that could not be asked */
+        }
+    }
+    return found;
+}
+/**
+ * `bir off [--here]` / `bir on [--here]` — the kill switch (util/off-switch.ts).
+ *
+ * Off is instant and reversible and uninstalls nothing: the hooks answer with
+ * nothing within a second (the recorder checks the switch on every call), the
+ * wrapped servers become plain pipes the next time they start, and the service
+ * is never called. `on` without `--here` means on everywhere: the machine-wide
+ * switch and every project's.
+ */
+async function offCommand(args, off) {
     const sidecar = readSidecar();
-    const paths = claudeCodePaths(cwd);
-    // `--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.
-    if (args.replay) {
-        const key = sidecarKey(cwd, SCENARIO_SERVER_KEY);
-        const record = sidecar.servers[key];
-        if (!record) {
-            out("Calculated replay is not installed for this directory.");
-            return 0;
+    const dir = projectDirFor(process.cwd(), sidecar);
+    if (off) {
+        try {
+            setRunnerOff(true, args.here ? dir : undefined);
         }
-        if (record.scope === "explicit") {
-            setGenericServerEntry(record.file, SCENARIO_SERVER_KEY, null);
+        catch (err) {
+            process.stderr.write(`[bir] could not write the switch: ${errText(err)}\n`);
+            return 1;
         }
-        else {
-            setServerEntry(record.scope, cwd, SCENARIO_SERVER_KEY, null, paths);
+        // A recorder older than the switch (0.2.12) ignores it. Asked, not
+        // assumed: one no session uses is stopped (the next session starts a
+        // current one, which honours the switch); one in use is named, and the
+        // "answers with nothing" promise is not made for it.
+        const older = await olderRecordersAfterOff(args.here ? [dir] : [...installedProjects(sidecar).values(), dir]);
+        out(args.here ? `The runner is OFF for ${dir}.` : "The runner is OFF on this machine, in every project.");
+        out(older.length
+            ? "  hooks        answer at once with nothing, within about a second — in sessions already open too, except"
+            : "  hooks        answer at once with nothing, within about a second — in sessions already open too;");
+        out(older.length
+            ? "               the ones served by the older recorder named below; nothing else is recorded, replayed or sent"
+            : "               nothing is recorded, replayed or sent to the service");
+        out("  MCP servers  the ones it wraps stop recording within about a second, and run as plain pipes");
+        out("               to the real server from their next start (a new session, or /mcp → reconnect)");
+        out("  bir server   withdraws its tools within a few seconds (it tells Claude Code its list changed)");
+        out(`Nothing is uninstalled and your servers keep working. \`bir on${args.here ? " --here" : ""}\` turns it back on.`);
+        for (const o of older) {
+            out(o.replaced
+                ? `  ~ the recorder for ${o.dir} (pid ${o.pid}, ${o.version || "an older version"}) predated the off switch; ` +
+                    "nothing was using it, so a current one replaced it, which honours the switch"
+                : `  ! the running recorder for ${o.dir} (pid ${o.pid}, ${o.version || "an older version"}) predates the off switch ` +
+                    "and keeps recording and approving until `bir up --restart` (once the session open there ends)");
+        }
+        if (process.env.BIR_OFF === "0" || process.env.BIR_OFF === "false") {
+            out("  ! BIR_OFF=0 is set in this shell: anything started from it ignores the switch");
         }
-        delete sidecar.servers[key];
-        writeSidecar(sidecar);
-        out(`  ← ${SCENARIO_SERVER_KEY} — scenario server removed from ${record.file}`);
-        out();
-        out("Calculated replay is uninstalled. Recording is unchanged.");
-        out("The prompt hook keeps its raised timeout; `bir install` rewrites it either way.");
-        return 0;
-    }
-    const mine = Object.entries(sidecar.servers).filter(([key]) => key.startsWith(`${cwd}::`));
-    if (mine.length === 0 && !(sidecar.hookFiles ?? []).length) {
-        out("Nothing installed for this directory.");
         return 0;
     }
-    // Byte-for-byte first: a file we wrote and nobody touched since goes back
-    // exactly as it was, comments-in-JSON quirks and all.
-    const restoredWhole = new Set();
-    for (const [file, backup] of Object.entries(sidecar.files ?? {})) {
-        const current = readTextOrNull(file);
-        if (current === null || !backup.writtenSha || sha256(current) !== backup.writtenSha)
-            continue;
-        if (backup.originalText === null) {
-            out(`  - ${file} — created by install; leaving in place (now empty of our entries)`);
-            continue;
+    const turnedOn = [];
+    try {
+        if (args.here) {
+            if (existsSync(projectOffFlagPath(dir)))
+                turnedOn.push(dir);
+            setRunnerOff(false, dir);
         }
-        writeFileSync(file, backup.originalText, "utf8");
-        restoredWhole.add(file);
-        out(`  ← ${file} — restored byte-for-byte`);
-    }
-    for (const [key, record] of mine) {
-        const name = key.slice(cwd.length + 2);
-        if (args.servers.length > 0 && !args.servers.includes(name))
-            continue;
-        if (!restoredWhole.has(record.file)) {
-            // Somebody edited the file after we did. Repair the entry rather than
-            // clobbering their work, and say which path was taken.
-            if (args.configPath || record.scope === "explicit") {
-                setGenericServerEntry(record.file, name, record.original);
+        else {
+            const flags = dirname(projectOffFlagPath(dir));
+            const names = new Map([...installedProjects(sidecar).values()].map((d) => [controlKey(d), d]));
+            let entries = [];
+            try {
+                entries = readdirSync(flags);
             }
-            else {
-                setServerEntry(record.scope, cwd, name, record.original, paths);
+            catch {
+                /* no per-project switches */
             }
-            out(`  ← ${name} — entry restored (file changed since install)`);
+            for (const flag of entries) {
+                rmSync(join(flags, flag), { force: true });
+                turnedOn.push(names.get(flag) ?? `a project (${flag})`);
+            }
+            if (existsSync(offFlagPath()))
+                turnedOn.unshift("the machine-wide switch");
+            setRunnerOff(false);
         }
-        delete sidecar.servers[key];
     }
-    for (const settings of sidecar.hookFiles ?? []) {
-        if (restoredWhole.has(settings))
-            continue;
-        if (existsSync(settings)) {
-            uninstallHooks(settings);
-            disableMcpjsonServers(settings, [SCENARIO_SERVER_KEY]);
-            out(`  ← hooks removed from ${settings}`);
-        }
-    }
-    // An install older than 0.2.9 wrote to the shared settings file; make sure
-    // nothing of ours is left there either, whether or not it was recorded.
-    if (!restoredWhole.has(paths.settings) && hasBirHooks(paths.settings)) {
-        uninstallHooks(paths.settings);
-        out(`  ← hooks removed from ${paths.settings}`);
-    }
-    sidecar.hookFiles = [];
-    sidecar.files = {};
-    if (sidecar.projects)
-        delete sidecar.projects[normalizePath(cwd)];
-    writeSidecar(sidecar);
-    const exclude = removeGitExclude(cwd);
-    if (exclude)
-        out(`  ← ${LOCAL_SETTINGS_EXCLUDE} removed from ${exclude}`);
-    out();
-    out("Uninstalled.");
+    catch (err) {
+        process.stderr.write(`[bir] could not remove the switch: ${errText(err)}\n`);
+        return 1;
+    }
+    const still = offSource(dir);
+    if (still) {
+        out(`The runner is still OFF here, ${describeOff(still, dir)}.`);
+        out(still === "env" ? "  Unset BIR_OFF (or set BIR_OFF=0) where Claude Code is started." : "  `bir on` (without --here) turns that off too.");
+        return 1;
+    }
+    out(args.here ? `The runner is ON for ${dir}.` : "The runner is ON, in every project on this machine.");
+    if (turnedOn.length)
+        out(`  switched back on: ${turnedOn.join(", ")}`);
+    out("  hooks record again within about a second, and so do wrapped MCP servers started before `bir off`;");
+    out("  ones started while it was off stay plain pipes until their next start");
     return 0;
 }
+/**
+ * What `bir down` leaves behind, said once — because it is not obvious.
+ *
+ * Stopping the recorder does not take the hooks out. A Claude Code session
+ * open here keeps calling them, and each call now fails: a "hook error" line
+ * on every prompt and tool call (the session itself keeps working) until the
+ * session ends, and the next session's SessionStart hook starts the recorder
+ * again. That is what `down` has always meant — stop this process — so it
+ * stays; the quiet way to take the runner out of a session is `bir off
+ * --here`, which keeps the recorder up to answer those hooks with nothing.
+ */
+function explainDown(cwd, inUse) {
+    const paths = claudeCodePaths(cwd);
+    if (!hasBirHooks(paths.settingsLocal) && !hasBirHooks(paths.settings))
+        return;
+    out(inUse
+        ? '  A Claude Code session is open here: until it ends it shows a "hook error" on each prompt and tool call'
+        : '  Its hooks stay installed: a Claude Code session open here shows a "hook error" on each prompt and tool call');
+    out("  (the session keeps working), and the next session here starts the recorder again.");
+    out("  To take the runner out of the way without that: `bir up`, then `bir off --here`.");
+}
 // ── status ─────────────────────────────────────────────────────────────────
-function status(args) {
+/** How long `bir status` waits for the recorder's /health: a status line, not a probe. */
+const STATUS_HEALTH_TIMEOUT_MS = 1_500;
+async function status(args) {
     const cwd = process.cwd();
     const entries = args.configPath
         ? Object.entries(readGenericServers(args.configPath)).map(([name, config]) => ({
@@ -744,18 +2597,48 @@ function status(args) {
         }))
         : resolveServers(cwd);
     const discovery = readDiscovery(cwd);
+    const sidecar = readSidecar();
+    const projectDir = projectDirFor(cwd, sidecar);
+    const off = offSource(projectDir);
+    // The recorder's own view (C8): whether the service answers it, and whether
+    // it sees the runner off. Both fields are absent from an older recorder.
+    const health = discovery
+        ? await new ControlClient(discovery.url, discovery.token, STATUS_HEALTH_TIMEOUT_MS).health()
+        : undefined;
+    const serviceView = (health?.service ?? null);
+    // Overrides whose source changed since they were copied (config/overrides.ts).
+    const drift = new Map(args.configPath ? [] : checkOverrides(cwd, sidecar).filter((c) => c.state !== "current").map((c) => [c.name, c]));
+    // The port a recorder here last could not take, and why (control/daemon.ts).
+    const hookPorts = args.configPath ? [] : hookFacts(claudeCodePaths(cwd)).ports;
+    const portProblem = openPortProblem(cwd, health ? portOf(discovery?.url) : undefined, hookPorts.length === 1 ? hookPorts[0] : undefined);
+    // Recorders a reinstall on another port left serving older windows (LC-1).
+    const superseded = await supersededRecorders(projectDir);
     const report = {
         cwd,
         authUrl: resolveAuthUrl() || null,
-        controlServer: discovery ? { url: discovery.url, pid: discovery.pid } : null,
+        controlServer: discovery ? { url: discovery.url, pid: discovery.pid, answering: health !== undefined } : null,
         discoveryFile: discoveryPath(cwd),
+        // null while the recorder can take its port (and from a runner older than the file).
+        portProblem: portProblem ?? null,
         stateDir: configDir(),
+        // The kill switch (`bir off`): null while the runner is on.
+        off: off ? { source: off, detail: describeOff(off, projectDir) } : null,
+        recorder: health
+            ? {
+                service: serviceView,
+                off: typeof health.off === "string" ? health.off : health.off === null ? null : undefined,
+                version: recorderVersion(health) || null,
+            }
+            : null,
+        superseded: superseded.map((r) => ({ pid: r.pid, url: r.url, version: r.version ?? null, since: r.since ?? null })),
+        otherProjects: otherProjects(sidecar, projectDir),
         servers: entries.map((e) => ({
             name: e.name,
             scope: e.scope,
             shadowed: e.shadowed,
             wrapped: isWrapped(e.config),
             upstream: isRemote(e.config) ? e.config.url : e.config.command,
+            ...(drift.has(e.name) ? { stale: { state: drift.get(e.name).state, why: drift.get(e.name).why } } : {}),
         })),
     };
     if (args.json) {
@@ -765,58 +2648,280 @@ function status(args) {
     out(`Directory : ${report.cwd}`);
     out(`BaseIn    : ${report.authUrl ?? "(not set — run `bir setup`, or set BIR_AUTH_URL; nothing is recorded)"}`);
     out(`Control   : ${discovery
-        ? `${discovery.url} (pid ${discovery.pid}${discovery.daemon ? "; background" : ""})`
+        ? `${discovery.url} (pid ${discovery.pid}${discovery.daemon ? "; background" : ""})${health ? "" : " — not answering; `bir doctor` says more"}`
         : "not running — `bir up` starts it"}`);
+    if (portProblem)
+        out(`Port      : ${describePortProblem(portProblem)}`);
+    for (const r of superseded) {
+        out(`Superseded: ${describeSuperseded(r)} — serves windows opened before the last reinstall; \`bir down\` stops it`);
+    }
     if (discovery?.logFile)
         out(`Log       : ${discovery.logFile}`);
+    if (serviceView) {
+        out(`Service   : ${serviceView.healthy === false
+            ? `not answering the recorder (${serviceView.lastError ?? "no answer"}) — sessions do not wait for it meanwhile`
+            : serviceView.lastOkAt
+                ? `answering the recorder (last ${ago(serviceView.lastOkAt)})`
+                : "no call yet"}`);
+    }
+    out(`Runner    : ${report.off
+        ? `OFF ${report.off.detail}: hooks answer nothing, wrapped servers are plain pipes — \`bir on${off === "project" ? " --here" : ""}\` turns it back on`
+        : "on (`bir off --here` takes it out of the way without uninstalling)"}`);
+    if (health && typeof health.off === "string" && !off) {
+        out(`            the recorder reports it OFF (${health.off}) — BIR_OFF=1 where it was started?`);
+    }
+    if (health && off && predatesOffSwitch(health)) {
+        out(`            but the running recorder (${recorderVersion(health) || "an older version"}) predates the off switch and keeps ` +
+            "recording — `bir up --restart` replaces it");
+    }
+    if (report.otherProjects.length)
+        out(`Elsewhere : also set up in ${report.otherProjects.join(", ")}`);
     out("Servers   :");
     if (report.servers.length === 0)
         out("  (none configured for this directory)");
     for (const s of report.servers) {
         const shadow = s.shadowed.length ? ` shadows:${s.shadowed.join("/")}` : "";
-        out(`  ${s.wrapped ? "[wrapped]" : "[  raw  ]"} ${s.name}  (${s.scope}${shadow}) → ${s.upstream}`);
+        const stale = s.stale ? ` — STALE: ${s.stale.why}; \`bir setup\` here fixes it` : "";
+        out(`  ${s.wrapped ? "[wrapped]" : "[  raw  ]"} ${s.name}  (${s.scope}${shadow}) → ${s.upstream}${stale}`);
     }
     return 0;
 }
-// ── doctor ─────────────────────────────────────────────────────────────────
+/**
+ * Read the hooks as Claude Code will run them. The settings file is the
+ * ground truth for the port: it is what every hook posts to, whatever
+ * installed.json or the recorder believe.
+ */
+function hookFacts(paths) {
+    const facts = { files: [], selfStarting: false, ports: [], ensure: [], unreadable: [] };
+    for (const file of [paths.settingsLocal, paths.settings]) {
+        let parsed;
+        try {
+            parsed = parseJsonFile(file);
+        }
+        catch {
+            facts.unreadable.push(file);
+            continue;
+        }
+        let ours = false;
+        for (const [event, matchers] of Object.entries(parsed?.hooks ?? {})) {
+            if (!Array.isArray(matchers))
+                continue;
+            for (const matcher of matchers) {
+                for (const hook of Array.isArray(matcher?.hooks) ? matcher.hooks : []) {
+                    if (!isBirHook(hook))
+                        continue;
+                    ours = true;
+                    if (hook.type === "command" && typeof hook.command === "string") {
+                        if (event === "SessionStart") {
+                            facts.selfStarting = true;
+                            facts.ensure.push({ file, command: hook.command, args: Array.isArray(hook.args) ? hook.args.map(String) : [] });
+                        }
+                    }
+                    else if (typeof hook.url === "string") {
+                        try {
+                            const port = Number(new URL(hook.url).port);
+                            if (port > 0 && !facts.ports.includes(port))
+                                facts.ports.push(port);
+                        }
+                        catch {
+                            /* isBirHook parsed it already */
+                        }
+                    }
+                }
+            }
+        }
+        if (ours)
+            facts.files.push(file);
+    }
+    return facts;
+}
+/** "3 min ago", for a timestamp in the past. */
+function ago(at) {
+    const s = Math.max(0, Math.round((Date.now() - at) / 1000));
+    if (s < 90)
+        return `${s} s ago`;
+    if (s < 5400)
+        return `${Math.round(s / 60)} min ago`;
+    return `${Math.round(s / 3600)} h ago`;
+}
+/** The port of a loopback URL, or undefined. */
+function portOf(url) {
+    if (!url)
+        return undefined;
+    try {
+        const port = Number(new URL(url).port);
+        return port > 0 ? port : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The port this directory's recorder last could not take (control/daemon.ts,
+ * readPortProblem), while it still matters: not once a recorder of ours
+ * answers on it (the first one that binds it removes the file, but a status
+ * may look in between), and not after the hooks moved to another port.
+ * Absent — the usual case, or a runner older than the file — is undefined.
+ */
+function openPortProblem(cwd, livePort, hookPort) {
+    let problem;
+    try {
+        problem = readPortProblem(cwd);
+    }
+    catch {
+        return undefined;
+    }
+    if (!problem)
+        return undefined;
+    if (livePort !== undefined && livePort === problem.port)
+        return undefined;
+    if (hookPort !== undefined && hookPort !== problem.port)
+        return undefined;
+    return problem;
+}
+/** One line for a person: what happened to the port, and what to run. */
+function describePortProblem(problem) {
+    const when = typeof problem.at === "number" && problem.at > 0 ? ` (${ago(problem.at)})` : "";
+    const fix = typeof problem.fix === "string" && problem.fix.trim() ? ` — ${problem.fix.trim()}` : "";
+    return `the recorder could not take port ${problem.port}${when}: ${problem.detail}${fix}`;
+}
 async function doctor(args) {
     const cwd = process.cwd();
+    // Three kinds of finding. PROBLEMS break a Claude Code session — a server or
+    // hook that cannot start, hooks posting to a port nobody answers — and only
+    // they make doctor exit 1. WARNINGS are the runner not doing all its job, or
+    // a configuration it should fix; sessions work. NOTES are facts. A doctor
+    // that failed machines where every session worked (a second project's port,
+    // a recorder not started yet between sessions) was support noise, and it
+    // failed the scripts that gate on it.
     const problems = [];
+    const warnings = [];
     const notes = [];
-    const entries = resolveServers(cwd);
+    const paths = claudeCodePaths(cwd);
+    const sidecar = readSidecar();
+    const projectDir = projectDirFor(cwd, sidecar);
+    const off = offSource(projectDir);
+    let entries = [];
+    try {
+        entries = resolveServers(cwd);
+    }
+    catch (err) {
+        problems.push(`${errText(err)} — Claude Code cannot read it either`);
+    }
     const wantWrapped = entries.filter((e) => isWrapped(e.config)).map((e) => e.name);
+    const hooks = hookFacts(paths);
+    for (const file of hooks.unreadable) {
+        warnings.push(`${file} is not plain JSON, so its hooks could not be checked (and \`bir setup\` will not rewrite it)`);
+    }
+    if (off) {
+        notes.push(`the runner is OFF ${describeOff(off, projectDir)}: hooks answer with nothing, wrapped servers record nothing ` +
+            `(and run as plain pipes from their next start), nothing is replayed — \`bir on${off === "project" ? " --here" : ""}\` turns it back on`);
+    }
     const discovery = readDiscovery(cwd);
     let health;
     if (discovery) {
-        health = await new ControlClient(discovery.url, discovery.token).health();
-        if (!health)
-            problems.push(`control server at ${discovery.url} did not answer /health`);
+        health = await new ControlClient(discovery.url, discovery.token, 3_000).health();
+        if (!health) {
+            problems.push(`the control server at ${discovery.url} (pid ${discovery.pid}) did not answer /health — hooks here wait on it ` +
+                "or fail; `bir up --restart` replaces it");
+        }
+    }
+    else if (hooks.files.length > 0 && !hooks.selfStarting) {
+        problems.push("hooks are installed here but nothing starts the recorder, so every hook fails until `bir up` — " +
+            "run `bir setup` here for the SessionStart hook that starts it");
+    }
+    else if (hooks.files.length > 0) {
+        notes.push("the recorder is not running; the SessionStart hook starts it with the next session (`bir up` starts it now)" +
+            (wantWrapped.length && !off ? ` — ${wantWrapped.join(", ")} register with it then` : ""));
     }
     else {
-        problems.push("no control server for this directory — recording will be Tier 2 (MCP only); " +
-            "`bir up` starts one, and the SessionStart hook starts one with each session");
+        notes.push("no hooks here: only MCP calls are recorded (standalone, Tier 2) — `bir setup` wires the hooks");
     }
     const registered = new Set((health?.registeredProxies ?? []).map((p) => p.serverName));
     // A recorder with no session yet is the normal state right after `bir setup`
     // and between sessions: the proxies are Claude Code's child processes, so
-    // there is nothing to register until a session starts. Reporting that as a
-    // problem made the first `bir doctor` a person ever ran exit non-zero on a
-    // machine where nothing was wrong.
+    // there is nothing to register until a session starts.
     const idleRecorder = Boolean(health) && (health?.sessions ?? []).length === 0;
     // The guarantee check: a *registered* proxy. Not the config file (which only
     // says what should happen) and not `serverInfo` (which stays the upstream's).
-    const unregistered = wantWrapped.filter((name) => !registered.has(name));
-    if (unregistered.length > 0 && idleRecorder) {
-        notes.push(`no Claude Code session is running here yet; ${unregistered.join(", ")} will register when one starts`);
-    }
-    else {
-        for (const name of unregistered) {
-            problems.push(`${name} is wrapped in config but no proxy has registered — is the session running?`);
+    const unregistered = health ? wantWrapped.filter((name) => !registered.has(name)) : [];
+    if (unregistered.length > 0) {
+        if (off) {
+            notes.push(`${unregistered.join(", ")} run as plain pipes while the runner is off, so they do not register`);
+        }
+        else if (idleRecorder) {
+            notes.push(`no Claude Code session is running here yet; ${unregistered.join(", ")} will register when one starts`);
+        }
+        else {
+            for (const name of unregistered) {
+                warnings.push(`${name} is wrapped in config but no proxy has registered — is the session running? ` +
+                    "(one started before `bir setup` needs a restart; until then its calls record standalone)");
+            }
         }
     }
     for (const e of entries) {
         if (!isWrapped(e.config) && e.shadowed.length > 0) {
-            problems.push(`${e.name} is defined in ${e.shadowed.join(", ")} as well as ${e.scope}`);
+            warnings.push(`${e.name} is defined in ${e.shadowed.join(", ")} as well as ${e.scope}`);
+        }
+    }
+    // AN ORGANISATION POLICY THAT MATCHES SERVERS BY COMMAND (config/mcp-approval.ts).
+    // A wrapped entry's command is the runner's: an allow-list then blocks it,
+    // a deny-list no longer sees it. `bir setup` leaves such servers unwrapped.
+    const policy = wantWrapped.length > 0 ? managedMcpPolicyBlocker() : undefined;
+    if (policy) {
+        warnings.push(`${wantWrapped.join(", ")} run through the runner, but ${policy} — Claude Code may refuse to start them; ` +
+            "run `bir setup` here, which leaves them unwrapped");
+    }
+    // A LOCAL COPY THAT NO LONGER COPIES ITS SOURCE (config/overrides.ts). The
+    // copy outranks the `.mcp.json` or user-scope entry it was made from, so a
+    // teammate's change there, or a rotated token, never reaches this project:
+    // Claude Code keeps starting the old server — broken because of the runner.
+    const overrides = checkOverrides(cwd, sidecar);
+    for (const c of overrides) {
+        const src = c.record.override?.source === "project" ? ".mcp.json" : "your user scope";
+        if (c.state === "changed") {
+            problems.push(`${c.name}'s local copy is out of date with ${src}: ${c.why} — run \`bir setup\` here`);
+        }
+        else if (c.state === "removed") {
+            problems.push(`${c.name}'s local copy outlives its source: ${c.why} — run \`bir setup\` here`);
+        }
+        else if (c.state === "unapproved") {
+            warnings.push(`${c.name} runs here through a local copy although ${c.why} — so it starts without Claude Code asking; ` +
+                "run `bir setup` here to take the copy out");
+        }
+    }
+    // THE LOCAL SCOPE IS PER REPOSITORY. In a linked worktree or a subdirectory
+    // Claude Code reads the main checkout's, so the wrapped entries here are
+    // that install's; and from the main checkout, the worktrees that share them.
+    const repoRoot = claudeProjectRoot(cwd);
+    const localWrapped = entries.filter((e) => e.scope === "local" && ourEntry(e.config)).map((e) => e.name);
+    if (localWrapped.length > 0 && normalizePath(repoRoot) !== normalizePath(cwd)) {
+        notes.push(`${localWrapped.join(", ")} run through the runner here because Claude Code shares the local scope of ${repoRoot} ` +
+            "with this directory — they record to that project's recorder; `bir uninstall` there takes them out");
+    }
+    else if (localWrapped.length > 0) {
+        const shared = linkedWorktrees(repoRoot);
+        if (shared.length > 0) {
+            notes.push(`the linked worktree${shared.length === 1 ? "" : "s"} ${shared.join(", ")} share${shared.length === 1 ? "s" : ""} this ` +
+                `local scope, so sessions there run ${localWrapped.join(", ")} through the runner too`);
+            for (const dir of shared) {
+                for (const c of overrides) {
+                    if (c.from !== "project" || !c.source)
+                        continue;
+                    let theirs;
+                    try {
+                        theirs = parseJsonFile(join(dir, ".mcp.json"))
+                            ?.mcpServers?.[c.name];
+                    }
+                    catch {
+                        theirs = undefined;
+                    }
+                    if (theirs !== undefined && !sameServerConfig(isWrapped(theirs) ? unwrapEntry(theirs) : theirs, c.source)) {
+                        warnings.push(`${dir} defines ${c.name} differently in its own .mcp.json, but sessions there run this checkout's copy — ` +
+                            `\`bir uninstall --server ${c.name}\` here if that worktree needs its own`);
+                    }
+                }
+            }
         }
     }
     // IS ANYTHING ACTUALLY BEING SAVED?
@@ -828,8 +2933,8 @@ async function doctor(args) {
     // was recording perfectly. Ask the recorder; it is the only process that knows.
     if (health) {
         if (health.recording === false) {
-            problems.push("the recorder is running but has nowhere to send steps — run `bir setup` " +
-                "(or set BIR_AUTH_URL and `bir login`), then `bir up --restart`");
+            warnings.push("the recorder is running but has nowhere to send steps — run `bir setup` " +
+                "(or set BIR_AUTH_URL and `bir login`); it starts recording by itself after that");
         }
         else {
             notes.push(`recording to ${String(health.authUrl ?? "the configured BaseIn service")}${health.account ? ` as ${String(health.account)}` : ""}`);
@@ -837,6 +2942,68 @@ async function doctor(args) {
         if (discovery?.daemon) {
             notes.push(`the recorder runs in the background (pid ${discovery.pid}); its audit log is ${discovery.logFile ?? "under ~/.baseinstrunner/logs"}`);
         }
+        // WHETHER THE SERVICE IS ANSWERING THE RECORDER (util/service-health.ts).
+        // A recorder older than that field says nothing, and nothing is claimed.
+        const service = health.service;
+        if (service && service.healthy === false) {
+            warnings.push(`the BaseIn service is not answering the recorder (${service.lastError ?? "no answer"}; ` +
+                `${service.consecutiveFailures ?? "several"} failure${service.consecutiveFailures === 1 ? "" : "s"} in a row). ` +
+                "Hooks do not wait for it meanwhile, so sessions are unaffected; the recorder's log has the details");
+        }
+        else if (service?.lastOkAt) {
+            notes.push(`the BaseIn service last answered the recorder ${ago(service.lastOkAt)}`);
+        }
+        // The recorder's own view of the switch. `off` is absent from a recorder
+        // that predates it — which keeps recording whatever the switch says.
+        if (off && predatesOffSwitch(health)) {
+            warnings.push("this recorder is older than the off switch and keeps recording — `bir up --restart` replaces it");
+        }
+        else if (!off && typeof health.off === "string") {
+            notes.push(`the recorder reports the runner OFF (${health.off}) — BIR_OFF=1 in the environment it was started with?`);
+        }
+        // A RECORDER OF ANOTHER VERSION. After an upgrade the old one keeps running
+        // until something replaces it — and a 0.2.12 one still auto-approves every
+        // wrapped MCP call, ignores `bir off`, and waits on the service in hooks.
+        const theirs = recorderVersion(health, discovery ?? undefined);
+        if (theirs && theirs !== VERSION) {
+            warnings.push(`the recorder running here is ${theirs}, this bir is ${VERSION} — \`bir up --restart\` replaces it ` +
+                "(once no Claude Code session here is mid-turn)");
+        }
+        // HOOKS THIS RECORDER DID NOT RECOGNISE. It answers them `{}` so the session
+        // never shows an error, which also means nothing else would ever say so:
+        // their steps are not recorded. A stale token is the usual cause (a
+        // reinstall while this recorder kept running).
+        const hookCounters = health.hooks;
+        const unauthorized = typeof hookCounters?.unauthorized === "number" ? hookCounters.unauthorized : 0;
+        if (unauthorized > 0) {
+            warnings.push(`${unauthorized} hook call(s) carried a token this recorder does not know, so they were answered ` +
+                "with nothing and not recorded — the hooks were reinstalled while it kept running: `bir up --restart`");
+        }
+        const overran = typeof hookCounters?.overran === "number" ? hookCounters.overran : 0;
+        if (overran > 0) {
+            notes.push(`${overran} hook call(s) hit their deadline and were answered early (control.hook_deadline in the log); ` +
+                "the session was not held");
+        }
+        // WHO APPROVES A WRAPPED MCP CALL. 0.2.12 answered each one "allow"; now
+        // Claude Code asks as it would without the runner, unless the recorder was
+        // started with BIR_CORRELATION_DECISION=allow. A headless fleet that relied
+        // on the old answer sees its MCP calls denied, so this is always said.
+        const correlation = health.correlation;
+        if (wantWrapped.length > 0 || correlation === "allow") {
+            notes.push(correlation === "allow"
+                ? "wrapped MCP calls are APPROVED by the recorder (BIR_CORRELATION_DECISION=allow where it was started): " +
+                    "Claude Code does not ask about them"
+                : correlation === "ask"
+                    ? "wrapped MCP calls are left to Claude Code, which asks about each (BIR_CORRELATION_DECISION=ask)"
+                    : correlation === "fingerprint"
+                        ? "wrapped MCP calls are left to Claude Code's own permissions (correlation off: steps joined by fingerprint)"
+                        : correlation === undefined
+                            ? "this recorder predates the approval change: it answers every wrapped MCP call \"allow\" " +
+                                "(`bir up --restart` replaces it with one that leaves them to Claude Code)"
+                            : "wrapped MCP calls are not approved by the runner: Claude Code asks as it would without it. " +
+                                "For headless runs (`claude -p`) allow them in permissions.allow or --allowedTools, or set " +
+                                "BIR_CORRELATION_DECISION=allow where the recorder starts");
+        }
         // Whether a recurring sub-task the service found may actually run mid-task
         // (segmented.md R-LIFE-8). Observe-only is the default and must be visible
         // without reading a log: an operator turns arming on by reading what *would*
@@ -862,35 +3029,108 @@ async function doctor(args) {
     // so this shell's BIR_AUTH_URL is evidence about them, if not about the
     // recorder. The one mistake worth catching is a URL that is a website rather
     // than the API: it answers `GET /health` with a page, so nothing else notices
-    // until a password has been posted to it and it says `405`.
+    // until a password has been posted to it and it says `405`. A warning, not a
+    // problem: sessions do not use this shell. `--quick` skips the network call.
     const shellAuthUrl = resolveAuthUrl();
-    const shellAuthProblem = shellAuthUrl ? await describeAuthService(shellAuthUrl) : undefined;
+    const shellAuthProblem = shellAuthUrl && !args.quick ? await describeAuthService(shellAuthUrl) : undefined;
     if (shellAuthProblem) {
-        problems.push(`BIR_AUTH_URL in this shell (${shellAuthUrl}) is not a BaseIn service: ${shellAuthProblem}. ` +
+        warnings.push(`BIR_AUTH_URL in this shell (${shellAuthUrl}) is not a BaseIn service: ${shellAuthProblem}. ` +
             `\`bir login\` and \`bir scenario\` here will fail — ${AUTH_URL_HINT}`);
     }
     // THE SESSIONSTART HOOK NAMES A NODE BY ABSOLUTE PATH. A version manager's
     // per-shell directory, an uninstalled Node, a moved private Node: the hook
     // then fails on every session and the recorder is never started, which
     // records Tier 2 and looks like nothing at all.
-    const paths = claudeCodePaths(cwd);
-    for (const file of [paths.settingsLocal, paths.settings]) {
-        let parsed;
-        try {
-            parsed = parseJsonFile(file);
+    for (const hook of hooks.ensure) {
+        if (isAbsolute(hook.command) && !existsSync(hook.command)) {
+            problems.push(`the SessionStart hook in ${hook.file} points at a Node that is gone (${hook.command}) — run \`bir setup\` here again`);
         }
-        catch {
+        const script = hook.args.find((a) => /\.js$/.test(a));
+        if (script && isAbsolute(script) && !existsSync(script)) {
+            problems.push(`the SessionStart hook in ${hook.file} runs a runner that is gone (${script}) — run \`bir setup\` here again`);
+        }
+    }
+    // EVERY WRAPPED ENTRY NAMES A NODE AND A SCRIPT BY ABSOLUTE PATH, and the
+    // host spawns them for the user's own servers now. A Node removed by a
+    // version manager, or a runner moved by an upgrade, and every one of those
+    // servers fails to start. Two `existsSync` calls each; no network.
+    for (const e of entries) {
+        if (isRemote(e.config) || !ourEntry(e.config))
+            continue;
+        const command = e.config.command;
+        if (isAbsolute(command) && !existsSync(command)) {
+            problems.push(`${e.name} cannot start: ${command} is gone — run \`bir setup\` here again`);
             continue;
         }
-        for (const matcher of parsed?.hooks?.SessionStart ?? []) {
-            for (const hook of matcher.hooks ?? []) {
-                if (hook.type !== "command" || !hook.command || !isBirHook(hook))
-                    continue;
-                if (!existsSync(hook.command)) {
-                    problems.push(`the SessionStart hook in ${file} points at a Node that is gone (${hook.command}) — run \`bir setup\` here again`);
-                }
+        const script = (e.config.args ?? []).find((a) => /bir-(proxy|scenario)\.js$/.test(a));
+        if (script && isAbsolute(script) && !existsSync(script)) {
+            problems.push(`${e.name} cannot start: ${script} is gone — run \`bir setup\` here again`);
+        }
+    }
+    // A REMOTE SERVER WRAPPED WITHOUT CREDENTIALS. The proxy sends only what the
+    // entry spells out; a server Claude Code signs in itself (OAuth) then answers
+    // 401 to every call, and /mcp no longer offers to sign in. An older install
+    // did this by default — `bir setup` un-wraps it; one wrapped because
+    // `--server` named it is the person's call, and only a warning.
+    for (const e of entries) {
+        if (!isWrapped(e.config))
+            continue;
+        const original = unwrapEntry(e.config);
+        if (!original || !isRemote(original))
+            continue;
+        const blocked = remoteWrapBlocker(original);
+        if (!blocked)
+            continue;
+        if (findRecord(sidecar, cwd, e.name)?.record.optedIn === true) {
+            warnings.push(`${e.name} is wrapped although ${blocked} (\`--server ${e.name}\` asked for it): if its calls answer 401, ` +
+                `\`bir uninstall --server ${e.name}\``);
+        }
+        else {
+            problems.push(`${e.name} is a remote server wrapped without credentials — ${blocked}, and the proxy cannot, so its calls ` +
+                "fail (401). Run `bir setup` here: it un-wraps it (the hooks still record its calls)");
+        }
+    }
+    // WRAPPED ENTRIES WHERE THEY DO NOT BELONG, left by an older install: the
+    // user scope applies to every project on the machine, and `.mcp.json` is a
+    // file a team commits — a teammate's clone would spawn this machine's paths.
+    // `bir setup` moves both to this project's local scope.
+    try {
+        const userServers = (parseJsonFile(paths.claudeJson)
+            ?.mcpServers ?? {});
+        for (const [name, config] of Object.entries(userServers)) {
+            if (isWrapped(config)) {
+                warnings.push(`${name} is wrapped in your user scope, so it runs through the runner in EVERY project — run \`bir setup\` here ` +
+                    "to limit it to this one (and `bir uninstall --all` before removing the runner)");
             }
         }
+        const mcpServers = (parseJsonFile(paths.mcpJson)
+            ?.mcpServers ?? {});
+        const inMcpJson = Object.entries(mcpServers).filter(([, c]) => ourEntry(c)).map(([n]) => n);
+        if (inMcpJson.length > 0) {
+            // A note, not a problem: `--mcp-json` writes this shape on purpose.
+            notes.push(`${paths.mcpJson} holds runner entries (${inMcpJson.join(", ")}) with this machine's paths — do not commit ` +
+                "it; `bir setup` (without --mcp-json) moves them to the local scope");
+        }
+    }
+    catch {
+        /* an unreadable config is reported by the checks above */
+    }
+    // ANOTHER CLAUDE CODE PROFILE. CLAUDE_CONFIG_DIR moves `.claude.json`, so an
+    // install run with another value wrote its local-scope entries to another
+    // file than the one this shell's Claude Code reads. Sessions started with
+    // that profile run them; `bir uninstall` finds both.
+    const elsewhere = otherClaudeFiles(sidecar, projectDir, paths.claudeJson);
+    if (elsewhere.length > 0) {
+        warnings.push(`this project was also installed into ${elsewhere.join(", ")} — not ${paths.claudeJson}, which Claude Code started ` +
+            "from this shell reads (CLAUDE_CONFIG_DIR differs). Sessions of that profile run those entries; " +
+            "`bir setup` from there updates them, and `bir uninstall` takes them out of both");
+    }
+    // RECORDERS A REINSTALL LEFT BEHIND (LC-1): a port change while a window was
+    // open starts a second recorder for the new port; the old one keeps serving
+    // that window and is found only through its own record.
+    for (const r of await supersededRecorders(projectDir)) {
+        notes.push(`a superseded recorder is still running (${describeSuperseded(r)}) for windows opened before the last ` +
+            "reinstall — `bir down` stops it");
     }
     // THE SCENARIO SERVER IS ON THE CRITICAL PATH OF THE FIRST TURN. A plan armed
     // at `UserPromptSubmit` is delivered through `mcp__bir__run_scenario`, so a
@@ -899,26 +3139,68 @@ async function doctor(args) {
     // ~6s in. The turn does not fail; it just quietly runs the ordinary way, which
     // is the failure this whole command exists to make visible.
     const scenarioEntry = entries.find((e) => e.name === SCENARIO_SERVER_KEY);
-    if (scenarioEntry && !isRemote(scenarioEntry.config) && scenarioEntry.config.command === "npx") {
+    if (scenarioEntry && isNpxEntry(scenarioEntry.config)) {
         notes.push("the bir scenario server starts via npx, which can take longer than the first tool call " +
-            "of a turn — reinstall with `bir install --replay --global` to pin it to the installed copy");
+            "of a turn — run `bir setup` (or `bir install --replay --global`) to pin it to the installed copy");
     }
-    const sidecar = readSidecar();
-    if (sidecar.controlPort && discovery && !discovery.url.endsWith(`:${sidecar.controlPort}`)) {
-        problems.push(`hooks were installed for port ${sidecar.controlPort} but the control server is on ${discovery.url}`);
+    // THE PORT. The hooks' own URLs are the ground truth — they are what every
+    // hook posts to — checked against the recorder actually answering here. Not
+    // the machine-wide "last port any install wrote", which named another
+    // project's port whenever two were installed and failed a working machine.
+    const hookPort = hooks.ports.length === 1 ? hooks.ports[0] : undefined;
+    if (hooks.ports.length > 1) {
+        warnings.push(`the hooks here post to several ports (${hooks.ports.join(", ")}) — run \`bir setup\` here`);
+    }
+    if (hookPort !== undefined && discovery && health) {
+        let livePort;
+        try {
+            livePort = Number(new URL(discovery.url).port);
+        }
+        catch {
+            livePort = undefined;
+        }
+        if (livePort && livePort !== hookPort) {
+            problems.push(`the hooks here post to port ${hookPort}, but this directory's recorder is on ${discovery.url}, so every hook ` +
+                "fails — run `bir setup` here");
+        }
+    }
+    const recordPort = projectRecord(sidecar, cwd)?.port;
+    if (hookPort !== undefined && recordPort !== undefined && recordPort !== hookPort) {
+        warnings.push(`installed.json gives this project port ${recordPort}, but its hooks name ${hookPort} — run \`bir setup\` here`);
+    }
+    // THE PORT THE RECORDER COULD NOT TAKE (control/daemon.ts). A recorder that
+    // exits because the port its hooks name is busy or reserved says why, and by
+    // whom; until one binds it, every hook here fails. Its own fix text names
+    // the way out, which the generic advice above cannot.
+    const portProblem = openPortProblem(cwd, health ? portOf(discovery?.url) : undefined, hookPort);
+    if (portProblem)
+        problems.push(describePortProblem(portProblem));
+    // THE OTHER PROJECTS. Uninstalling here leaves them as they are; removing
+    // the package without `bir uninstall --all` would break every one of them.
+    const others = otherProjects(sidecar, cwd);
+    if (others.length) {
+        notes.push(`also set up on this machine: ${others.join(", ")} — \`bir uninstall --all\` removes the runner from every ` +
+            "project (do that before removing the package)");
     }
     if (args.json) {
         out(JSON.stringify({
             ok: problems.length === 0,
             problems,
+            warnings,
             notes,
             health,
             wrapped: wantWrapped,
+            off: off ?? null,
+            service: health?.service ?? null,
+            otherProjects: others,
             shellAuthUrl: shellAuthUrl || null,
             shellAuthProblem: shellAuthProblem ?? null,
+            portProblem: portProblem ?? null,
         }, null, 2));
-        return problems.length === 0 ? 0 : 1;
+        return problems.length === 0 && !(args.strict && warnings.length > 0) ? 0 : 1;
     }
+    if (off)
+        out(`Runner            : OFF ${describeOff(off, projectDir)}`);
     // Replay first, and loudly. It auto-approves tool calls in the session and
     // bypasses the permission system entirely for direct steps
     // (docs/calculatedReplay.md §13.2), so it must never be discoverable only by
@@ -932,20 +3214,21 @@ async function doctor(args) {
         // it could describe then.
         const via = replay.deriveVia ?? (replay.deriveKey ? "key" : "samples");
         const derive = via === "key"
-            ? "this machine (ANTHROPIC_API_KEY)"
+            ? "this machine (a derivation key: BIR_DERIVE_API_KEY)"
             : via === "service"
                 ? "the service (no key needed here)"
                 : "recorded sample values — scenarios with a target will NOT run";
         out(`                    derive=${derive}`);
         if (via === "samples") {
             notes.push("nothing can read what this turn acts on: sign in with `bir login` so the " +
-                "service derives, or set ANTHROPIC_API_KEY to derive here. Until then a " +
+                "service derives, or set BIR_DERIVE_API_KEY where Claude Code starts to derive " +
+                "here (the background recorder ignores an inherited ANTHROPIC_API_KEY). Until then a " +
                 "matched scenario with a target is declined and the agent does the task");
         }
         const idle = wantWrapped.filter((n) => !(replay.pollingProxies ?? []).includes(n));
-        if (idle.length > 0 && !idleRecorder) {
+        if (idle.length > 0 && !idleRecorder && !off) {
             notes.push(`these proxies are not polling for replay work: ${idle.join(", ")} — ` +
-                "their steps will fall back to recorded outputs");
+                "a direct plan that needs one of them stops at that step and hands the task back to the agent");
         }
     }
     else if (health) {
@@ -955,24 +3238,31 @@ async function doctor(args) {
     out(`Registered proxies: ${[...registered].join(", ") || "(none)"}`);
     out(`Control server    : ${discovery?.url ?? "not running"}`);
     out(`BaseIn (shell)    : ${shellAuthUrl
-        ? `${shellAuthUrl}${shellAuthProblem ? " — NOT a BaseIn service, see below" : " (answers /health)"}`
+        ? `${shellAuthUrl}${shellAuthProblem ? " — NOT a BaseIn service, see below" : args.quick ? " (not checked: --quick)" : " (answers /health)"}`
         : "(BIR_AUTH_URL not set in this shell)"}`);
     out(`Recording tier    : ${discovery && health ? "bound (Tier 1)" : "standalone (Tier 2)"}`);
-    out(`Recording         : ${health ? (health.recording === false ? "no — see below" : "yes") : "unknown (no control server to ask)"}`);
+    out(`Recording         : ${off ? "no — the runner is off" : health ? (health.recording === false ? "no — see below" : "yes") : "unknown (no control server to ask)"}`);
     if (health?.lossy)
         out("Lossy             : yes — steps were dropped in this session");
     out();
     for (const n of notes)
         out(`  · ${n}`);
-    if (problems.length === 0) {
+    if (warnings.length) {
         if (notes.length)
             out();
+        out("Warnings (sessions work, but the runner is not doing all it should):");
+        for (const w of warnings)
+            out(`  ~ ${w}`);
+    }
+    if (problems.length === 0) {
+        if (notes.length || warnings.length)
+            out();
         out("No problems found.");
-        return 0;
+        return args.strict && warnings.length > 0 ? 1 : 0;
     }
-    if (notes.length)
+    if (notes.length || warnings.length)
         out();
-    out("Problems:");
+    out("Problems (these break a Claude Code session here):");
     for (const p of problems)
         out(`  ! ${p}`);
     return 1;
@@ -996,15 +3286,35 @@ async function service(method, path, body) {
     const session = await authenticate({ authUrl: baseUrl });
     if (!session)
         throw new Error("not signed in — run `bir login`");
-    const res = await fetch(`${baseUrl.replace(/\/+$/, "")}${path}`, {
-        method,
-        headers: {
-            "content-type": "application/json",
-            authorization: `Bearer ${session.accessToken}`,
-        },
-        body: body === undefined ? undefined : JSON.stringify(body),
-    });
-    const text = await res.text().catch(() => "");
+    // A ceiling (BIR_SERVICE_TIMEOUT_MS): a service that accepts the connection
+    // and never answers would otherwise hold `bir scenario list` for undici's
+    // 300 s. The verdict goes to the process-wide breaker, like every call.
+    let res;
+    let text;
+    try {
+        res = await fetch(`${baseUrl.replace(/\/+$/, "")}${path}`, {
+            method,
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${session.accessToken}`,
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: timeoutSignal(serviceTimeoutMs()),
+        });
+        text = await res.text();
+    }
+    catch (err) {
+        serviceHealth.fail(errText(err));
+        const timedOut = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
+        const ms = serviceTimeoutMs();
+        throw new Error(timedOut
+            ? `the BaseIn service did not answer within ${ms < 1_000 ? `${ms} ms` : `${Math.round(ms / 1_000)} s`} (BIR_SERVICE_TIMEOUT_MS)`
+            : `the BaseIn service is unreachable (${errText(err)})`);
+    }
+    if (isUnhealthyStatus(res.status))
+        serviceHealth.fail(`HTTP ${res.status}`);
+    else
+        serviceHealth.ok();
     let parsed = undefined;
     try {
         parsed = text ? JSON.parse(text) : undefined;
@@ -1124,7 +3434,11 @@ function replayPolicyCommand(args) {
     const word = args.positionals[0];
     const describe = (policy) => {
         out(`Replay policy for ${cwd}`);
-        out(`  replay         ${policy?.enabled === false ? "off" : "on"}`);
+        out(`  replay         ${policy?.enabled !== false
+            ? "on"
+            : policy.disabledBy === "install"
+                ? "off (not asked for at install: --no-replay, `bir uninstall --replay`, or no --replay) — `bir replay on` turns it on"
+                : "off"}`);
         out(`  direct servers ${policy?.allowServers?.length ? policy.allowServers.join(", ") : "(all wrapped)"}`);
         out(`  minSimilarity  ${policy?.minSimilarity ?? 0.92}`);
         const overrides = ["BIR_REPLAY", "BIR_REPLAY_ALLOW_SERVERS", "BIR_MIN_STEER_SIMILARITY"].filter((k) => process.env[k] !== undefined);
@@ -1144,10 +3458,13 @@ function replayPolicyCommand(args) {
         return 1;
     }
     const next = { ...(record.replay ?? {}) };
-    if (word === "on")
-        delete next.enabled;
-    else if (word === "off")
-        next.enabled = false;
+    // On or off, the person's own answer: kept as they said it (true, not just
+    // "absent"), so a later install without --replay does not overrule it, and
+    // no longer marked as an install's (generate.ts, settleReplaySwitch).
+    if (word === "on" || word === "off") {
+        next.enabled = word === "on";
+        delete next.disabledBy;
+    }
     else if (word === "allow") {
         const list = args.positionals[1];
         if (!list) {
@@ -1277,20 +3594,86 @@ function wrap(args) {
             out("usage: bir wrap --server-name <key> -- <command> [args…]");
             process.exit(2);
         })();
-    const sidecar = readSidecar();
+    // This directory's port, not the machine-wide "last port any install wrote",
+    // which is another project's whenever two are installed. None recorded: no
+    // control URL, and the proxy finds a recorder by its own directory.
+    const port = projectRecord(readSidecar(), process.cwd())?.port;
+    const invocation = resolveInvocation(args);
     const entry = wrapEntry(config, {
         serverName: name,
-        controlUrl: sidecar.controlPort ? `http://127.0.0.1:${sidecar.controlPort}` : undefined,
+        controlUrl: port ? `http://127.0.0.1:${port}` : undefined,
         noCorrelation: args.noCorrelation,
-        invocation: resolveInvocation(args),
-        proxyPath: args.local || args.global ? localProxyPath() : undefined,
+        invocation,
+        proxyPath: invocation === "npx" ? undefined : localProxyPath(),
         version: VERSION,
+        nodeFlags: invocation === "npx" ? undefined : nodeFlagsToCarry(),
+        node: invocation === "npx" ? undefined : chooseNodePath().path,
     });
     out(JSON.stringify({ mcpServers: { [name]: entry } }, null, 2));
     return 0;
 }
+// ── logout ─────────────────────────────────────────────────────────────────
+/** How long `bir logout` waits on the service in all: finding its address, then the revoke. */
+const LOGOUT_REVOKE_BUDGET_MS = 8_000;
+/**
+ * Ask the service to revoke a refresh token this machine no longer keeps.
+ * Never throws: the local sign-out already happened, and a service that does
+ * not answer only means the token lapses on its own; the audit log says so.
+ */
+async function revokeRefreshToken(configured, refreshToken) {
+    try {
+        const authUrl = await normalizeAuthUrl(configured);
+        const res = await fetch(`${authUrl}/auth/logout`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ refreshToken }),
+            signal: timeoutSignal(LOGOUT_REVOKE_BUDGET_MS),
+        });
+        if (isUnhealthyStatus(res.status))
+            serviceHealth.fail(`HTTP ${res.status}`);
+        else
+            serviceHealth.ok();
+        res.body?.cancel().catch(() => undefined);
+    }
+    catch (err) {
+        logLine("auth.logout_remote_failed", {
+            error: errText(err),
+            why: "the local credentials are cleared regardless",
+        });
+    }
+}
 // ── entry point ────────────────────────────────────────────────────────────
+/**
+ * Move records whose stash is redacted out of an older runner's sight NOW
+ * (generate.ts, REDACTED_KEY_PREFIX), not at the next install: a build before
+ * this one kept them under the plain key, and a rollback to 0.2.12 could come
+ * first — whose uninstall would write the blanked credentials back. One read
+ * of installed.json; a write only when something moved. Never throws.
+ */
+function migrateRecordKeys() {
+    try {
+        const path = installedPath();
+        if (!existsSync(path))
+            return;
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const servers = raw && typeof raw === "object" ? raw.servers : undefined;
+        if (!servers || typeof servers !== "object" || Array.isArray(servers))
+            return;
+        if (!normaliseRecordKeys({ ...servers }))
+            return;
+        writeSidecar(readSidecar());
+    }
+    catch {
+        /* the next install moves them */
+    }
+}
 async function main() {
+    // Started with --use-env-proxy (a launcher written behind a proxy) in a shell
+    // whose NO_PROXY does not name 127.0.0.1: without this, every call `bir`
+    // makes to the recorder — `bir up`, `bir doctor`, setup's wait — goes to the
+    // proxy and fails. Entries and hooks are still decided from the environment
+    // as it was (generate.ts, nodeFlagsToCarry).
+    exemptLoopbackFromProxy();
     const argv = process.argv.slice(2);
     if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help")
         usage(0);
@@ -1299,13 +3682,14 @@ async function main() {
         return 0;
     }
     const args = parseArgs(argv);
+    migrateRecordKeys();
     switch (args.command) {
         case "install":
             return install(args);
         case "uninstall":
-            return uninstall(args);
+            return await uninstall(args);
         case "status":
-            return status(args);
+            return await status(args);
         case "doctor":
             return doctor(args);
         case "wrap":
@@ -1332,8 +3716,10 @@ async function main() {
             });
         case "setup": {
             // The invocation is decided here, not asked: an installed package gets
-            // absolute paths (--global), a checkout points at itself (--local).
-            const installed = runsFromInstalledPackage();
+            // absolute paths (global), a checkout points at itself (local), and a
+            // `npx @basein/runner setup` gets pinned npx — never an absolute path
+            // into npx's cache, which npm deletes when it likes.
+            const invocation = runsFromInstalledPackage() ? "global" : runsFromNpxCache() ? "npx" : "local";
             return runSetup({
                 authUrl: args.authUrl,
                 token: args.token,
@@ -1342,10 +3728,20 @@ async function main() {
                 replay: !args.noReplay,
                 daemon: !args.noDaemon,
                 allowServers: args.allowServers,
+                portExplicit: args.portExplicit,
             }, {
                 out,
                 err: (line) => process.stderr.write(`[bir] ${line}\n`),
-                install: ({ replay }) => install({ ...args, global: installed, local: !installed, replay, hooks: true, servers: [] }),
+                install: ({ replay }) => install({
+                    ...args,
+                    global: false,
+                    local: false,
+                    npx: false,
+                    forceInvocation: invocation,
+                    replay,
+                    hooks: true,
+                    servers: [],
+                }),
                 hooksScript: localHooksPath(),
             });
         }
@@ -1353,30 +3749,58 @@ async function main() {
             const cwd = process.cwd();
             if (args.restart)
                 await stopDaemon(cwd);
-            const { status, started, restarted } = await ensureDaemon(cwd, {
+            // probeIdle: a recorder too old to say whether a turn is really open
+            // (0.2.12 keeps an interrupted turn "active" for its whole life) is
+            // replaced when two /health probes show it idle (control/daemon.ts).
+            const ensureOpts = {
                 hooksScript: localHooksPath(),
                 restartOnSkew: true,
-            });
+                probeIdle: true,
+            };
+            const { status, started, restarted } = await ensureDaemon(cwd, ensureOpts);
             const { info } = status;
             out(`Recorder ${started ? (restarted ? "restarted" : "started") : "already running"} for ${cwd}`);
             out(`  ${info.url}  (pid ${info.pid}${info.daemon ? "; background" : "; in a terminal"})`);
             if (info.logFile)
                 out(`  log ${info.logFile}`);
+            const running = recorderVersion(status.health, info);
+            if (!started && running && running !== VERSION) {
+                out(`  it is ${running}, not ${VERSION}: a Claude Code session here is mid-turn, so it was left running — ` +
+                    "`bir up --restart` once that turn ends replaces it");
+            }
             if (status.health.recording === false) {
-                out("  !! it has no session to record with — run `bir setup` or `bir login`, then `bir up --restart`");
+                out("  !! it has no session to record with — run `bir setup` or `bir login`; it starts recording by itself after that");
                 return 1;
             }
             return 0;
         }
         case "down": {
             const cwd = process.cwd();
+            // Superseded recorders first (LC-1): a reinstall on another port left
+            // them serving older windows, and the discovery file no longer names them.
+            let supersededStopped = 0;
+            for (const record of await supersededRecorders(cwd)) {
+                const result = await stopSuperseded(record);
+                if (result.stopped) {
+                    supersededStopped += 1;
+                    out(`Superseded recorder stopped (${describeSuperseded(record)}).`);
+                }
+                else if (!result.stale) {
+                    out(`A superseded recorder (pid ${record.pid}) did not stop.`);
+                }
+            }
             const before = readDiscovery(cwd);
             if (!before) {
-                out("No recorder is running for this directory.");
+                clearUninstallMark(cwd);
+                if (supersededStopped === 0)
+                    out("No recorder is running for this directory.");
                 return 0;
             }
+            const live = await daemonStatus(cwd);
+            const inUse = live ? recorderInUse(live.health) : false;
             const result = await stopDaemon(cwd);
             if (result.stale) {
+                clearUninstallMark(cwd);
                 out(`No recorder answered for this directory; a stale record (pid ${before.pid}) was removed.`);
                 return 0;
             }
@@ -1384,11 +3808,16 @@ async function main() {
                 out(`The recorder (pid ${before.pid}) did not stop.`);
                 return 1;
             }
+            clearUninstallMark(cwd);
             out(result.forced
                 ? `Recorder stopped (pid ${before.pid}; forced — it did not answer, so its last steps may be missing).`
                 : `Recorder stopped (pid ${before.pid}).`);
+            explainDown(cwd, inUse);
             return 0;
         }
+        case "off":
+        case "on":
+            return offCommand(args, args.command === "off");
         case "login": {
             // Settle the URL the way every other command does, then refuse to go on
             // when what is there is not the service. "Signed in" must mean the service
@@ -1465,11 +3894,31 @@ async function main() {
             return 0;
         }
         case "logout": {
-            // Revoke server-side before forgetting locally, so a stolen credentials
-            // file is dead rather than merely absent from this machine.
-            const configured = resolveAuthUrl();
-            await logout(configured ? await normalizeAuthUrl(configured) : undefined);
+            // LOCAL FIRST, before anything touches the network: the session file
+            // goes, then the service is asked to revoke the refresh token it held.
+            // Finding the service's address is a /health round trip (a redirect to
+            // https is followed), and a hung service or a Ctrl-C during it used to
+            // leave this machine signed in. Running recorders notice the missing
+            // file within seconds and stop sending.
+            const cached = loadCredentials();
+            clearCredentials();
             out("Logged out — cached credentials cleared.");
+            const configured = resolveAuthUrl();
+            // THE SERVICE THAT ISSUED IT, not whatever this shell names. A session is
+            // bound to its service (auth/client.ts, issuedFor); a stale or mistyped
+            // BIR_AUTH_URL here must not receive the refresh token, and the service
+            // that can revoke it is the one that issued it. A file from before the
+            // binding names none: the configured address, as before.
+            const bound = (cached?.authUrl ?? "").replace(/\/+$/, "");
+            const target = bound || configured;
+            if (target && cached?.refreshToken) {
+                if (bound && configured && bound !== configured.replace(/\/+$/, "")) {
+                    out(`  revoking the session at ${bound}, the service that issued it (not ${configured})`);
+                }
+                // Best effort, and bounded as a whole: revoking makes a copy of the
+                // file taken elsewhere dead rather than merely absent from here.
+                await awaitWithin(revokeRefreshToken(target, cached.refreshToken), LOGOUT_REVOKE_BUDGET_MS, "logout");
+            }
             return 0;
         }
         default: