@platless/axom-cli 0.3.13 → 0.5.9

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

@@ -0,0 +1,101 @@
+// Daemon-side: a typed `acp.*` client for keeper-acp (launch through KeeperLauncher, one long-lived KeeperClient per generation).
+// Exempt from the keeper-side import guard (it runs in the daemon), though it imports nothing but the kit and this keeper's protocol.
+import { KeeperClient } from '../kit/client.js';
+import { protocolWindow } from '../kit/protocol.js';
+import { ACP_PROTOCOL_VERSION, acpStream, } from './protocol.js';
+/** keeper-acp could not be reached (launch, connect or hello failed): the request was never sent. */
+export class AcpKeeperUnavailableError extends Error {
+    cause;
+    code = 'launch_failed';
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.cause = cause;
+        this.name = 'AcpKeeperUnavailableError';
+    }
+}
+export class AcpKeeperClient {
+    options;
+    client;
+    clientGen;
+    lostListeners = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    get daemonProtocol() { return this.options.daemonProtocol ?? protocolWindow(ACP_PROTOCOL_VERSION); }
+    clientFor(paths) {
+        if (this.client && this.clientGen === paths.gen)
+            return this.client;
+        this.client?.close();
+        this.client = new KeeperClient({
+            kind: 'acp', socket: paths.socket, tokenFile: paths.tokenFile, gen: paths.gen, daemonProtocol: this.daemonProtocol,
+            requestTimeoutMs: this.options.requestTimeoutMs, connectTimeoutMs: this.options.connectTimeoutMs,
+        });
+        this.client.on('error', () => { });
+        // An established connection dropped (keeper-acp died or restarted): the kit client reconnects to the same socket by itself, but
+        // nothing relaunches a keeper that is gone until a request is made — the sessions re-attach (Task 21), which does.
+        this.client.on('disconnected', (error) => { for (const listener of [...this.lostListeners])
+            listener(error); });
+        this.clientGen = paths.gen;
+        return this.client;
+    }
+    /** Called when an established connection to keeper-acp drops (not when this client is closed). Returns the unsubscribe. */
+    onConnectionLost(listener) {
+        this.lostListeners.add(listener);
+        return () => { this.lostListeners.delete(listener); };
+    }
+    get hello() { return this.client?.state === 'ready' ? this.client.hello : undefined; }
+    /** The generation this client is bound to (`gen`), or `undefined` for the current build's. */
+    get gen() { return this.options.gen; }
+    /** The connected client of the current build, launching keeper-acp only when needed (a `gen`-bound client only connects). */
+    async ensure() {
+        const current = this.client;
+        if (current && current.state === 'ready')
+            return current;
+        if (this.options.gen !== undefined) {
+            if (!this.options.launcher.pathsFor)
+                throw new Error('A generation-bound keeper-acp client needs launcher.pathsFor');
+            const client = this.clientFor(this.options.launcher.pathsFor('acp', this.options.gen));
+            await client.connect();
+            return client;
+        }
+        const handle = await this.options.launcher.launch('acp');
+        const client = this.clientFor(handle.paths);
+        await client.connect();
+        return client;
+    }
+    async call(method, params, options = {}) {
+        let client;
+        try {
+            client = await this.ensure();
+        }
+        catch (error) {
+            throw new AcpKeeperUnavailableError(error);
+        }
+        return client.request(method, params, options);
+    }
+    spawn(params, options = {}) { return this.call('acp.spawn', params, options); }
+    list() { return this.call('acp.list', {}); }
+    attach(sessionKey) { return this.call('acp.attach', { sessionKey }); }
+    write(params) { return this.call('acp.write', params); }
+    note(params) { return this.call('acp.note', params); }
+    read(params) { return this.call('acp.read', params); }
+    downs(sessionKey, from = 0) { return this.call('acp.downs', { sessionKey, from }); }
+    outboxAppend(params) { return this.call('acp.outbox.append', params); }
+    commit(params) { return this.call('acp.commit', params); }
+    /** Waits for the exit record (TERM → grace → KILL → 2 s → pipes closed); allow for both graces. */
+    terminate(params) { return this.call('acp.terminate', params, { timeoutMs: (params.graceMs ?? 2000) + 10_000 }); }
+    release(sessionKey) { return this.call('acp.release', { sessionKey }); }
+    activity() { return this.call('keeper.activity', {}); }
+    async subscribe(sessionKey, stream, handler, options) {
+        let client;
+        try {
+            client = await this.ensure();
+        }
+        catch (error) {
+            throw new AcpKeeperUnavailableError(error);
+        }
+        return client.subscribe(acpStream(stream, sessionKey), handler, options);
+    }
+    /** Drops the connection (keeper-acp and its adapters keep running). */
+    disconnect() { this.client?.close(); this.client = undefined; this.clientGen = undefined; }
+}

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

