@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/acp/processor/test/largeIdEcho.js

@@ -0,0 +1,50 @@
+/**
+ * The large-id echo contract (spec 2026-10-11 §5.4, analysis A §3 "Risks"): outbound request ids are
+ * `o * 16 + i`, which on a long-lived session's log reach far past what any adapter sees today, so
+ * every adapter must echo a numeric id near 2^50 **exactly** — same number, still a number.
+ *
+ * {@link probeLargeIdEcho} is the reusable hook: it speaks raw ndjson to any launch spec, sends `initialize` and two `session/new`
+ * requests (Task 23's ruling: nothing else — no prompt, so no model usage; an agent that wants credentials answers `session/new`
+ * with an error, which echoes the id just the same), and reports what came back. `largeIdEcho.test.ts` runs it against
+ * `acp/test/fakeAgent.ts` and — with `AXOM_REAL_ADAPTER_SMOKE=1` — against the real claude and codex adapters
+ * ({@link REAL_ADAPTER_ECHO_TARGETS_T23}).
+ */
+import { AXOM_AGENT_CATALOG } from '../../registry/catalog.js';
+import { initializeRequestParams } from '../../initializeResponse.js';
+import { outboundRequestId } from '../jsonrpc.js';
+import { startRawAgent } from './rawAgent.js';
+/** Ids around 2^50, including one built the way the processor builds them. */
+export const LARGE_ECHO_IDS = [2 ** 50 - 1, 2 ** 50 + 15, outboundRequestId({ o: 2 ** 46 + 12_345, i: 7 })];
+/** Every catalog adapter that must echo large ids: Task 23 runs claude and codex ({@link REAL_ADAPTER_SMOKE_T23}); the rest wait for
+ * Task 30's real-machine acceptance. */
+export const REAL_ADAPTER_ECHO_TARGETS_T23 = AXOM_AGENT_CATALOG.map((entry) => entry.registryAgent);
+/** The adapters Task 23's smoke installs and probes (the ruling: claude and codex, `initialize`/`session/new` only). */
+export const REAL_ADAPTER_SMOKE_T23 = ['claude-acp', 'codex-acp'];
+/** Pull the top-level `"id":…` token out of a response line without going through `JSON.parse`. */
+function idToken(line) {
+    const match = /"id"\s*:\s*("(?:[^"\\]|\\.)*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|null)/.exec(line);
+    return match ? match[1] : '<none>';
+}
+export async function probeLargeIdEcho(launch, cwd, timeoutMs = 60_000) {
+    const agent = startRawAgent(launch);
+    const observations = [];
+    try {
+        const [initId, ...rest] = LARGE_ECHO_IDS;
+        const probes = [
+            ['initialize', initId, initializeRequestParams()],
+            ...rest.map((id) => ['session/new', id, { cwd, mcpServers: [] }]),
+        ];
+        for (const [method, id, params] of probes) {
+            agent.send(JSON.stringify({ jsonrpc: '2.0', id, method, params }));
+            // Match on the number *or* any other spelling of it, so a mangled echo is reported, not timed out.
+            const line = await agent.nextLine((m) => !('method' in m) && (m.id === id || String(m.id) === String(id) || Number(m.id) === id), timeoutMs);
+            const parsed = JSON.parse(line);
+            observations.push({ method, sent: id, echoedText: idToken(line), echoed: parsed.id,
+                ...(parsed.error ? { error: `${String(parsed.error.code)} ${String(parsed.error.message)}`.slice(0, 200) } : {}) });
+        }
+    }
+    finally {
+        await agent.close();
+    }
+    return observations;
+}

package/dist/workstation/acp/processor/test/rawAgent.js

