@basein/runner 0.1.0

package/dist/bin/bir.js

@@ -0,0 +1,876 @@
+#!/usr/bin/env node
+/**
+ * bir — the command line (Phase 7).
+ *
+ *   bir install [--config <path>] [--server <name>]… [--local] [--no-hooks]
+ *   bir uninstall [--config <path>]
+ *   bir status
+ *   bir doctor
+ *   bir wrap --server-name <key> -- <command> [args…]
+ *   bir login | logout
+ *   bir --version
+ *
+ * `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
+ * 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, 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 { readGenericServers, setGenericServerEntry } from "../config/adapters/generic.js";
+import { clearCredentials, authenticate, resolveAuthUrl, normalizeAuthUrl } from "../auth/client.js";
+import { DEFAULT_CONTROL_PORT } from "../control/server.js";
+import { errText } from "../util/log.js";
+import { packageVersion } from "../util/version.js";
+const VERSION = packageVersion();
+const out = (line = "") => {
+    process.stdout.write(line + "\n");
+};
+function usage(code = 0) {
+    out(`bir ${VERSION} — a recording MCP proxy
+
+Commands:
+  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
+  logout      forget the cached credentials
+
+  scenario list                     recorded runs and their calculated scenarios
+  scenario show <runId>             a run's scenario: intent, params, steps
+  scenario calc <runId> [--force]   calculate (or re-derive) a run's scenario
+  scenario replay <scnId> --prompt "…" [--dry]
+  replay --scenario <scnId> --prompt "…" [--dry]
+
+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.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})
+  --json            machine-readable output for status / doctor
+  --dry             replay against recorded outputs only; run no real tools`);
+    process.exit(code);
+}
+function parseArgs(argv) {
+    const args = {
+        command: argv[0] ?? "",
+        servers: [],
+        local: false,
+        global: false,
+        hooks: true,
+        noCorrelation: false,
+        port: DEFAULT_CONTROL_PORT,
+        json: false,
+        rest: [],
+        replay: false,
+        positionals: [],
+        dry: false,
+        force: false,
+    };
+    for (let i = 1; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--") {
+            args.rest = argv.slice(i + 1);
+            break;
+        }
+        switch (arg) {
+            case "--replay":
+                args.replay = true;
+                break;
+            case "--prompt":
+                args.prompt = argv[++i];
+                break;
+            case "--scenario":
+                args.scenarioId = argv[++i];
+                break;
+            case "--dry":
+                args.dry = true;
+                break;
+            case "--force":
+                args.force = true;
+                break;
+            case "--config":
+                args.configPath = argv[++i];
+                break;
+            case "--server":
+                args.servers.push(argv[++i] ?? "");
+                break;
+            case "--server-name":
+                args.serverName = argv[++i];
+                break;
+            case "--local":
+                args.local = true;
+                break;
+            case "--global":
+                args.global = true;
+                break;
+            case "--no-hooks":
+                args.hooks = false;
+                break;
+            case "--no-correlation":
+                args.noCorrelation = true;
+                break;
+            case "--port":
+                args.port = Number(argv[++i]);
+                break;
+            case "--json":
+                args.json = true;
+                break;
+            default:
+                if (arg.startsWith("-"))
+                    usage(2);
+                else
+                    args.positionals.push(arg);
+        }
+    }
+    return args;
+}
+/** Absolute path to this package's built `bir-proxy.js`, for `--local`. */
+function localProxyPath() {
+    return resolvePath(dirname(fileURLToPath(import.meta.url)), "bir-proxy.js");
+}
+/** Absolute path to this package's built `bir-scenario.js`, for `--local`. */
+function localScenarioPath() {
+    return resolvePath(dirname(fileURLToPath(import.meta.url)), "bir-scenario.js");
+}
+/**
+ * Which invocation the generated entries use — and the guard that makes
+ * `--global` mean something.
+ *
+ * `--global` resolves to the very same absolute path `--local` does:
+ * `import.meta.url` already points into whichever copy of the package is
+ * running. What differs is the promise. `--global` asserts the path outlives
+ * this shell, and that is only true when `bir` is itself running from an
+ * installed package — a checkout's `dist/` moves with the checkout, so writing
+ * it into a runner's config as though it were permanent is the kind of install
+ * 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) {
+    if (args.local && args.global) {
+        process.stderr.write("[bir] --local and --global are mutually exclusive\n");
+        process.exit(2);
+    }
+    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";
+}
+/** Record a file's pre-install text once, so uninstall can restore it exactly. */
+function backupFile(sidecar, file) {
+    sidecar.files ??= {};
+    if (sidecar.files[file])
+        return;
+    sidecar.files[file] = { originalText: readTextOrNull(file), writtenSha: "" };
+}
+function noteWritten(sidecar, file, text) {
+    sidecar.files ??= {};
+    const backup = sidecar.files[file] ?? { originalText: null, writtenSha: "" };
+    backup.writtenSha = sha256(text);
+    sidecar.files[file] = backup;
+}
+// ── install ────────────────────────────────────────────────────────────────
+function install(args) {
+    const invocation = resolveInvocation(args);
+    const cwd = process.cwd();
+    const sidecar = readSidecar();
+    sidecar.token ??= randomBytes(32).toString("hex");
+    sidecar.controlPort = args.port;
+    const controlUrl = `http://127.0.0.1:${args.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) {
+        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;
+    }
+    const paths = claudeCodePaths(cwd);
+    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)`);
+            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`);
+            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 stale = args.hooks && !args.configPath && current !== controlUrl;
+            const stashed = sidecar.servers[sidecarKey(cwd, entry.name)]?.original;
+            if (!stale || !stashed) {
+                out(`  = ${entry.name} — already wrapped`);
+                continue;
+            }
+            entry.config = stashed;
+            out(`  ~ ${entry.name} — re-wrapping: its control URL was ` +
+                `${current ?? "unset"}, now ${controlUrl}`);
+        }
+        // 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,
+        });
+        let file;
+        let text;
+        if (args.configPath) {
+            file = args.configPath;
+            backupFile(sidecar, file);
+            text = setGenericServerEntry(file, entry.name, proxied);
+        }
+        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})`);
+        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,
+        });
+        // 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;
+        }
+        noteWritten(sidecar, file, text);
+        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(),
+        };
+        out(`  + ${SCENARIO_SERVER_KEY} → bir-scenario (calculated replay; ${scope} scope)`);
+    }
+    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})`);
+    }
+    writeSidecar(sidecar);
+    out();
+    out(`Wrapped ${wrapped} server${wrapped === 1 ? "" : "s"}.`);
+    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.");
+    }
+    else {
+        out("Recording will be standalone (Tier 2): MCP calls only, no prompt or final answer.");
+    }
+    if (args.replay) {
+        out();
+        out("Calculated replay is INSTALLED but not ON. Set BIR_REPLAY=1 where you run");
+        out("`bir-hooks` to enable it — and read docs/calculatedReplayGuide.md §5.1 first:");
+        out("a replayed step is auto-approved, and a directly executed one never reaches");
+        out("the permission system at all.");
+    }
+    return 0;
+}
+// ── uninstall ──────────────────────────────────────────────────────────────
+function uninstall(args) {
+    const cwd = process.cwd();
+    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;
+        }
+        if (record.scope === "explicit") {
+            setGenericServerEntry(record.file, SCENARIO_SERVER_KEY, null);
+        }
+        else {
+            setServerEntry(record.scope, cwd, SCENARIO_SERVER_KEY, null, paths);
+        }
+        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;
+        }
+        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 {
+                setServerEntry(record.scope, cwd, name, record.original, paths);
+            }
+            out(`  ← ${name} — entry restored (file changed since install)`);
+        }
+        delete sidecar.servers[key];
+    }
+    for (const settings of sidecar.hookFiles ?? []) {
+        if (restoredWhole.has(settings))
+            continue;
+        if (existsSync(settings)) {
+            uninstallHooks(settings);
+            out(`  ← hooks removed from ${settings}`);
+        }
+    }
+    sidecar.hookFiles = [];
+    sidecar.files = {};
+    writeSidecar(sidecar);
+    out();
+    out("Uninstalled.");
+    return 0;
+}
+// ── status ─────────────────────────────────────────────────────────────────
+function status(args) {
+    const cwd = process.cwd();
+    const entries = args.configPath
+        ? Object.entries(readGenericServers(args.configPath)).map(([name, config]) => ({
+            name,
+            config,
+            scope: "explicit",
+            shadowed: [],
+        }))
+        : resolveServers(cwd);
+    const discovery = readDiscovery(cwd);
+    const report = {
+        cwd,
+        authUrl: resolveAuthUrl() || null,
+        controlServer: discovery ? { url: discovery.url, pid: discovery.pid } : null,
+        discoveryFile: discoveryPath(cwd),
+        stateDir: configDir(),
+        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,
+        })),
+    };
+    if (args.json) {
+        out(JSON.stringify(report, null, 2));
+        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("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}`);
+    }
+    return 0;
+}
+// ── doctor ─────────────────────────────────────────────────────────────────
+async function doctor(args) {
+    const cwd = process.cwd();
+    const problems = [];
+    const entries = resolveServers(cwd);
+    const wantWrapped = entries.filter((e) => isWrapped(e.config)).map((e) => e.name);
+    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`);
+    }
+    else {
+        problems.push("no control server for this directory — recording will be Tier 2 (MCP only)");
+    }
+    const registered = new Set((health?.registeredProxies ?? []).map((p) => p.serverName));
+    // 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)) {
+            problems.push(`${name} is wrapped in config but no proxy has registered — is the session running?`);
+        }
+    }
+    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}`);
+        }
+    }
+    // IS ANYTHING ACTUALLY BEING SAVED?
+    //
+    // `bir doctor` runs in whatever shell you happen to be in — not the one that
+    // started `bir-hooks`, and not the one the host spawned the proxies from. So
+    // 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`");
+        }
+        else {
+            notes.push(`recording to ${String(health.authUrl ?? "the configured BaseIn service")}`);
+        }
+    }
+    else if (!resolveAuthUrl()) {
+        // No control server to ask, and nothing in this shell either. That is a
+        // reason to be uncertain, not a reason to declare failure.
+        notes.push("could not verify recording: no control server to ask, and BIR_AUTH_URL is " +
+            "unset in this shell (which is not where the proxies read it from)");
+    }
+    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}`);
+    }
+    if (args.json) {
+        out(JSON.stringify({ ok: problems.length === 0, problems, notes, health, wrapped: wantWrapped }, null, 2));
+        return problems.length === 0 ? 0 : 1;
+    }
+    // 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
+    // reading a log file.
+    const replay = health?.replay;
+    if (replay?.enabled) {
+        out(`Replay            : ON  servers=${replay.allowServers?.join(",") || "(all wrapped)"}  ` +
+            `minSimilarity=${replay.minSimilarity ?? "?"}`);
+        out(`                    derive=${replay.deriveKey ? "anthropic" : "recorded sample values (no ANTHROPIC_API_KEY)"}`);
+        const idle = wantWrapped.filter((n) => !(replay.pollingProxies ?? []).includes(n));
+        if (idle.length > 0) {
+            notes.push(`these proxies are not polling for replay work: ${idle.join(", ")} — ` +
+                "their steps will fall back to recorded outputs");
+        }
+    }
+    else if (health) {
+        out("Replay            : off");
+    }
+    out(`Wrapped in config : ${wantWrapped.join(", ") || "(none)"}`);
+    out(`Registered proxies: ${[...registered].join(", ") || "(none)"}`);
+    out(`Control server    : ${discovery?.url ?? "not running"}`);
+    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)"}`);
+    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 (notes.length)
+            out();
+        out("No problems found.");
+        return 0;
+    }
+    if (notes.length)
+        out();
+    out("Problems:");
+    for (const p of problems)
+        out(`  ! ${p}`);
+    return 1;
+}
+// ── scenario / replay ──────────────────────────────────────────────────────
+/**
+ * A thin authenticated client for the BaseIn scenario endpoints.
+ *
+ * Everything below is a wrapper over routes that already exist server-side.
+ * They are here because telling somebody to `curl` with a token dug out of
+ * `~/.baseinstrunner/credentials.json` is not an interface, and because
+ * dry-replaying a scenario before trusting it is the cheapest useful thing an
+ * operator can do (docs/calculatedReplayGuide.md §3.1).
+ */
+async function service(method, path, body) {
+    const configured = resolveAuthUrl();
+    if (!configured)
+        throw new Error("BIR_AUTH_URL is not set");
+    // A cross-origin redirect strips the bearer token; settle the URL first.
+    const baseUrl = await normalizeAuthUrl(configured);
+    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(() => "");
+    let parsed = undefined;
+    try {
+        parsed = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        parsed = text;
+    }
+    return { status: res.status, body: parsed };
+}
+function pad(text, width) {
+    return text.length >= width ? text.slice(0, width) : text + " ".repeat(width - text.length);
+}
+async function scenarioCommand(args) {
+    const sub = args.positionals[0] ?? "";
+    const target = args.positionals[1];
+    if (sub === "list") {
+        const { status, body } = await service("GET", "/recordings/runs?pageSize=50");
+        if (status !== 200) {
+            out(`Could not list runs (HTTP ${status}).`);
+            return 1;
+        }
+        const runs = (body?.runs ?? []);
+        if (args.json) {
+            out(JSON.stringify(body, null, 2));
+            return 0;
+        }
+        if (runs.length === 0) {
+            out("No recorded runs yet.");
+            return 0;
+        }
+        // Ids are 40 characters and are meant to be copied into `calc` / `replay`,
+        // so they get their own line rather than a column that truncates them.
+        for (const r of runs) {
+            const title = r.title ?? (r.input ?? "").split("\n")[0];
+            out(`${r.id}  ${title.slice(0, 60)}`);
+            const facts = [`iterations=${r.iterations ?? 1}`, `steps=${r.step_count ?? "?"}`];
+            if (r.scenario_id)
+                facts.push(`scenario=${r.scenario_id} (${r.scenario_state ?? "?"})`);
+            else
+                facts.push("scenario=none — run `bir scenario calc <runId>`");
+            out(`    ${facts.join("  ")}`);
+        }
+        return 0;
+    }
+    if (sub === "show") {
+        if (!target) {
+            out("usage: bir scenario show <runId>");
+            return 2;
+        }
+        const { status, body } = await service("GET", `/recordings/runs/${target}/scenario`);
+        if (status === 404) {
+            out("No scenario for that run yet — `bir scenario calc <runId>` first.");
+            return 1;
+        }
+        if (status !== 200) {
+            out(`Could not read the scenario (HTTP ${status}).`);
+            return 1;
+        }
+        out(JSON.stringify(body, null, 2));
+        return 0;
+    }
+    if (sub === "calc") {
+        if (!target) {
+            out("usage: bir scenario calc <runId> [--force]");
+            return 2;
+        }
+        const { status, body } = await service("POST", `/recordings/runs/${target}/calculate`, args.force ? { force: true } : {});
+        if (status === 202) {
+            const b = body;
+            out(`Calculating ${b.scenarioId ?? ""} — poll with \`bir scenario show ${target}\`.`);
+            return 0;
+        }
+        if (status === 409) {
+            out("That run already has a scenario. Re-derive it in place with --force.");
+            return 1;
+        }
+        if (status === 503) {
+            out("The service has no Anthropic configuration, so it cannot calculate scenarios.");
+            return 1;
+        }
+        out(`Could not start calculation (HTTP ${status}): ${JSON.stringify(body)}`);
+        return 1;
+    }
+    if (sub === "replay") {
+        return replayCommand({ ...args, scenarioId: args.scenarioId ?? target });
+    }
+    out("usage: bir scenario <list|show|calc|replay> …");
+    return 2;
+}
+/**
+ * `--dry` evaluates the scenario's stored logic against the **source run's
+ * recorded outputs**, server-side: no real tools, no side effects, one Haiku
+ * call. It is the cheapest way to find out whether a scenario's parameters and
+ * per-step inputs actually vary with the prompt, which is the difference between
+ * a scenario and a recording.
+ *
+ * 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).
+ */
+async function replayCommand(args) {
+    const scenarioId = args.scenarioId ?? args.positionals[0];
+    if (!scenarioId || !args.prompt) {
+        out('usage: bir replay --scenario <scnId> --prompt "…" [--dry]');
+        return 2;
+    }
+    if (args.dry) {
+        const { status, body } = await service("POST", `/scenarios/${scenarioId}/replay`, {
+            prompt: args.prompt,
+        });
+        if (status !== 200) {
+            out(`Dry replay failed (HTTP ${status}): ${JSON.stringify(body)}`);
+            return 1;
+        }
+        if (args.json) {
+            out(JSON.stringify(body, null, 2));
+            return 0;
+        }
+        const r = body;
+        out(`params      ${JSON.stringify(r.params ?? {})}`);
+        (r.steps ?? []).forEach((s, i) => {
+            out(`step ${i}      ${s.toolName}  ${JSON.stringify(s.input)}`);
+            const emitted = Object.keys(s.emitted ?? {});
+            if (emitted.length)
+                out(`              → emitted: ${emitted.join(", ")}`);
+            else
+                out("              → emitted: (nothing — toolOutputLogic derived no keys)");
+        });
+        out(`response    ${JSON.stringify(r.response ?? {})}`);
+        out(`cost        $${(r.costUsd ?? 0).toFixed(4)}`);
+        return 0;
+    }
+    // Live. The split is deliberate: this process holds the credentials, so it
+    // fetches the scenario; the control server holds the proxies, so it runs it.
+    const runId = args.positionals[1] ?? args.positionals[0];
+    if (!runId || !runId.startsWith("run_")) {
+        out("Live replay needs the scenario's source run, so it can be fetched:");
+        out('  bir replay --scenario <scnId> --prompt "…" <runId>');
+        out("Or check the logic without running anything, with --dry.");
+        return 2;
+    }
+    const cwd = process.cwd();
+    const discovery = readDiscovery(cwd);
+    if (!discovery) {
+        out("No control server for this directory — start `bir-hooks` first.");
+        out("(Or use --dry, which needs only the service.)");
+        return 1;
+    }
+    const fetched = await service("GET", `/recordings/runs/${runId}/scenario`);
+    if (fetched.status !== 200) {
+        out(`Could not fetch that run's scenario (HTTP ${fetched.status}).`);
+        return 1;
+    }
+    const scenario = fetched.body?.scenario;
+    if (!scenario) {
+        out("That run has no calculated scenario yet — `bir scenario calc` first.");
+        return 1;
+    }
+    const res = await fetch(`${discovery.url.replace(/\/+$/, "")}/scenario/replay`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${discovery.token}`,
+        },
+        body: JSON.stringify({ scenario, prompt: args.prompt }),
+    });
+    const result = (await res.json().catch(() => ({})));
+    if (args.json) {
+        out(JSON.stringify(result, null, 2));
+        return result.ok ? 0 : 1;
+    }
+    if (!result.ok) {
+        out(`Replay failed: ${result.why ?? "unknown"}`);
+        return 1;
+    }
+    for (const t of result.trace ?? []) {
+        out(`step ${t.step}      ${t.tool}  ${JSON.stringify(t.input)}  [${t.outcome}, ${t.ms}ms]`);
+    }
+    out(`response    ${JSON.stringify(result.responseModel ?? {})}`);
+    out(`steps       ${result.steps ?? 0}${result.partial ? " (partial — budget reached)" : ""}`);
+    return 0;
+}
+// ── wrap ───────────────────────────────────────────────────────────────────
+/**
+ * Print the proxied entry for one server without touching any file. This is what
+ * makes D8 real: a client with no adapter never needs us to know where it keeps
+ * its settings — the user pastes this in.
+ */
+function wrap(args) {
+    const name = args.serverName;
+    if (!name) {
+        out("usage: bir wrap --server-name <key> [--url <url> --transport http|sse] -- <command> [args…]");
+        return 2;
+    }
+    const rest = args.rest;
+    const config = rest.length
+        ? { command: rest[0], args: rest.slice(1) }
+        : (() => {
+            out("usage: bir wrap --server-name <key> -- <command> [args…]");
+            process.exit(2);
+        })();
+    const sidecar = readSidecar();
+    const entry = wrapEntry(config, {
+        serverName: name,
+        controlUrl: sidecar.controlPort ? `http://127.0.0.1:${sidecar.controlPort}` : undefined,
+        noCorrelation: args.noCorrelation,
+        invocation: resolveInvocation(args),
+        proxyPath: args.local || args.global ? localProxyPath() : undefined,
+        version: VERSION,
+    });
+    out(JSON.stringify({ mcpServers: { [name]: entry } }, null, 2));
+    return 0;
+}
+// ── entry point ────────────────────────────────────────────────────────────
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help")
+        usage(0);
+    if (argv[0] === "--version" || argv[0] === "-v") {
+        out(VERSION);
+        return 0;
+    }
+    const args = parseArgs(argv);
+    switch (args.command) {
+        case "install":
+            return install(args);
+        case "uninstall":
+            return uninstall(args);
+        case "status":
+            return status(args);
+        case "doctor":
+            return doctor(args);
+        case "wrap":
+            return wrap(args);
+        case "scenario":
+            return scenarioCommand(args);
+        case "replay":
+            return replayCommand(args);
+        case "login": {
+            const session = await authenticate();
+            if (!session)
+                return 1;
+            out(`Signed in as ${session.user.email}.`);
+            return 0;
+        }
+        case "logout":
+            clearCredentials();
+            out("Logged out — cached credentials cleared.");
+            return 0;
+        default:
+            usage(2);
+    }
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    process.stderr.write(`[bir] ${errText(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=bir.js.map