@@ -0,0 +1,62 @@
+// Envelope diagnostics for keeper-acp (spec §5.3): sniff only a JSON-RPC line's `id` and `method`, and keep the requests each
+// direction has not answered yet. For diagnostics and activity only — the processor's checkpoint plus replay is the truth.
+// Keeper-side module: node builtins and kit siblings only (the import guard enforces it).
+import { ACP_ENVELOPE_PENDING, ACP_ENVELOPE_SNIFF_BYTES } from './protocol.js';
+/** `id`/`method` of a JSON-RPC object line, or undefined (not sniffable: too long, not JSON, not an object). */
+export function sniffEnvelope(line) {
+    if (line.length > ACP_ENVELOPE_SNIFF_BYTES)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const message = value;
+    const id = typeof message.id === 'string' || typeof message.id === 'number' ? JSON.stringify(message.id) : undefined;
+    const method = typeof message.method === 'string' ? message.method.slice(0, 128) : undefined;
+    return { ...(id !== undefined ? { id } : {}), ...(method !== undefined ? { method } : {}) };
+}
+/** Unpaired requests per direction. A request is a line with both `id` and `method`; a response is `id` without `method`. */
+export class EnvelopeTracker {
+    /** Daemon → adapter requests (down lines) awaiting an up response. */
+    outbound = new Map();
+    /** Adapter → daemon requests (up lines) awaiting a down response. */
+    inbound = new Map();
+    lastUp = null;
+    lastDown = null;
+    unsniffed = 0;
+    /** A new process: nothing from the previous one can be answered any more. */
+    reset() { this.outbound.clear(); this.inbound.clear(); }
+    up(line, at) { this.lastUp = at; this.observe(line, at, this.inbound, this.outbound); }
+    down(line, at) { this.lastDown = at; this.observe(line, at, this.outbound, this.inbound); }
+    observe(line, at, mine, theirs) {
+        const envelope = sniffEnvelope(line);
+        if (!envelope) {
+            this.unsniffed += 1;
+            return;
+        }
+        if (envelope.id === undefined)
+            return; // a notification
+        if (envelope.method !== undefined) {
+            mine.delete(envelope.id); // re-insert at the end (most recent)
+            mine.set(envelope.id, { id: envelope.id, method: envelope.method, sinceEpochMs: at });
+            while (mine.size > ACP_ENVELOPE_PENDING)
+                mine.delete(mine.keys().next().value);
+        }
+        else
+            theirs.delete(envelope.id);
+    }
+    get pendingInboundCount() { return this.inbound.size; }
+    get pendingOutboundCount() { return this.outbound.size; }
+    snapshot() {
+        return {
+            pendingOutbound: [...this.outbound.values()].map((p) => ({ ...p })),
+            pendingInbound: [...this.inbound.values()].map((p) => ({ ...p })),
+            lastUpEpochMs: this.lastUp, lastDownEpochMs: this.lastDown, unsniffed: this.unsniffed,
+        };
+    }
+}

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

