@basein/runner 0.2.12 → 0.3.1

package/dist/bin/service-read.js

@@ -0,0 +1,128 @@
+/**
+ * service-read — what `bir scenario show|edits` and `bir investigate` share
+ * about asking the service and printing its answer, so a slow service, a
+ * signed-out machine or a large scenario never turns into a stall or a flood.
+ *
+ * WHY A BOUND OF THEIR OWN. The `service()` these commands are handed settles
+ * the service address with a `/health` probe, may refresh the session, and
+ * then makes its request; a service (or a corporate proxy in front of it) that
+ * accepts the connection and never answers held every one of those for as long
+ * as Node's fetch waits — measured at 120 s through the `bir` MCP server, which
+ * is 120 s of a turn stalled on a debugging tool. A read is safe to abandon:
+ * nothing was asked to change. So each one gets {@link readTimeoutMs} — a
+ * command that reads twice shares it between them ({@link ReadClock}) — and
+ * then an answer in words. Writes (`check`, `edit`, `undo`, `calc`) are not
+ * bounded here — abandoning one would leave "was it saved?" unanswerable — and
+ * the MCP server bounds the whole command instead.
+ *
+ * WHY COMPACT JSON UNDER THE MCP SERVER. The `bir` MCP server runs these
+ * commands with `BIR_MCP=1` and hands their `--json` output to the model.
+ * Indentation is for a person at a terminal; in a model's context it is a
+ * quarter of the tokens and none of the meaning.
+ */
+/** Default bound on one command's reads of the service. `BIR_READ_TIMEOUT_MS` overrides it. */
+export const DEFAULT_READ_TIMEOUT_MS = 15_000;
+/**
+ * The most any timer here is set for from the environment. Node turns a delay
+ * past 2^31 - 1 ms into 1 ms, so a mistyped `BIR_READ_TIMEOUT_MS=3000000000`
+ * used to make every read give up at once; ten minutes is already far longer
+ * than anybody waits for a debugging tool.
+ */
+export const MAX_ENV_TIMEOUT_MS = 600_000;
+/**
+ * A number of milliseconds from the environment: positive and at most
+ * {@link MAX_ENV_TIMEOUT_MS}, or `fallback`. Out of range is a mistake, and
+ * the default is the value known to work.
+ */
+export function envTimeoutMs(name, fallback) {
+    const n = Number(process.env[name]);
+    return Number.isFinite(n) && n > 0 && n <= MAX_ENV_TIMEOUT_MS ? n : fallback;
+}
+export function readTimeoutMs() {
+    return envTimeoutMs("BIR_READ_TIMEOUT_MS", DEFAULT_READ_TIMEOUT_MS);
+}
+/** True when the `bir` MCP server ran this command for a model (it sets `BIR_MCP=1`). */
+export function underMcp() {
+    return process.env.BIR_MCP === "1";
+}
+/** `--json` output: indented for a person, compact for a model. */
+export function jsonText(value) {
+    return underMcp() ? JSON.stringify(value) : JSON.stringify(value, null, 2);
+}
+/**
+ * `pending`, or `{ error }` when it takes longer than `ms`. The request itself
+ * is not cancelled — `bir` exits as soon as the command returns, which is what
+ * ends it — and a late rejection is observed here, so it can never surface as
+ * an unhandled one. `statedMs` is the bound the answer names, when `ms` is
+ * only what was left of it ({@link ReadClock}).
+ */
+export async function readWithin(pending, ms = readTimeoutMs(), statedMs = ms) {
+    pending.catch(() => undefined);
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ error: `the BaseIn service did not answer within ${seconds(statedMs)} s` }), Math.max(0, ms));
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([pending, late]);
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * One command's reads of the service, sharing one bound. A command that reads
+ * twice — `scenario edits` on a `run_` id finds the scenario, then its
+ * history; `investigate` tries the matched run after a "no" — used to give
+ * each read the whole bound, so a service that answered the first slowly and
+ * held the second took twice as long as the `bir` MCP server allows a
+ * reading tool, and was killed there with none of the answer the command
+ * already had (the journal half of `investigate`, say). Sharing the bound
+ * keeps the whole command inside it, and the timeout still names the bound,
+ * not the scrap of it the last read had left.
+ */
+export class ReadClock {
+    totalMs;
+    deadline;
+    constructor(totalMs = readTimeoutMs()) {
+        this.totalMs = totalMs;
+        this.deadline = Date.now() + totalMs;
+    }
+    /** What is left of the bound, in ms (0 once it is spent). */
+    remaining() {
+        return Math.max(0, this.deadline - Date.now());
+    }
+    /** {@link readWithin}, with what is left of the command's bound. */
+    within(pending) {
+        return readWithin(pending, this.remaining(), this.totalMs);
+    }
+}
+/** Whether a `{ error }` means the service could not be reached at all, as opposed to answering. */
+export function unreachable(error) {
+    return /did not answer within|fetch failed|ECONN|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|socket|network|aborted|timed out|UND_ERR/i.test(error);
+}
+/**
+ * A failure to reach the service, in words a person (or a model) can act on.
+ * The transport's own words — "fetch failed", "This operation was aborted" —
+ * say nothing about what to do, so they are replaced; the sentences `bir`
+ * itself wrote ("not signed in — run `bir login`") are already the answer.
+ */
+export function serviceProblem(error) {
+    if (/BIR_AUTH_URL is not set/.test(error)) {
+        return "no BaseIn service is configured on this machine — run `bir setup` or `bir login`";
+    }
+    if (/did not answer within/.test(error))
+        return error;
+    if (unreachable(error))
+        return "the BaseIn service could not be reached — check the network, or try again later";
+    return error;
+}
+function seconds(ms) {
+    const s = ms / 1000;
+    return Number.isInteger(s) ? String(s) : s.toFixed(1);
+}
+//# sourceMappingURL=service-read.js.map

