@basein/runner 0.2.7 → 0.2.10

package/dist/bin/bir.js

@@ -2,6 +2,8 @@
 /**
  * bir — the command line (Phase 7).
  *
+ *   bir setup [--auth-url <url>] [--token <t>] [--project <dir>]   ← the one command
+ *   bir up [--restart] | bir down
  *   bir install [--config <path>] [--server <name>]… [--local] [--no-hooks]
  *   bir uninstall [--config <path>]
  *   bir status
@@ -18,17 +20,19 @@
  * from `serverInfo`, which must stay the upstream's (Phase 3).
  */
 import { randomBytes } from "node:crypto";
-import { existsSync, writeFileSync } from "node:fs";
+import { existsSync, realpathSync, writeFileSync } from "node:fs";
 import { dirname, 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 { configDir, discoveryPath } from "../control/paths.js";
-import { isScenarioServer, isWrapped, PACKAGE_NAME, readSidecar, scenarioEntry, sidecarKey, wrapEntry, writeSidecar, SCENARIO_SERVER_KEY, } from "../config/generate.js";
-import { isRemote, resolveServers } from "../config/resolve.js";
-import { buildHooksBlock, claudeCodePaths, fileForScope, installHooks, readTextOrNull, setServerEntry, sha256, uninstallHooks, } from "../config/adapters/claude-code.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 { 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 { readGenericServers, setGenericServerEntry } from "../config/adapters/generic.js";
-import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, deviceLogin, describeAuthService, legacyPasswordLogin, tokenLogin, logout, normalizeAuthUrl, resolveAuthUrl, } from "../auth/client.js";
+import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, deviceLogin, describeAuthService, legacyPasswordLogin, tokenLogin, logout, normalizeAuthUrl, rememberAuthUrl, resolveAuthUrl, } from "../auth/client.js";
 import { DEFAULT_CONTROL_PORT } from "../control/server.js";
 import { errText } from "../util/log.js";
 import { journalPath, readJournal } from "../util/journal.js";
@@ -43,6 +47,9 @@ 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
@@ -56,6 +63,8 @@ Commands:
   scenario calc <runId> [--force]   calculate (or re-derive) a run's scenario
   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