@@ -0,0 +1,419 @@
+// keeper-acp's host: the sessions it holds under `<configDir>/keepers/acp/data/sessions/<id>/`, the `acp.*` methods on the kit
+// server, start-up recovery, the disk guard and activity. Keeper-side module: node builtins and kit siblings only (guarded).
+//
+// On disk, per session (0700 directories, 0600 files, never /tmp):
+//   session.json  SessionMeta: key, opaque label, owner keeper, latest spawn identity (pid, pgid, start time), exit, removeOnExit.
+//                 Never env values or secrets. Atomically replaced.
+//   raw/          kit stream log: up / down / proc / note / err (+ gap, discontinuity); the processor's checkpoints live in its slots.
+//   outbox/       kit stream log: frame{seq, src, frame}; `committedTail` is its commit watermark.
+//   stderr.log    redacted stderr, rotated to stderr.log.1 at 1 MiB.
+import { createHash } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, renameSync, rmSync, statfs, writeSync } from 'node:fs';
+import path from 'node:path';
+import { manifestProcessLive } from '../kit/lock.js';
+import { KeeperMethodError } from '../kit/protocol.js';
+import { StreamLog } from '../kit/streamLog.js';
+import { annotationOf, bad, labelOf, noteOf, offsetOf, onlyKeys, outboxEntriesOf, redactionsOf, sessionKeyOf, spawnSpecOf, } from './params.js';
+import { ACP_CAPABILITY, ACP_DISK_CHECK_MS, ACP_MIN_FREE_DISK_BYTES, ACP_SESSION_LIMIT, AcpErrorCode, parseAcpStream, } from './protocol.js';
+import { SESSION_FILE, STDERR_FILE, listSessionDirs, readSessionMeta, settleLostAdapter, stderrTailOf } from './recover.js';
+import { AcpSession } from './session.js';
+const META_TMP = `${SESSION_FILE}.tmp`;
+function privateDir(dir) { mkdirSync(dir, { recursive: true, mode: 0o700 }); }
+function atomicJson(file, value) {
+    const temp = path.join(path.dirname(file), META_TMP);
+    const fd = openSync(temp, 'w', 0o600);
+    try {
+        const data = Buffer.from(JSON.stringify(value));
+        let written = 0;
+        while (written < data.length)
+            written += writeSync(fd, data, written, data.length - written);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(temp, file);
+}
+/** The session directory name: never the key itself (a daemon-chosen string), so no key can name a path. */
+export const sessionDirName = (sessionKey) => createHash('sha256').update(sessionKey).digest('hex').slice(0, 32);
+const labelText = (label) => {
+    for (const key of ['agentKey', 'agentId'])
+        if (typeof label[key] === 'string' && label[key])
+            return label[key].slice(0, 128);
+    return 'adapter';
+};
+export class AcpHost {
+    options;
+    sessions = new Map();
+    dirs = new Map();
+    sessionsDir;
+    now;
+    logLine;
+    diskTimer;
+    maintenanceTimer;
+    stdoutHeld = false;
+    stopping = false;
+    adopting;
+    /** Lost adapters of adopted sessions still being settled (SIGTERM, grace, SIGKILL), by key: a spawn into one waits (minor 8). */
+    settling = new Map();
+    constructor(options) {
+        this.options = options;
+        this.sessionsDir = path.join(options.dataDir, 'sessions');
+        this.now = options.now ?? Date.now;
+        this.logLine = options.log ?? (() => { });
+    }
+    report(error) { this.logLine(`acp: ${error instanceof Error ? error.message : String(error)}`); }
+    /** Start-up: adopt every session whose keeper is gone (keeper_lost), then start the disk guard and the periodic adoption. */
+    async open() {
+        privateDir(this.sessionsDir);
+        await this.adopt();
+        this.diskTimer = setInterval(() => { void this.checkDisk(); }, ACP_DISK_CHECK_MS);
+        this.diskTimer.unref();
+        void this.checkDisk();
+        this.maintenanceTimer = setInterval(() => { void this.adopt(); }, this.options.maintenanceMs ?? 60_000);
+        this.maintenanceTimer.unref();
+    }
+    async ownerAlive(owner) {
+        if (!owner || owner.pid === this.options.owner.pid)
+            return false; // ours (or nobody's): adopt
+        return (this.options.ownerAlive ?? manifestProcessLive)(owner);
+    }
+    /** Adopt now every session directory whose keeper is gone (what the periodic adoption does). */
+    adoptNow() { return this.adopt(); }
+    adopt() {
+        this.adopting ??= (async () => {
+            // One liveness probe per owner per pass (each may spawn `ps`): many directories of one older generation share its owner, and
+            // `acp.list` runs this pass every time (Task 21 fix round 2).
+            const alive = new Map();
+            const ownerAlive = (owner) => {
+                const key = JSON.stringify(owner ?? null);
+                let probe = alive.get(key);
+                if (!probe)
+                    alive.set(key, probe = this.ownerAlive(owner));
+                return probe;
+            };
+            for (const { dir, meta } of listSessionDirs(this.sessionsDir, (message) => this.logLine(`acp: ${message}`))) {
+                if (this.sessions.has(meta.sessionKey) || this.stopping)
+                    continue;
+                if (path.basename(dir) !== sessionDirName(meta.sessionKey)) {
+                    this.logLine(`acp: ${path.basename(dir)}: misnamed session directory, left alone`);
+                    continue;
+                }
+                try {
+                    if (await ownerAlive(meta.owner))
+                        continue;
+                    if (this.sessions.has(meta.sessionKey))
+                        continue;
+                    await this.adoptOne(dir, meta);
+                }
+                catch (error) {
+                    this.report(error);
+                }
+            }
+        })().finally(() => { this.adopting = undefined; });
+        return this.adopting;
+    }
+    async adoptOne(dir, meta) {
+        meta.owner = { ...this.options.owner };
+        // The lost adapter's removeOnExit, captured BEFORE the session is registered: once it is, a spawn into it replaces
+        // meta.removeOnExit with the new adapter's, which this cleanup must never remove (final review minor 8).
+        const lostRemoveOnExit = [...meta.removeOnExit];
+        const key = meta.sessionKey;
+        const session = this.openSession(dir, meta, { fresh: false });
+        this.sessions.set(key, session);
+        this.dirs.set(key, dir);
+        session.persist();
+        if (meta.spawn && !meta.exited) {
+            session.recordKeeperLost(stderrTailOf(dir));
+            // A spawn into the session waits until the lost adapter's group is settled (SIGKILL due) and its files are removed.
+            let settled;
+            const settling = new Promise((resolve) => { settled = resolve; });
+            this.settling.set(key, settling);
+            void settling.then(() => { if (this.settling.get(key) === settling)
+                this.settling.delete(key); });
+            let outcome;
+            try {
+                outcome = await settleLostAdapter(meta, () => { try {
+                    session.removeOnExit(lostRemoveOnExit);
+                }
+                finally {
+                    settled();
+                } }, this.options.sweep);
+            }
+            catch (error) {
+                settled();
+                throw error;
+            } // never leave a spawn waiting on a settle that failed
+            this.logLine(`acp: session ${key}: keeper lost; adapter group ${outcome}`);
+        }
+        else if (lostRemoveOnExit.length > 0)
+            session.removeOnExit(lostRemoveOnExit); // exited, but its keeper died before cleaning up
+    }
+    openSession(dir, meta, options) {
+        const onError = (error) => this.report(error);
+        const raw = StreamLog.open({ dir: path.join(dir, 'raw'), now: this.now, immediateKinds: ['proc'], onError, ...(options.baseOffset !== undefined ? { baseOffset: options.baseOffset } : {}) });
+        let outbox;
+        try {
+            outbox = StreamLog.open({ dir: path.join(dir, 'outbox'), now: this.now, immediateKinds: [], onError });
+        }
+        catch (error) {
+            raw.close();
+            throw error;
+        }
+        const session = new AcpSession({
+            meta, raw, outbox, freshRaw: options.fresh, detached: true, stderrFile: path.join(dir, STDERR_FILE),
+            saveMeta: (m) => atomicJson(path.join(dir, SESSION_FILE), m), now: this.now, log: this.logLine,
+        });
+        if (this.stdoutHeld)
+            session.holdStdout(true);
+        return session;
+    }
+    find(sessionKey) {
+        const session = this.sessions.get(sessionKey);
+        if (!session)
+            throw new KeeperMethodError(AcpErrorCode.notFound, 'ACP session not found');
+        return session;
+    }
+    // ---- methods ---------------------------------------------------------------------------------------------------------------
+    async spawn(params) {
+        onlyKeys(params, ['sessionKey', 'spec', 'label', 'baseOffset']);
+        const sessionKey = sessionKeyOf(params.sessionKey);
+        const spec = spawnSpecOf(params.spec, [this.options.dataDir]);
+        const label = labelOf(params.label);
+        const baseOffset = params.baseOffset === undefined ? undefined : offsetOf(params.baseOffset, 'baseOffset');
+        const existing = this.sessions.get(sessionKey);
+        if (existing) {
+            if (baseOffset !== undefined)
+                bad('baseOffset only applies to a new session');
+            await this.settling.get(sessionKey);
+            return existing.spawn(spec);
+        }
+        if (this.sessions.size >= ACP_SESSION_LIMIT)
+            throw new KeeperMethodError(AcpErrorCode.limit, 'Too many ACP sessions in keeper-acp');
+        const dir = path.join(this.sessionsDir, sessionDirName(sessionKey));
+        if (existsSync(dir)) {
+            // A directory this keeper does not hold. Another LIVE generation's session is never touched; a dead keeper's is adopted
+            // right here (keeper_lost, as the periodic adoption would, without waiting for it). A directory WITHOUT session.json (a start
+            // killed between mkdir and the metadata rename) names no owner and holds no acknowledged-anything: reclaimed. One whose
+            // session.json exists but cannot be read (corrupt, a future schema) is never deleted — its outbox may hold unacknowledged frames.
+            // Reclaiming relies on the daemon spawning a sessionKey in one keeper generation at a time (interface-contracts).
+            const found = readSessionMeta(dir);
+            if (found === 'unreadable')
+                throw new KeeperMethodError(AcpErrorCode.unreadable, 'This ACP session directory has unreadable metadata; it is left alone');
+            if (found !== 'absent') {
+                if (found.sessionKey !== sessionKey || await this.ownerAlive(found.owner))
+                    throw new KeeperMethodError(AcpErrorCode.foreign, 'This ACP session belongs to another keeper-acp');
+                if (!this.sessions.has(sessionKey))
+                    await this.adoptOne(dir, found);
+                const adopted = this.sessions.get(sessionKey);
+                if (baseOffset !== undefined)
+                    bad('baseOffset only applies to a new session');
+                await this.settling.get(sessionKey);
+                return adopted.spawn(spec);
+            }
+            rmSync(dir, { recursive: true, force: true });
+        }
+        const meta = { v: 1, sessionKey, label, createdAtMs: this.now(), owner: { ...this.options.owner }, spawn: null, exited: false, removeOnExit: [], lastExit: null };
+        let session;
+        try {
+            privateDir(dir);
+            atomicJson(path.join(dir, SESSION_FILE), meta);
+            session = this.openSession(dir, meta, { fresh: true, baseOffset });
+        }
+        catch (error) {
+            rmSync(dir, { recursive: true, force: true });
+            throw error;
+        }
+        this.sessions.set(sessionKey, session);
+        this.dirs.set(sessionKey, dir);
+        try {
+            return await session.spawn(spec);
+        }
+        catch (error) {
+            // A new session whose first spawn failed leaves nothing behind.
+            if (this.sessions.get(sessionKey) === session) {
+                this.sessions.delete(sessionKey);
+                this.dirs.delete(sessionKey);
+            }
+            session.close();
+            rmSync(dir, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    list() { return { sessions: [...this.sessions.values()].map((s) => s.summary()) }; }
+    attach(params) {
+        onlyKeys(params, ['sessionKey']);
+        return this.find(sessionKeyOf(params.sessionKey)).attach();
+    }
+    write(params) {
+        onlyKeys(params, ['sessionKey', 'spawnId', 'line', 'annotation', 'redact']);
+        const session = this.find(sessionKeyOf(params.sessionKey));
+        if (typeof params.spawnId !== 'string' || !params.spawnId)
+            bad('Invalid spawnId');
+        if (typeof params.line !== 'string')
+            bad('Invalid line');
+        return session.write(params.spawnId, params.line, annotationOf(params.annotation), redactionsOf(params.redact));
+    }
+    note(params) {
+        onlyKeys(params, ['sessionKey', 'note']);
+        return this.find(sessionKeyOf(params.sessionKey)).note(noteOf(params.note));
+    }
+    read(params) {
+        onlyKeys(params, ['sessionKey', 'stream', 'from', 'limit']);
+        const session = this.find(sessionKeyOf(params.sessionKey));
+        if (params.stream !== 'raw' && params.stream !== 'outbox')
+            bad('Invalid stream');
+        const limit = params.limit === undefined ? undefined : offsetOf(params.limit, 'limit', 1);
+        return session.read(params.stream, offsetOf(params.from, 'from'), limit);
+    }
+    downs(params) {
+        onlyKeys(params, ['sessionKey', 'from']);
+        return this.find(sessionKeyOf(params.sessionKey)).downsFrom(params.from === undefined ? 0 : offsetOf(params.from, 'from'));
+    }
+    outboxAppend(params) {
+        onlyKeys(params, ['sessionKey', 'entries']);
+        return this.find(sessionKeyOf(params.sessionKey)).outboxAppend(outboxEntriesOf(params.entries));
+    }
+    commit(params) {
+        onlyKeys(params, ['sessionKey', 'checkpoint', 'outbox', 'rawThrough']);
+        const session = this.find(sessionKeyOf(params.sessionKey));
+        const checkpoint = params.checkpoint;
+        const outbox = params.outbox;
+        if (checkpoint !== undefined && (typeof checkpoint !== 'object' || checkpoint === null || typeof checkpoint.blob !== 'string'))
+            bad('Invalid checkpoint');
+        if (outbox !== undefined && (typeof outbox !== 'object' || outbox === null || typeof outbox.tail !== 'object' || outbox.tail === null))
+            bad('Invalid outbox commit');
+        return session.commit({
+            ...(checkpoint ? { checkpoint: { offset: offsetOf(checkpoint.offset, 'checkpoint.offset', -1), blob: checkpoint.blob } } : {}),
+            ...(outbox ? { outbox: { through: offsetOf(outbox.through, 'outbox.through', -1), tail: outbox.tail } } : {}),
+            ...(params.rawThrough !== undefined ? { rawThrough: offsetOf(params.rawThrough, 'rawThrough', -1) } : {}),
+        });
+    }
+    async terminate(params) {
+        onlyKeys(params, ['sessionKey', 'graceMs']);
+        const session = this.find(sessionKeyOf(params.sessionKey));
+        const graceMs = params.graceMs === undefined ? undefined : Math.min(offsetOf(params.graceMs, 'graceMs'), 60_000);
+        return { exit: await session.terminate(graceMs) };
+    }
+    release(params) {
+        onlyKeys(params, ['sessionKey']);
+        const sessionKey = sessionKeyOf(params.sessionKey);
+        const session = this.find(sessionKey);
+        if (session.busy)
+            throw new KeeperMethodError(AcpErrorCode.busy, 'Terminate the process before releasing the session');
+        this.sessions.delete(sessionKey);
+        const dir = this.dirs.get(sessionKey);
+        this.dirs.delete(sessionKey);
+        session.close();
+        if (dir)
+            rmSync(dir, { recursive: true, force: true });
+        return { released: true };
+    }
+    source(stream) {
+        const parsed = parseAcpStream(stream);
+        return parsed ? this.sessions.get(parsed.sessionKey)?.source(parsed.stream) : undefined;
+    }
+    // ---- disk guard, activity, shutdown --------------------------------------------------------------------------------------------
+    async freeBytes() {
+        if (this.options.diskFree)
+            return this.options.diskFree();
+        return new Promise((resolve, reject) => statfs(this.sessionsDir, (error, stats) => (error ? reject(error) : resolve(Number(stats.bavail) * Number(stats.bsize)))));
+    }
+    /** Spec §3.4's hard limit: with less than 1 GiB free, adapter stdout is no longer read (the adapter blocks) until space returns. */
+    async checkDisk() {
+        let free;
+        try {
+            free = await this.freeBytes();
+        }
+        catch (error) {
+            this.report(error);
+            return;
+        }
+        const hold = free < ACP_MIN_FREE_DISK_BYTES;
+        if (hold === this.stdoutHeld)
+            return;
+        this.stdoutHeld = hold;
+        this.logLine(`acp: ${hold ? 'less than 1 GiB free: adapter stdout paused' : 'disk space back: adapter stdout resumed'}`);
+        for (const session of this.sessions.values())
+            session.holdStdout(hold);
+    }
+    /** Adapters this keeper runs now (any state but exited). */
+    get runningAdapters() { let count = 0; for (const session of this.sessions.values())
+        if (session.running)
+            count += 1; return count; }
+    /** Mechanical facts only (spec §3.5): sessions, running adapters, unanswered adapter requests; one item per session. */
+    activity() {
+        const items = [];
+        let running = 0;
+        let overQuota = 0;
+        let pendingInbound = 0;
+        for (const session of this.sessions.values()) {
+            const info = session.processInfo();
+            if (session.running)
+                running += 1;
+            if (session.overQuota)
+                overQuota += 1;
+            pendingInbound += session.pendingInbound;
+            const since = info.state === 'exited' ? (info.exit?.atMs ?? session.meta.createdAtMs) : info.state === 'none' ? session.meta.createdAtMs : info.sinceEpochMs;
+            items.push({ type: 'acp', id: session.sessionKey, label: labelText(session.meta.label), state: info.state, sinceEpochMs: since });
+        }
+        return { metrics: { sessions: this.sessions.size, sessionsRunning: running, sessionsOverQuota: overQuota, pendingInbound, stdoutPaused: this.stdoutHeld ? 1 : 0 }, items };
+    }
+    /** The keeper stops: every adapter is terminated (`keeper_stopped`; force: SIGKILL at once) and every stream closed. */
+    async dispose(mode = 'graceful') {
+        this.stopping = true;
+        clearInterval(this.diskTimer);
+        clearInterval(this.maintenanceTimer);
+        await Promise.all([...this.sessions.values()].map((s) => s.terminate(mode === 'force' ? 0 : 1500, 'keeper_stopped').catch((error) => this.report(error))));
+        for (const session of this.sessions.values())
+            session.close();
+    }
+}
+/**
+ * keeper-acp stops by itself once it has had no authenticated daemon connection AND no running adapter for this long (final review
+ * finding 4): a keeper an uninstalled or downgraded CLI left behind does not live forever. Any daemon connection, or any adapter
+ * running, restarts the clock.
+ */
+export const ACP_IDLE_EXIT_MS = 24 * 60 * 60 * 1000;
+/** How often the idle clock is looked at. */
+export const ACP_IDLE_CHECK_MS = 60_000;
+export function createAcpKeeper(host, options = {}) {
+    const now = options.now ?? Date.now;
+    let idleTimer;
+    return {
+        capabilities: [ACP_CAPABILITY],
+        install(server) {
+            // The idle self-exit: a graceful stop through the kit's stop path (shutdown, manifest and token removed, exit 0).
+            const idleExitMs = options.idleExitMs ?? ACP_IDLE_EXIT_MS;
+            let busyAt = now();
+            idleTimer = setInterval(() => {
+                if (server.authenticatedConnectionCount > 0 || host.runningAdapters > 0) {
+                    busyAt = now();
+                    return;
+                }
+                if (now() - busyAt < idleExitMs)
+                    return;
+                clearInterval(idleTimer);
+                options.log?.(`acp: no daemon connection and no running adapter for ${Math.round(idleExitMs / 60_000)} min; stopping`);
+                server.stopped('graceful');
+            }, options.idleCheckMs ?? ACP_IDLE_CHECK_MS);
+            idleTimer.unref();
+            server.register('acp.spawn', (params) => host.spawn(params), { startsWork: true });
+            // A listing first adopts what a keeper that is gone left (an older generation the daemon just stopped, Task 21): the daemon sees
+            // those sessions at once instead of after the next periodic adoption.
+            server.register('acp.list', async () => { await host.adoptNow(); return host.list(); });
+            server.register('acp.attach', (params) => host.attach(params));
+            server.register('acp.write', (params) => host.write(params));
+            server.register('acp.note', (params) => host.note(params));
+            server.register('acp.read', (params) => host.read(params));
+            server.register('acp.downs', (params) => host.downs(params));
+            server.register('acp.outbox.append', (params) => host.outboxAppend(params));
+            server.register('acp.commit', (params) => host.commit(params));
+            server.register('acp.terminate', (params) => host.terminate(params));
+            server.register('acp.release', (params) => host.release(params));
+            server.setStreamResolver((stream) => host.source(stream));
+            server.addActivitySampler(() => host.activity());
+        },
+        shutdown: (mode) => { clearInterval(idleTimer); return host.dispose(mode); },
+    };
+}

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

@@ -0,0 +1,18 @@
+// keeper-acp: hosts ACP adapter processes so they survive daemon restarts, upgrades and crashes (spec §5.3). Started by the daemon's
+// KeeperLauncher as `node <bundleDir>/keeper.mjs <launch config>`. It holds, per session, an ACP-agnostic ordered raw log, an outbox
+// and checkpoint slots; it never interprets ACP beyond sniffing `id`/`method` for diagnostics.
+// `scripts/bundle-keepers.mjs` reads `protocolVersion` below (the line must keep this exact shape) and `../daemonProtocol.json` for
+// the daemon protocol range. It must equal ACP_PROTOCOL_VERSION (protocol.ts).
+import { runKeeperMain } from '../kit/bootstrap.js';
+import { AcpHost, createAcpKeeper } from './host.js';
+export const protocolVersion = 1;
+await runKeeperMain({
+    kind: 'acp',
+    protocolVersion,
+    create: async (config, { log }) => {
+        // Sessions live under the kind's data dir (shared by its generations; each session belongs to the keeper process that owns it).
+        const host = new AcpHost({ dataDir: config.dataDir, owner: { pid: process.pid, gen: config.gen, bundleDir: config.bundleDir }, log });
+        await host.open(); // start-up recovery: sessions whose keeper died are exited (keeper_lost) before anyone can ask
+        return createAcpKeeper(host, { log });
+    },
+});