@basein/runner 0.2.7 → 0.2.10

package/dist/config/adapters/claude-code.js

@@ -14,16 +14,135 @@
  * the entries back" and "the file is as you left it".
  */
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, parse as parsePath } from "node:path";
 import { claudeJsonPath, parseJsonFile, projectKeyFor } from "../resolve.js";
 export function claudeCodePaths(cwd, claudeJsonOverride) {
     return {
         claudeJson: claudeJsonPath(claudeJsonOverride),
         mcpJson: join(cwd, ".mcp.json"),
         settings: join(cwd, ".claude", "settings.json"),
+        settingsLocal: join(cwd, ".claude", "settings.local.json"),
     };
 }
+/** The line `bir` adds to a repository's exclude file. */
+export const LOCAL_SETTINGS_EXCLUDE = ".claude/settings.local.json";
+/**
+ * Keep `.claude/settings.local.json` out of version control, the way Claude
+ * Code does when *it* creates the file — it only does so for files it wrote.
+ *
+ * `.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
+ * 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 function ensureGitExclude(dir, line = LOCAL_SETTINGS_EXCLUDE) {
+    let gitDir;
+    let current = dir;
+    for (;;) {
+        const candidate = join(current, ".git");
+        if (existsSync(candidate)) {
+            try {
+                if (statSync(candidate).isDirectory()) {
+                    gitDir = candidate;
+                }
+                else {
+                    // A worktree or submodule: `.git` is a file naming the real directory.
+                    const pointer = readFileSync(candidate, "utf8").match(/^gitdir:\s*(.+)$/m)?.[1]?.trim();
+                    if (pointer)
+                        gitDir = join(current, pointer);
+                }
+            }
+            catch {
+                /* unreadable — treat as no repository */
+            }
+            break;
+        }
+        const parent = dirname(current);
+        if (parent === current || parsePath(current).root === current)
+            break;
+        current = parent;
+    }
+    if (!gitDir)
+        return undefined;
+    try {
+        const infoDir = join(gitDir, "info");
+        mkdirSync(infoDir, { recursive: true });
+        const exclude = join(infoDir, "exclude");
+        const existing = existsSync(exclude) ? readFileSync(exclude, "utf8") : "";
+        const lines = existing.split(/\r?\n/).map((l) => l.trim());
+        if (!lines.includes(line)) {
+            const sep = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+            appendFileSync(exclude, `${sep}${line}\n`);
+        }
+        return exclude;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Undo {@link ensureGitExclude}: drop the line, leave everything else. */
+export function removeGitExclude(dir, line = LOCAL_SETTINGS_EXCLUDE) {
+    const exclude = ensureGitExclude(dir, line); // finds the file (and would add the line, which is there)
+    if (!exclude)
+        return undefined;
+    try {
+        const kept = readFileSync(exclude, "utf8")
+            .split(/\r?\n/)
+            .filter((l) => l.trim() !== line);
+        const text = kept.join("\n").replace(/\n+$/, "");
+        writeFileSync(exclude, text ? `${text}\n` : "");
+        return exclude;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Pre-approve project-scoped MCP servers by name (`enabledMcpjsonServers`).
+ *
+ * Claude Code asks before it uses a server from `.mcp.json`, and a "No" there
+ * silently leaves a direct replay with nowhere to deliver its results. The
+ * runner's own scenario server is approved here, in the person's local
+ * settings, so the question is never asked. Returns the file's new text.
+ */
+export function enableMcpjsonServers(settingsPath, names) {
+    const parsed = parseJsonFile(settingsPath) ?? {};
+    const current = Array.isArray(parsed.enabledMcpjsonServers)
+        ? parsed.enabledMcpjsonServers.map(String)
+        : [];
+    parsed.enabledMcpjsonServers = [...new Set([...current, ...names])];
+    return writeJson(settingsPath, parsed);
+}
+/** Undo {@link enableMcpjsonServers} for `names`; drops the key when empty. */
+export function disableMcpjsonServers(settingsPath, names) {
+    const parsed = parseJsonFile(settingsPath);
+    if (!parsed || !Array.isArray(parsed.enabledMcpjsonServers))
+        return undefined;
+    const kept = parsed.enabledMcpjsonServers.map(String).filter((n) => !names.includes(n));
+    if (kept.length === 0)
+        delete parsed.enabledMcpjsonServers;
+    else
+        parsed.enabledMcpjsonServers = kept;
+    return writeJson(settingsPath, parsed);
+}
+/** True when `settingsPath` holds any hook of ours. */
+export function hasBirHooks(settingsPath) {
+    let parsed;
+    try {
+        parsed = parseJsonFile(settingsPath);
+    }
+    catch {
+        return false;
+    }
+    const hooks = parsed?.hooks;
+    if (!hooks)
+        return false;
+    return Object.values(hooks).some((matchers) => (matchers ?? []).some((m) => (m.hooks ?? []).some((h) => isBirHook(h))));
+}
 /** Which file holds a given scope's `mcpServers` for this cwd. */
 export function fileForScope(scope, paths) {
     switch (scope) {
@@ -120,27 +239,56 @@ export const HOOK_ROUTES = [
     // that is actually finished is worth a few hundred milliseconds at shutdown.
     { event: "SessionEnd", route: "/session/end", matcher: "", timeout: 30 },
 ];
-/** Build the `hooks` block pointing at a control server. */
-export function buildHooksBlock(controlUrl, token) {
+/**
+ * The argument that makes a 'bir-hooks' invocation the SessionStart hook.
+ * Exported so the binary and the adapter cannot drift apart on the spelling.
+ */
+export const ENSURE_ARG = "ensure";
+/** How long SessionStart may wait for a background recorder to come up. */
+export const ENSURE_TIMEOUT_S = 30;
+/** Build the 'hooks' block pointing at a control server. */
+export function buildHooksBlock(controlUrl, token, opts = {}) {
     const base = controlUrl.replace(/\/+$/, "");
     const block = {};
     for (const { event, route, matcher, timeout, async } of HOOK_ROUTES) {
-        const hook = {
-            type: "http",
-            url: `${base}${route}`,
-            timeout,
-            headers: { Authorization: `Bearer ${token}` },
-        };
-        if (async)
-            hook.async = true;
+        let hook;
+        if (event === "SessionStart" && opts.ensure) {
+            hook = {
+                type: "command",
+                command: opts.ensure.node,
+                args: [...(opts.ensure.nodeFlags ?? []), opts.ensure.hooksScript, ENSURE_ARG],
+                timeout: ENSURE_TIMEOUT_S,
+            };
+        }
+        else {
+            const http = {
+                type: "http",
+                url: `${base}${route}`,
+                timeout,
+                headers: { Authorization: `Bearer ${token}` },
+            };
+            if (async)
+                http.async = true;
+            hook = http;
+        }
         block[event] = [{ matcher: matcher ?? "", hooks: [hook] }];
     }
     return block;
 }
-/** True when a hook entry points at a BaseInstRunner control server. */
-function isBirHook(entry) {
-    const url = entry.url ?? "";
-    return HOOK_ROUTES.some(({ route }) => url.endsWith(route));
+/**
+ * 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.
+ */
+export function isBirHook(entry) {
+    const e = entry;
+    const url = e.url ?? "";
+    if (HOOK_ROUTES.some(({ route }) => url.endsWith(route)))
+        return true;
+    if (Array.isArray(e.args)) {
+        const args = e.args.map(String);
+        return args.some((a) => /[\\/]bir-hooks\.js$/.test(a)) && args.includes(ENSURE_ARG);
+    }
+    return false;
 }
 /**
  * Merge our hooks into a settings file, leaving every other hook alone. Returns

package/dist/config/generate.d.ts

@@ -60,7 +60,21 @@ export interface WrapOptions {
     proxyPath?: string;
     /** Pins the npx spec. Omitted only by tests that do not care which version. */
     version?: string;
+    /**
+     * Node flags written in front of the script for `local` and `global`
+     * entries — `--use-system-ca` on a network that inspects TLS, so the proxies
+     * trust what the install did (see {@link nodeFlagsToCarry}).
+     */
+    nodeFlags?: string[];
 }
+/**
+ * The node flags this process was started with that everything it sets up
+ * should share. The install scripts run `bir setup` with `--use-system-ca`
+ * when the Node supports it; a hook, a proxy or a recorder started without it
+ * would then fail the first TLS-inspected upload while the install itself
+ * succeeded.
+ */
+export declare function nodeFlagsToCarry(execArgv?: string[]): string[];
 /** A wrapped entry is always a stdio entry: the proxy is the process the host spawns. */
 export interface WrappedEntry {
     command: string;
@@ -84,6 +98,7 @@ export declare function scenarioEntry(opts: {
     scenarioPath?: string;
     controlUrl?: string;
     version?: string;
+    nodeFlags?: string[];
 }): WrappedEntry;
 /** True when this entry is the scenario server — makes `install --replay` idempotent. */
 export declare function isScenarioServer(config: McpServerConfig): boolean;
@@ -108,12 +123,58 @@ export interface FileBackup {
     originalText: string | null;
     writtenSha: string;
 }
+/**
+ * The replay switches an operator set for one project, kept where a recorder
+ * started by a hook can read them. They used to be environment variables read
+ * by `bir-hooks` at start — which was fine while a person started it in a
+ * terminal, and silently reset an allow-list to "(all wrapped)" the first time
+ * the SessionStart hook started it with Claude Code's environment instead.
+ */
+export interface ReplayPolicy {
+    /** `bir replay off` → false. Absent means on. */
+    enabled?: boolean;
+    /** Server keys eligible for direct execution. Absent means every wrapped one. */
+    allowServers?: string[];
+    /** `BIR_MIN_STEER_SIMILARITY`'s stored twin. */
+    minSimilarity?: number;
+}
+/** What `bir install` decided for one project directory. */
+export interface ProjectRecord {
+    /** The control-server port written into this project's hook URLs. */
+    port: number;
+    /**
+     * This project's loopback bearer token. One per project, so a token in one
+     * project's settings file opens that project's recorder and no other. A
+     * record without one (written by 0.2.8) falls back to the machine-wide
+     * {@link InstalledSidecar.token}.
+     */
+    token?: string;
+    /** Replay switches for this project; see {@link ReplayPolicy}. */
+    replay?: ReplayPolicy;
+    /**
+     * How the entries were generated last time (`global`, `local` or `npx`), so
+     * a later install with neither flag keeps the same shape instead of turning
+     * a fleet's absolute paths into pinned-npx entries.
+     */
+    invocation?: Invocation;
+}
 export interface InstalledSidecar {
     version: 1;
     /** Stable loopback token written into the hook settings at install time. */
     token?: string;
-    /** Port the hook settings were written with. */
+    /**
+     * Port the most recent install wrote. Kept for a `bir-hooks` older than
+     * {@link InstalledSidecar.projects}; new code reads the per-project record.
+     */
     controlPort?: number;
+    /**
+     * Per-project decisions, keyed by the normalised directory. Two projects
+     * recorded at once used to share port 53411: the second control server fell
+     * back to an ephemeral port while both projects' hooks kept posting to the
+     * first, so one project's steps landed in the other's run. Each project now
+     * gets its own port, chosen once and reused.
+     */
+    projects?: Record<string, ProjectRecord>;
     /** `<cwd>::<serverName>` → record. */
     servers: Record<string, InstalledRecord>;
     /** Absolute path → the text that was there before we touched it. */
@@ -124,4 +185,35 @@ export interface InstalledSidecar {
 export declare function readSidecar(): InstalledSidecar;
 export declare function writeSidecar(sidecar: InstalledSidecar): void;
 export declare function sidecarKey(cwd: string, serverName: string): string;
+/** The lowest port a project is given when none was asked for. */
+export declare const FIRST_PROJECT_PORT = 53411;
+/** This project's record, if an install has decided anything for it. */
+export declare function projectRecord(sidecar: InstalledSidecar, cwd: string): ProjectRecord | undefined;
+/**
+ * The port this project's hooks and control server should agree on.
+ *
+ * A port already chosen for this directory is kept — moving it would orphan
+ * the URLs in `settings.json`. Otherwise the lowest port from
+ * {@link FIRST_PROJECT_PORT} upward that no *other* project holds, so the first
+ * project on a machine keeps the documented default and the second one does not
+ * collide with it. Deterministic, so re-running install changes nothing.
+ */
+export declare function allocateProjectPort(sidecar: InstalledSidecar, cwd: string): number;
+/** True when nothing on this machine is bound to `port` on the loopback address. */
+export declare function probeFreePort(port: number): Promise<boolean>;
+/**
+ * {@link allocateProjectPort}, but a port nobody else already holds.
+ *
+ * The sidecar only knows about our own projects. 53411 sits in the dynamic
+ * range on every OS and inside the blocks Hyper-V and WSL reserve on Windows,
+ * so "unused by another project" is not "free": a recorder told to use a port
+ * the system has excluded exits, and every session records Tier 2 until
+ * somebody reads the log. A port that has been recorded for this project is
+ * kept as it is — the hooks name it — and the recorder says so if it is busy.
+ */
+export declare function allocateFreeProjectPort(sidecar: InstalledSidecar, cwd: string): Promise<number>;
+/** Merge `patch` into the record for `cwd`, creating it when absent. */
+export declare function setProjectRecord(sidecar: InstalledSidecar, cwd: string, patch: Partial<ProjectRecord> & Pick<ProjectRecord, "port">): ProjectRecord;
+/** The bearer token this project's hooks and control server share. */
+export declare function projectToken(sidecar: InstalledSidecar, cwd: string): string | undefined;
 //# sourceMappingURL=generate.d.ts.map

package/dist/config/generate.js

@@ -12,7 +12,8 @@
  * BaseInstRunner never understood.
  */
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { configDir, ensureDir, installedPath } from "../control/paths.js";
+import { createServer } from "node:net";
+import { configDir, ensureDir, installedPath, normalizePath } from "../control/paths.js";
 import { isRemote } from "./resolve.js";
 /** npm package name, as it appears in a generated `npx -p` invocation. */
 export const PACKAGE_NAME = "@basein/runner";
@@ -31,6 +32,16 @@ export function packageSpec(version) {
  * model, and a collision would route that call somewhere else entirely.
  */
 export const SCENARIO_SERVER_KEY = "bir";
+/**
+ * The node flags this process was started with that everything it sets up
+ * should share. The install scripts run `bir setup` with `--use-system-ca`
+ * when the Node supports it; a hook, a proxy or a recorder started without it
+ * would then fail the first TLS-inspected upload while the install itself
+ * succeeded.
+ */
+export function nodeFlagsToCarry(execArgv = process.execArgv) {
+    return execArgv.filter((a) => a === "--use-system-ca");
+}
 /** True when this entry already points at `bir-proxy` — makes install idempotent. */
 export function isWrapped(config) {
     if (isRemote(config))
@@ -68,7 +79,7 @@ export function wrapEntry(config, opts) {
     }
     const invocation = opts.invocation ?? "npx";
     const entry = invocation !== "npx" && opts.proxyPath
-        ? { command: process.execPath, args: [opts.proxyPath, ...proxyArgs] }
+        ? { command: process.execPath, args: [...(opts.nodeFlags ?? []), opts.proxyPath, ...proxyArgs] }
         : { command: "npx", args: ["-y", "-p", packageSpec(opts.version), "bir-proxy", ...proxyArgs] };
     if (Object.keys(env).length > 0)
         entry.env = env;
@@ -80,7 +91,7 @@ export function wrapEntry(config, opts) {
  */
 export function scenarioEntry(opts) {
     const entry = opts.invocation && opts.invocation !== "npx" && opts.scenarioPath
-        ? { command: process.execPath, args: [opts.scenarioPath] }
+        ? { command: process.execPath, args: [...(opts.nodeFlags ?? []), opts.scenarioPath] }
         : { command: "npx", args: ["-y", "-p", packageSpec(opts.version), "bir-scenario"] };
     if (opts.controlUrl)
         entry.env = { BIR_CONTROL_URL: opts.controlUrl };
@@ -111,4 +122,80 @@ export function writeSidecar(sidecar) {
 export function sidecarKey(cwd, serverName) {
     return `${cwd}::${serverName}`;
 }
+/** The lowest port a project is given when none was asked for. */
+export const FIRST_PROJECT_PORT = 53411;
+/** This project's record, if an install has decided anything for it. */
+export function projectRecord(sidecar, cwd) {
+    return sidecar.projects?.[normalizePath(cwd)];
+}
+/**
+ * The port this project's hooks and control server should agree on.
+ *
+ * A port already chosen for this directory is kept — moving it would orphan
+ * the URLs in `settings.json`. Otherwise the lowest port from
+ * {@link FIRST_PROJECT_PORT} upward that no *other* project holds, so the first
+ * project on a machine keeps the documented default and the second one does not
+ * collide with it. Deterministic, so re-running install changes nothing.
+ */
+export function allocateProjectPort(sidecar, cwd) {
+    const mine = projectRecord(sidecar, cwd);
+    if (mine)
+        return mine.port;
+    const key = normalizePath(cwd);
+    const taken = new Set(Object.entries(sidecar.projects ?? {})
+        .filter(([k]) => k !== key)
+        .map(([, r]) => r.port));
+    let port = FIRST_PROJECT_PORT;
+    while (taken.has(port))
+        port += 1;
+    return port;
+}
+/** True when nothing on this machine is bound to `port` on the loopback address. */
+export function probeFreePort(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", () => resolve(false));
+        server.listen(port, "127.0.0.1", () => {
+            server.close(() => resolve(true));
+        });
+    });
+}
+/**
+ * {@link allocateProjectPort}, but a port nobody else already holds.
+ *
+ * The sidecar only knows about our own projects. 53411 sits in the dynamic
+ * range on every OS and inside the blocks Hyper-V and WSL reserve on Windows,
+ * so "unused by another project" is not "free": a recorder told to use a port
+ * the system has excluded exits, and every session records Tier 2 until
+ * somebody reads the log. A port that has been recorded for this project is
+ * kept as it is — the hooks name it — and the recorder says so if it is busy.
+ */
+export async function allocateFreeProjectPort(sidecar, cwd) {
+    const mine = projectRecord(sidecar, cwd);
+    if (mine)
+        return mine.port;
+    const key = normalizePath(cwd);
+    const taken = new Set(Object.entries(sidecar.projects ?? {})
+        .filter(([k]) => k !== key)
+        .map(([, r]) => r.port));
+    for (let port = FIRST_PROJECT_PORT; port < FIRST_PROJECT_PORT + 200; port += 1) {
+        if (taken.has(port))
+            continue;
+        if (await probeFreePort(port))
+            return port;
+    }
+    return allocateProjectPort(sidecar, cwd);
+}
+/** Merge `patch` into the record for `cwd`, creating it when absent. */
+export function setProjectRecord(sidecar, cwd, patch) {
+    sidecar.projects ??= {};
+    const key = normalizePath(cwd);
+    const next = { ...(sidecar.projects[key] ?? {}), ...patch };
+    sidecar.projects[key] = next;
+    return next;
+}
+/** The bearer token this project's hooks and control server share. */
+export function projectToken(sidecar, cwd) {
+    return projectRecord(sidecar, cwd)?.token ?? sidecar.token;
+}
 //# sourceMappingURL=generate.js.map

package/dist/control/client.d.ts

@@ -50,6 +50,11 @@ export declare class ControlClient {
     /** Report one completed MCP call. Resolves false when the send was dropped. */
     report(step: ProxyStepReport): Promise<boolean>;
     health(): Promise<Record<string, unknown> | undefined>;
+    /**
+     * Ask the control server to shut down. Resolves true when it agreed; the
+     * exit itself follows once it has finished the run it was writing.
+     */
+    stop(): Promise<boolean>;
     /**
      * Park until the control server has a tool call for this proxy, or the hold
      * elapses (docs/calculatedReplay.md §16.2).

package/dist/control/client.js

@@ -29,6 +29,14 @@ export class ControlClient {
     async health() {
         return (await this.request("GET", "/health"));
     }
+    /**
+     * Ask the control server to shut down. Resolves true when it agreed; the
+     * exit itself follows once it has finished the run it was writing.
+     */
+    async stop() {
+        const body = (await this.post("/control/stop", {}));
+        return body?.ok === true;
+    }
     /**
      * Park until the control server has a tool call for this proxy, or the hold
      * elapses (docs/calculatedReplay.md §16.2).

package/dist/control/daemon.d.ts

@@ -0,0 +1,116 @@
+/**
+ * daemon — the recorder as a background process nobody has to keep a window for.
+ *
+ * `bir-hooks` was designed to run in a terminal of its own, and every guide
+ * said "leave this running". That was the one step in the install a person
+ * could not be spared, and it was also the one they forgot: a session started
+ * without it records Tier 2 — tool calls only, no prompt, nothing to match a
+ * scenario against — and looks fine until the console shows a run with no
+ * prompt. This module removes the window.
+ *
+ * Three verbs, one file so they cannot disagree about where things are:
+ *
+ *   ensureDaemon(cwd)  the control server for `cwd`, started if there is none.
+ *                      Called by `bir up`, by `bir setup`, and by the
+ *                      SessionStart hook on every session, so a recorder that
+ *                      died or was never started is running by the first prompt.
+ *   stopDaemon(cwd)    `bir down`. Asks it to stop; kills it if it will not.
+ *   daemonStatus(cwd)  what `bir status` and `bir doctor` say about it.
+ *
+ * WHY THE HOOK STARTS IT, rather than a service manager. A Scheduled Task, a
+ * launchd agent and a systemd unit are three recipes for three platforms, each
+ * with a working directory that must equal the project's, each needing the
+ * person to know which one they are on. The hook already runs in the right
+ * directory with the right environment at exactly the right moment, and Claude
+ * Code already supervises it. What is lost is restart-on-crash mid-session,
+ * which the proxies already survive (they fall to Tier 2 and say so).
+ *
+ * HOW IT IS LAUNCHED. The daemon opens its own log file (`BIR_DAEMON_LOG`) and
+ * inherits nothing from our stdio. On POSIX that is a `detached` spawn with
+ * `stdio: "ignore"`, unref'd — the documented shape for a child that outlives
+ * its parent. On Windows it is `Start-Process -WindowStyle Hidden` inside a
+ * short-lived `powershell.exe`: libuv's CreateProcess inherits *every*
+ * inheritable handle of the parent, not only the three it was told about, and
+ * a node started under a PowerShell layer (the `irm | iex` bootstrap, a `.ps1`
+ * shim, a captured `bir up`) carries an extra copy of its own stdout pipe. A
+ * daemon that inherits it holds that pipe open for days, and whoever is reading
+ * it never sees EOF. `Start-Process` passes the environment and no handles.
+ */
+import { type DiscoveryInfo } from "./discovery.js";
+/** A log file larger than this is rolled over to `.1` when a daemon starts. */
+export declare const LOG_ROTATE_BYTES: number;
+/** Marks a `bir-hooks` as started by this module; it says so in its discovery file. */
+export declare const DAEMON_ENV = "BIR_DAEMON";
+/** Where that process writes its audit lines. It opens the file itself. */
+export declare const DAEMON_LOG_ENV = "BIR_DAEMON_LOG";
+/**
+ * The setup token's environment variable (`bir setup` reads it when `--token`
+ * is absent). Never handed to the recorder: it is a one-use secret for signing
+ * in, and a process that lives for days has no business holding it.
+ */
+export declare const SETUP_TOKEN_ENV = "BIR_SETUP_TOKEN";
+export interface DaemonStatus {
+    info: DiscoveryInfo;
+    health: Record<string, unknown>;
+}
+/** Absolute path of `dist/bin/bir-hooks.js` in the package this module runs from. */
+export declare function hooksScriptPath(): string;
+/**
+ * The live control server for `cwd`, or undefined.
+ *
+ * "Live" means the discovery file is fresh, its pid is alive, **and** it
+ * answers `/health` with its token. A file left by a crash fails the second
+ * test; a process that hung, or a recycled pid, fails the third.
+ */
+export declare function daemonStatus(cwd: string): Promise<DaemonStatus | undefined>;
+export interface EnsureOptions {
+    /** `dist/bin/bir-hooks.js` to run. Defaults to this package's. */
+    hooksScript?: string;
+    /** Environment for the new process. Defaults to this process's. */
+    env?: NodeJS.ProcessEnv;
+    /** How long to wait for a fresh process to answer `/health`. */
+    timeoutMs?: number;
+    /**
+     * Restart a running recorder whose version is not ours, provided no session
+     * is mid-run. Off by default: only `bir setup`/`bir up` and the SessionStart
+     * hook — the moments a restart costs nothing — ask for it.
+     */
+    restartOnSkew?: boolean;
+}
+export interface EnsureResult {
+    status: DaemonStatus;
+    /** True when this call started the process. */
+    started: boolean;
+    /** True when this call replaced a running process of another version. */
+    restarted: boolean;
+}
+/** How many of the recorder's sessions are mid-run right now. */
+export declare function activeSessions(health: Record<string, unknown>): number;
+/**
+ * The control server for `cwd`, started in the background if none is live.
+ *
+ * Idempotent: a live one is returned as-is. Throws when a fresh process did
+ * not come up in time, with the tail of its log, because "it did not start" is
+ * the one message that must carry its own diagnosis.
+ */
+export declare function ensureDaemon(cwd: string, opts?: EnsureOptions): Promise<EnsureResult>;
+/**
+ * Stop the control server for `cwd`.
+ *
+ * Asks first — `POST /control/stop`, which lets it finish the run it is
+ * writing and drain its queue — and only then, if it is still there, kills it.
+ * A `SIGTERM` on Windows is a hard kill with no handler, which is exactly why
+ * the polite route exists. Only a process that answers `/health` as the
+ * recorder is ever signalled: a discovery file survives a crash, and its pid
+ * is recycled — on Windows quickly — so "the pid in the file is alive" is not
+ * evidence that it is ours.
+ */
+export declare function stopDaemon(cwd: string, opts?: {
+    timeoutMs?: number;
+}): Promise<{
+    stopped: boolean;
+    pid?: number;
+    stale?: boolean;
+    forced?: boolean;
+}>;
+//# sourceMappingURL=daemon.d.ts.map