@@ -69,17 +78,24 @@ Options:
   --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.json (Tier 2 recording 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>        control-server port to write into the hook URLs (default ${DEFAULT_CONTROL_PORT})
+  --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
   --dry             replay against recorded outputs only; run no real tools
   --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`);
+  --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`);
     process.exit(code);
 }
 function parseArgs(argv) {
@@ -98,6 +114,10 @@ function parseArgs(argv) {
         dry: false,
         force: false,
         password: false,
+        noReplay: false,
+        noDaemon: false,
+        restart: false,
+        portExplicit: false,
     };
     for (let i = 1; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -153,6 +173,31 @@ function parseArgs(argv) {
                 break;
             case "--port":
                 args.port = Number(argv[++i]);
+                args.portExplicit = true;
+                break;
+            case "--auth-url":
+                args.authUrl = argv[++i];
+                if (!args.authUrl)
+                    usage(2);
+                break;
+            case "--project":
+                args.project = argv[++i];
+                if (!args.project)
+                    usage(2);
+                break;
+            case "--no-replay":
+                args.noReplay = true;
+                break;
+            case "--allow-servers":
+                args.allowServers = argv[++i];
+                if (args.allowServers === undefined)
+                    usage(2);
+                break;
+            case "--no-daemon":
+                args.noDaemon = true;
+                break;
+            case "--restart":
+                args.restart = true;
                 break;
             case "--json":
                 args.json = true;
@@ -186,6 +231,27 @@ function localProxyPath() {
 function localScenarioPath() {
     return resolvePath(dirname(fileURLToPath(import.meta.url)), "bir-scenario.js");
 }
+/** Absolute path to this package's built `bir-hooks.js`, for the SessionStart hook. */
+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. */
+function runsFromInstalledPackage() {
+    return /[\\/]node_modules[\\/]/.test(localProxyPath());
+}
+/**
+ * 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.
+ */
+function hookNodePath() {
+    try {
+        return realpathSync(process.execPath);
+    }
+    catch {
+        return process.execPath;
+    }
+}
 /**
  * Which invocation the generated entries use — and the guard that makes
  * `--global` mean something.
@@ -199,11 +265,20 @@ function localScenarioPath() {
  * 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) {
+function resolveInvocation(args, remembered) {
     if (args.local && args.global) {
         process.stderr.write("[bir] --local and --global are mutually exclusive\n");
         process.exit(2);
     }
+    // Neither 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) {
+        if (remembered === "global" && !runsFromInstalledPackage())
+            return "local";
+        return remembered;
+    }
     if (!args.global)
         return args.local ? "local" : "npx";
     const proxy = localProxyPath();
@@ -229,13 +304,20 @@ function noteWritten(sidecar, file, text) {
     sidecar.files[file] = backup;
 }
 // ── install ────────────────────────────────────────────────────────────────
-function install(args) {
-    const invocation = resolveInvocation(args);
+async function install(args) {
     const cwd = process.cwd();
     const sidecar = readSidecar();
+    const invocation = resolveInvocation(args, projectRecord(sidecar, cwd)?.invocation);
     sidecar.token ??= randomBytes(32).toString("hex");
-    sidecar.controlPort = args.port;
-    const controlUrl = `http://127.0.0.1:${args.port}`;
+    // 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.
+    const port = args.portExplicit ? args.port : await allocateFreeProjectPort(sidecar, cwd);
+    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 controlUrl = `http://127.0.0.1:${port}`;
     const entries = args.configPath
         ? Object.entries(readGenericServers(args.configPath)).map(([name, config]) => ({
             name,
@@ -245,18 +327,52 @@ function install(args) {
         }))
         : resolveServers(cwd);
     const wanted = entries.filter((e) => args.servers.length === 0 || args.servers.includes(e.name));
-    if (wanted.length === 0) {
+    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).");
         }
         return 0;
     }
+    if (wanted.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("  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(" ");
+    };
     let wrapped = 0;
     for (const entry of wanted) {
         if (entry.name === SCENARIO_SERVER_KEY && isScenarioServer(entry.config)) {
-            out(`  = ${entry.name} — the scenario server (calculated replay)`);
+            if (!args.replay || stillCurrent(entry.config, localScenarioPath())) {
+                out(`  = ${entry.name} — the scenario server (calculated replay)`);
+            }
+            else {
+                out(`  ~ ${entry.name} — re-writing the scenario server: its runner moved`);
+            }
             continue;
         }
         if (entry.name === SCENARIO_SERVER_KEY) {
@@ -277,15 +393,18 @@ function install(args) {
             // 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 stale = args.hooks && !args.configPath && current !== controlUrl;
+            const urlStale = args.hooks && !args.configPath && current !== controlUrl;
+            const pathStale = !stillCurrent(entry.config, localProxyPath());
             const stashed = sidecar.servers[sidecarKey(cwd, entry.name)]?.original;
-            if (!stale || !stashed) {
+            if (!(urlStale || pathStale) || !stashed) {
                 out(`  = ${entry.name} — already wrapped`);
                 continue;
             }
+            const was = `${entry.config.command} ${(entry.config.args ?? [])[0] ?? ""}`.trim();
             entry.config = stashed;
-            out(`  ~ ${entry.name} — re-wrapping: its control URL was ` +
-                `${current ?? "unset"}, now ${controlUrl}`);
+            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) {
@@ -299,6 +418,7 @@ function install(args) {
             invocation,
             proxyPath: invocation === "npx" ? undefined : localProxyPath(),
             version: VERSION,
+            nodeFlags,
         });
         let file;
         let text;
@@ -336,6 +456,7 @@ function install(args) {
             scenarioPath: invocation === "npx" ? undefined : localScenarioPath(),
             version: VERSION,
             controlUrl: args.hooks ? controlUrl : undefined,
+            nodeFlags,
         });
         // PROJECT SCOPE, NOT LOCAL — this was a bug worth the comment.
         //
@@ -373,17 +494,47 @@ function install(args) {
         };
         out(`  + ${SCENARIO_SERVER_KEY} → bir-scenario (calculated replay; ${scope} scope)`);
     }
+    // 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) {
-        backupFile(sidecar, paths.settings);
-        const text = installHooks(paths.settings, buildHooksBlock(controlUrl, sidecar.token));
-        noteWritten(sidecar, paths.settings, text);
-        sidecar.hookFiles = [...new Set([...(sidecar.hookFiles ?? []), paths.settings])];
-        out(`  + hooks → ${paths.settings} (control server on ${controlUrl})`);
+        // 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)`);
+        }
+        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]);
+        }
+        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}`);
     }
     writeSidecar(sidecar);
     out();
     out(`Wrapped ${wrapped} server${wrapped === 1 ? "" : "s"}.`);
-    if (args.hooks && !args.configPath) {
+    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.");
+    }
+    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.");
     }
@@ -392,8 +543,8 @@ function install(args) {
     }
     if (args.replay) {
         out();
-        out("Calculated replay is INSTALLED and ON by default once `bir-hooks` runs. Set");
-        out("BIR_REPLAY=0 where you run `bir-hooks` to turn it off — and read");
+        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.");
     }
@@ -470,12 +621,24 @@ function uninstall(args) {
             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.");
     return 0;
@@ -511,8 +674,12 @@ function status(args) {
         return 0;
     }
     out(`Directory : ${report.cwd}`);
-    out(`BaseIn    : ${report.authUrl ?? "(BIR_AUTH_URL not set — nothing is recorded)"}`);
-    out(`Control   : ${discovery ? `${discovery.url} (pid ${discovery.pid})` : "not running"}`);
+    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" : ""})`
+        : "not running — `bir up` starts it"}`);
+    if (discovery?.logFile)
+        out(`Log       : ${discovery.logFile}`);
     out("Servers   :");
     if (report.servers.length === 0)
         out("  (none configured for this directory)");
@@ -526,6 +693,7 @@ function status(args) {
 async function doctor(args) {
     const cwd = process.cwd();
     const problems = [];
+    const notes = [];
     const entries = resolveServers(cwd);
     const wantWrapped = entries.filter((e) => isWrapped(e.config)).map((e) => e.name);
     const discovery = readDiscovery(cwd);
@@ -536,13 +704,24 @@ async function doctor(args) {
             problems.push(`control server at ${discovery.url} did not answer /health`);
     }
     else {
-        problems.push("no control server for this directory — recording will be Tier 2 (MCP only)");
+        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");
     }
     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.
+    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).
-    for (const name of wantWrapped) {
-        if (!registered.has(name)) {
+    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?`);
         }
     }
@@ -558,14 +737,16 @@ async function doctor(args) {
     // its own `BIR_AUTH_URL` is not evidence about either, and treating it as
     // evidence produced a confident "nothing will be recorded" on a session that
     // was recording perfectly. Ask the recorder; it is the only process that knows.
-    const notes = [];
     if (health) {
         if (health.recording === false) {
-            problems.push("the recorder is running but has nowhere to send steps — set BIR_AUTH_URL " +
-                "and run `bir login` in the terminal where you start `bir-hooks`");
+            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`");
         }
         else {
-            notes.push(`recording to ${String(health.authUrl ?? "the configured BaseIn service")}`);
+            notes.push(`recording to ${String(health.authUrl ?? "the configured BaseIn service")}${health.account ? ` as ${String(health.account)}` : ""}`);
+        }
+        if (discovery?.daemon) {
+            notes.push(`the recorder runs in the background (pid ${discovery.pid}); its audit log is ${discovery.logFile ?? "under ~/.baseinstrunner/logs"}`);
         }
         // 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
@@ -599,6 +780,29 @@ async function doctor(args) {
         problems.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);
+        }
+        catch {
+            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`);
+                }
+            }
+        }
+    }
     // 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
     // `bir` entry that starts with `npx` has to resolve and unpack the package
@@ -633,7 +837,8 @@ async function doctor(args) {
     const replay = health?.replay;
     if (replay?.enabled) {
         out(`Replay            : ON  servers=${replay.allowServers?.join(",") || "(all wrapped)"}  ` +
-            `minSimilarity=${replay.minSimilarity ?? "?"}`);
+            `minSimilarity=${replay.minSimilarity ?? "?"}` +
+            (replay.source ? `  source=${replay.source}` : ""));
         // An older control server sends only `deriveKey`; read it as the two states
         // it could describe then.
         const via = replay.deriveVia ?? (replay.deriveKey ? "key" : "samples");
@@ -649,7 +854,7 @@ async function doctor(args) {
                 "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) {
+        if (idle.length > 0 && !idleRecorder) {
             notes.push(`these proxies are not polling for replay work: ${idle.join(", ")} — ` +
                 "their steps will fall back to recorded outputs");
         }
@@ -810,7 +1015,63 @@ async function scenarioCommand(args) {
  * Without `--dry` the same plan runs against the live proxies through the
  * control server — the Tier 2 and debugging path (docs/calculatedReplay.md §12.1).
  */
+/**
+ * `bir replay status | on | off | allow <a,b> | allow all` — this project's
+ * replay switches, stored in the sidecar so a recorder started by the
+ * SessionStart hook keeps them (generate.ts, `ReplayPolicy`).
+ */
+function replayPolicyCommand(args) {
+    const cwd = process.cwd();
+    const sidecar = readSidecar();
+    const record = projectRecord(sidecar, cwd);
+    const word = args.positionals[0];
+    const describe = (policy) => {
+        out(`Replay policy for ${cwd}`);
+        out(`  replay         ${policy?.enabled === false ? "off" : "on"}`);
+        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);
+        if (overrides.length) {
+            out(`  (set in this shell's environment, which a recorder started from it would prefer: ${overrides.join(", ")})`);
+        }
+        if (!record)
+            out("  (this directory has not been installed — `bir setup` here first)");
+        out("Restart the recorder to apply a change: `bir up --restart`.");
+    };
+    if (word === "status") {
+        describe(record?.replay);
+        return 0;
+    }
+    if (!record) {
+        out("This directory has not been installed — run `bir setup` (or `bir install --replay`) here first.");
+        return 1;
+    }
+    const next = { ...(record.replay ?? {}) };
+    if (word === "on")
+        delete next.enabled;
+    else if (word === "off")
+        next.enabled = false;
+    else if (word === "allow") {
+        const list = args.positionals[1];
+        if (!list) {
+            out("usage: bir replay allow <server,server>  |  bir replay allow all");
+            return 2;
+        }
+        if (list === "all")
+            delete next.allowServers;
+        else
+            next.allowServers = list.split(",").map((s) => s.trim()).filter(Boolean);
+    }
+    setProjectRecord(sidecar, cwd, { port: record.port, replay: next });
+    writeSidecar(sidecar);
+    describe(next);
+    return 0;
+}
 async function replayCommand(args) {
+    const word = args.positionals[0];
+    if (word === "status" || word === "on" || word === "off" || word === "allow") {
+        return replayPolicyCommand(args);
+    }
     const scenarioId = args.scenarioId ?? args.positionals[0];
     if (!scenarioId || !args.prompt) {
         out('usage: bir replay --scenario <scnId> --prompt "…" [--dry]');
@@ -972,6 +1233,65 @@ 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();
+            return runSetup({
+                authUrl: args.authUrl,
+                token: args.token,
+                project: args.project,
+                browser: args.browser,
+                replay: !args.noReplay,
+                daemon: !args.noDaemon,
+                allowServers: args.allowServers,
+            }, {
+                out,
+                err: (line) => process.stderr.write(`[bir] ${line}\n`),
+                install: ({ replay }) => install({ ...args, global: installed, local: !installed, replay, hooks: true, servers: [] }),
+                hooksScript: localHooksPath(),
+            });
+        }
+        case "up": {
+            const cwd = process.cwd();
+            if (args.restart)
+                await stopDaemon(cwd);
+            const { status, started, restarted } = await ensureDaemon(cwd, {
+                hooksScript: localHooksPath(),
+                restartOnSkew: true,
+            });
+            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}`);
+            if (status.health.recording === false) {
+                out("  !! it has no session to record with — run `bir setup` or `bir login`, then `bir up --restart`");
+                return 1;
+            }
+            return 0;
+        }
+        case "down": {
+            const cwd = process.cwd();
+            const before = readDiscovery(cwd);
+            if (!before) {
+                out("No recorder is running for this directory.");
+                return 0;
+            }
+            const result = await stopDaemon(cwd);
+            if (result.stale) {
+                out(`No recorder answered for this directory; a stale record (pid ${before.pid}) was removed.`);
+                return 0;
+            }
+            if (!result.stopped) {
+                out(`The recorder (pid ${before.pid}) did not stop.`);
+                return 1;
+            }
+            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}).`);
+            return 0;
+        }
         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
@@ -1041,6 +1361,9 @@ async function main() {
             }
             if (!session)
                 return 1;
+            // From here on no terminal needs BIR_AUTH_URL: the address a session was
+            // just issued by is the one every process should use.
+            rememberAuthUrl(baseUrl);
             out(`Signed in to ${baseUrl} as ${session.user.email}.`);
             return 0;
         }

package/dist/bin/investigate.js

@@ -179,7 +179,11 @@ export const DECLINES = {
     },
     known_bad_first_step: {
         cause: "the chain's first step is parked after repeated failures.",
-        fix: "recalculate the scenario (`bir scenario calc <runId> --force`).",
+        fix: "wait: the service retries it once an hour for a day, then repairs the plan from the next run of the prompt. To repair now: `bir scenario calc <runId> --force`.",
+    },
+    nondeterministic_first_step: {
+        cause: "the chain's first step needs a judgement the calculation could not write code for, so the plan cannot start.",
+        fix: "the agent does this task itself; a model step for such judgements is planned (plan-services.md W3.1).",
     },
     unusable_first_step: {
         cause: "the first step calls a sub-task that is gone, switched off or stale.",