@basein/runner 0.2.11 → 0.3.0

package/dist/upstream/stdio-client.js

@@ -14,17 +14,92 @@
  *     mangles JSON), {@link resolveCommand} resolves the real file on PATH and,
  *     for a batch file, invokes `cmd.exe /d /s /c` with `windowsVerbatimArguments`
  *     and its own quoting.
+ *
+ * AND ONE THING THAT BREAKS THE USER'S MACHINE: a server the proxy started must
+ * not outlive it. On Windows a batch-file upstream is `cmd.exe` → `node` (or
+ * `python`, or Chrome), and killing `cmd.exe` leaves the rest running — holding
+ * a browser profile or a database lock the next session then cannot open. So
+ * {@link StdioUpstreamClient.shutdown} closes stdin first (the MCP-spec way to
+ * ask a server to exit), waits briefly, and only then kills the whole tree.
  */
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { delimiter, isAbsolute, join } from "node:path";
-import { readFrames, writeFrame } from "../jsonrpc/framing.js";
+import { DEFAULT_MAX_LINE_BYTES, classifyOversizedLine, readFrames, writeFrame } from "../jsonrpc/framing.js";
+import { isRequest } from "../jsonrpc/types.js";
 import { logDetail, logLine, errText } from "../util/log.js";
-import { BaseUpstreamClient } from "./client.js";
+import { timeoutSignal } from "../util/service-health.js";
+import { BaseUpstreamClient, isBirId } from "./client.js";
 const BATCH_EXT = /\.(cmd|bat)$/i;
