@platless/axom-cli 0.1.0 → 0.5.9

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

@@ -0,0 +1,249 @@
+// Daemon-side: starts, probes and stops keepers. Exempt from the keeper-side import guard.
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { keeperOneShot, readKeeperToken } from './client.js';
+import { BundleIntegrityError, ensureBundle, gcBundles, readKeeperManifest } from './bundle.js';
+import { keeperGen } from './identity.js';
+import { encodeLaunchConfig, launchConfigOf } from './launchConfig.js';
+import { acquireStartupLock, liveManifest, manifestProcessLive, pidAlive, processCommand, readPidManifest, releaseStartupLock } from './lock.js';
+import { bundleDirFor, ensureKeeperDirectories, keeperPaths, touchSocket } from './paths.js';
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** `keeper.ping` on a fresh connection. Null unless the answer is from this exact keeper generation. */
+export async function pingKeeper(paths, timeoutMs = 250) {
+    try {
+        const reply = await keeperOneShot(paths.socket, 'keeper.ping', {}, timeoutMs);
+        if (reply.identity !== paths.identity || reply.gen !== paths.gen || !Number.isSafeInteger(reply.pid))
+            return null;
+        return { pid: reply.pid, identity: paths.identity, gen: paths.gen };
+    }
+    catch {
+        return null;
+    }
+}
+/** Arguments for the Linux transient unit. `Restart=no`: a crash is handled by the daemon with the right build, never by systemd with stale arguments. */
+export function systemdRunArgs(unit, nodePath, script, config) {
+    return ['--user', '--quiet', '--collect', `--unit=${unit}`, '--property=Type=exec', '--property=Restart=no', '--', nodePath, script, config];
+}
+function runQuiet(command, args, timeoutMs) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, { stdio: 'ignore' });
+        let done = false;
+        const finish = (ok) => { if (done)
+            return; done = true; clearTimeout(timer); resolve(ok); };
+        const timer = setTimeout(() => { child.kill(); finish(false); }, timeoutMs);
+        child.on('error', () => finish(false));
+        child.on('exit', (code) => finish(code === 0));
+    });
+}
+export const systemdAvailable = () => runQuiet('systemctl', ['--user', 'show-environment'], 500);
+export const defaultDistDir = () => fileURLToPath(new URL('../../../keepers/', import.meta.url));
+export class KeeperLauncher {
+    options;
+    starting = new Map();
+    current = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    get distDir() { return this.options.distDir ?? defaultDistDir(); }
+    probe(paths, timeoutMs) { return this.options.probe ? this.options.probe(paths) : pingKeeper(paths, timeoutMs); }
+    /** Paths of generation `gen` of `kind` (no build needed). */
+    pathsFor(kind, gen) { return keeperPaths(this.options, kind, gen); }
+    /** The generation the current build of `kind` runs as (`dist/keepers/<kind>/manifest.json`); starts nothing. */
+    async currentGen(kind) {
+        return keeperGen((await readKeeperManifest(path.join(this.distDir, kind))).buildVersion);
+    }
+    /** Generations of `kind` whose pid manifest names a live keeper of that generation (`<root>/run/<gen>`); starts nothing. */
+    async liveGenerations(kind) {
+        const runRoot = path.join(this.pathsFor(kind, 'probe').root, 'run');
+        const gens = await fs.readdir(runRoot).catch(() => []);
+        const live = [];
+        for (const gen of gens.sort())
+            if (await liveManifest(this.pathsFor(kind, gen)).catch(() => false))
+                live.push(gen);
+        return live;
+    }
+    /** Ensures the current build of `kind` is running (snapshot, lock, probe, spawn) and returns it. One start per kind in flight. */
+    launch(kind) {
+        let pending = this.starting.get(kind);
+        if (!pending) {
+            pending = this.start(kind).finally(() => { this.starting.delete(kind); });
+            this.starting.set(kind, pending);
+        }
+        return pending;
+    }
+    async start(kind) {
+        const deadline = Date.now() + (this.options.startTimeoutMs ?? 7500);
+        const manifest = await readKeeperManifest(path.join(this.distDir, kind));
+        const paths = keeperPaths(this.options, kind, keeperGen(manifest.buildVersion));
+        await ensureKeeperDirectories(paths);
+        // A keeper that already answers needs no snapshot check: it runs from the snapshot it was started with.
+        const alive = await this.probe(paths);
+        if (alive) {
+            this.current.add(manifest.buildVersion);
+            return { paths, manifest, bundleDir: bundleDirFor(paths, manifest.buildVersion), pid: alive.pid, launched: false };
+        }
+        const snapshot = await ensureBundle(path.join(this.distDir, kind), paths.bundlesDir); // BundleIntegrityError refuses the launch
+        this.current.add(snapshot.buildVersion);
+        const handle = (pid, launched) => ({ paths, manifest, bundleDir: snapshot.bundleDir, pid, launched });
+        while (Date.now() < deadline - 500) {
+            const found = await this.probe(paths);
+            if (found)
+                return handle(found.pid, false);
+            let lock;
+            try {
+                lock = await acquireStartupLock(paths.lockPort);
+            }
+            catch (error) {
+                if (error.code !== 'EADDRINUSE')
+                    throw error;
+                await delay(50);
+                continue;
+            }
+            try {
+                const winner = await this.probe(paths);
+                if (winner)
+                    return handle(winner.pid, false);
+                // A probe timeout is not process death: a busy keeper may be slow to ping, and unlinking its live
+                // socket would orphan everything it hosts. The pid manifest is written before the keeper initialises.
+                while (await liveManifest(paths)) {
+                    const slow = await this.probe(paths);
+                    if (slow)
+                        return handle(slow.pid, false);
+                    if (Date.now() >= deadline - 300)
+                        throw new Error(`Keeper ${kind} is alive but busy or unavailable; retry later`);
+                    await delay(50);
+                }
+                await fs.unlink(paths.socket).catch((error) => { if (error.code !== 'ENOENT')
+                    throw error; });
+                await this.spawnKeeper(paths, snapshot.buildVersion, snapshot.bundleDir, deadline);
+                while (Date.now() < deadline - 100) {
+                    const started = await this.probe(paths);
+                    if (started) {
+                        void this.gc().catch(() => { });
+                        return handle(started.pid, true);
+                    }
+                    await delay(50);
+                }
+                throw new Error(`Keeper ${kind} failed to start`);
+            }
+            finally {
+                await releaseStartupLock(lock);
+            }
+        }
+        throw new Error(`Keeper ${kind} startup is busy or timed out`);
+    }
+    async spawnKeeper(paths, buildVersion, bundleDir, deadline) {
+        const script = path.join(bundleDir, 'keeper.mjs'); // always the immutable snapshot, never dist/
+        const config = encodeLaunchConfig(launchConfigOf(paths, buildVersion, bundleDir, this.options.umask ?? process.umask()));
+        const nodePath = this.options.nodePath ?? process.execPath;
+        if ((this.options.platform ?? process.platform) === 'linux' && this.options.useSystemd !== false && await systemdAvailable()) {
+            // setsid/detached cannot escape systemd's KillMode=control-group. A separate transient unit gives the keeper
+            // (and everything it hosts) its own cgroup so the daemon can restart or upgrade freely.
+            const timeout = Math.max(1, Math.min(2000, deadline - Date.now() - 500));
+            if (await runQuiet('systemd-run', systemdRunArgs(paths.unit, nodePath, script, config), timeout))
+                return;
+            // The unit may still be starting. Never fall back to a same-cgroup child on a systemd host.
+            while (Date.now() < deadline - 100) {
+                if (await this.probe(paths))
+                    return;
+                await delay(50);
+            }
+            throw new Error(`Cannot start isolated keeper user service ${paths.unit}`);
+        }
+        // macOS (and Linux without a user systemd): a detached new session. Task 0 verified it survives launchd
+        // bootout/bootstrap/kickstart and kill -9 of the daemon (docs/superpowers/reports/2026-10-11-keeper-launch-spike.md).
+        // `detached` is what makes it survive; do not add launchd keys or drop it.
+        const child = spawn(nodePath, [script, config], { detached: true, stdio: 'ignore' });
+        child.on('error', () => { });
+        child.unref();
+    }
+    /**
+     * Spec §3.1: a socket that fell back to `/tmp` (its configDir path is too long for sockaddr_un) is touched for every generation
+     * of `kind` with a run directory, so a periodic /tmp cleaner (macOS removes files unused for days) never reaps a live keeper's
+     * socket. Sockets under configDir are left alone. Returns how many were touched; never throws.
+     */
+    async touchSockets(kind) {
+        const runRoot = path.join(this.pathsFor(kind, 'probe').root, 'run');
+        let touched = 0;
+        for (const gen of await fs.readdir(runRoot).catch(() => [])) {
+            const paths = this.pathsFor(kind, gen);
+            if (paths.socketFallback && await touchSocket(paths).catch(() => false))
+                touched += 1;
+        }
+        return touched;
+    }
+    /** Removes bundle snapshots no live keeper references (never the daemon's current builds). */
+    gc(minAgeMs) {
+        return gcBundles({ configDir: this.options.configDir, keep: this.current, minAgeMs });
+    }
+    /**
+     * Stops generation `gen` of `kind`. `graceful` asks the keeper (`keeper.stop`) and waits; it never escalates, so a
+     * keeper that refuses stays up. `force` additionally stops the transient unit and finally SIGKILLs the pid from the
+     * manifest, but only if that pid is still running this keeper's snapshot (guards against pid reuse). A manifest whose pid
+     * is dead or belongs to another program is stale: it is cleaned up and reported as stopped, nothing is signalled.
+     */
+    async stop(kind, gen, mode, waitMs = 5000) {
+        const paths = this.pathsFor(kind, gen);
+        const manifest = await readPidManifest(paths.pidFile);
+        if (!manifest || manifest.identity !== paths.identity || manifest.kind !== kind || manifest.gen !== gen)
+            return { stopped: true, pid: null };
+        const pid = manifest.pid;
+        if (!await manifestProcessLive(manifest)) { // dead, or the pid now belongs to an unrelated process: the manifest is stale
+            await fs.unlink(paths.socket).catch(() => { });
+            await fs.unlink(paths.pidFile).catch(() => { });
+            return { stopped: true, pid: null };
+        }
+        const dead = async (ms) => {
+            const until = Date.now() + ms;
+            while (pidAlive(pid)) {
+                if (Date.now() >= until)
+                    return false;
+                await delay(25);
+            }
+            return true;
+        };
+        // keeper.stop needs the connection token (the daemon owns the run directory it lives in). Without a usable token
+        // the keeper cannot be asked, so after the same identity check the force path uses, SIGTERM it (its handler is the graceful stop).
+        let reason;
+        let token;
+        try {
+            token = await readKeeperToken(paths.tokenFile);
+        }
+        catch (error) {
+            reason = `keeper token unavailable: ${error.message}`;
+        }
+        if (token) {
+            try {
+                await keeperOneShot(paths.socket, 'keeper.stop', { mode }, 1000, { kind, token });
+            }
+            catch (error) {
+                reason = `keeper.stop failed: ${error.message}`;
+            }
+        }
+        else if (((await processCommand(pid)) ?? '').includes(manifest.bundleDir)) {
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch { /* already gone */ }
+        }
+        if (!await dead(mode === 'force' ? 1000 : waitMs) && mode === 'force') {
+            if (process.platform === 'linux')
+                await runQuiet('systemctl', ['--user', 'stop', paths.unit], 2000);
+            if (!await dead(500) && ((await processCommand(pid)) ?? '').includes(manifest.bundleDir)) {
+                try {
+                    process.kill(pid, 'SIGKILL');
+                }
+                catch { /* already gone */ }
+                await dead(waitMs);
+            }
+        }
+        if (pidAlive(pid))
+            return { stopped: false, pid, ...(reason ? { reason } : {}) };
+        await fs.unlink(paths.socket).catch(() => { });
+        await fs.unlink(paths.pidFile).catch(() => { });
+        return { stopped: true, pid, ...(reason ? { reason } : {}) };
+    }
+}
+export { BundleIntegrityError, keeperOneShot };

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

