@basein/runner 0.2.8 → 0.2.10

package/dist/control/daemon.js

@@ -0,0 +1,339 @@
+/**
+ * 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 { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync, closeSync, } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ControlClient } from "./client.js";
+import { pidAlive, readDiscovery, removeDiscovery } from "./discovery.js";
+import { controlDir, controlKey, daemonLogPath, ensureDir, logsDir } from "./paths.js";
+import { nodeFlagsToCarry } from "../config/generate.js";
+import { errText, logLine } from "../util/log.js";
+import { packageVersion } from "../util/version.js";
+/** A log file larger than this is rolled over to `.1` when a daemon starts. */
+export const LOG_ROTATE_BYTES = 8 * 1024 * 1024;
+/** Marks a `bir-hooks` as started by this module; it says so in its discovery file. */
+export const DAEMON_ENV = "BIR_DAEMON";
+/** Where that process writes its audit lines. It opens the file itself. */
+export 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 const SETUP_TOKEN_ENV = "BIR_SETUP_TOKEN";
+/** A start lock older than this belongs to a starter that died; it is ignored. */
+const LOCK_STALE_MS = 30_000;
+/** Absolute path of `dist/bin/bir-hooks.js` in the package this module runs from. */
+export function hooksScriptPath() {
+    return resolvePath(dirname(fileURLToPath(import.meta.url)), "..", "bin", "bir-hooks.js");
+}
+/**
+ * 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 async function daemonStatus(cwd) {
+    const info = readDiscovery(cwd);
+    if (!info)
+        return undefined;
+    const health = await new ControlClient(info.url, info.token, 3_000).health();
+    if (!health || health.pid !== info.pid)
+        return undefined;
+    return { info, health };
+}
+/** How many of the recorder's sessions are mid-run right now. */
+export function activeSessions(health) {
+    const sessions = health.sessions ?? [];
+    return sessions.filter((s) => s.active === true).length;
+}
+/**
+ * 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 async function ensureDaemon(cwd, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 15_000;
+    let restarted = false;
+    const live = await daemonStatus(cwd);
+    if (live) {
+        const theirs = String(live.health.hooksVersion ?? live.info.version ?? "");
+        const skewed = opts.restartOnSkew && theirs && theirs !== packageVersion();
+        if (!skewed || activeSessions(live.health) > 0) {
+            return { status: live, started: false, restarted: false };
+        }
+        // An upgraded package with last week's recorder still running is the
+        // "half-upgraded machine" of docs/installRun.md §8 — the update that looks
+        // like success. Nothing is mid-run, so this is the free moment to fix it.
+        logLine("daemon.restart", {
+            cwd,
+            from: theirs,
+            to: packageVersion(),
+            why: "the recorder is an older version than the package; no session is mid-run",
+        });
+        await stopDaemon(cwd);
+        restarted = true;
+    }
+    else if (readDiscovery(cwd)) {
+        // A file whose pid is alive but that nothing answers for: a crash whose pid
+        // was recycled. Gone now, so no proxy resolves it in the moments before the
+        // new one writes its own.
+        removeDiscovery(cwd);
+    }
+    // Two Claude Code windows opened together in one project both run the
+    // SessionStart hook. The first to take the lock spawns; the second waits for
+    // that spawn rather than racing it onto another port.
+    const lock = lockPath(cwd);
+    if (!acquireLock(lock)) {
+        const theirs = await waitForDaemon(cwd, undefined, timeoutMs);
+        if (theirs)
+            return { status: theirs, started: false, restarted: false };
+        releaseLock(lock); // theirs died or hung; the lock is ours to take
+        if (!acquireLock(lock))
+            throw new Error("another recorder start is in progress — try again");
+    }
+    try {
+        const script = opts.hooksScript ?? hooksScriptPath();
+        const logFile = daemonLogPath(cwd);
+        ensureDir(logsDir());
+        rotateLog(logFile);
+        const env = {
+            ...(opts.env ?? process.env),
+            [DAEMON_ENV]: "1",
+            [DAEMON_LOG_ENV]: logFile,
+        };
+        delete env[SETUP_TOKEN_ENV];
+        const launched = process.platform === "win32"
+            ? launchWindows(script, cwd, env)
+            : launchPosix(script, cwd, env);
+        const status = await waitForDaemon(cwd, launched.pid, timeoutMs, () => {
+            if (launched.exited()) {
+                throw new Error(`the recorder exited before it was ready — ${tailOf(logFile)}`);
+            }
+        });
+        if (!status) {
+            throw new Error(`the recorder did not answer within ${Math.round(timeoutMs / 1000)}s — ${tailOf(logFile)}`);
+        }
+        return { status, started: true, restarted };
+    }
+    finally {
+        releaseLock(lock);
+    }
+}
+function launchPosix(script, cwd, env) {
+    const child = spawn(process.execPath, [...nodeFlagsToCarry(), script], {
+        cwd,
+        detached: true,
+        stdio: "ignore",
+        env,
+    });
+    let exited = false;
+    child.once("exit", () => {
+        exited = true;
+    });
+    child.once("error", () => {
+        exited = true;
+    });
+    child.unref();
+    return { pid: child.pid, exited: () => exited };
+}
+/** Single-quote a value for a PowerShell string literal. */
+function psQuote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function launchWindows(script, cwd, env) {
+    // Start-Process joins -ArgumentList with spaces and quotes nothing, so the
+    // script path carries its own double quotes.
+    const argumentList = [...nodeFlagsToCarry().map(psQuote), psQuote(`"${script}"`)].join(", ");
+    const command = `$p = Start-Process -FilePath ${psQuote(process.execPath)} ` +
+        `-ArgumentList @(${argumentList}) ` +
+        `-WorkingDirectory ${psQuote(cwd)} -WindowStyle Hidden -PassThru; ` +
+        `Write-Output $p.Id`;
+    const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", command], { env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true, timeout: 30_000 });
+    const pid = Number((result.stdout ?? "").trim().split(/\s+/).pop());
+    if (result.status !== 0 || !Number.isInteger(pid) || pid <= 0) {
+        // No PowerShell, or it refused: fall back to a plain spawn. It records;
+        // the handle it may inherit is the lesser evil next to not recording.
+        logLine("daemon.start_fallback", {
+            why: "Start-Process failed; using a plain spawn",
+            detail: (result.stderr ?? "").trim().slice(0, 200) || errText(result.error),
+        });
+        return launchPosix(script, cwd, env);
+    }
+    return { pid, exited: () => !pidAlive(pid) };
+}
+/**
+ * Poll until the recorder for `cwd` answers — with `pid` when the caller knows
+ * which process it is waiting for — or `timeoutMs` passes.
+ */
+async function waitForDaemon(cwd, pid, timeoutMs, check) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const status = await daemonStatus(cwd);
+        if (status && (pid === undefined || status.info.pid === pid))
+            return status;
+        check?.();
+        if (Date.now() >= deadline)
+            return undefined;
+        await sleep(200);
+    }
+}
+/**
+ * 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 async function stopDaemon(cwd, opts = {}) {
+    const info = readDiscovery(cwd);
+    if (!info)
+        return { stopped: false };
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const client = new ControlClient(info.url, info.token, 3_000);
+    const health = await client.health();
+    if (!health || health.pid !== info.pid) {
+        removeDiscovery(cwd);
+        return { stopped: false, pid: info.pid, stale: true };
+    }
+    const asked = await client.stop();
+    const deadline = Date.now() + timeoutMs;
+    while (asked && pidAlive(info.pid) && Date.now() < deadline) {
+        await sleep(100);
+    }
+    let forced = false;
+    if (pidAlive(info.pid)) {
+        forced = true;
+        try {
+            process.kill(info.pid, "SIGTERM");
+        }
+        catch (err) {
+            logLine("daemon.kill_failed", { pid: info.pid, error: errText(err) });
+        }
+        const hardDeadline = Date.now() + 3_000;
+        while (pidAlive(info.pid) && Date.now() < hardDeadline) {
+            await sleep(100);
+        }
+    }
+    // Its own shutdown removes the file; a killed process could not.
+    if (!pidAlive(info.pid))
+        removeDiscovery(cwd);
+    return { stopped: !pidAlive(info.pid), pid: info.pid, forced };
+}
+// ── the start lock ─────────────────────────────────────────────────────────
+function lockPath(cwd) {
+    return join(controlDir(), `${controlKey(cwd)}.lock`);
+}
+function acquireLock(path) {
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    }
+    catch {
+        /* the open below reports it */
+    }
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const fd = openSync(path, "wx", 0o600);
+            writeSync(fd, `${process.pid} ${Date.now()}\n`);
+            closeSync(fd);
+            return true;
+        }
+        catch (err) {
+            // Anything but "it exists" means the lock cannot be kept at all (an
+            // unwritable state directory, say). Then there is nothing to wait for:
+            // go ahead uncoordinated rather than sit out the whole timeout.
+            if (err.code !== "EEXIST")
+                return true;
+            // Somebody holds it. Alive and recent: theirs. Old: they died holding it.
+            try {
+                if (Date.now() - statSync(path).mtimeMs < LOCK_STALE_MS)
+                    return false;
+                unlinkSync(path);
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    return false;
+}
+function releaseLock(path) {
+    try {
+        if (existsSync(path))
+            unlinkSync(path);
+    }
+    catch {
+        /* best effort */
+    }
+}
+// ── helpers ────────────────────────────────────────────────────────────────
+/** Roll a large log to `.1`. Best effort: a log that will not rotate is still a log. */
+function rotateLog(path) {
+    try {
+        if (existsSync(path) && statSync(path).size > LOG_ROTATE_BYTES) {
+            renameSync(path, `${path}.1`);
+        }
+    }
+    catch {
+        /* keep appending to the big one */
+    }
+}
+/** The last few lines of the log, for an error message. */
+function tailOf(path) {
+    try {
+        const text = readFileSync(path, "utf8");
+        const lines = text.trimEnd().split(/\r?\n/).slice(-3);
+        return lines.length ? `see ${path}:\n    ${lines.join("\n    ")}` : `see ${path}`;
+    }
+    catch {
+        return `see ${path}`;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=daemon.js.map

package/dist/control/discovery.d.ts

@@ -26,6 +26,14 @@
  */
 /** A discovery file older than this is ignored even if its pid is somehow alive. */
 export declare const MAX_DISCOVERY_AGE_MS: number;
+/**
+ * How often a running control server rewrites its discovery file.
+ *
+ * Well inside {@link MAX_DISCOVERY_AGE_MS}: a background recorder that misses
+ * a few beats (a laptop asleep over a weekend) is still found on Monday, and a
+ * dead one is still forgotten within a day.
+ */
+export declare const HEARTBEAT_MS: number;
 export interface DiscoveryInfo {
     url: string;
     /** Random 32 bytes hex; required on every control-server route. */
@@ -34,9 +42,27 @@ export interface DiscoveryInfo {
     pid: number;
     startedAt: number;
     cwd: string;
+    /**
+     * Last time the control server rewrote this file (see {@link readDiscovery}).
+     * Absent on a file written by a control server that predates the heartbeat.
+     */
+    heartbeatAt?: number;
+    /** The control server's package version, so a hook can spot a stale daemon. */
+    version?: string;
+    /**
+     * True when the process was started in the background — by `bir up` or by
+     * the SessionStart hook — rather than in somebody's terminal. `bir status`
+     * and `bir doctor` say so, and name the log file, because "the recorder is
+     * running" is not a useful sentence when there is no window to look at.
+     */
+    daemon?: boolean;
+    /** Where a background process's stderr goes. */
+    logFile?: string;
 }
 export declare function writeDiscovery(info: DiscoveryInfo): string;
 export declare function removeDiscovery(cwd: string): void;
+/** True when a pid is still running (or when we cannot tell, which we treat as alive). */
+export declare function pidAlive(pid: number): boolean;
 /**
  * Read the discovery file for `cwd`, or undefined when there is none, it is
  * malformed, or it is stale.

package/dist/control/discovery.js

@@ -24,15 +24,29 @@
  * SECURITY (§9). Files are mode 0600 and carry the loopback bearer token. A local
  * port that accepts unauthenticated step reports is a local exfiltration channel.
  */
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { controlDir, discoveryPath, ensureDir } from "./paths.js";
 import { logDetail, errText } from "../util/log.js";
 /** A discovery file older than this is ignored even if its pid is somehow alive. */
 export const MAX_DISCOVERY_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * How often a running control server rewrites its discovery file.
+ *
+ * Well inside {@link MAX_DISCOVERY_AGE_MS}: a background recorder that misses
+ * a few beats (a laptop asleep over a weekend) is still found on Monday, and a
+ * dead one is still forgotten within a day.
+ */
+export const HEARTBEAT_MS = 30 * 60 * 1000;
 export function writeDiscovery(info) {
     ensureDir(controlDir());
     const path = discoveryPath(info.cwd);
-    writeFileSync(path, JSON.stringify(info, null, 2), { mode: 0o600 });
+    // Write beside, then rename over: a reader never sees a half-written file.
+    // The heartbeat rewrites this every half hour, and a proxy or the ensure
+    // hook reading an empty file in that instant would conclude "no recorder"
+    // and start a second one.
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(info, null, 2), { mode: 0o600 });
+    renameSync(tmp, path);
     return path;
 }
 export function removeDiscovery(cwd) {
@@ -46,7 +60,7 @@ export function removeDiscovery(cwd) {
     }
 }
 /** True when a pid is still running (or when we cannot tell, which we treat as alive). */
-function pidAlive(pid) {
+export function pidAlive(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
         return false;
     try {
@@ -73,7 +87,12 @@ export function readDiscovery(cwd) {
             typeof parsed.pid !== "number") {
             return undefined;
         }
-        if (Date.now() - (parsed.startedAt ?? 0) > MAX_DISCOVERY_AGE_MS) {
+        // Aged from the newest of the two stamps. A background recorder that has
+        // run for a week is still the right one to talk to; it rewrites this file
+        // every `HEARTBEAT_MS` precisely so this check keeps saying so. A file
+        // whose process died keeps its last stamp and ages out as before.
+        const freshest = Math.max(parsed.startedAt ?? 0, parsed.heartbeatAt ?? 0);
+        if (Date.now() - freshest > MAX_DISCOVERY_AGE_MS) {
             logDetail("discovery.stale", { path, reason: "too old" });
             return undefined;
         }
@@ -94,20 +113,33 @@ export function readDiscovery(cwd) {
  */
 export async function resolveControl(cwd, timeoutMs, pollMs = 250) {
     const envUrl = process.env.BIR_CONTROL_URL;
+    const deadline = Date.now() + timeoutMs;
     if (envUrl) {
-        // The env channel may still race the server's own startup, so it is verified
-        // against the discovery file when one exists (that is where the token lives).
-        const fromFile = readDiscovery(cwd);
+        // The env channel names the address but not, on its own, the token: that
+        // lives in the discovery file the control server writes when it starts.
+        // Since the SessionStart hook is what starts the recorder, the host has
+        // usually spawned this proxy *before* that file exists — so wait for it
+        // the way the file-only path below does, rather than register with an
+        // empty token and be refused. `BIR_CONTROL_TOKEN` (the SDK channel) skips
+        // the wait; so does a file that is already there.
+        const fromEnv = process.env.BIR_CONTROL_TOKEN;
+        let fromFile = readDiscovery(cwd);
+        while (!fromEnv && !fromFile && Date.now() < deadline) {
+            await new Promise((resolve) => {
+                const t = setTimeout(resolve, Math.min(pollMs, Math.max(0, deadline - Date.now())));
+                t.unref?.();
+            });
+            fromFile = readDiscovery(cwd);
+        }
         return {
             url: envUrl.replace(/\/+$/, ""),
-            token: process.env.BIR_CONTROL_TOKEN ?? fromFile?.token ?? "",
+            token: fromEnv ?? fromFile?.token ?? "",
             sessionId: fromFile?.sessionId ?? "",
             pid: fromFile?.pid ?? 0,
             startedAt: fromFile?.startedAt ?? Date.now(),
             cwd,
         };
     }
-    const deadline = Date.now() + timeoutMs;
     for (;;) {
         const found = readDiscovery(cwd);
         if (found)

package/dist/control/ensure-hook.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ensure-hook — what `bir-hooks ensure` does when Claude Code fires SessionStart.
+ *
+ * Installed by `bir install` as the SessionStart hook, in exec form (no shell):
+ *
+ *     { "type": "command", "command": "<node>", "args": ["<dist>/bin/bir-hooks.js", "ensure"] }
+ *
+ * It does two things the HTTP hook it replaces could not: it **starts the
+ * recorder** when this directory has none (see daemon.ts), and only then
+ * **relays the SessionStart payload** to it, so the control server still sees
+ * the event that used to reach it over HTTP. The two must be one hook: Claude
+ * Code runs every hook of an event in parallel, and an HTTP hook racing the
+ * daemon it depends on would fail on every first session of the day.
+ *
+ * THE ONE RULE: a host session never fails because of BaseInstRunner. Every
+ * path here ends in exit 0. A recorder that would not start is one line on
+ * stderr and a session that records Tier 2, exactly what happened before this
+ * hook existed.
+ *
+ * STDOUT IS CONTEXT. For SessionStart, Claude Code adds whatever a command hook
+ * prints on stdout to the model's context. So nothing is printed unless the
+ * control server answered with something (today it answers `{}`), and then it
+ * is the answer, verbatim, as JSON.
+ */
+import { type EnsureOptions } from "./daemon.js";
+export interface EnsureHookOptions extends EnsureOptions {
+    stdin?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    /** How long to wait for the payload on stdin before going on without it. */
+    stdinTimeoutMs?: number;
+}
+/**
+ * Run the hook for `cwd`. Resolves the exit code, which is always 0.
+ */
+export declare function runEnsureHook(cwd: string, opts?: EnsureHookOptions): Promise<number>;
+//# sourceMappingURL=ensure-hook.d.ts.map

package/dist/control/ensure-hook.js

@@ -0,0 +1,98 @@
+/**
+ * ensure-hook — what `bir-hooks ensure` does when Claude Code fires SessionStart.
+ *
+ * Installed by `bir install` as the SessionStart hook, in exec form (no shell):
+ *
+ *     { "type": "command", "command": "<node>", "args": ["<dist>/bin/bir-hooks.js", "ensure"] }
+ *
+ * It does two things the HTTP hook it replaces could not: it **starts the
+ * recorder** when this directory has none (see daemon.ts), and only then
+ * **relays the SessionStart payload** to it, so the control server still sees
+ * the event that used to reach it over HTTP. The two must be one hook: Claude
+ * Code runs every hook of an event in parallel, and an HTTP hook racing the
+ * daemon it depends on would fail on every first session of the day.
+ *
+ * THE ONE RULE: a host session never fails because of BaseInstRunner. Every
+ * path here ends in exit 0. A recorder that would not start is one line on
+ * stderr and a session that records Tier 2, exactly what happened before this
+ * hook existed.
+ *
+ * STDOUT IS CONTEXT. For SessionStart, Claude Code adds whatever a command hook
+ * prints on stdout to the model's context. So nothing is printed unless the
+ * control server answered with something (today it answers `{}`), and then it
+ * is the answer, verbatim, as JSON.
+ */
+import { ensureDaemon } from "./daemon.js";
+import { errText } from "../util/log.js";
+/** Read stdin to its end, or give up after `timeoutMs` with what arrived. */
+function readStdin(stream, timeoutMs) {
+    // A person running `bir-hooks ensure` by hand has nothing to paste; do not
+    // sit waiting for a Ctrl-D they do not know to press.
+    if (stream.isTTY)
+        return Promise.resolve("");
+    return new Promise((resolve) => {
+        let text = "";
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve(text);
+        };
+        const timer = setTimeout(finish, timeoutMs);
+        stream.setEncoding("utf8");
+        stream.on("data", (chunk) => {
+            text += chunk;
+        });
+        stream.on("end", finish);
+        stream.on("error", finish);
+    });
+}
+/**
+ * Run the hook for `cwd`. Resolves the exit code, which is always 0.
+ */
+export async function runEnsureHook(cwd, opts = {}) {
+    const stdout = opts.stdout ?? process.stdout;
+    const stderr = opts.stderr ?? process.stderr;
+    const raw = await readStdin(opts.stdin ?? process.stdin, opts.stdinTimeoutMs ?? 3_000);
+    let payload = {};
+    if (raw.trim()) {
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch {
+            // Not our problem to diagnose; the control server copes with an empty one.
+            payload = {};
+        }
+    }
+    try {
+        const { status, started, restarted } = await ensureDaemon(cwd, {
+            hooksScript: opts.hooksScript,
+            env: opts.env,
+            timeoutMs: opts.timeoutMs,
+            restartOnSkew: opts.restartOnSkew ?? true,
+        });
+        if (started) {
+            stderr.write(`[bir] recorder ${restarted ? "restarted" : "started"} in the background (pid ${status.info.pid}, log ${status.info.logFile ?? "?"})\n`);
+        }
+        const res = await fetch(`${status.info.url}/session/start`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${status.info.token}`,
+            },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(5_000),
+        });
+        const answer = (await res.json().catch(() => ({})));
+        if (res.ok && answer && typeof answer === "object" && Object.keys(answer).length > 0) {
+            stdout.write(JSON.stringify(answer));
+        }
+    }
+    catch (err) {
+        stderr.write(`[bir] ensure: ${errText(err)} — this session records standalone (Tier 2)\n`);
+    }
+    return 0;
+}
+//# sourceMappingURL=ensure-hook.js.map

package/dist/control/paths.d.ts

@@ -13,6 +13,20 @@ export declare function configDir(): string;
 export declare function controlDir(): string;
 /** The sidecar holding original MCP entries so `bir uninstall` can restore them. */
 export declare function installedPath(): string;
+/**
+ * Settings that outlive a shell: today, the service address.
+ *
+ * `bir setup` and `bir login` write it; every process reads it when
+ * `BIR_AUTH_URL` is unset. It is what lets a recorder started by a hook —
+ * with whatever environment the host happened to have — know where to send
+ * steps, and it is why "close the terminal and open a new one" is no longer a
+ * step in the install.
+ */
+export declare function configPath(): string;
+/** Where a background `bir-hooks` writes its audit lines, one file per project. */
+export declare function logsDir(): string;
+/** The log file of the background recorder for `cwd`. */
+export declare function daemonLogPath(cwd: string): string;
 /** Create a directory with restrictive permissions. Idempotent, never throws. */
 export declare function ensureDir(dir: string, mode?: number): void;
 /**

package/dist/control/paths.js

@@ -23,6 +23,26 @@ export function controlDir() {
 export function installedPath() {
     return join(configDir(), "installed.json");
 }
+/**
+ * Settings that outlive a shell: today, the service address.
+ *
+ * `bir setup` and `bir login` write it; every process reads it when
+ * `BIR_AUTH_URL` is unset. It is what lets a recorder started by a hook —
+ * with whatever environment the host happened to have — know where to send
+ * steps, and it is why "close the terminal and open a new one" is no longer a
+ * step in the install.
+ */
+export function configPath() {
+    return join(configDir(), "config.json");
+}
+/** Where a background `bir-hooks` writes its audit lines, one file per project. */
+export function logsDir() {
+    return join(configDir(), "logs");
+}
+/** The log file of the background recorder for `cwd`. */
+export function daemonLogPath(cwd) {
+    return join(logsDir(), `${controlKey(cwd)}.log`);
+}
 /** Create a directory with restrictive permissions. Idempotent, never throws. */
 export function ensureDir(dir, mode = 0o700) {
     try {