@platless/axom-cli 0.3.13 → 0.5.9

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

@@ -0,0 +1,584 @@
+// One keeper-acp session (spec §5.3): the adapter process it hosts, its raw stream, its outbox stream, checkpoints, the
+// `down`-cause index, envelope diagnostics and stderr handling. Pure mechanism — no ACP beyond sniffing `id`/`method`.
+//
+// The same class runs in keeper-acp (raw and outbox are kit stream logs under `data/sessions/<id>/`, the adapter leads its own
+// process group) and in the daemon's fallback (raw in memory, outbox a kit stream log under `<configDir>/agents/local/<key>/`,
+// the adapter a plain daemon child): both transports therefore produce identical record sequences for the same adapter traffic.
+// Keeper-side module: node builtins and kit siblings only (the import guard enforces it).
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { rmSync } from 'node:fs';
+import { KeeperMethodError } from '../kit/protocol.js';
+import { processStartTime, signalGroup } from '../kit/orphanSweep.js';
+import { EnvelopeTracker } from './envelope.js';
+import { ACP_EXIT_DRAIN_MS, ACP_KILL_GRACE_MS, ACP_MAX_RECORD_BYTES, ACP_READ_MAX_BYTES, ACP_READ_MAX_RECORDS, ACP_TERMINATE_GRACE_MS, AcpErrorCode, } from './protocol.js';
+import { StderrCapture, jsonEscaped } from './stderr.js';
+const MAX_EVENT_RECORDS = 256;
+const GROUP_POLL_MS = 50;
+export class SpawnFailedError extends KeeperMethodError {
+    constructor(message) { super(AcpErrorCode.spawnFailed, message); this.name = 'SpawnFailedError'; }
+}
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+const causeKeyOf = (cause) => `${cause.o}:${cause.i}`;
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms).unref(); });
+export class AcpSession {
+    options;
+    meta;
+    raw;
+    outbox;
+    proc;
+    lastExit = null;
+    downs = new Map();
+    downsComplete;
+    envelope = new EnvelopeTracker();
+    stderr;
+    lastSeq = null;
+    stdoutHeld = false;
+    released = false;
+    spawning = false;
+    constructor(options) {
+        this.options = options;
+        this.meta = options.meta;
+        this.raw = options.raw;
+        this.outbox = options.outbox;
+        this.downsComplete = options.freshRaw;
+        this.lastExit = options.meta.lastExit ?? null;
+        this.stderr = new StderrCapture({ file: options.stderrFile, onLine: (line) => this.appendRaw({ k: 'err', l: line }), onError: (error) => this.report(error) });
+        const head = this.outbox.state().head;
+        if (head >= this.outbox.state().first) {
+            const last = this.outbox.readFrom(head, 1).records[0];
+            if (last && Number.isSafeInteger(last.seq))
+                this.lastSeq = last.seq;
+        }
+    }
+    get sessionKey() { return this.meta.sessionKey; }
+    get running() { return !!this.proc && this.proc.state !== 'exited'; }
+    get pendingInbound() { return this.envelope.pendingInboundCount; }
+    report(error) { this.options.log(`session ${this.meta.sessionKey}: ${messageOf(error)}`); }
+    appendRaw(input) { return this.raw.append(input); }
+    // ---- spawn ---------------------------------------------------------------------------------------------------------------
+    /**
+     * Starts the adapter: `spawn(command, args, {cwd, env, detached})` with exactly the daemon's env (never this process's own).
+     * Either a `proc spawn` record is appended (and later exactly one `proc exit`), or the spawn fails with nothing appended.
+     * stdout/stderr are held until the spawn record is in raw, so it is always the process's first record.
+     */
+    async spawn(spec) {
+        if (this.released)
+            throw new KeeperMethodError(AcpErrorCode.notFound, 'Session released');
+        if (this.spawning || (this.proc && this.proc.state !== 'exited'))
+            throw new KeeperMethodError(AcpErrorCode.busy, 'A process is already running in this session');
+        this.spawning = true;
+        try {
+            return await this.spawnNow(spec);
+        }
+        finally {
+            this.spawning = false;
+        }
+    }
+    get busy() { return this.spawning || this.running; }
+    async spawnNow(spec) {
+        const spawnId = randomUUID();
+        let child;
+        try {
+            child = (this.options.spawnProcess ?? spawn)(spec.command, spec.args, { cwd: spec.cwd, env: spec.env, detached: this.options.detached, stdio: ['pipe', 'pipe', 'pipe'] });
+        }
+        catch (error) {
+            throw new SpawnFailedError(messageOf(error));
+        }
+        child.stdin.on('error', () => { }); // EPIPE from a dying adapter: its exit is reported by the exit record
+        if (child.pid === undefined) {
+            const error = await new Promise((resolve) => child.once('error', resolve));
+            throw new SpawnFailedError(messageOf(error));
+        }
+        child.on('error', (error) => this.report(error));
+        const pid = child.pid;
+        const pgid = this.options.detached ? pid : 0;
+        let markRecorded;
+        const proc = {
+            spawnId, child, pid, pgid, startTime: null, sinceMs: this.options.now(), state: 'starting',
+            recorded: new Promise((resolve) => { markRecorded = resolve; }),
+            stdout: { chunks: [], bytes: 0, dropping: 0 },
+        };
+        this.proc = proc;
+        this.envelope.reset();
+        this.stderr.restart();
+        this.stderr.addSecrets(spec.stderrSecrets ?? []);
+        this.meta.spawn = { spawnId, pid, pgid, startTime: null, atMs: proc.sinceMs };
+        this.meta.exited = false;
+        this.meta.removeOnExit = [...(spec.removeOnExit ?? [])];
+        this.saveMeta(); // the pid (and what to remove) is durable before anything else happens
+        // Listeners right away (Node resumes stdio on the leader's exit; data without a listener would be lost); chunks that arrive
+        // before the spawn record is written are held and the stream paused.
+        let held = [];
+        child.stdout.on('data', (chunk) => { if (held) {
+            held.push(['out', chunk]);
+            child.stdout.pause();
+            return;
+        } this.onStdout(proc, chunk); });
+        child.stderr.on('data', (chunk) => { if (held) {
+            held.push(['err', chunk]);
+            child.stderr.pause();
+            return;
+        } this.stderr.push(chunk); });
+        child.stdout.on('error', () => { });
+        child.stderr.on('error', () => { });
+        child.stdout.pause();
+        child.stderr.pause();
+        child.once('exit', (code, signal) => this.onLeaderExit(proc, code, signal));
+        child.once('close', () => { void this.finish(proc); });
+        let record;
+        try {
+            proc.startTime = await (this.options.startTime ?? ((p) => processStartTime(p)))(pid).catch(() => null);
+            this.meta.spawn.startTime = proc.startTime;
+            this.saveMeta();
+            record = this.appendRaw({
+                k: 'proc', kind: 'spawn', spawnId, pid, pgid, startTime: proc.startTime ?? '',
+                command: spec.command, args: spec.args, cwd: spec.cwd, envKeys: Object.keys(spec.env).sort(),
+            });
+        }
+        catch (error) {
+            // The spawn record could not be written: the process must not run unrecorded.
+            this.signal(proc, 'SIGKILL');
+            held = undefined;
+            proc.state = 'exited';
+            this.proc = undefined;
+            this.meta.spawn = null;
+            this.meta.exited = true;
+            this.saveMeta();
+            markRecorded();
+            throw new SpawnFailedError(`Could not record the spawn: ${messageOf(error)}`);
+        }
+        if (proc.state === 'starting')
+            proc.state = 'running';
+        markRecorded();
+        const pending = held;
+        held = undefined;
+        for (const [stream, chunk] of pending) {
+            if (stream === 'out')
+                this.onStdout(proc, chunk);
+            else
+                this.stderr.push(chunk);
+        }
+        if (!this.stdoutHeld)
+            child.stdout.resume();
+        child.stderr.resume();
+        return { spawnId, pid, pgid, o: record.o };
+    }
+    saveMeta() {
+        try {
+            this.options.saveMeta(this.meta);
+        }
+        catch (error) {
+            this.report(error);
+        }
+    }
+    /** Persists the metadata now (an adopting keeper records itself as the owner). */
+    persist() { this.saveMeta(); }
+    /** stdout → one `up` record per line, verbatim (no newline). A line over the record cap is dropped and a `gap` says so. */
+    onStdout(proc, chunk) {
+        const out = proc.stdout;
+        let start = 0;
+        for (;;) {
+            const newline = chunk.indexOf(0x0a, start);
+            if (newline < 0)
+                break;
+            const piece = chunk.subarray(start, newline);
+            start = newline + 1;
+            if (out.dropping > 0) {
+                this.appendGap(out.dropping + piece.length);
+                out.dropping = 0;
+                continue;
+            }
+            const line = out.chunks.length === 0 ? piece : Buffer.concat([...out.chunks, piece], out.bytes + piece.length);
+            out.chunks = [];
+            out.bytes = 0;
+            this.upLine(line);
+        }
+        if (start >= chunk.length)
+            return;
+        const rest = chunk.subarray(start);
+        if (out.dropping > 0) {
+            out.dropping += rest.length;
+            return;
+        }
+        out.chunks.push(Buffer.from(rest));
+        out.bytes += rest.length;
+        if (out.bytes > ACP_MAX_RECORD_BYTES) {
+            out.dropping = out.bytes;
+            out.chunks = [];
+            out.bytes = 0;
+        }
+    }
+    upLine(bytes) {
+        const line = bytes.toString('utf8');
+        if (bytes.length > ACP_MAX_RECORD_BYTES / 2 && Buffer.byteLength(JSON.stringify(line)) > ACP_MAX_RECORD_BYTES - 1024) {
+            this.appendGap(bytes.length);
+            return;
+        }
+        try {
+            const record = this.appendRaw({ k: 'up', l: line });
+            this.envelope.up(line, record.t);
+        }
+        catch (error) {
+            this.report(error);
+        }
+    }
+    appendGap(droppedBytes) {
+        try {
+            this.appendRaw({ k: 'gap', stream: 'stdout', droppedBytes });
+        }
+        catch (error) {
+            this.report(error);
+        }
+    }
+    /** The keeper's disk guard (spec §3.4: below 1 GiB free, stop reading adapter stdout). stderr keeps flowing (bounded file). */
+    holdStdout(hold) {
+        if (this.stdoutHeld === hold)
+            return;
+        this.stdoutHeld = hold;
+        const proc = this.proc;
+        if (!proc || proc.state === 'starting' || proc.state === 'exited')
+            return;
+        if (hold)
+            proc.child.stdout.pause();
+        else
+            proc.child.stdout.resume();
+    }
+    // ---- exit ----------------------------------------------------------------------------------------------------------------
+    onLeaderExit(proc, code, signal) {
+        proc.leaderExit = { code, signal };
+        if (proc.state !== 'exited')
+            proc.state = 'exiting';
+        if (this.stdoutHeld)
+            proc.child.stdout.resume(); // nothing more can be produced; let it drain
+        if (proc.terminateReason)
+            return; // terminate() drives the rest
+        // The adapter ended by itself: whatever is left of its group (an MCP server, a CLI it started) goes too, and stdio is drained
+        // for a bounded time (a survivor may hold the pipes open).
+        if (this.options.detached && this.groupAlive(proc)) {
+            signalGroup(proc.pgid, 'SIGTERM');
+            proc.groupTimer = setTimeout(() => { if (this.groupAlive(proc))
+                signalGroup(proc.pgid, 'SIGKILL'); }, ACP_KILL_GRACE_MS);
+            proc.groupTimer.unref();
+        }
+        proc.drainTimer = setTimeout(() => { this.closePipes(proc); void this.finish(proc); }, ACP_EXIT_DRAIN_MS);
+        proc.drainTimer.unref();
+    }
+    /** Writes the exit record once: flushes partial lines, appends `proc exit`, runs `removeOnExit`. */
+    finish(proc) {
+        proc.finished ??= (async () => {
+            await proc.recorded;
+            clearTimeout(proc.drainTimer);
+            if (this.proc !== proc)
+                return this.lastExit; // the spawn record could not be written: nothing to close
+            if (proc.stdout.dropping > 0) {
+                this.appendGap(proc.stdout.dropping);
+                proc.stdout.dropping = 0;
+            }
+            if (proc.stdout.bytes > 0) {
+                const line = Buffer.concat(proc.stdout.chunks, proc.stdout.bytes);
+                proc.stdout.chunks = [];
+                proc.stdout.bytes = 0;
+                this.upLine(line);
+            }
+            this.stderr.end();
+            const code = proc.leaderExit?.code ?? proc.child.exitCode ?? null;
+            const signal = proc.leaderExit?.signal ?? proc.child.signalCode ?? null;
+            const stderrTail = this.stderr.tail;
+            let exit = null;
+            try {
+                const record = this.appendRaw({ k: 'proc', kind: 'exit', code, signal, stderrTail, ...(proc.terminateReason ? { reason: proc.terminateReason } : {}) });
+                exit = { code, signal, stderrTail, ...(proc.terminateReason ? { reason: proc.terminateReason } : {}), o: record.o, atMs: record.t };
+            }
+            catch (error) {
+                this.report(error);
+            }
+            proc.state = 'exited';
+            this.lastExit = exit;
+            this.meta.exited = true;
+            this.meta.lastExit = exit;
+            this.saveMeta();
+            this.removeOnExit();
+            return exit;
+        })();
+        return proc.finished;
+    }
+    /**
+     * Removes `targets` (default: what the current spawn named) and drops them from the metadata. A caller cleaning up after an
+     * EARLIER spawn passes the list it captured then: a later spawn's own targets are never touched (final review minor 8).
+     */
+    removeOnExit(targets = this.meta.removeOnExit) {
+        const removing = [...targets];
+        for (const target of removing) {
+            try {
+                rmSync(target, { recursive: true, force: true });
+            }
+            catch (error) {
+                this.report(error);
+            }
+        }
+        const remaining = this.meta.removeOnExit.filter((target) => !removing.includes(target));
+        if (remaining.length !== this.meta.removeOnExit.length) {
+            this.meta.removeOnExit = remaining;
+            this.saveMeta();
+        }
+    }
+    groupAlive(proc) {
+        if (!this.options.detached)
+            return proc.child.exitCode === null && proc.child.signalCode === null;
+        try {
+            process.kill(-proc.pgid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        } // ESRCH: no member left (EPERM: the id is no longer ours)
+    }
+    signal(proc, signal) {
+        if (this.options.detached) {
+            signalGroup(proc.pgid, signal);
+            return;
+        }
+        try {
+            proc.child.kill(signal);
+        }
+        catch { /* gone */ }
+    }
+    closePipes(proc) {
+        proc.child.stdin.destroy();
+        proc.child.stdout.destroy();
+        proc.child.stderr.destroy();
+    }
+    /** Until the group (fallback: the child) is gone or `ms` passed. True when it is gone. */
+    async goneWithin(proc, ms) {
+        const end = Date.now() + ms;
+        for (;;) {
+            const leaderDone = proc.leaderExit !== undefined;
+            if (leaderDone && !this.groupAlive(proc))
+                return true;
+            if (!this.options.detached && leaderDone)
+                return true;
+            if (Date.now() >= end)
+                return false;
+            await sleep(Math.min(GROUP_POLL_MS, Math.max(1, end - Date.now())));
+        }
+    }
+    /**
+     * SIGTERM to the process group → up to `graceMs` → SIGKILL → up to 2 s → close the pipes → `exit` record (spec §5.3). The group,
+     * not just the leader: an adapter's CLI and MCP servers must not survive it. Idempotent; an exited session answers its last exit.
+     */
+    async terminate(graceMs = ACP_TERMINATE_GRACE_MS, reason = 'terminated') {
+        const proc = this.proc;
+        if (!proc)
+            return this.lastExit;
+        await proc.recorded;
+        if (this.proc !== proc || proc.state === 'exited')
+            return this.lastExit;
+        if (proc.terminating)
+            return proc.terminating;
+        proc.terminateReason ??= reason;
+        proc.terminating = (async () => {
+            clearTimeout(proc.drainTimer);
+            clearTimeout(proc.groupTimer);
+            if (graceMs > 0) {
+                this.signal(proc, 'SIGTERM');
+                if (await this.goneWithin(proc, graceMs)) {
+                    await this.drainBriefly(proc);
+                    this.closePipes(proc);
+                    return this.finish(proc);
+                }
+            }
+            this.signal(proc, 'SIGKILL');
+            await this.goneWithin(proc, ACP_KILL_GRACE_MS);
+            this.closePipes(proc);
+            return this.finish(proc);
+        })();
+        return proc.terminating;
+    }
+    /** After a clean exit, give stdio a moment to deliver what the adapter wrote last (it normally closes at once). */
+    async drainBriefly(proc) {
+        if (proc.finished)
+            return;
+        await Promise.race([new Promise((resolve) => proc.child.once('close', () => resolve())), sleep(250)]);
+    }
+    // ---- write / note / outbox / commit --------------------------------------------------------------------------------------
+    /**
+     * Atomic (one synchronous step, so no other request interleaves): refused unless `spawnId` is the process running now; a cause
+     * already in raw is a duplicate; otherwise secrets join the stderr redaction, the LOGGED line is appended as `down`, and the line
+     * with secrets substituted goes to stdin. Append before stdin: a line that reached the adapter always has its record.
+     */
+    write(spawnId, line, annotation, redact) {
+        const proc = this.proc;
+        if (!proc || proc.state !== 'running' || proc.terminateReason)
+            return { status: 'refused', reason: 'not_running' };
+        if (proc.spawnId !== spawnId)
+            return { status: 'refused', reason: 'spawn_mismatch' };
+        const key = causeKeyOf(annotation.cause);
+        const existing = this.downs.get(key);
+        if (existing !== undefined)
+            return { status: 'duplicate', o: existing };
+        if (line.includes('\n'))
+            throw new KeeperMethodError(AcpErrorCode.badRequest, 'A down line may not contain a newline');
+        if (line.length > ACP_MAX_RECORD_BYTES / 4 && Buffer.byteLength(JSON.stringify(line)) > ACP_MAX_RECORD_BYTES - 64 * 1024)
+            throw new KeeperMethodError(AcpErrorCode.badRequest, 'Down line exceeds the record limit');
+        let stdinLine = line;
+        for (const { ref, value } of redact)
+            stdinLine = stdinLine.split(ref).join(jsonEscaped(value));
+        this.stderr.addSecrets(redact.map((r) => r.value));
+        const record = this.appendRaw({ k: 'down', l: line, a: annotation, ...(redact.length > 0 ? { redact: redact.map((r) => r.ref) } : {}) });
+        this.downs.set(key, record.o);
+        this.envelope.down(line, record.t);
+        proc.child.stdin.write(`${stdinLine}\n`);
+        return { status: 'written', o: record.o };
+    }
+    note(note) {
+        return { o: this.appendRaw({ k: 'note', n: note }).o };
+    }
+    outboxAppend(entries) {
+        let last = this.lastSeq;
+        for (const entry of entries) {
+            if (last !== null && entry.seq <= last)
+                throw new KeeperMethodError(AcpErrorCode.badRequest, `Outbox seq ${entry.seq} does not follow ${last}`);
+            last = entry.seq;
+        }
+        let first = -1;
+        let lastO = -1;
+        for (const entry of entries) {
+            const record = this.outbox.append({ k: 'frame', seq: entry.seq, src: entry.src, frame: entry.frame });
+            if (first < 0)
+                first = record.o;
+            lastO = record.o;
+            this.lastSeq = entry.seq;
+        }
+        return { first, last: lastO };
+    }
+    /** Checkpoint, then outbox truncation (with its watermark), then raw truncation — never past the latest checkpoint. */
+    commit(params) {
+        const rawState = this.raw.state();
+        if (params.checkpoint) {
+            if (params.checkpoint.offset > rawState.head)
+                throw new KeeperMethodError(AcpErrorCode.badRequest, 'Checkpoint offset is beyond the raw head');
+            this.raw.writeCheckpoint(params.checkpoint.offset, Buffer.from(params.checkpoint.blob, 'base64'));
+        }
+        if (params.outbox) {
+            if (params.outbox.through > this.outbox.state().head)
+                throw new KeeperMethodError(AcpErrorCode.badRequest, 'Outbox commit is beyond the outbox head');
+            this.outbox.commit(params.outbox.through, params.outbox.tail);
+        }
+        if (params.rawThrough !== undefined) {
+            const checkpointOffset = this.raw.latestCheckpoint()?.offset ?? -1;
+            if (params.rawThrough > checkpointOffset)
+                throw new KeeperMethodError(AcpErrorCode.badRequest, 'Raw may only be truncated through the latest checkpoint');
+            this.raw.commit(params.rawThrough);
+            for (const [key, o] of this.downs)
+                if (o <= params.rawThrough)
+                    this.downs.delete(key);
+        }
+        return { raw: this.streamState('raw'), outbox: this.streamState('outbox'), checkpointOffset: this.raw.latestCheckpoint()?.offset ?? -1 };
+    }
+    // ---- read ------------------------------------------------------------------------------------------------------------------
+    read(stream, from, limit = ACP_READ_MAX_RECORDS) {
+        const log = stream === 'raw' ? this.raw : this.outbox;
+        const result = log.readFrom(from, Math.min(limit, ACP_READ_MAX_RECORDS), { maxBytes: ACP_READ_MAX_BYTES });
+        const state = log.state();
+        const next = result.records.length > 0 ? result.records[result.records.length - 1].o + 1 : Math.max(from, result.first);
+        return { records: result.records, first: result.first, head: state.head, next, truncated: result.truncated };
+    }
+    source(stream) {
+        const log = stream === 'raw' ? this.raw : this.outbox;
+        const inner = log.asEventSource({ maxBytes: ACP_READ_MAX_BYTES });
+        return { read: (from, limit, options) => inner.read(from, Math.min(limit, MAX_EVENT_RECORDS), options), watch: (notify) => inner.watch(notify) };
+    }
+    /** Is a `down` with this cause in raw (the in-process lookup of the daemon's fallback)? */
+    hasDown(cause) {
+        if (!this.downsComplete)
+            this.downsFrom(0);
+        return this.downs.has(causeKeyOf(cause));
+    }
+    /** Every retained `down` with a cause at or after `from` (scans raw once for a session this owner did not create). */
+    downsFrom(from) {
+        if (!this.downsComplete) {
+            let next = this.raw.state().first;
+            for (;;) {
+                const { records } = this.raw.readFrom(next, ACP_READ_MAX_RECORDS, { maxBytes: ACP_READ_MAX_BYTES });
+                if (records.length === 0)
+                    break;
+                for (const record of records) {
+                    const cause = record.k === 'down' ? record.a?.cause : undefined;
+                    if (cause && Number.isSafeInteger(cause.o) && Number.isSafeInteger(cause.i))
+                        this.downs.set(causeKeyOf(cause), record.o);
+                }
+                next = records[records.length - 1].o + 1;
+            }
+            this.downsComplete = true;
+        }
+        const downs = [...this.downs.entries()].filter(([, o]) => o >= from).sort((a, b) => a[1] - b[1])
+            .map(([key, o]) => { const [co, ci] = key.split(':').map(Number); return { o, cause: { o: co, i: ci } }; });
+        const state = this.raw.state();
+        return { downs, first: state.first, head: state.head };
+    }
+    // ---- state -----------------------------------------------------------------------------------------------------------------
+    streamState(stream) {
+        const s = (stream === 'raw' ? this.raw : this.outbox).state();
+        return { head: s.head, first: s.first, next: s.next, committed: s.committed, bytes: s.bytes, overQuota: s.overQuota };
+    }
+    get overQuota() { return this.raw.state().overQuota || this.outbox.state().overQuota; }
+    processInfo() {
+        const proc = this.proc;
+        if (proc && proc.state !== 'exited')
+            return { state: proc.state, spawnId: proc.spawnId, pid: proc.pid, pgid: proc.pgid, startTime: proc.startTime, sinceEpochMs: proc.sinceMs };
+        if (proc || this.meta.spawn)
+            return { state: 'exited', spawnId: proc?.spawnId ?? this.meta.spawn?.spawnId ?? null, exit: this.lastExit };
+        return { state: 'none' };
+    }
+    /**
+     * A keeper loss (spec §5.3): the process this session's metadata names was not started by this keeper, so whatever it was is
+     * over for this session. `proc exit{reason:'keeper_lost'}` is appended with the stderr tail the file kept, and the session is exited.
+     */
+    recordKeeperLost(stderrTail) {
+        let exit = null;
+        try {
+            const record = this.appendRaw({ k: 'proc', kind: 'exit', code: null, signal: null, stderrTail, reason: 'keeper_lost' });
+            exit = { code: null, signal: null, stderrTail, reason: 'keeper_lost', o: record.o, atMs: record.t };
+        }
+        catch (error) {
+            this.report(error);
+        }
+        this.lastExit = exit;
+        this.meta.exited = true;
+        this.meta.lastExit = exit;
+        this.saveMeta();
+        return exit;
+    }
+    summary() {
+        const outbox = this.outbox.state();
+        return {
+            sessionKey: this.meta.sessionKey, label: this.meta.label, createdAtMs: this.meta.createdAtMs, process: this.processInfo(),
+            raw: this.streamState('raw'), outbox: { ...this.streamState('outbox'), committedTail: outbox.committedTail, lastSeq: this.lastSeq },
+        };
+    }
+    attach() {
+        const summary = this.summary();
+        const raw = this.raw.state();
+        const checkpoint = this.raw.latestCheckpoint();
+        const cp = checkpoint ? { seq: checkpoint.seq, offset: checkpoint.offset, t: checkpoint.t, blob: checkpoint.blob.toString('base64') } : null;
+        return { ...summary, head: raw.head, committed: raw.committed, committedTail: this.outbox.state().committedTail, checkpoint: cp, envelope: this.envelope.snapshot() };
+    }
+    /** Closes the streams (the process must have exited). `remove` also deletes what the caller keeps on disk for it. */
+    close() {
+        this.released = true;
+        this.stderr.close();
+        try {
+            this.raw.close();
+        }
+        catch (error) {
+            this.report(error);
+        }
+        try {
+            this.outbox.close();
+        }
+        catch (error) {
+            this.report(error);
+        }
+    }
+}