package/dist/bin/setup.d.ts

@@ -43,7 +43,26 @@ export interface SetupArgs {
     daemon: boolean;
     /** `--allow-servers a,b`: the servers replay may call unattended, stored for this project. */
     allowServers?: string;
+    /**
+     * `--port` was given: the port is the person's, and is never moved. Without
+     * it a recorded port this machine no longer lets the recorder bind is
+     * replaced (see {@link runSetup}, step 4).
+     */
+    portExplicit?: boolean;
 }
+/**
+ * The project directory every later step keys by: the PHYSICAL path on POSIX.
+ *
+ * After `chdir`, `process.cwd()` — which install keys the sidecar by and the
+ * recorder keys its discovery file by — is the resolved path. Keying setup's own
+ * steps by the logical one (a symlinked ~/code, macOS's /tmp → /private/tmp)
+ * made it wait 15 s for a discovery file that was written under the other
+ * spelling, report "the recorder did not start" while it ran, and store
+ * `--allow-servers` where the recorder never looks. Windows keeps the path as
+ * given: its cwd is not resolved through junctions, and resolving would only
+ * change the drive letter's case.
+ */
+export declare function canonicalProject(dir: string, platform?: NodeJS.Platform): string;
 export interface SetupDeps {
     out: (line?: string) => void;
     err: (line: string) => void;

package/dist/bin/setup.js

@@ -28,16 +28,41 @@
  * `cd <project>` and `bir setup`. The second needs no token; the session is
  * cached.
  */
-import { existsSync, statSync } from "node:fs";
+import { existsSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, join, parse as parsePath, resolve as resolvePath } from "node:path";
+import { pidAlive, readDiscovery } from "../control/discovery.js";
 import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, describeAuthService, deviceLogin, loadStoredConfig, normalizeAuthUrl, rememberAuthUrl, tokenLogin, } from "../auth/client.js";
-import { activeSessions, ensureDaemon, SETUP_TOKEN_ENV, stopDaemon, } from "../control/daemon.js";
+import { activeSessions, compareVersions, ensureDaemon, SETUP_TOKEN_ENV, stopDaemon, } from "../control/daemon.js";
 import { normalizePath } from "../control/paths.js";