@@ -0,0 +1,70 @@
+/**
+ * Drive an ACP agent process over raw ndjson stdio — no SDK on our side — so a test sees exactly the
+ * bytes each side wrote. Used by the processor's equivalence and large-id echo tests.
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const FAKE_AGENT = fileURLToPath(new URL('../../test/fakeAgent.ts', import.meta.url));
+const FAKE_BOOTSTRAP = "eval(require('node:fs').readFileSync(process.argv[1], 'utf8'))";
+/** `acp/test/fakeAgent.ts` as a real child process, configured exactly as `acpClient.test.ts` does. */
+export function fakeAgentLaunch(config = {}) {
+    return { command: process.execPath, args: ['-e', FAKE_BOOTSTRAP, FAKE_AGENT, JSON.stringify(config)] };
+}
+export function startRawAgent(launch) {
+    const child = spawn(launch.command, [...launch.args], {
+        env: launch.inheritEnv === false ? { ...launch.env } : { ...process.env, ...launch.env },
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const lines = [];
+    const waiters = [];
+    let buffer = '';
+    let stderr = '';
+    child.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+    child.stdout.on('data', (chunk) => {
+        buffer += chunk.toString('utf8');
+        let newline;
+        while ((newline = buffer.indexOf('\n')) >= 0) {
+            const line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            if (line.trim())
+                lines.push(line);
+        }
+        for (const wake of waiters.splice(0))
+            wake();
+    });
+    return {
+        send(line) {
+            child.stdin.write(`${line}\n`);
+        },
+        async nextLine(match, timeoutMs = 10_000) {
+            const deadline = Date.now() + timeoutMs;
+            for (;;) {
+                const index = lines.findIndex((line) => {
+                    try {
+                        return match(JSON.parse(line));
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+                if (index >= 0)
+                    return lines.splice(index, 1)[0];
+                const remaining = deadline - Date.now();
+                if (remaining <= 0 || child.exitCode !== null) {
+                    throw new Error(`no matching line from ${launch.command} (exit ${child.exitCode}); stderr: ${stderr.slice(-500)}`);
+                }
+                await new Promise((resolve) => {
+                    const timer = setTimeout(resolve, Math.min(remaining, 200));
+                    waiters.push(() => { clearTimeout(timer); resolve(); });
+                });
+            }
+        },
+        async close() {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            const exited = new Promise((resolve) => child.once('exit', () => resolve()));
+            child.kill();
+            await exited;
+        },
+    };
+}

package/dist/workstation/acp/processor/transport/generations.js

@@ -0,0 +1,76 @@
+/**
+ * keeper-acp generations, as the daemon sees them (Task 21, spec §5.5, §6.3): one keeper-acp per build ("generation") may be running,
+ * and after a CLI upgrade an **older** generation can still host live adapters. Those sessions are adopted where they are — the daemon
+ * attaches to each through the generation that hosts it and routes that session's IPC there — and stay there until §6.3 switching
+ * (Task 24) moves one at an `agent_open`. New sessions always go to the current build's generation.
+ *
+ * An older generation is never stopped while it hosts a running adapter; once it hosts none ({@link KeeperGenerations.stopIfIdle})
+ * it is asked to stop gracefully, and the current generation adopts the session directories it leaves (keeper-acp's own periodic
+ * adoption, or on the spot when a spawn needs one) — their outboxes survive.
+ */
+import { readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { AcpKeeperClient } from '../../../keepers/acp/client.js';
+import { sessionDirName } from '../../../keepers/acp/host.js';
+import { KeeperTransport } from './keeper.js';
+/** A process that is (or may still be) running an adapter: never stop the generation that hosts it. */
+export function hostsRunningAdapter(summary) {
+    return summary.process.state === 'starting' || summary.process.state === 'running' || summary.process.state === 'exiting';
+}
+export function keeperGenerations(options) {
+    const { launcher } = options;
+    const log = options.log ?? ((line) => console.warn(line));
+    const older = new Map();
+    let currentGen;
+    const current = () => {
+        currentGen ??= launcher.currentGen('acp').catch((error) => { currentGen = undefined; throw error; });
+        return currentGen;
+    };
+    const transportFor = async (gen) => {
+        if (gen === await current())
+            return options.current;
+        let transport = older.get(gen);
+        if (!transport)
+            older.set(gen, transport = new KeeperTransport(new AcpKeeperClient({ launcher, gen })));
+        return transport;
+    };
+    return {
+        current,
+        live: () => launcher.liveGenerations('acp'),
+        async hasSessionData() {
+            const dir = path.join(launcher.pathsFor('acp', await current()).dataDir, 'sessions');
+            return (await readdir(dir).catch(() => [])).length > 0;
+        },
+        async hasSessionDir(sessionKey) {
+            const dir = path.join(launcher.pathsFor('acp', await current()).dataDir, 'sessions', sessionDirName(sessionKey));
+            return stat(dir).then(() => true, (error) => { if (error.code === 'ENOENT')
+                return false; throw error; });
+        },
+        transportFor,
+        async stopIfIdle(gen, held) {
+            if (gen === await current())
+                return false;
+            const transport = await transportFor(gen);
+            let sessions;
+            try {
+                sessions = await transport.list();
+            }
+            catch {
+                return false;
+            } // unreachable: nothing to decide on
+            if (sessions.some(hostsRunningAdapter) || held?.())
+                return false;
+            transport.close();
+            older.delete(gen);
+            const result = await launcher.stop('acp', gen, 'graceful');
+            log(`[acp] keeper-acp generation ${gen} hosts no running adapter: ${result.stopped ? 'stopped' : `could not be stopped${result.reason ? ` (${result.reason})` : ''}`}` +
+                (sessions.length > 0 ? `; the current generation adopts its ${sessions.length} kept session(s)` : ''));
+            return result.stopped;
+        },
+        close() {
+            for (const transport of older.values())
+                transport.close();
+            older.clear();
+        },
+    };
+}

package/dist/workstation/acp/processor/transport/keeper.js

@@ -0,0 +1,130 @@
+import { CauseIndex, RawTruncatedError, SessionNotAttachedError, checkpointBlob, rawRecordOf, } from './types.js';
+/** Raw records in flight per subscription. */
+const RAW_WINDOW = 32;
+/**
+ * Raw bytes in flight per subscription (Task 20): one record can be a ~10 MB image prompt, so a window of records alone could
+ * park 32 of them in daemon memory. keeper-acp pushes at most this many bytes plus one record ahead of the processor loop.
+ */
+export const RAW_WINDOW_BYTES = 8 * 1024 * 1024;
+const toOutbox = (record) => ({ o: record.o, t: record.t, seq: record.seq, src: record.src, frame: record.frame });
+export class KeeperTransport {
+    client;
+    mode = 'keeper';
+    indexes = new Map();
+    constructor(client) {
+        this.client = client;
+    }
+    async spawn(sessionKey, spec, options) {
+        const result = await this.client.spawn({ sessionKey, spec, label: options.label, ...(options.baseOffset !== undefined ? { baseOffset: options.baseOffset } : {}) });
+        // A new session (its spawn record is its first record) has no downs yet; an existing one is indexed by `attach`.
+        if (result.o === (options.baseOffset ?? 0) && !this.indexes.has(sessionKey))
+            this.indexes.set(sessionKey, new CauseIndex());
+        return result;
+    }
+    async list() { return (await this.client.list()).sessions; }
+    async attach(sessionKey) {
+        const attached = await this.client.attach(sessionKey);
+        const { downs } = await this.client.downs(sessionKey, 0);
+        const index = new CauseIndex();
+        for (const down of downs)
+            index.add(down.cause, down.o);
+        this.indexes.set(sessionKey, index); // anything an earlier index knew is in raw, hence in `downs`
+        return attached;
+    }
+    hasDown(sessionKey, cause) {
+        const index = this.indexes.get(sessionKey);
+        if (!index)
+            throw new SessionNotAttachedError(sessionKey);
+        return index.has(cause);
+    }
+    observe(sessionKey, records) {
+        const index = this.indexes.get(sessionKey);
+        if (index)
+            for (const record of records)
+                index.observe(record);
+    }
+    async subscribeRaw(sessionKey, from, handler, options = {}) {
+        let expected = from;
+        let failed = false;
+        let subscription;
+        const fail = (error) => { if (failed)
+            return; failed = true; void subscription?.unsubscribe(); options.onClosed?.(error); };
+        subscription = await this.client.subscribe(sessionKey, 'raw', async (batch) => {
+            if (failed)
+                return;
+            if (batch.length > 0 && batch[0].o !== expected) {
+                fail(new RawTruncatedError(expected, batch[0].o));
+                return;
+            }
+            let records;
+            try {
+                records = batch.map((record) => rawRecordOf(record));
+            }
+            catch (error) {
+                fail(error instanceof Error ? error : new Error(String(error)));
+                return;
+            }
+            for (let i = 1; i < records.length; i++)
+                if (records[i].o !== records[i - 1].o + 1) {
+                    fail(new RawTruncatedError(records[i - 1].o + 1, records[i].o));
+                    return;
+                }
+            if (records.length === 0)
+                return;
+            expected = records[records.length - 1].o + 1;
+            this.observe(sessionKey, records);
+            await handler(records);
+        }, { from, window: options.window ?? RAW_WINDOW, windowBytes: options.windowBytes ?? RAW_WINDOW_BYTES, onClosed: (error) => fail(error) });
+        const inner = subscription;
+        return { get nextOffset() { return expected; }, unsubscribe: () => inner.unsubscribe() };
+    }
+    async readRaw(sessionKey, from, limit) {
+        const result = await this.client.read({ sessionKey, stream: 'raw', from, ...(limit !== undefined ? { limit } : {}) });
+        if (result.truncated)
+            throw new RawTruncatedError(from, result.first);
+        const records = result.records.map((record) => rawRecordOf(record));
+        this.observe(sessionKey, records);
+        return records;
+    }
+    async readOutbox(sessionKey, from, limit) {
+        const result = await this.client.read({ sessionKey, stream: 'outbox', from, ...(limit !== undefined ? { limit } : {}) });
+        return result.records.map(toOutbox);
+    }
+    async write(sessionKey, line, options) {
+        const result = await this.client.write({
+            sessionKey, spawnId: options.spawnId, line, annotation: { ...options.annotation },
+            ...(options.redact && options.redact.length > 0 ? { redact: options.redact.map((r) => ({ ref: r.ref, value: r.value })) } : {}),
+        });
+        if (result.status !== 'refused')
+            this.indexes.get(sessionKey)?.add(options.annotation.cause, result.o);
+        return result;
+    }
+    note(sessionKey, note) {
+        return this.client.note({ sessionKey, note: { ...note } });
+    }
+    appendOutbox(sessionKey, entries) {
+        return this.client.outboxAppend({ sessionKey, entries: [...entries] });
+    }
+    async commit(sessionKey, params) {
+        const result = await this.client.commit({
+            sessionKey,
+            ...(params.checkpoint ? { checkpoint: { offset: params.checkpoint.offset, blob: checkpointBlob(params.checkpoint.blob) } } : {}),
+            ...(params.outbox ? { outbox: { through: params.outbox.through, tail: { seq: params.outbox.tail.seq, src: { ...params.outbox.tail.src } } } } : {}),
+            ...(params.rawThrough !== undefined ? { rawThrough: params.rawThrough } : {}),
+        });
+        if (params.rawThrough !== undefined)
+            this.indexes.get(sessionKey)?.forgetThrough(params.rawThrough);
+        return result;
+    }
+    async terminate(sessionKey, graceMs) {
+        return (await this.client.terminate({ sessionKey, ...(graceMs !== undefined ? { graceMs } : {}) })).exit;
+    }
+    async release(sessionKey) {
+        await this.client.release(sessionKey);
+        this.indexes.delete(sessionKey);
+    }
+    close() { this.client.disconnect(); }
+    onConnectionLost(listener) {
+        return this.client.onConnectionLost?.(listener) ?? (() => { });
+    }
+}

package/dist/workstation/acp/processor/transport/local.js

@@ -0,0 +1,269 @@
+/**
+ * The fallback transport (spec 2026-10-11 §5.7: keeper-acp unavailable or protocol-incompatible): the same session mechanism as
+ * keeper-acp (`keepers/acp/session.ts`), in the daemon. The adapter is a plain daemon child (signalled alone, as today's
+ * `closeAgentTransport` does), raw lives in memory, and the outbox is a kit stream log under
+ * `<configDir>/agents/local/<sessionKey>/` — today's journal guarantee: unacknowledged frames survive a daemon crash. Sessions do not
+ * survive the daemon (as today); an outbox left behind by a previous daemon is listed (`raw: null`) so its frames can be offered once
+ * and then released.
+ *
+ * Because the session code is shared, the same adapter traffic yields the same records as through keeper-acp.
+ */
+import { createHash } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { sessionKeyOf, spawnSpecOf } from '../../../keepers/acp/params.js';
+import { MemoryStream } from '../../../keepers/acp/memoryStream.js';
+import { AcpErrorCode } from '../../../keepers/acp/protocol.js';
+import { AcpSession } from '../../../keepers/acp/session.js';
+import { KeeperMethodError } from '../../../keepers/kit/protocol.js';
+import { StreamLog } from '../../../keepers/kit/streamLog.js';
+import { DAEMON_FRAME_INDEX } from '../../outbox.js';
+import { RawTruncatedError, checkpointBlob, rawRecordOf, } from './types.js';
+const DEFAULT_WINDOW = 32;
+/** Longest directory name used as is (file systems cap a name at 255 bytes); longer keys get a hashed name. */
+const MAX_DIR_NAME = 200;
+/** The key of a hashed directory, stored beside the outbox's own files (the stream log ignores it). */
+const KEY_FILE = 'session-key';
+/**
+ * A session key as a directory name: percent-encoded (keys are daemon strings, not paths), never `.`/`..`; a key whose encoding
+ * is longer than {@link MAX_DIR_NAME} becomes `~<sha256(key)[:32]>` and its key is kept in `session-key`.
+ */
+export function localSessionDir(root, sessionKey) {
+    const name = encodeURIComponent(sessionKey).replace(/^\.+$/, (dots) => '%2E'.repeat(dots.length));
+    return path.join(root, name.length <= MAX_DIR_NAME ? name : `~${createHash('sha256').update(sessionKey).digest('hex').slice(0, 32)}`);
+}
+const toOutbox = (record) => ({ o: record.o, t: record.t, seq: record.seq, src: record.src, frame: record.frame });
+export class LocalTransport {
+    options;
+    mode = 'local';
+    root;
+    entries = new Map();
+    now;
+    logLine;
+    constructor(options) {
+        this.options = options;
+        this.root = path.join(options.configDir, 'agents', 'local');
+        this.now = options.now ?? Date.now;
+        this.logLine = options.log ?? (() => { });
+    }
+    open(sessionKey, label, baseOffset, orphan) {
+        const dir = localSessionDir(this.root, sessionKey);
+        if (path.basename(dir).startsWith('~')) {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            writeFileSync(path.join(dir, KEY_FILE), sessionKey, { mode: 0o600 });
+        }
+        const meta = { v: 1, sessionKey, label, createdAtMs: this.now(), spawn: null, exited: false, removeOnExit: [], lastExit: null };
+        const outbox = StreamLog.open({ dir, now: this.now, immediateKinds: [], onError: (error) => this.logLine(`acp local ${sessionKey}: ${error.message}`) });
+        const session = new AcpSession({
+            meta, raw: new MemoryStream({ now: this.now, ...(baseOffset !== undefined ? { baseOffset } : {}) }), outbox, freshRaw: true, detached: false,
+            saveMeta: () => { }, now: this.now, log: this.logLine,
+        });
+        const entry = { session, dir, orphan };
+        this.entries.set(sessionKey, entry);
+        return entry;
+    }
+    /**
+     * Writes an outbox for `sessionKey` holding `records` (a legacy journal's entries, Task 20) — listed afterwards like any outbox a
+     * previous daemon left. Built under a staging name and renamed into place, so a crash leaves either nothing or the whole outbox;
+     * a key that already has a directory is left as it is (an import that already happened, or a session's own outbox).
+     */
+    async importOutbox(key, records) {
+        const sessionKey = sessionKeyOf(key);
+        const dir = localSessionDir(this.root, sessionKey);
+        if (this.entries.has(sessionKey) || existsSync(dir))
+            return false;
+        mkdirSync(this.root, { recursive: true, mode: 0o700 });
+        const staging = path.join(this.root, `.staging-${randomUUID()}`);
+        try {
+            mkdirSync(staging, { mode: 0o700 });
+            if (path.basename(dir).startsWith('~'))
+                writeFileSync(path.join(staging, KEY_FILE), sessionKey, { mode: 0o600 });
+            const log = StreamLog.open({ dir: staging, now: this.now, immediateKinds: [] });
+            try {
+                let last = -Infinity;
+                for (const record of records) {
+                    if (!(record.seq > last))
+                        continue; // strictly increasing, as `acp.outbox.append` requires
+                    last = record.seq;
+                    log.append({ k: 'frame', seq: record.seq, src: record.src ?? { o: 0, i: DAEMON_FRAME_INDEX }, frame: record.frame });
+                }
+            }
+            finally {
+                log.close();
+            }
+            renameSync(staging, dir);
+            return true;
+        }
+        catch (error) {
+            rmSync(staging, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    /** The outboxes a previous daemon left behind (no live session). */
+    orphans() {
+        let names;
+        try {
+            names = readdirSync(this.root);
+        }
+        catch {
+            return [];
+        }
+        const keys = [];
+        for (const name of names) {
+            if (name.startsWith('.staging-'))
+                continue;
+            let key;
+            try {
+                key = name.startsWith('~') ? readFileSync(path.join(this.root, name, KEY_FILE), 'utf8') : decodeURIComponent(name);
+            }
+            catch {
+                continue;
+            }
+            try {
+                if (!statSync(path.join(this.root, name)).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            if (!this.entries.has(key))
+                keys.push(key);
+        }
+        return keys.sort();
+    }
+    entry(key) {
+        const sessionKey = sessionKeyOf(key);
+        const existing = this.entries.get(sessionKey);
+        if (existing)
+            return existing;
+        if (this.orphans().includes(sessionKey))
+            return this.open(sessionKey, {}, undefined, true);
+        throw new KeeperMethodError(AcpErrorCode.notFound, 'ACP session not found');
+    }
+    async spawn(key, spec, options) {
+        const sessionKey = sessionKeyOf(key);
+        const checked = spawnSpecOf(spec, [this.root]);
+        const existing = this.entries.get(sessionKey);
+        if (existing && !existing.orphan) {
+            if (options.baseOffset !== undefined)
+                throw new KeeperMethodError(AcpErrorCode.badRequest, 'baseOffset only applies to a new session');
+            return existing.session.spawn(checked);
+        }
+        if (existing) {
+            existing.session.close();
+            this.entries.delete(sessionKey);
+        } // an orphan's outbox is reopened by the new session
+        const existed = existsSync(localSessionDir(this.root, sessionKey));
+        const entry = this.open(sessionKey, options.label, options.baseOffset, false);
+        try {
+            return await entry.session.spawn(checked);
+        }
+        catch (error) {
+            // A new session whose first spawn failed leaves nothing behind (an older outbox found there is kept).
+            this.entries.delete(sessionKey);
+            entry.session.close();
+            if (!existed)
+                rmSync(entry.dir, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    async list() {
+        const live = [...this.entries.values()].map((e) => (e.orphan ? { ...e.session.summary(), raw: null } : e.session.summary()));
+        const left = this.orphans().map((key) => { const e = this.open(key, {}, undefined, true); return { ...e.session.summary(), raw: null }; });
+        return [...live, ...left];
+    }
+    async attach(sessionKey) {
+        const entry = this.entry(sessionKey);
+        const attached = entry.session.attach();
+        return entry.orphan ? { ...attached, raw: null } : attached;
+    }
+    hasDown(sessionKey, cause) { return this.entry(sessionKey).session.hasDown(cause); }
+    async subscribeRaw(sessionKey, from, handler, options = {}) {
+        const source = this.entry(sessionKey).session.source('raw');
+        const window = options.window ?? DEFAULT_WINDOW;
+        let next = from;
+        let closed = false;
+        let pumping = false;
+        let dirty = true;
+        const fail = (error) => { if (closed)
+            return; closed = true; unwatch(); options.onClosed?.(error); };
+        const pump = async () => {
+            if (pumping) {
+                dirty = true;
+                return;
+            }
+            pumping = true;
+            try {
+                while (dirty && !closed) {
+                    dirty = false;
+                    for (;;) {
+                        const batch = await source.read(next, window);
+                        if (closed || batch.length === 0)
+                            break;
+                        if (batch[0].o !== next) {
+                            fail(new RawTruncatedError(next, batch[0].o));
+                            return;
+                        }
+                        const records = batch.map(rawRecordOf);
+                        next = records[records.length - 1].o + 1;
+                        await handler(records);
+                    }
+                }
+            }
+            catch (error) {
+                fail(error instanceof Error ? error : new Error(String(error)));
+            }
+            finally {
+                pumping = false;
+            }
+        };
+        const unwatch = source.watch(() => { dirty = true; void pump(); });
+        queueMicrotask(() => { void pump(); });
+        return { get nextOffset() { return next; }, unsubscribe: async () => { closed = true; unwatch(); } };
+    }
+    async readRaw(sessionKey, from, limit) {
+        const result = this.entry(sessionKey).session.read('raw', from, limit);
+        if (result.truncated)
+            throw new RawTruncatedError(from, result.first);
+        return result.records.map((record) => rawRecordOf(record));
+    }
+    async readOutbox(sessionKey, from, limit) {
+        return this.entry(sessionKey).session.read('outbox', from, limit).records.map(toOutbox);
+    }
+    async write(sessionKey, line, options) {
+        return this.entry(sessionKey).session.write(options.spawnId, line, { ...options.annotation }, (options.redact ?? []).map((r) => ({ ref: r.ref, value: r.value })));
+    }
+    async note(sessionKey, note) {
+        return this.entry(sessionKey).session.note({ ...note });
+    }
+    async appendOutbox(sessionKey, entries) {
+        return this.entry(sessionKey).session.outboxAppend([...entries]);
+    }
+    async commit(sessionKey, params) {
+        return this.entry(sessionKey).session.commit({
+            ...(params.checkpoint ? { checkpoint: { offset: params.checkpoint.offset, blob: checkpointBlob(params.checkpoint.blob) } } : {}),
+            ...(params.outbox ? { outbox: { through: params.outbox.through, tail: { seq: params.outbox.tail.seq, src: { ...params.outbox.tail.src } } } } : {}),
+            ...(params.rawThrough !== undefined ? { rawThrough: params.rawThrough } : {}),
+        });
+    }
+    terminate(sessionKey, graceMs) { return this.entry(sessionKey).session.terminate(graceMs); }
+    async release(sessionKey) {
+        const entry = this.entry(sessionKey);
+        if (entry.session.busy)
+            throw new KeeperMethodError(AcpErrorCode.busy, 'Terminate the process before releasing the session');
+        this.entries.delete(sessionKey);
+        entry.session.close();
+        rmSync(entry.dir, { recursive: true, force: true });
+    }
+    /** Fallback sessions die with the daemon: every adapter is terminated and every outbox closed (its frames stay on disk). */
+    async dispose(graceMs) {
+        const entries = [...this.entries.values()];
+        await Promise.all(entries.map((e) => e.session.terminate(graceMs).catch(() => null)));
+        for (const e of entries)
+            e.session.close();
+        this.entries.clear();
+    }
+    /** The daemon exits: same as {@link dispose} (fallback sessions do not outlive it). */
+    close() { void this.dispose(); }
+}

package/dist/workstation/acp/processor/transport/types.js

@@ -0,0 +1,78 @@
+import { materializeLine } from '../commands.js';
+import { causeKey, decodeStreamRecord } from '../record.js';
+/** Raw records are retained only from `first`: a read or subscription below it cannot give the processor a contiguous log. */
+export class RawTruncatedError extends Error {
+    from;
+    first;
+    constructor(from, first) {
+        super(`Raw records ${from}..${first - 1} are no longer retained`);
+        this.from = from;
+        this.first = first;
+        this.name = 'RawTruncatedError';
+    }
+}
+/** `hasDown` was asked about a session the transport has not attached (the index is built by `attach`). */
+export class SessionNotAttachedError extends Error {
+    constructor(sessionKey) { super(`ACP session ${sessionKey} is not attached`); this.name = 'SessionNotAttachedError'; }
+}
+/**
+ * The kit record as the processor sees it. Explicit losses the keeper wrote (`gap`: a stdout line over the record cap;
+ * `discontinuity`: a torn tail repaired at open) keep their offset and become a `keeper_<kind>` note, which the processor counts as an
+ * unknown note: offsets stay contiguous and nothing is silently skipped.
+ */
+export function rawRecordOf(record) {
+    if (record.k === 'gap' || record.k === 'discontinuity') {
+        const { o, t, k, ...rest } = record;
+        return { o, t, kind: 'note', note: { ...rest, type: `keeper_${k}` } };
+    }
+    return decodeStreamRecord(record);
+}
+/** A down-cause index: `causeKey` → offset of its `down`. */
+export class CauseIndex {
+    downs = new Map();
+    add(cause, o) { this.downs.set(causeKey(cause), o); }
+    has(cause) { return this.downs.has(causeKey(cause)); }
+    observe(record) { if (record.kind === 'down' && record.annotation)
+        this.add(record.annotation.cause, record.o); }
+    /** Raw was truncated through `through`: those downs can never be asked about again. */
+    forgetThrough(through) { for (const [key, o] of this.downs)
+        if (o <= through)
+            this.downs.delete(key); }
+    get size() { return this.downs.size; }
+}
+/**
+ * `executeDownCommands` (commands.ts) over a transport: the same rules — a cause already in raw is dropped; a `fill` whose blocks
+ * are gone is `unresolved` (so is a command whose `secretRef` the daemon no longer holds); a refusal (another spawn runs) and a
+ * keeper-side duplicate count as dropped/refused — but writes are awaited one by one, in order.
+ */
+export async function executeDownCommandsVia(transport, sessionKey, commands, resolve, secrets) {
+    const written = [];
+    const dropped = [];
+    const refused = [];
+    const unresolved = [];
+    for (const command of commands) {
+        if (transport.hasDown(sessionKey, command.cause)) {
+            dropped.push(command);
+            continue;
+        }
+        const line = materializeLine(command, resolve);
+        const redact = (command.redact ?? []).map((ref) => ({ ref, value: secrets?.(ref) }));
+        if (line === undefined || redact.some((r) => r.value === undefined)) {
+            unresolved.push(command);
+            continue;
+        }
+        const result = await transport.write(sessionKey, line, {
+            annotation: { ...command.annotation, cause: command.cause, spawnId: command.spawnId },
+            ...(redact.length > 0 ? { redact: redact } : {}),
+            spawnId: command.spawnId,
+        });
+        if (result.status === 'written')
+            written.push(command);
+        else if (result.status === 'duplicate')
+            dropped.push(command);
+        else
+            refused.push(command);
+    }
+    return { written, dropped, refused, unresolved };
+}
+export const checkpointBlob = (blob) => (typeof blob === 'string' ? Buffer.from(blob, 'utf8') : blob).toString('base64');