@@ -0,0 +1,123 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import net from 'node:net';
+const MAX_MANIFEST_BYTES = 4096;
+export function pidAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+const readProcCmdline = (pid) => fs.readFile(`/proc/${pid}/cmdline`);
+/** A `ps` that has not answered by then is killed; the answer is then "cannot tell" (null), which callers treat conservatively. */
+export const PS_TIMEOUT_MS = 2000;
+function processCommandFromPs(pid) {
+    return new Promise((resolve) => execFile('ps', ['-ww', '-p', String(pid), '-o', 'command='], { timeout: PS_TIMEOUT_MS }, (error, stdout) => {
+        if (!error) {
+            resolve(stdout.trim());
+            return;
+        }
+        resolve(error.code === 1 ? '' : null); // ps exits 1 for "no such process"; killed by the timeout: null
+    }));
+}
+/**
+ * The full command line of `pid`, '' when no such process, null when it cannot be determined so callers can stay conservative.
+ * Linux reads `/proc/<pid>/cmdline` (NUL-separated arguments, joined with spaces): Debian-slim workstation images may have no
+ * `ps`, and busybox `ps` exits 1 on unknown flags, which would read as "no such process". macOS uses `ps -ww` (it truncates
+ * to the terminal width otherwise).
+ */
+export async function processCommand(pid, deps = {}) {
+    if ((deps.platform ?? process.platform) !== 'linux')
+        return processCommandFromPs(pid);
+    const read = deps.readCmdline ?? readProcCmdline;
+    try {
+        return (await read(pid)).toString('utf8').split('\0').filter((part) => part.length > 0).join(' ');
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT' && code !== 'ESRCH')
+            return null;
+        // Without /proc mounted every pid is ENOENT; only a readable /proc/self proves the pid really is gone.
+        try {
+            await read('self');
+            return '';
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Whether the process named by `manifest.pid` is that keeper. The run dir lives under configDir and survives reboots,
+ * so a stale manifest's pid may now belong to anything. A keeper is started as `node <bundleDir>/keeper.mjs <config>`,
+ * so its command line must contain its bundleDir. If the command cannot be read at all, assume it is alive (never
+ * risk unlinking the socket of a live keeper); keepers must therefore not rewrite `process.title`.
+ */
+export async function manifestProcessLive(manifest) {
+    if (!pidAlive(manifest.pid))
+        return false;
+    const command = await processCommand(manifest.pid);
+    return command === null ? true : command.includes(manifest.bundleDir);
+}
+export async function writePidManifest(pidFile, manifest) {
+    const temp = `${pidFile}.${randomUUID()}.tmp`;
+    await fs.writeFile(temp, JSON.stringify(manifest), { mode: 0o600 });
+    await fs.rename(temp, pidFile);
+}
+function validManifest(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const m = value;
+    return (m.kind === 'terminal' || m.kind === 'acp') && typeof m.gen === 'string' && typeof m.buildVersion === 'string'
+        && typeof m.bundleDir === 'string' && typeof m.identity === 'string'
+        && Number.isFinite(m.startedAt) && Number.isSafeInteger(m.pid);
+}
+/** The manifest at `pidFile`, null when there is none. Anything malformed throws: it must not be mistaken for "no keeper". */
+export async function readPidManifest(pidFile) {
+    try {
+        const stat = await fs.lstat(pidFile);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_MANIFEST_BYTES)
+            throw new Error('Invalid keeper PID manifest');
+        const value = JSON.parse(await fs.readFile(pidFile, 'utf8'));
+        if (!validManifest(value))
+            throw new Error('Invalid keeper PID manifest');
+        return value;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+/**
+ * True when the manifest names a live process that is exactly this keeper (see `manifestProcessLive`). A probe timeout is not process death:
+ * a busy keeper can be slow to ping, and unlinking its live socket would orphan everything it hosts.
+ */
+export async function liveManifest(paths) {
+    const manifest = await readPidManifest(paths.pidFile);
+    if (!manifest)
+        return false;
+    if (manifest.identity !== paths.identity || manifest.kind !== paths.kind || manifest.gen !== paths.gen)
+        throw new Error('Keeper identity mismatch');
+    return manifestProcessLive(manifest);
+}
+/**
+ * A kernel bind is an atomic cross-process lock with automatic release on process death. It carries no
+ * requests and needs no stale-file unlink or ownership-blind cleanup. A rare port collision only serialises startup.
+ */
+export function acquireStartupLock(port) {
+    return new Promise((resolve, reject) => {
+        const lock = net.createServer((socket) => socket.destroy());
+        lock.once('error', reject);
+        lock.listen({ host: '127.0.0.1', port, exclusive: true }, () => resolve(lock));
+    });
+}
+export function releaseStartupLock(lock) {
+    return new Promise((resolve) => lock.close(() => resolve()));
+}

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

@@ -0,0 +1,86 @@
+// PID-reuse-safe process identity for keeper processes (keeper-terminal execs, keeper-acp adapters), and what a restarted keeper does with a group whose keeper died
+// while it ran (spec §4.2, analysis E §6.1). Keeper-side module: node builtins and kit siblings only (the import guard enforces it).
+//
+// A process is identified by (pid, start time). The start time is read once, right after spawn, and later compared EXACTLY:
+//   - Linux: `linux:<boot_id>:<starttime>` (field 22 of /proc/<pid>/stat, clock ticks since boot; boot_id makes a reboot never match);
+//   - macOS: `darwin:<lstart>` from `ps -o lstart=` under LC_ALL=C and TZ=UTC (an absolute wall-clock second, stable across
+//     reboots and time-zone changes).
+// A pid whose start time cannot be read, or reads differently, is NOT the process that was spawned: it is never signalled.
+import { execFile } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+const procStat = (pid) => readFileSync(`/proc/${pid}/stat`, 'utf8');
+const procBootId = () => readFileSync('/proc/sys/kernel/random/boot_id', 'utf8');
+function darwinLstart(pid) {
+    return new Promise((resolve) => {
+        execFile('/bin/ps', ['-o', 'lstart=', '-p', String(pid)], { timeout: 5000, env: { LC_ALL: 'C', TZ: 'UTC', PATH: '/bin:/usr/bin' } }, (error, stdout) => {
+            if (!error) {
+                resolve(stdout.trim());
+                return;
+            }
+            resolve(error.code === 1 ? '' : null); // ps exits 1 for "no such process"
+        });
+    });
+}
+/** `starttime` (field 22) of a /proc/<pid>/stat line; the command name (field 2) may hold spaces and parentheses. */
+export function linuxStartTicks(stat) {
+    const close = stat.lastIndexOf(')');
+    if (close < 0)
+        return null;
+    const fields = stat.slice(close + 2).trim().split(/\s+/); // fields[0] is field 3 (state)
+    const ticks = fields[19];
+    return ticks && /^\d+$/.test(ticks) ? ticks : null;
+}
+/** The start-time token of `pid`, or null when there is no such process or it cannot be read. */
+export async function processStartTime(pid, deps = {}) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    const platform = deps.platform ?? process.platform;
+    if (platform === 'linux') {
+        try {
+            const ticks = linuxStartTicks((deps.readStat ?? procStat)(pid));
+            const boot = (deps.readBootId ?? procBootId)().trim();
+            return ticks && boot ? `linux:${boot}:${ticks}` : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    const lstart = await (deps.psLstart ?? darwinLstart)(pid);
+    return lstart ? `${platform}:${lstart.replace(/\s+/g, ' ')}` : null;
+}
+/** True only when `pid` runs now AND started at exactly `startTime` (so it is the process that was spawned, not a reuse of its pid). */
+export async function sameProcess(pid, startTime, deps = {}) {
+    if (!startTime)
+        return false;
+    return (await processStartTime(pid, deps)) === startTime;
+}
+/** Sends `signal` to process group `pgid`; false when the group is gone (or the signal could not be sent). */
+export function signalGroup(pgid, signal) {
+    if (!Number.isSafeInteger(pgid) || pgid <= 1)
+        return false;
+    try {
+        process.kill(-pgid, signal);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Applies `onKeeperLoss` to one orphaned exec (spawned, no exit, its keeper gone). `kill`: only after `sameProcess(pid, startTime)`
+ * holds, SIGTERM the group now and SIGKILL it `killGraceMs` later. The SIGKILL goes to the group even when the leader has died
+ * from the SIGTERM (members that ignore it must still die): a process group id is not reused while any member lives, so within
+ * the grace the id still names our group, or nothing. A group whose leader already ended before the sweep (or whose start time
+ * was never recorded) cannot be verified and is left alone: never signal what cannot be proven to be ours.
+ */
+export async function settleOrphan(spawn, onKeeperLoss, killGraceMs, deps = {}) {
+    if (!(await sameProcess(spawn.pid, spawn.startTime, deps)))
+        return 'gone';
+    if (onKeeperLoss === 'leave')
+        return 'left';
+    const send = deps.signal ?? signalGroup;
+    send(spawn.pgid, 'SIGTERM');
+    const later = deps.later ?? ((ms, run) => { setTimeout(run, ms).unref(); });
+    later(killGraceMs, () => { send(spawn.pgid, 'SIGKILL'); });
+    return 'killed';
+}

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

@@ -0,0 +1,75 @@
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { keeperIdentity, keeperUnit } from './identity.js';
+export const KEEPER_PORT_MIN = 18000;
+export const KEEPER_PORT_MAX = 19999;
+/** sockaddr_un.sun_path sizes, including the terminating NUL. */
+export const SOCKADDR_LIMIT = { darwin: 104, linux: 108 };
+export function socketLimit(platform = process.platform) {
+    return platform === 'darwin' ? SOCKADDR_LIMIT.darwin : SOCKADDR_LIMIT.linux;
+}
+/** Startup-lock port derived from (identity, gen), inside the keeper range 18000-19999. */
+export function keeperLockPort(identity, gen) {
+    const digest = createHash('sha256').update(`${identity}:${gen}`).digest('hex');
+    return KEEPER_PORT_MIN + (Number.parseInt(digest.slice(0, 8), 16) % (KEEPER_PORT_MAX - KEEPER_PORT_MIN + 1));
+}
+export function keeperPaths(input, kind, gen, options = {}) {
+    const identity = keeperIdentity(input, kind);
+    const root = path.join(path.resolve(input.configDir), 'keepers', kind);
+    const runDir = path.join(root, 'run', gen);
+    let socket = path.join(runDir, 'keeper.sock');
+    let socketDir = runDir;
+    let socketFallback = false;
+    // Only the socket may leave configDir. A path of `limit` bytes or more leaves no room for the NUL.
+    if (Buffer.byteLength(socket) >= socketLimit(options.platform)) {
+        socketDir = path.join(options.fallbackRoot ?? '/tmp', `axom-keeper-${options.uid ?? process.getuid?.() ?? 'user'}`);
+        socket = path.join(socketDir, `${identity}-${gen}.sock`);
+        socketFallback = true;
+    }
+    return {
+        kind, identity, gen, unit: keeperUnit(kind, identity, gen), root,
+        bundlesDir: path.join(root, 'bundles'), runDir, dataDir: path.join(root, 'data'),
+        socket, socketFallback, socketDir,
+        pidFile: path.join(runDir, 'keeper.pid.json'), tokenFile: path.join(runDir, 'token'),
+        lockPort: keeperLockPort(identity, gen),
+    };
+}
+export function bundleDirFor(paths, buildVersion) {
+    return path.join(paths.bundlesDir, buildVersion);
+}
+/** Creates `dir` (and parents) as a private 0700 directory owned by this user; refuses symlinks and foreign owners. */
+export async function privateDirectory(dir) {
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    const stat = await fs.lstat(dir);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()))
+        throw new Error('Unsafe keeper state directory');
+    await fs.chmod(dir, 0o700);
+}
+/** Creates the keeper's private directories (root, data, run/<gen>, and the fallback socket dir if used). */
+export async function ensureKeeperDirectories(paths) {
+    const configKeepers = path.dirname(paths.root);
+    await privateDirectory(configKeepers);
+    for (const dir of [paths.root, paths.bundlesDir, path.dirname(paths.runDir), paths.runDir, paths.dataDir])
+        await privateDirectory(dir);
+    if (paths.socketFallback)
+        await privateDirectory(paths.socketDir);
+}
+/**
+ * The daemon calls this on every heartbeat for a fallback socket so periodic /tmp cleaners (macOS removes
+ * long-unused files) never reap it. A no-op for sockets under configDir. Returns false when the socket is gone.
+ */
+export async function touchSocket(paths) {
+    if (!paths.socketFallback)
+        return true;
+    const now = new Date();
+    try {
+        await fs.utimes(paths.socket, now, now);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}

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

@@ -0,0 +1,43 @@
+export const FRAME_LIMITS = {
+    terminal: { in: 128 * 1024, out: 2 * 1024 * 1024 },
+    acp: { in: 32 * 1024 * 1024, out: 32 * 1024 * 1024 },
+};
+/** Frame cap for a connection whose kind is not known (probes, diagnostics). */
+export const UNKNOWN_KIND_LIMITS = { in: 1024 * 1024, out: 1024 * 1024 };
+export const frameLimitsOf = (kind) => (kind ? FRAME_LIMITS[kind] : UNKNOWN_KIND_LIMITS);
+export const MAX_CONNECTIONS = 32;
+/** Largest frame accepted from a connection that has not completed `keeper.hello` (hello and ping are tiny). */
+export const PRE_HELLO_MAX_BYTES = 64 * 1024;
+/** Max records in one pushed `evt` frame. */
+export const MAX_EVT_RECORDS = 256;
+/** The daemon speaks `[N-1, N]` of every kind; protocol upgrades may only remove N-2. */
+export const protocolWindow = (current) => [Math.max(0, current - 1), current];
+export const inProtocolWindow = (window, version) => version >= window[0] && version <= window[1];
+export function isProtocolWindow(value) {
+    return Array.isArray(value) && value.length === 2 && Number.isSafeInteger(value[0]) && Number.isSafeInteger(value[1])
+        && value[0] >= 0 && value[0] <= value[1];
+}
+/** Methods every keeper answers. `keeper.ping` works before hello; everything else needs a hello. */
+export const GENERIC_METHODS = ['keeper.hello', 'keeper.ping', 'keeper.info', 'keeper.activity', 'keeper.drain', 'keeper.stop', 'keeper.subscribe', 'keeper.unsubscribe'];
+/** Still allowed on a connection to a keeper outside the daemon's protocol window (so policy code can drain/stop/inspect it). */
+export const WINDOW_EXEMPT_METHODS = new Set(['keeper.ping', 'keeper.info', 'keeper.activity', 'keeper.drain', 'keeper.stop']);
+export const ErrorCode = {
+    badRequest: 'bad_request',
+    unauthenticated: 'unauthenticated',
+    badToken: 'bad_token',
+    unknownMethod: 'unknown_method',
+    unknownStream: 'unknown_stream',
+    frameTooLarge: 'frame_too_large',
+    /** A method that starts new work was called on a keeper that is draining or stopping. */
+    draining: 'draining',
+    internal: 'internal',
+};
+/** Thrown by a method handler to answer with a specific wire error code. Any other exception answers `internal`. */
+export class KeeperMethodError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'KeeperMethodError';
+    }
+}