-/** Quote one argument for `cmd.exe /c`, which re-parses what it is handed. */
-function quoteForCmd(arg) {
-    return '"' + arg.replace(/"/g, '""') + '"';
+/** A forwarded stderr line longer than this is flushed without waiting for its newline. */
+const MAX_STDERR_LINE = 8 * 1024;
+/** Messages held while a `--restart` is in progress. Past this, the oldest are dropped. */
+const MAX_RESTART_BUFFER = 1_000;
+/** How long a restarted upstream gets to answer the replayed `initialize`. */
+const REINIT_TIMEOUT_MS = 15_000;
+/** Default time a closing upstream gets to exit on stdin EOF before it is killed. */
+export const DEFAULT_SHUTDOWN_GRACE_MS = 1_500;
+/**
+ * Quote one argument for `cmd.exe /c` and, behind it, the C runtime's argv
+ * parser in whatever the batch file launches.
+ *
+ * Three rules, each for a case that used to arrive mangled:
+ *   - An embedded `"` becomes `""`, which cmd reads as leaving and re-entering
+ *     a quoted run (so its metacharacters stay quoted) and the C runtime reads
+ *     as one literal quote.
+ *   - Backslashes before a quote — an embedded one or our closing one — are
+ *     doubled, because the C runtime reads `\"` as an escaped quote.
+ *     `C:\projects\` used to swallow the next argument whole.
+ *   - `%` is taken *out* of the quotes and caret-escaped: cmd expands `%NAME%`
+ *     even inside quotes, and a caret is literal there. Outside them, `^%`
+ *     survives expansion (the text between the two percents is no longer a
+ *     variable name, because it contains a quote) and the caret is removed
+ *     afterwards, leaving `%`. The C runtime then joins the pieces:
+ *     `"a"%"B"%"c"` is the single argument `a%B%c`.
+ */
+export function quoteForCmd(arg) {
+    return arg
+        .split("%")
+        .map((piece) => '"' + piece.replace(/(\\*)"/g, '$1$1""').replace(/(\\+)$/, "$1$1") + '"')
+        .join("^%");
+}
+/**
+ * Read an environment variable the way Windows does — case-insensitively.
+ *
+ * `process.env` is case-insensitive on Windows, but a *copy* of it (`{ ...process.env }`,
+ * which is what spawning with extra variables needs) is a plain object, and a
+ * normal Windows process spells the key `Path`. Reading `.PATH` off the copy
+ * found nothing, `npx` stayed unresolved, and every npx-launched server failed
+ * with `spawn npx ENOENT` whenever a host passed its environment through.
+ */
+export function envValue(env, key) {
+    if (env[key] !== undefined)
+        return env[key];
+    if (process.platform !== "win32")
+        return undefined;
+    const upper = key.toUpperCase();
+    const match = Object.keys(env).find((k) => k.toUpperCase() === upper);
+    return match === undefined ? undefined : env[match];
+}
+/**
+ * `base` overlaid with `extra`. On Windows a key in `extra` replaces *every*
+ * spelling of it in `base`: spawn keeps only one of `Path`/`PATH`, and it
+ * would not necessarily be the one the caller meant to set.
+ */
+function mergeEnv(base, extra) {
+    const out = { ...base };
+    if (!extra)
+        return out;
+    for (const [key, value] of Object.entries(extra)) {
+        if (process.platform === "win32") {
+            const upper = key.toUpperCase();
+            for (const k of Object.keys(out))
+                if (k !== key && k.toUpperCase() === upper)
+                    delete out[k];
+        }
+        out[key] = value;
+    }
+    return out;
 }
 /** Find `command` on PATH, trying PATHEXT extensions. Returns undefined if absent. */
 export function whichSync(command, env = process.env) {
@@ -32,9 +107,9 @@ export function whichSync(command, env = process.env) {
         return existsSync(command) ? command : undefined;
     }
     const exts = process.platform === "win32"
-        ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
+        ? (envValue(env, "PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
         : [""];
-    const dirs = (env.PATH ?? "").split(delimiter).filter(Boolean);
+    const dirs = (envValue(env, "PATH") ?? "").split(delimiter).filter(Boolean);
     for (const dir of dirs) {
         for (const ext of exts) {
             const candidate = join(dir, command + ext);
@@ -54,7 +129,7 @@ export function resolveCommand(command, args, env = process.env) {
     const resolved = whichSync(command, env) ?? command;
     if (!BATCH_EXT.test(resolved))
         return { command: resolved, args };
-    const comspec = env.ComSpec ?? env.COMSPEC ?? "cmd.exe";
+    const comspec = envValue(env, "ComSpec") ?? "cmd.exe";
     const line = [resolved, ...args].map(quoteForCmd).join(" ");
     return {
         command: comspec,
@@ -64,6 +139,88 @@ export function resolveCommand(command, args, env = process.env) {
         windowsVerbatimArguments: true,
     };
 }
+/** Resolve when `child` has exited, or after `ms`. True when it exited. */
+function waitForExit(child, ms) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        const onExit = () => {
+            clearTimeout(timer);
+            resolve(true);
+        };
+        const timer = setTimeout(() => {
+            child.off("exit", onExit);
+            resolve(false);
+        }, ms);
+        timer.unref?.();
+        child.once("exit", onExit);
+    });
+}
+/**
+ * Kill `child` and everything it started. On Windows that takes `taskkill /T`
+ * (a plain kill terminates one process: `cmd.exe`, not the server behind it);
+ * elsewhere SIGTERM, then SIGKILL. Bounded; never throws.
+ */
+async function killTree(child) {
+    const pid = child.pid;
+    if (pid === undefined)
+        return;
+    if (process.platform === "win32") {
+        await new Promise((resolve) => {
+            let killer;
+            try {
+                killer = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
+                    windowsHide: true,
+                    stdio: "ignore",
+                });
+            }
+            catch {
+                resolve();
+                return;
+            }
+            const timer = setTimeout(() => {
+                try {
+                    killer.kill();
+                }
+                catch {
+                    /* already gone */
+                }
+                resolve();
+            }, 3_000);
+            timer.unref?.();
+            const done = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            killer.once("exit", done);
+            killer.once("error", done);
+        });
+        // taskkill failing (no such binary, access denied) must still end our child.
+        if (child.exitCode === null && child.signalCode === null) {
+            try {
+                child.kill();
+            }
+            catch {
+                /* already gone */
+            }
+        }
+        return;
+    }
+    try {
+        child.kill("SIGTERM");
+    }
+    catch {
+        return;
+    }
+    if (!(await waitForExit(child, 1_000))) {
+        try {
+            child.kill("SIGKILL");
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
 export class StdioUpstreamClient extends BaseUpstreamClient {
     ready;
     child;
@@ -72,6 +229,17 @@ export class StdioUpstreamClient extends BaseUpstreamClient {
     opts;
     restartsLeft;
     closing = false;
+    /**
+     * Set while a `--restart` is in progress: host messages wait here for the
+     * new process to be spawned and re-initialised, instead of being written
+     * into a dead pipe and lost.
+     */
+    restartBuffer;
+    /** True while our replayed `initialize` is the one message allowed through. */
+    handshaking = false;
+    /** The host's `initialize` params, replayed to a restarted upstream. */
+    hostInitParams;
+    hostInitialized = false;
     constructor(opts) {
         super();
         this.opts = opts;
@@ -81,7 +249,7 @@ export class StdioUpstreamClient extends BaseUpstreamClient {
     }
     start() {
         const { command, args = [], env, cwd } = this.opts;
-        const spawnEnv = { ...process.env, ...env };
+        const spawnEnv = mergeEnv(process.env, env);
         const resolved = resolveCommand(command, args, spawnEnv);
         return new Promise((resolve, reject) => {
             let child;
@@ -100,8 +268,16 @@ export class StdioUpstreamClient extends BaseUpstreamClient {
                 return;
             }
             this.child = child;
+            // 'error' and 'exit' can both fire for one child; it is gone once.
+            let gone = false;
+            const goneOnce = (info) => {
+                if (gone)
+                    return;
+                gone = true;
+                this.onChildGone(child, info);
+            };
             child.once("spawn", () => {
-                logLine("upstream.spawned", {
+                logDetail("upstream.spawned", {
                     server: this.label,
                     pid: child.pid,
                     command: resolved.command,
@@ -111,33 +287,82 @@ export class StdioUpstreamClient extends BaseUpstreamClient {
             child.once("error", (err) => {
                 // A spawn failure (ENOENT) and a mid-life error arrive the same way.
                 reject(err);
-                this.onChildGone({ error: err });
+                goneOnce({ error: err });
             });
-            child.once("exit", (code, signal) => this.onChildGone({ code, signal }));
+            child.once("exit", (code, signal) => goneOnce({ code, signal }));
+            // A child that dies with our write in flight raises EPIPE on its stdin;
+            // unhandled, that would be an uncaught exception in the proxy.
+            child.stdin.on("error", (err) => logDetail("upstream.stdin_error", { server: this.label, error: errText(err) }));
+            const maxLineBytes = this.opts.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES;
             this.detach = readFrames(child.stdout, {
                 onMessage: (msg) => this.accept(msg),
-                onParseError: (d) => logLine("upstream.unparseable", {
-                    server: this.label,
-                    reason: d.reason,
-                    bytes: d.bytes,
-                }),
-            });
-            // Upstream stderr → our stderr, never our stdout. Line-prefixed.
+                onParseError: (d) => {
+                    logLine("upstream.unparseable", {
+                        server: this.label,
+                        reason: d.reason,
+                        bytes: d.bytes,
+                    });
+                    if (!d.oversized)
+                        return;
+                    const shape = classifyOversizedLine(d.sample, d.tail);
+                    if (shape.kind === "request") {
+                        // A notification (a huge log or progress line) or a request from
+                        // the server (sampling with an image). No host call is waiting on
+                        // it, so nothing is answered toward the host — answering the one
+                        // call in flight used to hand it a false "too large" error, and
+                        // then its real answer as well. A request the server is waiting
+                        // on gets a JSON-RPC error back, so it is not left waiting either.
+                        if (shape.id !== undefined) {
+                            this.write({
+                                jsonrpc: "2.0",
+                                id: shape.id,
+                                error: {
+                                    code: -32600,
+                                    message: `request too large to deliver (${d.bytes} bytes; the limit is ${maxLineBytes} bytes)`,
+                                },
+                            });
+                        }
+                        return;
+                    }
+                    // An answer too big to parse is still an answer the host is waiting
+                    // for. Without this, its request stayed pending forever and the tool
+                    // call spun until the user pressed Esc.
+                    this.undeliverable({
+                        id: shape.id,
+                        // Only a line known to be an answer may be matched to the one call
+                        // in flight when it carries no id; and not while a request of our
+                        // own is out too, since the answer could as well be that one's.
+                        response: shape.kind === "response" && this.ownRequestsInFlight === 0,
+                        bytes: d.bytes,
+                        reason: `the result was too large to deliver (${d.bytes} bytes; ` +
+                            `the limit is ${maxLineBytes} bytes)`,
+                    });
+                },
+            }, { maxLineBytes });
+            // Upstream stderr → our stderr, never our stdout. Line-prefixed, split on
+            // any line ending (a `\r`-only progress spinner is still lines), and
+            // bounded: a writer that never ends a line is flushed in pieces rather
+            // than buffered for the life of the session.
             let errBuf = "";
             child.stderr.setEncoding("utf8");
             child.stderr.on("data", (chunk) => {
                 errBuf += chunk;
-                let nl;
-                while ((nl = errBuf.indexOf("\n")) !== -1) {
-                    const line = errBuf.slice(0, nl).replace(/\r$/, "");
-                    errBuf = errBuf.slice(nl + 1);
+                const lines = errBuf.split(/\r\n|\n|\r/);
+                errBuf = lines.pop() ?? "";
+                for (const line of lines) {
                     if (line)
                         process.stderr.write("[" + this.label + "] " + line + "\n");
                 }
+                while (errBuf.length > MAX_STDERR_LINE) {
+                    process.stderr.write("[" + this.label + "] " + errBuf.slice(0, MAX_STDERR_LINE) + "\n");
+                    errBuf = errBuf.slice(MAX_STDERR_LINE);
+                }
             });
         });
     }
-    onChildGone(info) {
+    onChildGone(child, info) {
+        if (child !== this.child)
+            return; // an earlier process, already replaced
         this.detach?.();
         this.detach = undefined;
         if (this.closing) {
@@ -154,22 +379,88 @@ export class StdioUpstreamClient extends BaseUpstreamClient {
             this.restartsLeft -= 1;
             const delay = this.opts.restartDelayMs ?? 500;
             logLine("upstream.restarting", { server: this.label, delayMs: delay });
-            const timer = setTimeout(() => {
-                this.start().catch((err) => {
-                    logLine("upstream.restart_failed", { server: this.label, error: errText(err) });
-                    this.closed({ error: err instanceof Error ? err : new Error(String(err)) });
-                });
-            }, delay);
+            // Whatever was in flight died with the process: answer it now (the relay
+            // does, on this event) rather than leave the host waiting on a process
+            // that will never reply. What arrives from here on waits for the new one.
+            this.restartBuffer ??= [];
+            this.restarting(info);
+            const timer = setTimeout(() => void this.restart(), delay);
             timer.unref?.();
             return;
         }
-        // Dead for good. The relay answers in-flight requests and stays up: the host
-        // sees one broken server, not a broken session (§10).
+        // Dead for good. The relay answers in-flight requests; bir-proxy then exits,
+        // so the host sees the server disconnect exactly as it would unwrapped.
+        this.restartBuffer = undefined;
         this.closed(info);
     }
+    /** Start a new process, replay the host's handshake to it, then release held messages. */
+    async restart() {
+        if (this.closing || this.dead)
+            return;
+        try {
+            await this.start();
+            if (this.closing) {
+                // Shut down while the new process was starting: it must not outlive us.
+                const child = this.child;
+                if (child)
+                    void killTree(child);
+                return;
+            }
+            if (this.hostInitParams !== undefined) {
+                this.handshaking = true;
+                try {
+                    await this.request("initialize", this.hostInitParams, timeoutSignal(REINIT_TIMEOUT_MS));
+                }
+                finally {
+                    this.handshaking = false;
+                }
+                if (this.hostInitialized)
+                    this.write({ jsonrpc: "2.0", method: "notifications/initialized" });
+            }
+        }
+        catch (err) {
+            logLine("upstream.restart_failed", { server: this.label, error: errText(err) });
+            this.restartBuffer = undefined;
+            const child = this.child;
+            this.closing = true;
+            if (child && child.exitCode === null && child.signalCode === null)
+                void killTree(child);
+            this.closed({ error: err instanceof Error ? err : new Error(String(err)) });
+            return;
+        }
+        const held = this.restartBuffer ?? [];
+        this.restartBuffer = undefined;
+        logLine("upstream.restarted", { server: this.label, released: held.length || undefined });
+        for (const msg of held)
+            this.write(msg);
+    }
     send(msg) {
+        if (this.dead)
+            return;
+        const id = msg.id;
+        const method = msg.method;
+        if (!isBirId(id)) {
+            // Remember the host's half of the handshake, for a restart to replay.
+            if (method === "initialize" && isRequest(msg))
+                this.hostInitParams = msg.params ?? {};
+            if (method === "notifications/initialized")
+                this.hostInitialized = true;
+        }
+        if (this.restartBuffer) {
+            if (this.handshaking && method === "initialize" && isBirId(id)) {
+                this.write(msg);
+                return;
+            }
+            if (this.restartBuffer.length >= MAX_RESTART_BUFFER)
+                this.restartBuffer.shift();
+            this.restartBuffer.push(msg);
+            return;
+        }
+        this.write(msg);
+    }
+    write(msg) {
         const child = this.child;
-        if (!child || this.dead || child.stdin.destroyed)
+        if (!child || child.stdin.destroyed)
             return;
         logDetail("upstream.send", {
             server: this.label,
@@ -179,6 +470,7 @@ export class StdioUpstreamClient extends BaseUpstreamClient {
     }
     close() {
         this.closing = true;
+        this.restartBuffer = undefined;
         this.detach?.();
         const child = this.child;
         if (!child) {
@@ -199,5 +491,36 @@ export class StdioUpstreamClient extends BaseUpstreamClient {
         }
         this.closed({});
     }
+    /**
+     * Close the way the MCP spec asks a client to: end stdin, give the server
+     * `graceMs` to exit on its own, then kill it — with its whole process tree on
+     * Windows. A server that exits on EOF (nearly all do) costs no wait at all.
+     */
+    async shutdown(graceMs = DEFAULT_SHUTDOWN_GRACE_MS) {
+        this.closing = true;
+        this.restartBuffer = undefined;
+        const child = this.child;
+        if (!child || child.exitCode !== null || child.signalCode !== null) {
+            this.detach?.();
+            this.closed({});
+            return;
+        }
+        // Stop parsing, but keep draining: a server blocked writing to a full
+        // stdout pipe could never exit on its own.
+        this.detach?.();
+        this.detach = undefined;
+        child.stdout.resume();
+        try {
+            child.stdin.end();
+        }
+        catch {
+            /* already gone */
+        }
+        if (!(await waitForExit(child, graceMs))) {
+            logDetail("upstream.kill", { server: this.label, pid: child.pid, why: `no exit within ${graceMs}ms of stdin closing` });
+            await killTree(child);
+        }
+        this.closed({});
+    }
 }
 //# sourceMappingURL=stdio-client.js.map

package/dist/util/atomic-write.d.ts

@@ -0,0 +1,29 @@
+/**
+ * atomic-write — replace a file so a reader never sees half of it.
+ *
+ * Every file the runner writes is read by something else while it runs:
+ * ~/.claude.json by Claude Code (which also rewrites it constantly),
+ * settings.local.json and .mcp.json by Claude Code at start, credentials.json
+ * and installed.json by every sibling `bir-*` process. A plain `writeFileSync`
+ * truncates first and fills second, so a reader that lands in between gets an
+ * empty or torn JSON document — and for ~/.claude.json that means Claude Code
+ * starting with no MCP servers, or worse, rewriting it from the torn copy.
+ *
+ * Write a sibling temp file, then rename over the target: rename is atomic on
+ * one volume on every platform Node supports. Windows adds two wrinkles:
+ *
+ *   - antivirus and indexers hold files briefly, so a rename can fail with
+ *     EPERM/EBUSY/EACCES for a few milliseconds; it is retried, and if it keeps
+ *     failing the write falls back to an in-place write rather than failing the
+ *     caller's whole operation;
+ *   - a symlinked target (dotfile managers do this to ~/.claude.json) must keep
+ *     being a symlink, so the rename goes to the link's real target.
+ *
+ * The existing file's mode is kept; `mode` applies to a new file.
+ */
+export interface AtomicWriteOptions {
+    /** Mode for a file that does not exist yet. An existing file keeps its own. */
+    mode?: number;
+}
+export declare function writeFileAtomic(path: string, data: string | Uint8Array, opts?: AtomicWriteOptions): void;
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/util/atomic-write.js

@@ -0,0 +1,96 @@
+/**
+ * atomic-write — replace a file so a reader never sees half of it.
+ *
+ * Every file the runner writes is read by something else while it runs:
+ * ~/.claude.json by Claude Code (which also rewrites it constantly),
+ * settings.local.json and .mcp.json by Claude Code at start, credentials.json
+ * and installed.json by every sibling `bir-*` process. A plain `writeFileSync`
+ * truncates first and fills second, so a reader that lands in between gets an
+ * empty or torn JSON document — and for ~/.claude.json that means Claude Code
+ * starting with no MCP servers, or worse, rewriting it from the torn copy.
+ *
+ * Write a sibling temp file, then rename over the target: rename is atomic on
+ * one volume on every platform Node supports. Windows adds two wrinkles:
+ *
+ *   - antivirus and indexers hold files briefly, so a rename can fail with
+ *     EPERM/EBUSY/EACCES for a few milliseconds; it is retried, and if it keeps
+ *     failing the write falls back to an in-place write rather than failing the
+ *     caller's whole operation;
+ *   - a symlinked target (dotfile managers do this to ~/.claude.json) must keep
+ *     being a symlink, so the rename goes to the link's real target.
+ *
+ * The existing file's mode is kept; `mode` applies to a new file.
+ */
+import { chmodSync, lstatSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { basename, dirname, join } from "node:path";
+const RETRYABLE = new Set(["EPERM", "EBUSY", "EACCES", "EEXIST", "ENOTEMPTY"]);
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** Where a write to `path` should really land: through a symlink, to its target. */
+function resolveTarget(path) {
+    try {
+        if (lstatSync(path).isSymbolicLink())
+            return realpathSync(path);
+    }
+    catch {
+        /* missing: write it where asked */
+    }
+    return path;
+}
+export function writeFileAtomic(path, data, opts = {}) {
+    const target = resolveTarget(path);
+    let mode = opts.mode;
+    try {
+        mode = statSync(target).mode & 0o777;
+    }
+    catch {
+        /* new file */
+    }
+    const tmp = join(dirname(target), `.${basename(target)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
+    try {
+        writeFileSync(tmp, data, mode === undefined ? undefined : { mode });
+    }
+    catch {
+        // The directory refuses temp files (odd permissions, a read-only sibling
+        // policy). Writing in place is still better than not writing.
+        writeFileSync(target, data, mode === undefined ? undefined : { mode });
+        return;
+    }
+    for (let attempt = 0;; attempt++) {
+        try {
+            renameSync(tmp, target);
+            if (mode !== undefined && process.platform !== "win32") {
+                try {
+                    chmodSync(target, mode);
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+            return;
+        }
+        catch (err) {
+            const code = err.code ?? "";
+            if (RETRYABLE.has(code) && attempt < 6) {
+                sleepSync(10 * (attempt + 1));
+                continue;
+            }
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+                /* already gone */
+            }
+            if (RETRYABLE.has(code)) {
+                // Held open by something that will not let go. Fall back to the
+                // non-atomic write the caller used to do, rather than losing the change.
+                writeFileSync(target, data, mode === undefined ? undefined : { mode });
+                return;
+            }
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/util/journal.d.ts

@@ -23,9 +23,24 @@ export interface JournalEntry {
 }
 export declare function isJournaled(event: string): boolean;
 export declare const JOURNAL_MAX_BYTES: number;
+/**
+ * The longest string one journal field keeps. The journal explains decisions;
+ * a field that carries a whole error page or a pasted log would spend the
+ * 4 MB budget on one line and rotate the useful ones out.
+ */
+export declare const JOURNAL_FIELD_MAX_CHARS = 4000;
+/** A journal nobody has written to for this long belongs to a project that is gone. */
+export declare const JOURNAL_STALE_MS: number;
 export declare function journalPath(cwd: string): string;
 /** Start journaling this directory's audit lines. Returns the file, for the startup log. */
 export declare function openJournal(cwd: string): string;
+/**
+ * Delete other projects' journals untouched for {@link JOURNAL_STALE_MS}.
+ * One file per directory ever recorded in, each up to 4 MB, never pruned, is
+ * how a year of throwaway checkouts becomes a gigabyte nobody asked for.
+ * Best-effort, and never the open file.
+ */
+export declare function pruneStaleJournals(dir: string, keep?: string, now?: number): number;
 export declare function closeJournal(): void;
 /**
  * Append one entry, if a journal is open and the event is one we keep.