@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/keepers/acp/stderr.js

@@ -0,0 +1,154 @@
+// An adapter's stderr in keeper-acp (spec §5.3, §13; analysis A §5): read continuously (a full pipe would block the adapter),
+// split into lines, redacted BEFORE anything is written anywhere, then (1) appended to a per-session rotating, size-capped file,
+// (2) handed to the caller as an `err` record, and (3) kept as an 8 KiB tail for the `exit` record.
+// Keeper-side module: node builtins and kit siblings only (the import guard enforces it).
+import { closeSync, fstatSync, openSync, renameSync, writeSync } from 'node:fs';
+import { StringDecoder } from 'node:string_decoder';
+import { ACP_STDERR_FILE_BYTES, ACP_STDERR_LINE_BYTES, ACP_STDERR_TAIL_BYTES } from './protocol.js';
+export const REDACTED = '[REDACTED]';
+/** What replaces a line that was too long to keep (it is never cut: a cut could split a secret and leak its halves). */
+export const omittedLine = (chars) => `[keeper-acp] stderr line of ${chars}+ characters omitted`;
+/** A string as it appears inside a JSON string literal (what keeper-acp substitutes into a stdin line). */
+export const jsonEscaped = (value) => JSON.stringify(value).slice(1, -1);
+/** The JSON-escaped form with every non-ASCII character as `\uXXXX` (Python's `ensure_ascii`, many loggers). */
+const asciiEscaped = (value) => jsonEscaped(value).replace(/[^\x00-\x7e]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+/**
+ * The strings to remove for one secret: the value itself, the token of a `Bearer <token>` value (today's rule,
+ * `acpClient.ts` `redactSecret`), each non-trivial line of a multi-line value (a line-based log can only ever hold one line of it),
+ * and of each of those the encodings an adapter plausibly logs: JSON-escaped (stdin receives that form, an adapter echoing its input
+ * prints it), JSON-escaped twice (that line logged inside another JSON string), and ASCII-only JSON escapes.
+ */
+export function secretForms(secret) {
+    if (!secret)
+        return [];
+    const base = new Set([secret]);
+    if (secret.startsWith('Bearer ') && secret.length > 'Bearer '.length)
+        base.add(secret.slice('Bearer '.length));
+    if (/[\r\n]/.test(secret))
+        for (const line of secret.split(/\r?\n|\r/))
+            if (line.trim().length >= 8)
+                base.add(line);
+    const forms = new Set();
+    for (const form of base)
+        for (const encoded of [form, jsonEscaped(form), jsonEscaped(jsonEscaped(form)), asciiEscaped(form)])
+            if (encoded)
+                forms.add(encoded);
+    return [...forms];
+}
+export class StderrCapture {
+    options;
+    /** Longest first, so a secret that contains another is removed whole. */
+    secrets = [];
+    decoder = new StringDecoder('utf8');
+    partial = '';
+    dropping = false;
+    tailText = '';
+    fd;
+    fileSize = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Adds secrets to redact from now on (kept for the session's lifetime: a later spawn may print an earlier secret). */
+    addSecrets(values) {
+        const all = new Set(this.secrets);
+        for (const value of values)
+            for (const form of secretForms(value))
+                all.add(form);
+        this.secrets = [...all].sort((a, b) => b.length - a.length);
+    }
+    redact(text) {
+        let safe = text;
+        for (const secret of this.secrets)
+            if (safe.includes(secret))
+                safe = safe.replaceAll(secret, REDACTED);
+        return safe;
+    }
+    /** A new process: a fresh line buffer and tail (the tail belongs to one process's exit). */
+    restart() { this.decoder = new StringDecoder('utf8'); this.partial = ''; this.dropping = false; this.tailText = ''; }
+    get tail() { return this.tailText; }
+    push(chunk) {
+        let text = this.decoder.write(chunk);
+        for (;;) {
+            const newline = text.indexOf('\n');
+            if (newline < 0)
+                break;
+            const piece = text.slice(0, newline);
+            text = text.slice(newline + 1);
+            if (this.dropping) {
+                this.dropping = false;
+                this.partial = '';
+                continue;
+            }
+            this.line(this.partial + piece);
+            this.partial = '';
+        }
+        if (this.dropping)
+            return;
+        this.partial += text;
+        if (this.partial.length > ACP_STDERR_LINE_BYTES) {
+            this.emit(omittedLine(ACP_STDERR_LINE_BYTES));
+            this.partial = '';
+            this.dropping = true;
+        }
+    }
+    /** The stream ended: a final unterminated line is still a line. */
+    end() {
+        const rest = this.partial + this.decoder.end();
+        this.partial = '';
+        if (this.dropping) {
+            this.dropping = false;
+            return;
+        }
+        if (rest)
+            this.line(rest);
+    }
+    line(raw) {
+        this.emit(raw.length > ACP_STDERR_LINE_BYTES ? omittedLine(ACP_STDERR_LINE_BYTES) : this.redact(raw));
+    }
+    emit(safe) {
+        this.tailText = (this.tailText + safe + '\n').slice(-ACP_STDERR_TAIL_BYTES);
+        this.writeFile(`${safe}\n`);
+        try {
+            this.options.onLine(safe);
+        }
+        catch (error) {
+            this.options.onError?.(error);
+        }
+    }
+    writeFile(text) {
+        const file = this.options.file;
+        if (!file)
+            return;
+        try {
+            const data = Buffer.from(text, 'utf8');
+            const cap = this.options.fileBytes ?? ACP_STDERR_FILE_BYTES;
+            if (this.fd === undefined) {
+                this.fd = openSync(file, 'a', 0o600);
+                this.fileSize = fstatSync(this.fd).size;
+            }
+            if (this.fileSize > 0 && this.fileSize + data.length > cap) {
+                closeSync(this.fd);
+                this.fd = undefined;
+                renameSync(file, `${file}.1`);
+                this.fd = openSync(file, 'a', 0o600);
+                this.fileSize = 0;
+            }
+            let written = 0;
+            while (written < data.length)
+                written += writeSync(this.fd, data, written, data.length - written);
+            this.fileSize += data.length;
+        }
+        catch (error) {
+            this.options.onError?.(error);
+        }
+    }
+    close() {
+        if (this.fd !== undefined) {
+            try {
+                closeSync(this.fd);
+            }
+            catch { /* ignore */ }
+            this.fd = undefined;
+        }
+    }
+}

package/dist/workstation/keepers/kit/activity.js

@@ -0,0 +1,103 @@
+/** Hard cap on `items` in one answer (spec §3.5). */
+export const MAX_ACTIVITY_ITEMS = 32;
+/** Longest `type`, `id`, `label` and `state` of an item; longer strings are cut. */
+export const MAX_ACTIVITY_STRING = 256;
+/** Metric names starting with this belong to the kit; a sampler's own are dropped. */
+export const RESERVED_METRIC_PREFIX = 'kit.';
+/** A sampler that has not answered by then is abandoned for this sample. */
+export const DEFAULT_SAMPLE_TIMEOUT_MS = 2000;
+const validItem = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const item = value;
+    return typeof item.type === 'string' && typeof item.id === 'string' && typeof item.label === 'string'
+        && typeof item.state === 'string' && typeof item.sinceEpochMs === 'number' && Number.isFinite(item.sinceEpochMs);
+};
+const clip = (value) => (value.length > MAX_ACTIVITY_STRING ? value.slice(0, MAX_ACTIVITY_STRING) : value);
+/** A sampler whose previous sample has not settled. A new sample joins it instead of calling the sampler again, so a hung sampler never piles up calls. */
+const pending = new WeakMap();
+async function runSampler(sampler, timeoutMs) {
+    let timer;
+    let sample = pending.get(sampler);
+    if (!sample) {
+        const started = Promise.resolve().then(sampler);
+        sample = started;
+        pending.set(sampler, started);
+        const release = () => { if (pending.get(sampler) === started)
+            pending.delete(sampler); };
+        started.then(release, release);
+    }
+    try {
+        return await Promise.race([
+            sample,
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('activity sampler timed out')), timeoutMs); timer.unref(); }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Samples every sampler now and merges the answers: metrics are summed per name (finite numbers only), items are
+ * concatenated in sampler order and cut at {@link MAX_ACTIVITY_ITEMS}; item strings (and an optional string `jobId`, the only
+ * extra field kept) are cut at {@link MAX_ACTIVITY_STRING}.
+ * A failing sampler is skipped and counted in `kit.sampleErrors`; cut items are counted in `kit.itemsOmitted`; a sampler metric
+ * in the reserved `kit.` namespace is dropped and counted in `kit.reservedDropped`. These kit metrics appear only when non-zero.
+ *
+ * Same-named metrics from different samplers are SUMMED. That is right for counts and wrong for gauges, so samplers
+ * must use distinct names for anything that is not additive.
+ */
+export async function sampleActivity(samplers, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_SAMPLE_TIMEOUT_MS;
+    const settled = await Promise.allSettled(samplers.map((sampler) => runSampler(sampler, timeoutMs)));
+    const metrics = {};
+    const items = [];
+    let errors = 0;
+    let omitted = 0;
+    let reserved = 0;
+    for (const result of settled) {
+        if (result.status === 'rejected') {
+            errors += 1;
+            try {
+                options.onError?.(result.reason);
+            }
+            catch { /* diagnostics must not matter */ }
+            continue;
+        }
+        const part = result.value;
+        if (typeof part !== 'object' || part === null)
+            continue;
+        if (typeof part.metrics === 'object' && part.metrics !== null) {
+            for (const [name, value] of Object.entries(part.metrics)) {
+                if (typeof value !== 'number' || !Number.isFinite(value))
+                    continue;
+                if (name.startsWith(RESERVED_METRIC_PREFIX)) {
+                    reserved += 1;
+                    continue;
+                }
+                metrics[name] = (metrics[name] ?? 0) + value;
+            }
+        }
+        if (Array.isArray(part.items)) {
+            for (const item of part.items) {
+                if (!validItem(item))
+                    continue;
+                if (items.length < MAX_ACTIVITY_ITEMS) {
+                    const kept = { type: clip(item.type), id: clip(item.id), label: clip(item.label), state: clip(item.state), sinceEpochMs: item.sinceEpochMs };
+                    if (typeof item.jobId === 'string' && item.jobId)
+                        kept.jobId = clip(item.jobId);
+                    items.push(kept);
+                }
+                else
+                    omitted += 1;
+            }
+        }
+    }
+    if (errors > 0)
+        metrics['kit.sampleErrors'] = errors;
+    if (omitted > 0)
+        metrics['kit.itemsOmitted'] = omitted;
+    if (reserved > 0)
+        metrics['kit.reservedDropped'] = reserved;
+    return { metrics, items };
+}

package/dist/workstation/keepers/kit/bootstrap.js

@@ -0,0 +1,164 @@
+// The shared start-up of every keeper process (`keepers/<kind>/main.ts`): read the launch config, publish the pid manifest,
+// listen with a fresh token, wire `keeper.stop` and SIGTERM/SIGINT to a clean exit, and report errors. A keeper main only
+// says what it hosts (capabilities, methods, activity, what to do on stop). Keeper-side module: node builtins and kit siblings only.
+import { readFileSync, unlinkSync } from 'node:fs';
+import { decodeLaunchConfig } from './launchConfig.js';
+import { manifestProcessLive, readPidManifest, writePidManifest } from './lock.js';
+import { KeeperServer } from './server.js';
+const STRING_FIELDS = ['identity', 'gen', 'unit', 'buildVersion', 'bundleDir', 'runDir', 'dataDir', 'socket', 'pidFile', 'tokenFile'];
+/** The launch config from argv, refusing anything incomplete or meant for another kind. */
+export function readLaunchConfig(argv, kind) {
+    const encoded = argv[2];
+    if (!encoded)
+        throw new Error('Missing keeper launch config argument');
+    let config;
+    try {
+        config = decodeLaunchConfig(encoded);
+    }
+    catch {
+        throw new Error('Unreadable keeper launch config');
+    }
+    if (typeof config !== 'object' || config === null)
+        throw new Error('Unreadable keeper launch config');
+    if (config.kind !== kind)
+        throw new Error(`Launch config is for keeper kind ${String(config.kind)}, not ${kind}`);
+    for (const field of STRING_FIELDS)
+        if (typeof config[field] !== 'string' || !config[field])
+            throw new Error(`Launch config lacks ${field}`);
+    if (!Number.isInteger(config.umask) || config.umask < 0 || config.umask > 0o777)
+        throw new Error('Launch config lacks umask');
+    return config;
+}
+const defaultLog = (kind) => (line) => {
+    try {
+        process.stderr.write(`${new Date().toISOString()} keeper-${kind}: ${line}\n`);
+    }
+    catch { /* no stderr */ }
+};
+const unlinkIf = (file, owned) => {
+    try {
+        if (owned())
+            unlinkSync(file);
+    }
+    catch { /* already gone or unreadable: not ours to remove */ }
+};
+/**
+ * Starts a keeper process. Order matters:
+ *  0. (process hooks) the daemon's umask from the launch config becomes the process umask, so PTYs, execs and files follow it;
+ *  1. the pid manifest is written before anything else initialises, so a launcher probing a slow start sees a live keeper
+ *     (and never unlinks its socket); a manifest naming another live keeper of this generation makes this start give up;
+ *  2. the keeper module is created and installed;
+ *  3. the server listens (token published only once the socket is ours) under a private 077 umask, restored to the daemon's
+ *     umask afterwards;
+ *  4. `keeper.stop` and SIGTERM/SIGINT stop through the kit's stop path; the stop runs the module's shutdown, removes the
+ *     pid manifest and token (only if still ours), closes the socket and exits 0.
+ * A start that fails exits 1 after removing what it published. Uncaught errors are logged, never fatal: a keeper
+ * hosts live user sessions, and dying on an unexpected exception would lose every one of them.
+ */
+export async function bootstrapKeeper(options) {
+    const log = options.log ?? defaultLog(options.kind);
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const report = (error) => log(error instanceof Error ? (error.stack ?? error.message) : String(error));
+    const hooks = options.processHooks !== false;
+    const config = readLaunchConfig(options.argv ?? process.argv, options.kind);
+    const ownsManifest = () => { try {
+        return JSON.parse(readFileSync(config.pidFile, 'utf8')).pid === process.pid;
+    }
+    catch {
+        return false;
+    } };
+    if (hooks) {
+        // The daemon's umask, process-wide: under a systemd transient unit the inherited one is the user manager's, not the user's.
+        process.umask(config.umask);
+        // Never hold the daemon's working directory (a removable volume, a deleted worktree) for the keeper's whole life.
+        try {
+            process.chdir(config.runDir);
+        }
+        catch (error) {
+            report(error);
+        }
+        process.on('uncaughtException', (error) => report(error));
+        process.on('unhandledRejection', (error) => report(error));
+        process.on('SIGHUP', () => { }); // detached and without a controlling terminal; never let a stray hangup end the keeper
+    }
+    const previous = await readPidManifest(config.pidFile).catch(() => null);
+    if (previous && previous.pid !== process.pid && previous.identity === config.identity && previous.gen === config.gen && await manifestProcessLive(previous))
+        throw new Error(`Keeper ${options.kind} ${config.gen} already runs as pid ${previous.pid}`);
+    await writePidManifest(config.pidFile, {
+        kind: config.kind, gen: config.gen, buildVersion: config.buildVersion, bundleDir: config.bundleDir, startedAt: Date.now(), identity: config.identity, pid: process.pid,
+    });
+    let finishStop;
+    const stopped = new Promise((resolve) => { finishStop = resolve; });
+    let module;
+    let server;
+    let token = '';
+    let stopping = false;
+    const onStop = (mode) => {
+        if (stopping)
+            return;
+        stopping = true;
+        void (async () => {
+            try {
+                if (module?.shutdown) {
+                    let timer;
+                    await Promise.race([
+                        Promise.resolve().then(() => module.shutdown(mode)),
+                        new Promise((resolve) => { timer = setTimeout(resolve, options.shutdownTimeoutMs ?? 5000); timer.unref(); }),
+                    ]).catch(report).finally(() => clearTimeout(timer));
+                }
+            }
+            finally {
+                unlinkIf(config.pidFile, ownsManifest);
+                unlinkIf(config.tokenFile, () => token !== '' && readFileSync(config.tokenFile, 'utf8') === token);
+                await server.close().catch(report);
+                finishStop();
+                exit(0);
+            }
+        })();
+    };
+    try {
+        module = await options.create(config, { log });
+        server = new KeeperServer({
+            kind: options.kind, identity: config.identity, gen: config.gen, buildVersion: config.buildVersion, protocolVersion: options.protocolVersion,
+            socket: config.socket, tokenFile: config.tokenFile, capabilities: module.capabilities ?? [], onError: report, onStop, ...options.server,
+        });
+        module.install(server);
+        const umask = hooks ? process.umask(0o077) : undefined; // process-wide; in-process (tests, workers) the socket's 0700 directory suffices
+        try {
+            await server.listen();
+        }
+        finally {
+            if (umask !== undefined)
+                process.umask(umask);
+        }
+        token = server.token;
+    }
+    catch (error) {
+        unlinkIf(config.pidFile, ownsManifest);
+        try {
+            await module?.shutdown?.('force');
+        }
+        catch (shutdownError) {
+            report(shutdownError);
+        }
+        throw error;
+    }
+    const stop = (mode) => server.stopped(mode);
+    if (hooks) {
+        process.on('SIGTERM', () => stop('graceful'));
+        process.on('SIGINT', () => stop('graceful'));
+    }
+    log(`listening (pid ${process.pid}, build ${config.buildVersion.slice(0, 12)}, protocol ${options.protocolVersion})`);
+    return { config, server, stop, stopped };
+}
+/** `bootstrapKeeper` for a keeper process's main: a failed start is logged and exits 1. */
+export async function runKeeperMain(options) {
+    try {
+        return await bootstrapKeeper(options);
+    }
+    catch (error) {
+        (options.log ?? defaultLog(options.kind))(`start failed: ${error instanceof Error ? error.message : String(error)}`);
+        (options.exit ?? ((code) => process.exit(code)))(1);
+        return undefined;
+    }
+}

package/dist/workstation/keepers/kit/buildVersion.js

@@ -0,0 +1,51 @@
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+/**
+ * The keeper buildVersion: sha256 over the bundle bytes plus the sorted list of
+ * (relative path, executable flag, sha256) of every file under `node_modules/`.
+ *
+ * This is the single implementation of the hash. `scripts/bundle-keepers.mjs` imports the compiled module to
+ * stamp `manifest.json`, and `ensureBundle` re-runs it over the copied snapshot, so the two cannot drift.
+ * The snapshot is a full copy of `dist/keepers/<kind>` (all darwin/linux prebuilds, ~600 KiB), because the
+ * hash covers every native file the build carried; copying only the current platform would not verify.
+ *
+ * It depends on nothing else (no package version, timestamps or absolute paths), so shipping a CLI with
+ * unchanged keeper code does not change it.
+ */
+const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+function walkFiles(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...walkFiles(full));
+        else
+            out.push(full);
+    }
+    return out;
+}
+/** Relative (posix) paths of the native files carried next to a bundle, sorted. */
+export function nativeFilesOf(kindDir) {
+    let files;
+    try {
+        files = walkFiles(join(kindDir, 'node_modules'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return files.map((file) => relative(kindDir, file).split(sep).join('/')).sort();
+}
+export function computeBuildVersion(kindDir) {
+    const hash = createHash('sha256');
+    const bundle = readFileSync(join(kindDir, 'keeper.mjs'));
+    hash.update(`bundle ${bundle.length}\n`).update(bundle);
+    for (const rel of nativeFilesOf(kindDir)) {
+        const file = join(kindDir, rel);
+        const executable = (statSync(file).mode & 0o111) !== 0 ? 'x' : '-';
+        hash.update(`\nnative ${rel} ${executable} ${sha256(readFileSync(file))}`);
+    }
+    return hash.digest('hex');
+}

package/dist/workstation/keepers/kit/bundle.js

@@ -0,0 +1,120 @@
+import { randomUUID } from 'node:crypto';
+import { chmodSync, cpSync, promises as fs, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { computeBuildVersion } from './buildVersion.js';
+import { KEEPER_KINDS } from './identity.js';
+import { manifestProcessLive, readPidManifest } from './lock.js';
+export class BundleIntegrityError extends Error {
+    constructor(message) { super(message); this.name = 'BundleIntegrityError'; }
+}
+const BUILD_VERSION = /^[0-9a-f]{64}$/;
+export async function readKeeperManifest(kindDir) {
+    const value = JSON.parse(await fs.readFile(path.join(kindDir, 'manifest.json'), 'utf8'));
+    const range = value.daemonProtocol;
+    if (!KEEPER_KINDS.includes(value.kind) || !Number.isInteger(value.protocolVersion) || typeof value.buildVersion !== 'string'
+        || !BUILD_VERSION.test(value.buildVersion) || !Array.isArray(range) || range.length !== 2 || !range.every(Number.isInteger))
+        throw new BundleIntegrityError(`Invalid keeper manifest in ${kindDir}`);
+    return value;
+}
+/** Throws unless the files under `dir` hash to `buildVersion` (the same hash `bundle-keepers.mjs` stamped). */
+function verify(dir, buildVersion, what) {
+    let actual;
+    try {
+        actual = computeBuildVersion(dir);
+    }
+    catch (error) {
+        throw new BundleIntegrityError(`${what} is unreadable: ${error.message}`);
+    }
+    if (actual !== buildVersion)
+        throw new BundleIntegrityError(`${what} does not match keeper build ${buildVersion.slice(0, 12)}`);
+}
+/** Copies preserving modes explicitly: spawn-helper must stay executable whatever the copy primitive does. */
+function copyTree(source, target) {
+    cpSync(source, target, { recursive: true, dereference: true });
+    const walk = (from, to) => {
+        for (const entry of readdirSync(from, { withFileTypes: true })) {
+            const src = path.join(from, entry.name);
+            const dst = path.join(to, entry.name);
+            if (entry.isDirectory())
+                walk(src, dst);
+            else
+                chmodSync(dst, statSync(src).mode & 0o777);
+        }
+    };
+    walk(source, target);
+}
+/**
+ * Makes `bundlesDir/<buildVersion>` an immutable snapshot of `distKindDir` and returns it. The keeper runs from
+ * the snapshot, so replacing `dist/keepers` (npm upgrade, rebuild) never changes a running keeper's files.
+ *
+ * Copy to `.tmp-<uuid>`, recompute the hash over the copy (all of it: bundle plus every native file the build
+ * carried) and compare with the manifest, then rename. A snapshot that already exists is re-verified instead of
+ * trusted, and a mismatch throws: the caller must not launch from it.
+ */
+export async function ensureBundle(distKindDir, bundlesDir) {
+    const manifest = await readKeeperManifest(distKindDir);
+    const target = path.join(bundlesDir, manifest.buildVersion);
+    const existing = await fs.lstat(target).then((stat) => stat, (error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (existing) {
+        if (!existing.isDirectory() || existing.isSymbolicLink())
+            throw new BundleIntegrityError(`${target} is not a keeper bundle directory`);
+        verify(target, manifest.buildVersion, `Existing keeper bundle ${target}`);
+        return { manifest, buildVersion: manifest.buildVersion, bundleDir: target, created: false };
+    }
+    await fs.mkdir(bundlesDir, { recursive: true, mode: 0o700 });
+    const temp = path.join(bundlesDir, `.tmp-${randomUUID()}`);
+    try {
+        copyTree(distKindDir, temp);
+        verify(temp, manifest.buildVersion, `Keeper bundle copy of ${distKindDir}`);
+        try {
+            await fs.rename(temp, target);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOTEMPTY' && code !== 'EEXIST')
+                throw error;
+            // A concurrent ensure won the rename. Its snapshot must be as good as ours.
+            verify(target, manifest.buildVersion, `Existing keeper bundle ${target}`);
+            return { manifest, buildVersion: manifest.buildVersion, bundleDir: target, created: false };
+        }
+    }
+    finally {
+        await fs.rm(temp, { recursive: true, force: true });
+    }
+    return { manifest, buildVersion: manifest.buildVersion, bundleDir: target, created: true };
+}
+/**
+ * Deletes `bundles/*` that no live keeper's pid manifest references (a pid reused by an unrelated process does not count) (and stale `.tmp-*` leftovers).
+ * Returns the removed paths.
+ */
+export async function gcBundles(options) {
+    const minAge = options.minAgeMs ?? 10 * 60_000;
+    const now = options.now ?? Date.now();
+    const keep = new Set(options.keep ?? []);
+    const removed = [];
+    for (const kind of KEEPER_KINDS) {
+        const root = path.join(path.resolve(options.configDir), 'keepers', kind);
+        const referenced = new Set(keep);
+        for (const gen of await fs.readdir(path.join(root, 'run')).catch(() => [])) {
+            const manifest = await readPidManifest(path.join(root, 'run', gen, 'keeper.pid.json')).catch(() => null);
+            if (manifest && await manifestProcessLive(manifest))
+                referenced.add(manifest.buildVersion);
+        }
+        const bundles = path.join(root, 'bundles');
+        for (const name of await fs.readdir(bundles).catch(() => [])) {
+            if (referenced.has(name))
+                continue;
+            const dir = path.join(bundles, name);
+            const stat = await fs.lstat(dir).catch(() => null);
+            if (!stat || (minAge > 0 && now - Math.max(stat.mtimeMs, stat.ctimeMs) < minAge))
+                continue;
+            await fs.rm(dir, { recursive: true, force: true });
+            removed.push(dir);
+        }
+    }
+    return removed;
+}