-import { isWrapped, projectRecord, readSidecar, SCENARIO_SERVER_KEY, setProjectRecord, writeSidecar, allocateFreeProjectPort, } from "../config/generate.js";
+import { allocateReplacementPort, isScenarioServer, isWrapped, LOOPBACK_NO_PROXY, probeFreePort, proxyConfigured, projectRecord, readSidecar, SCENARIO_SERVER_KEY, setProjectRecord, writeSidecar, allocateFreeProjectPort, } from "../config/generate.js";
 import { resolveServers } from "../config/resolve.js";
 import { errText } from "../util/log.js";
+import { offSource } from "../util/off-switch.js";
 import { packageVersion } from "../util/version.js";
+/**
+ * The project directory every later step keys by: the PHYSICAL path on POSIX.
+ *
+ * After `chdir`, `process.cwd()` — which install keys the sidecar by and the
+ * recorder keys its discovery file by — is the resolved path. Keying setup's own
+ * steps by the logical one (a symlinked ~/code, macOS's /tmp → /private/tmp)
+ * made it wait 15 s for a discovery file that was written under the other
+ * spelling, report "the recorder did not start" while it ran, and store
+ * `--allow-servers` where the recorder never looks. Windows keeps the path as
+ * given: its cwd is not resolved through junctions, and resolving would only
+ * change the drive letter's case.
+ */
+export function canonicalProject(dir, platform = process.platform) {
+    const logical = resolvePath(dir);
+    if (platform === "win32")
+        return logical;
+    try {
+        return realpathSync(logical);
+    }
+    catch {
+        return logical;
+    }
+}
 /** True when `claude` (Claude Code) is on PATH or in its native install location. */
 export function claudeOnPath(env = process.env) {
     const names = process.platform === "win32" ? ["claude.exe", "claude.cmd", "claude"] : ["claude"];
@@ -93,7 +118,18 @@ export async function runSetup(args, deps) {
     const problem = await describeAuthService(baseUrl);
     if (problem) {
         err(`${baseUrl} is not a BaseIn service: ${problem}.`);
-        err(AUTH_URL_HINT);
+        if (/unreachable/.test(problem) && proxyConfigured(env) && !process.execArgv.includes("--use-env-proxy")) {
+            // Behind a proxy-only network the likeliest cause, and not the address:
+            // Node's fetch ignores HTTPS_PROXY unless it is started with this flag.
+            // NO_PROXY too: with the flag, the runner's own calls to 127.0.0.1 would
+            // go to the proxy as well, and install leaves the flag out without it.
+            err("HTTPS_PROXY/HTTP_PROXY is set, but this node does not use it without --use-env-proxy: set " +
+                `NO_PROXY=${LOOPBACK_NO_PROXY} (plus your own entries) and run ` +
+                "`node --use-env-proxy <path to bir.js> setup …` (the install line does this for you).");
+        }
+        else {
+            err(AUTH_URL_HINT);
+        }
         return 1;
     }
     const envUrl = (env.BIR_AUTH_URL ?? "").replace(/\/+$/, "");
@@ -107,7 +143,7 @@ export async function runSetup(args, deps) {
         err(`BIR_AUTH_URL in this environment is ${envUrl}, but ${args.authUrl ? "this sets up" : "the stored address is"} ${args.authUrl ? baseUrl : storedUrl}.`);
         err("Remove that variable (check your shell profile), or the recorder will not record.");
     }
-    const project = resolvePath(args.project ?? process.cwd());
+    const project = canonicalProject(args.project ?? process.cwd());
     if (!existsSync(project) || !statSync(project).isDirectory()) {
         err(`Project directory not found: ${project}`);
         return 1;
@@ -185,6 +221,33 @@ export async function runSetup(args, deps) {
     }
     // ── 4. the project ───────────────────────────────────────────────────────
     chdir(project);
+    if (!args.portExplicit) {
+        // A port chosen at the first install is kept on later ones — the hooks name
+        // it — but this machine may no longer let it be bound: Hyper-V, WSL and
+        // Docker reserve blocks inside the dynamic range, and those move across
+        // reboots. A recorder told to use it exits, and every hook of every session
+        // then fails. Setup is the upgrade and repair path, so it moves the project
+        // to a free port and lets install rewrite the hooks and entries with it —
+        // unless the port is busy because THIS project's recorder is on it.
+        const sidecar = readSidecar();
+        const recorded = projectRecord(sidecar, project);
+        if (recorded) {
+            // Age does not matter here, only a live pid: a recorder whose file went
+            // stale over a long sleep (or an older runner's, whose heartbeat is
+            // slower) still holds the port, and moving away from it would leave
+            // two recorders and hooks pointing at the new one.
+            const ours = readDiscovery(project, { ignoreAge: true });
+            const heldByUs = Boolean(ours && pidAlive(ours.pid) && ours.url.endsWith(`:${recorded.port}`));
+            if (!heldByUs && !(await probeFreePort(recorded.port))) {
+                const next = await allocateReplacementPort(sidecar, project, recorded.port);
+                if (next !== undefined) {
+                    setProjectRecord(sidecar, project, { port: next });
+                    writeSidecar(sidecar);
+                    out(`    port ${recorded.port} is not available on this machine; this project moves to ${next}`);
+                }
+            }
+        }
+    }
     if (args.allowServers !== undefined) {
         // Stored before install so the recorder started below reads it at start.
         const sidecar = readSidecar();
@@ -202,11 +265,17 @@ export async function runSetup(args, deps) {
     if (args.daemon) {
         out("==> Starting the recorder in the background");
         try {
-            ensured = await ensureDaemon(project, {
+            // probeIdle: a recorder too old to say whether its "open" turn is real
+            // (0.2.12 never closes an interrupted one) is replaced when two /health
+            // probes a few seconds apart show it idle (control/daemon.ts). Setup has
+            // the time; the SessionStart hook does not ask for it.
+            const ensureOpts = {
                 hooksScript: deps.hooksScript,
                 env,
                 restartOnSkew: true,
-            });
+                probeIdle: true,
+            };
+            ensured = await ensureDaemon(project, ensureOpts);
             if (!ensured.started &&
                 ensured.status.health.recording === false &&
                 activeSessions(ensured.status.health) === 0) {
@@ -219,6 +288,36 @@ export async function runSetup(args, deps) {
                 ensured = await ensureDaemon(project, { hooksScript: deps.hooksScript, env });
                 ensured = { ...ensured, restarted: true };
             }
+            const port = projectRecord(readSidecar(), project)?.port;
+            if (port !== undefined &&
+                !ensured.status.info.url.endsWith(`:${port}`) &&
+                activeSessions(ensured.status.health) === 0) {
+                // A recorder still on the port this project had before (moved above,
+                // or by `--port`): the hooks now post to the new one, so it would
+                // receive nothing. Nothing is mid-run; replace it.
+                out(`    the running recorder is on ${ensured.status.info.url}, not port ${port}; replacing it`);
+                await stopDaemon(project);
+                ensured = await ensureDaemon(project, { hooksScript: deps.hooksScript, env });
+                ensured = { ...ensured, restarted: true };
+            }
+            // The replay switch is read once, when a recorder starts: one started
+            // before this setup turned replay off (--no-replay) or on would go on
+            // doing what it did. `source: "env"` is BIR_REPLAY where it started,
+            // which outranks the switch — a restart from here would not carry it.
+            const wantReplay = projectRecord(readSidecar(), project)?.replay?.enabled !== false;
+            const running = ensured.status.health.replay;
+            if (typeof running?.enabled === "boolean" && running.enabled !== wantReplay && running.source !== "env") {
+                if (activeSessions(ensured.status.health) === 0) {
+                    out(`    the running recorder has replay ${running.enabled ? "on" : "off"}; replacing it`);
+                    await stopDaemon(project);
+                    ensured = await ensureDaemon(project, { hooksScript: deps.hooksScript, env });
+                    ensured = { ...ensured, restarted: true };
+                }
+                else {
+                    out(`    the running recorder keeps replay ${running.enabled ? "on" : "off"} for the session open now; ` +
+                        "`bir up --restart` once it ends applies the change");
+                }
+            }
         }
         catch (e) {
             err(`the recorder did not start: ${errText(e)}`);
@@ -227,40 +326,67 @@ export async function runSetup(args, deps) {
         }
     }
     // ── 6. the summary ───────────────────────────────────────────────────────
-    const wrapped = resolveServers(project)
-        .filter((s) => s.name !== SCENARIO_SERVER_KEY && isWrapped(s.config))
-        .map((s) => s.name);
+    const live = resolveServers(project).filter((s) => s.name !== SCENARIO_SERVER_KEY);
+    const wrapped = live.filter((s) => isWrapped(s.config)).map((s) => s.name);
+    // Servers install left as Claude Code runs them (not approved there yet, a
+    // remote it signs in itself, …) are still here: "no MCP servers" would lie.
+    const unwrapped = live.filter((s) => !isWrapped(s.config)).map((s) => s.name);
     const health = ensured?.status.health;
     const replay = health?.replay;
     const recording = health ? health.recording !== false : undefined;
     const policy = projectRecord(readSidecar(), project)?.replay;
     const allow = replay?.allowServers ?? policy?.allowServers ?? null;
+    // The stored switch, which every recorder here reads at start — unless the
+    // one that answered was started with BIR_REPLAY, which outranks it.
+    const replayOn = replay?.source === "env" ? replay.enabled !== false : policy?.enabled !== false;
     out();
-    out(`Done. Recording${args.replay ? " and replay are" : " is"} on for ${project}`);
+    out(`Done. Recording${args.replay && replayOn ? " and replay are" : " is"} on for ${project}`);
+    // The kill switch outranks all of it, and setup leaves it as the person set
+    // it: turning the runner back on is theirs to decide, not an upgrade's.
+    const off = offSource(project);
+    if (off) {
+        out(`  !! but the runner is OFF (${off === "env" ? "BIR_OFF=1 in this environment" : off === "global" ? "`bir off`, every project" : "`bir off --here`"}): nothing is recorded or replayed until \`bir on${off === "project" ? " --here" : ""}\``);
+    }
     out(`  account    ${session.user.email}  (${baseUrl})`);
-    out(`  wrapped    ${wrapped.length ? wrapped.join(", ") : "(no MCP servers here)"}`);
+    out(`  wrapped    ${wrapped.length ? wrapped.join(", ") : unwrapped.length ? `(none — ${unwrapped.join(", ")} left as they are, see above)` : "(no MCP servers here)"}`);
     if (!args.replay) {
-        out("  replay     not installed (--no-replay)");
+        const scenarioLeft = resolveServers(project).some((s) => s.name === SCENARIO_SERVER_KEY && isScenarioServer(s.config));
+        out(replayOn
+            ? "  replay     ON despite --no-replay: BIR_REPLAY is set where the recorder started"
+            : `  replay     off (--no-replay) — \`bir replay on\` turns it on${scenarioLeft ? "; the scenario server an earlier setup added stays (`bir uninstall --replay` removes it)" : ""}`);
+    }
+    else if (!replayOn) {
+        out(replay?.source === "env"
+            ? "  replay     off — BIR_REPLAY=0 where the recorder started"
+            : "  replay     off here (`bir replay off`) — `bir replay on` turns it on");
     }
     else if (wrapped.length === 0) {
-        out("  replay     steer mode only — no MCP servers wrapped here; add a .mcp.json and run `bir setup` again for direct replay");
+        out(unwrapped.length
+            ? "  replay     steer mode only — none of this project's MCP servers is wrapped (why is above); `bir setup` again once one can be, for direct replay"
+            : "  replay     steer mode only — no MCP servers wrapped here; add a .mcp.json and run `bir setup` again for direct replay");
     }
     else {
-        const on = replay ? replay.enabled !== false : policy?.enabled !== false;
-        out(`  replay     ${on ? "on" : "off"} — direct execution allowed for: ${allow?.length ? allow.join(", ") : `all wrapped (narrow it with \`bir replay allow ${wrapped[0]}\`)`}`);
+        out(`  replay     on — direct execution allowed for: ${allow?.length ? allow.join(", ") : `all wrapped (narrow it with \`bir replay allow ${wrapped[0]}\`)`}`);
     }
     if (ensured) {
         const { info, health: h } = ensured.status;
         const theirs = String(h.hooksVersion ?? info.version ?? "");
         out(`  recorder   ${ensured.started ? (ensured.restarted ? "restarted" : "started") : "already running"} in the background (pid ${info.pid})` +
             " — it starts itself with every Claude Code session");
-        if (theirs && theirs !== packageVersion()) {
-            out(`             recorder ${theirs} is still serving an open Claude Code session; it restarts to ${packageVersion()} with the next session`);
+        // Only for an OLDER recorder: a newer one is kept on purpose
+        // (daemon.newer_kept) and nothing about it waits on a restart.
+        if (theirs && compareVersions(theirs, packageVersion()) === -1) {
+            // Said as it is: nothing replaces it by itself while that session runs —
+            // the next session's start keeps it too, as long as it reports a turn
+            // open — and until it is replaced it behaves as ${theirs} does (0.2.12:
+            // approves every wrapped MCP call, ignores `bir off`).
+            out(`             it is still ${theirs}, serving a Claude Code session that is mid-turn; it keeps running as ${theirs} ` +
+                `until \`bir up --restart\` (run it once that session ends) replaces it with ${packageVersion()}`);
         }
         if (info.logFile)
             out(`  log        ${info.logFile}`);
         if (recording === false) {
-            out("  !! the recorder has no session to record with — run `bir login`, then `bir up --restart`");
+            out("  !! the recorder has no session to record with — run `bir login`; it starts recording by itself after that");
         }
     }
     else {
@@ -280,7 +406,7 @@ export async function runSetup(args, deps) {
     out('  first time in this folder: say Yes to "trust this folder"');
     out("  just installed Claude Code? it asks you to sign in to Claude (it needs a Claude subscription)");
     out(`  give it a task that takes 4+ tool calls — it appears ${console_ ? `at ${console_}/recordings` : "in the console's Recordings"} within a minute of finishing`);
-    out("Any time:  bir doctor     bir investigate     bir down (stop)     bir uninstall (undo)");
+    out("Any time:  bir doctor     bir investigate     bir off (out of the way, at once)     bir uninstall (undo)");
     return recording === false ? 1 : 0;
 }
 //# sourceMappingURL=setup.js.map

package/dist/config/adapters/claude-code.d.ts

@@ -7,11 +7,18 @@
  * runs. `resolveServers` reports the winner; this module writes there and warns
  * loudly when a lower scope also defines the name.
  *
- * Byte-for-byte reversibility: the *text* of every file touched is stashed before
- * the first edit, together with a hash of what we wrote. On uninstall, a file
- * still matching that hash is restored verbatim; a file edited since is repaired
- * entry-by-entry instead, with a warning. That is the difference between "we put
- * the entries back" and "the file is as you left it".
+ * Byte-for-byte reversibility: the *text* of every project file touched is
+ * stashed before the first edit, together with a hash of what we wrote. On
+ * uninstall, a file still matching that hash — and not changed by anybody else
+ * between two of our writes — is restored verbatim; a file edited since is
+ * repaired entry-by-entry instead, with a warning. `~/.claude.json` is always
+ * repaired entry by entry: it is Claude Code's own, rewritten constantly, and
+ * holds every project's settings.
+ *
+ * Where the wrapped entries go (bir.ts, install): the LOCAL scope, as an
+ * override of the same name — never the team's `.mcp.json`, which gets
+ * committed and would carry this machine's node and runner paths to every
+ * clone, and never the user scope, which applies to every project.
  */
 import { type McpServerConfig, type Scope } from "../resolve.js";
 export interface ClaudeCodePaths {
@@ -42,12 +49,21 @@ export declare const LOCAL_SETTINGS_EXCLUDE = ".claude/settings.local.json";
  * `.git/info/exclude`, never `.gitignore`: the first is the person's own,
  * untracked list; the second is a file the team owns and would see in a diff.
  * Walks up from `dir` to find the repository, follows a worktree's `gitdir:`
- * pointer, and appends the line once. Returns the exclude file's path when the
+ * pointer to the repository's common git directory (the only exclude file git
+ * reads for a linked worktree), and appends the line once. Returns the exclude file's path when the
  * line is there (added or already present), undefined outside a repository or
  * when the file could not be written — an exclude that fails is a note, not a
  * failed install.
  */
 export declare function ensureGitExclude(dir: string, line?: string): string | undefined;
+/**
+ * {@link ensureGitExclude}, also saying whether the line was ADDED now (false:
+ * it was already there — somebody's own, which uninstall must leave alone).
+ */
+export declare function ensureGitExcludeLine(dir: string, line?: string): {
+    path: string;
+    added: boolean;
+} | undefined;
 /** Undo {@link ensureGitExclude}: drop the line, leave everything else. */
 export declare function removeGitExclude(dir: string, line?: string): string | undefined;
 /**
@@ -68,6 +84,28 @@ export declare function fileForScope(scope: Scope, paths: ClaudeCodePaths): stri
 export declare function sha256(text: string): string;
 /** Read a file's text, or null when it does not exist. */
 export declare function readTextOrNull(path: string): string | null;
+/**
+ * Read-modify-write one JSON file, safely:
+ *
+ *   - a file that is not plain JSON (comments, trailing commas, a torn write)
+ *     is REFUSED with an error naming it, never rewritten from a guess;
+ *   - the file is re-read just before the write, and the edit is applied again
+ *     to the fresh text when somebody else changed it in between (Claude Code
+ *     rewrites `~/.claude.json` constantly, and a lost update there loses a
+ *     server the user just added, or ours);
+ *   - the write itself is atomic (util/atomic-write.ts), so Claude Code never
+ *     reads a half-written config, and a symlinked file stays a symlink.
+ *
+ * `mutate` gets a fresh parse each attempt and must not keep state between
+ * calls. Returns the text written, for the sidecar's hash.
+ */
+export declare function editJson(path: string, mutate: (parsed: Record<string, unknown>) => void): string;
+/**
+ * Throw (naming the file) when `path` exists and is not a plain JSON object —
+ * so an install can refuse up front, before it has written anything, instead
+ * of stopping halfway through with some files changed and others not.
+ */
+export declare function assertEditableJson(path: string): void;
 /**
  * Set (or delete, with `entry === null`) one MCP server entry in `scope`.
  * Returns the file's new text so the caller can hash it for the sidecar.
@@ -76,6 +114,17 @@ export declare function setServerEntry(scope: Scope, cwd: string, name: string,
     file: string;
     text: string;
 };
+/**
+ * Set (or delete) one entry of the local scope under each of `keys` in
+ * `~/.claude.json`, in ONE atomic edit. `shouldTouch` sees the entry currently
+ * under a key (or undefined) and may veto that key — so a user's own entry
+ * under another spelling of the project is never overwritten or deleted.
+ * Returns the text written and the keys actually changed (none: no write).
+ */
+export declare function setLocalEntries(claudeJson: string, keys: string[], name: string, entry: McpServerConfig | null, shouldTouch?: (current: McpServerConfig | undefined) => boolean): {
+    text?: string;
+    keys: string[];
+};
 /**
  * The hook events `bir-hooks` registers, and the control route each drives.
  *
@@ -84,6 +133,17 @@ export declare function setServerEntry(scope: Scope, cwd: string, name: string,
  * only listens to the success one records a step that never closes.
  * `SubagentStart` / `SubagentStop` carry `agent_id`, which is what lets a
  * subagent's steps be attributed rather than silently interleaved.
+ *
+ * THE TIMEOUTS ARE THE USER'S WORST CASE. Claude Code waits for a hung hook up
+ * to its `timeout`, so each number here is how long a slow or blackholed
+ * service could make a person wait — at every prompt, every tool call, every
+ * `/exit`. The control server keeps its own per-route deadlines well inside
+ * them (prompt ≤ 7 s, tool/pre ≤ 12 s, tool/post and stop ≤ 2 s, end ≤ 1 s,
+ * start ≤ 2 s) and answers `{}` on overrun, so these are the second line of
+ * defence, not a budget to spend. SessionEnd matters twice: Claude Code's own
+ * default for it is 1.5 s, and whatever is written here RAISES that — the 30 it
+ * used to be turned every `/exit` during a service incident into a 30 s wait.
+ * A re-run of `bir setup` rewrites existing installs with these.
  */
 export declare const HOOK_ROUTES: Array<{
     event: string;
@@ -121,8 +181,12 @@ export type HooksBlock = Record<string, Array<{
  * Exported so the binary and the adapter cannot drift apart on the spelling.
  */
 export declare const ENSURE_ARG = "ensure";
-/** How long SessionStart may wait for a background recorder to come up. */
-export declare const ENSURE_TIMEOUT_S = 30;
+/**
+ * How long SessionStart may wait for a background recorder to come up. The
+ * ensure hook keeps its own budget at 12 s or less and always exits 0; this is
+ * the host's ceiling on top of it.
+ */
+export declare const ENSURE_TIMEOUT_S = 15;
 export interface HooksBlockOptions {
     /**
      * Make SessionStart start the recorder itself when none is running.
@@ -134,27 +198,41 @@ export interface HooksBlockOptions {
      * **replaced**, not added to. Hooks for one event run in parallel, and an
      * HTTP hook racing the daemon it depends on would fail every first session.
      *
-     * Omitted for an npx invocation: resolving a package inside a hook is too
-     * slow to start a recorder from, so those installs keep the HTTP hook and a
-     * recorder someone started.
+     * The `{ command, args }` form is an already-built exec-form invocation —
+     * what an npx install uses (`npx --prefer-offline -y -p <spec> bir-hooks
+     * ensure`, in `cmd /c` on Windows). It pays npx's start-up once per session,
+     * which is affordable there and not per tool call; without it nothing ever
+     * starts the recorder of an npx install, and every hook of every session
+     * fails against a port nobody listens on.
      */
     ensure?: {
         node: string;
         hooksScript: string;
         nodeFlags?: string[];
+    } | {
+        command: string;
+        args: string[];
     };
 }
 /** Build the 'hooks' block pointing at a control server. */
 export declare function buildHooksBlock(controlUrl: string, token: string, opts?: HooksBlockOptions): HooksBlock;
 /**
- * True when a hook entry is one of ours: an HTTP hook aimed at a control-server
- * route, or the exec-form command hook that starts the recorder.
+ * True when a hook entry is one of ours, and only then — install and uninstall
+ * delete what this says is ours, so a false positive deletes somebody's hook.
+ *
+ *   HTTP: a loopback URL (127.0.0.1 / localhost / [::1]) whose path is exactly
+ *         one of our routes, AND either our kind of bearer token or a port in
+ *         the range `bir` allocates (the token-less 0.2.8 shape). A hook to
+ *         `https://hooks.example.com/session/end` is somebody else's.
+ *   exec: our self-starting SessionStart hook — `bir-hooks.js ensure`, or the
+ *         npx form `… -p @basein/runner@<v> bir-hooks ensure`.
  */
 export declare function isBirHook(entry: unknown): boolean;
 /**
  * Merge our hooks into a settings file, leaving every other hook alone. Returns
  * the new text. Our own entries are replaced rather than appended, so repeated
- * installs stay idempotent.
+ * installs stay idempotent — hook by hook: a user's own hook that happens to
+ * share a matcher group with one of ours stays exactly where it is.
  */
 export declare function installHooks(settingsPath: string, block: HooksBlock): string;
 /** Remove only our hook entries, and drop events left empty. */