@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/files/uploads.js

@@ -0,0 +1,351 @@
+import { constants, lstatSync, linkSync, promises as fs, renameSync } from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { pinned } from './fence.js';
+/** Staging entries and reserved names start with this; `files.list` / `files.find` hide them. */
+export const TEMP_PREFIX = '.axom-upload-';
+export const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
+export const MAX_UPLOADS = 8;
+export const MAX_UPLOAD_CHUNKS = 16384;
+export const UPLOAD_TTL_MS = 15 * 60_000;
+const same = (stat, identity) => stat.dev === identity.dev && stat.ino === identity.ino;
+/**
+ * Upload sessions: one opened temporary file per upload inside a private 0700 staging directory beneath a trusted root
+ * on the destination's filesystem, per-block SHA-256 receipts, a private manifest per upload so `recover()` can remove
+ * orphans after a crash, and a synchronous identity-checked commit (exclusive hard link, or rename for overwrite).
+ * Every method that names a destination runs inside the caller's `pinned()` section on the destination parent.
+ */
+export class UploadStore {
+    roots;
+    ttl;
+    stateDir;
+    uploads = new Map();
+    sweeping;
+    constructor(roots, ttl = UPLOAD_TTL_MS, stateDir) {
+        this.roots = roots;
+        this.ttl = ttl;
+        this.stateDir = stateDir;
+    }
+    /** Creates the private manifest directory (0700, owned by this uid, not a symlink). */
+    static async prepareStateDir(stateDir) {
+        await fs.mkdir(stateDir, { recursive: true, mode: 0o700 });
+        const stat = await fs.lstat(stateDir);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()))
+            throw new Error('Unsafe upload state directory');
+        await fs.chmod(stateDir, 0o700);
+    }
+    /** Uploads in flight (the daemon samples this as activity). */
+    get size() { return this.uploads.size; }
+    get(id) { return this.uploads.get(id); }
+    /** Looks an upload up for a client call and refreshes its idle timer. */
+    use(id) {
+        const upload = this.uploads.get(id);
+        if (!upload)
+            throw new Error('Upload not found or expired');
+        upload.touched = Date.now();
+        return upload;
+    }
+    /** Removes temporary files that a crashed process left behind, as recorded in the private manifests. */
+    async recover(resolve) {
+        if (!this.stateDir)
+            return;
+        for (const name of await fs.readdir(this.stateDir)) {
+            if (!/^[0-9a-f-]{36}\.json$/.test(name))
+                continue;
+            const manifest = path.join(this.stateDir, name);
+            try {
+                const stat = await fs.lstat(manifest);
+                if (!stat.isFile() || stat.size > 8192)
+                    continue;
+                const value = JSON.parse(await fs.readFile(manifest, 'utf8'));
+                if (typeof value.dir !== 'string' || path.basename(value.dir) !== TEMP_PREFIX + name.slice(0, -5) || value.temp !== path.join(value.dir, 'payload'))
+                    throw new Error('Invalid orphan upload');
+                await resolve(value.dir, false, true);
+                const directory = await fs.lstat(value.dir);
+                if (!directory.isDirectory() || !same(directory, value.dirIdentity))
+                    throw new Error('Orphan upload directory changed');
+                await pinned(value.dir, async () => {
+                    for (const entry of await fs.readdir('.')) {
+                        if (entry !== 'payload' && !/^commit-[0-9a-f-]{36}$/.test(entry))
+                            continue;
+                        const item = await fs.lstat(entry);
+                        if (item.isFile() && same(item, value.identity))
+                            await fs.unlink(entry);
+                    }
+                });
+                await fs.rmdir(value.dir);
+            }
+            catch { /* Replaced entries are never followed or deleted during cleanup. */ }
+            await fs.unlink(manifest).catch(() => { });
+        }
+    }
+    /** Staging names must live beneath a root protected from other-UID rename/write. The destination
+     * parent remains kernel-pinned; staging can be on any allowed root on that same filesystem. */
+    async stagingRoot(dev, extraRoot) {
+        const uid = process.getuid?.();
+        for (const root of [...this.roots, ...(extraRoot ? [extraRoot] : [])]) {
+            const rootStat = await fs.lstat(root);
+            if (!rootStat.isDirectory() || rootStat.dev !== dev || rootStat.uid !== uid || (rootStat.mode & 0o022))
+                continue;
+            let child = root;
+            let childStat = rootStat;
+            let trusted = true;
+            while (path.dirname(child) !== child) {
+                const parent = path.dirname(child);
+                const stat = await fs.lstat(parent);
+                if (!stat.isDirectory() || ((stat.mode & 0o022) && !((stat.mode & 0o1000) && childStat.uid === uid))) {
+                    trusted = false;
+                    break;
+                }
+                child = parent;
+                childStat = stat;
+            }
+            if (trusted)
+                return root;
+        }
+        throw new Error('Upload requires a trusted private staging root on the destination filesystem');
+    }
+    async verify(upload) {
+        const directory = await fs.lstat(upload.dir);
+        if (!directory.isDirectory() || !same(directory, upload.dirIdentity) || (directory.mode & 0o077))
+            throw new Error('Upload staging directory changed');
+        const opened = await upload.handle.stat();
+        const named = await fs.lstat(upload.temp);
+        if (!opened.isFile() || opened.size !== upload.size || !named.isFile() || !same(named, opened))
+            throw new Error('Upload temporary file changed');
+        for (const [offset, receipt] of upload.chunks) {
+            const data = Buffer.alloc(receipt.length);
+            let read = 0;
+            while (read < data.length) {
+                const result = await upload.handle.read(data, read, data.length - read, offset + read);
+                if (!result.bytesRead)
+                    throw new Error('Upload integrity changed');
+                read += result.bytesRead;
+            }
+            if (createHash('sha256').update(data).digest('hex') !== receipt.digest)
+                throw new Error('Upload integrity changed');
+        }
+        const after = await upload.handle.stat();
+        if (after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs)
+            throw new Error('Upload integrity changed during verification');
+        return after;
+    }
+    /** Runs inside `pinned(dirname(target))`; `resolveTarget` is the caller's configured-roots resolution of the path. */
+    async begin(pin, resolveTarget, size, overwrite, filesystem = false, reportedPath) {
+        if (this.uploads.size >= MAX_UPLOADS)
+            throw new Error('Upload limit exceeded');
+        const target = await resolveTarget();
+        if (path.basename(target).startsWith(TEMP_PREFIX))
+            throw new Error('Reserved upload filename');
+        let existing;
+        try {
+            existing = await fs.lstat(pin.leaf(target));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (existing && (overwrite !== true || !existing.isFile()))
+            throw new Error('Target already exists');
+        const inPlace = filesystem && !!existing && overwrite;
+        if (inPlace)
+            await fs.access(pin.leaf(target), constants.W_OK);
+        const id = randomUUID();
+        const parent = await fs.stat('.');
+        const root = await this.stagingRoot(inPlace ? (await fs.stat(this.roots[0])).dev : parent.dev, filesystem ? path.dirname(target) : undefined);
+        const dir = path.join(root, `${TEMP_PREFIX}${id}`);
+        const temp = path.join(dir, 'payload');
+        const manifest = this.stateDir ? path.join(this.stateDir, `${id}.json`) : undefined;
+        await fs.mkdir(dir, { mode: 0o700 });
+        let handle;
+        try {
+            handle = await fs.open(temp, constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        }
+        catch (error) {
+            await fs.rmdir(dir).catch(() => { });
+            throw error;
+        }
+        const directory = await fs.lstat(dir);
+        const inode = await handle.stat();
+        const dirIdentity = { dev: directory.dev, ino: directory.ino };
+        const identity = { dev: inode.dev, ino: inode.ino };
+        try {
+            if (manifest)
+                await fs.writeFile(manifest, JSON.stringify({ temp, dir, identity, dirIdentity }), { flag: 'wx', mode: 0o600 });
+        }
+        catch (error) {
+            await handle.close();
+            await fs.unlink(temp).catch(() => { });
+            await fs.rmdir(dir).catch(() => { });
+            throw error;
+        }
+        this.uploads.set(id, { id, manifest, target, temp, dir, dirIdentity, identity, handle, size, offset: 0, overwrite, inPlace, reportedPath: filesystem ? reportedPath : undefined, touched: Date.now(), parent: { dev: parent.dev, ino: parent.ino }, chunks: new Map(), commits: new Set() });
+        return { uploadId: id };
+    }
+    async chunk(upload, offset, bytes) {
+        const digest = createHash('sha256').update(bytes).digest('hex');
+        const receipt = upload.chunks.get(offset);
+        if (receipt && receipt.length === bytes.length && receipt.digest === digest)
+            return { offset: upload.offset };
+        if (upload.chunks.size >= MAX_UPLOAD_CHUNKS)
+            throw new Error('Upload chunk count limit exceeded');
+        if (offset !== upload.offset || !bytes.length || offset + bytes.length > upload.size)
+            throw new Error('Upload offset or size mismatch');
+        let written = 0;
+        while (written < bytes.length) {
+            const result = await upload.handle.write(bytes, written, bytes.length - written, offset + written);
+            if (!result.bytesWritten)
+                throw new Error('Upload write failed');
+            written += result.bytesWritten;
+        }
+        upload.chunks.set(offset, { length: bytes.length, digest });
+        upload.offset += bytes.length;
+        return { offset: upload.offset };
+    }
+    /** Runs inside `pinned(dirname(upload.target))`. */
+    async finish(pin, upload, resolve) {
+        if (upload.offset !== upload.size)
+            throw new Error('Upload size mismatch');
+        await resolve(upload.target, true, true);
+        const parent = await fs.stat('.');
+        if (parent.dev !== upload.parent.dev || parent.ino !== upload.parent.ino)
+            throw new Error('Upload parent changed');
+        await upload.handle.sync();
+        await this.verify(upload);
+        if (upload.inPlace) {
+            // Write through the existing inode: the kernel enforces file ACLs and retains ownership,
+            // permissions and hard links, including when the parent does not permit replacement.
+            const destination = await pin.regularHandle(upload.target, constants.O_WRONLY);
+            try {
+                const buffer = Buffer.alloc(64 * 1024);
+                let offset = 0;
+                while (offset < upload.size) {
+                    const { bytesRead } = await upload.handle.read(buffer, 0, Math.min(buffer.length, upload.size - offset), offset);
+                    if (!bytesRead)
+                        throw new Error('Upload temporary file changed');
+                    let written = 0;
+                    while (written < bytesRead) {
+                        const result = await destination.write(buffer, written, bytesRead - written, offset + written);
+                        if (!result.bytesWritten)
+                            throw new Error('Upload write failed');
+                        written += result.bytesWritten;
+                    }
+                    offset += bytesRead;
+                }
+                await destination.truncate(upload.size);
+                await destination.sync();
+            }
+            finally {
+                await destination.close();
+            }
+            await this.clean(upload);
+            return { ok: true, path: upload.reportedPath ?? upload.target };
+        }
+        const commit = path.join(upload.dir, `commit-${randomUUID()}`);
+        upload.commits.add(commit);
+        await fs.link(upload.temp, commit);
+        // The link may have raced source replacement. Check the actual linked inode before ever
+        // touching the destination; the final source lives in a trusted 0700 directory.
+        const linked = await fs.lstat(commit);
+        const opened = await upload.handle.stat();
+        if (!linked.isFile() || !same(linked, opened))
+            throw new Error('Upload staging integrity changed');
+        const verified = await this.verify(upload);
+        // No asynchronous yield between the final identity guard and atomic commit. Other-UID
+        // processes cannot replace the private staging entry; unrestricted same-UID tampering is
+        // outside this boundary (that UID can also control the files host or ptrace its process).
+        const directory = lstatSync(upload.dir);
+        const source = lstatSync(commit);
+        const original = lstatSync(upload.temp);
+        if (!directory.isDirectory() || !same(directory, upload.dirIdentity) || (directory.mode & 0o077)
+            || !source.isFile() || !original.isFile() || !same(source, verified) || !same(original, verified)
+            || source.size !== upload.size || source.mtimeMs !== verified.mtimeMs || source.ctimeMs !== verified.ctimeMs)
+            throw new Error('Upload commit source changed');
+        if (upload.overwrite) {
+            try {
+                if (!lstatSync(pin.leaf(upload.target)).isFile())
+                    throw new Error('Target is not a regular file');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            renameSync(commit, pin.leaf(upload.target));
+        }
+        else
+            linkSync(commit, pin.leaf(upload.target));
+        await this.clean(upload);
+        return { ok: true, path: upload.reportedPath ?? upload.target };
+    }
+    async cancel(id) {
+        const upload = this.uploads.get(id);
+        if (upload)
+            await this.clean(upload);
+        return { ok: true };
+    }
+    async clean(upload) {
+        this.uploads.delete(upload.id);
+        await upload.handle.close().catch(() => { });
+        try {
+            const directory = await fs.lstat(upload.dir);
+            if (directory.isDirectory() && same(directory, upload.dirIdentity)) {
+                for (const item of [upload.temp, ...upload.commits]) {
+                    try {
+                        const stat = await fs.lstat(item);
+                        if (stat.isFile() && same(stat, upload.identity))
+                            await fs.unlink(item);
+                    }
+                    catch { /* Preserve substituted entries. */ }
+                }
+                await fs.rmdir(upload.dir).catch(() => { });
+            }
+        }
+        catch { /* Inaccessible private staging paths are not followed. */ }
+        if (upload.manifest)
+            await fs.unlink(upload.manifest).catch(() => { });
+    }
+    async abandon(upload) {
+        this.uploads.delete(upload.id);
+        await upload.handle.close().catch(() => { });
+        // Retain the private journal when its original parent cannot be safely resolved for cleanup.
+        // A later startup can retry; never remove a same-name file in a replacement directory.
+    }
+    /**
+     * Cleans (or, when its parent was replaced, abandons) every upload idle for the TTL. Sweeps never overlap: a caller
+     * that arrives while one runs (the periodic timer, or another request) waits for it and then sweeps again itself, so
+     * once `expire()` returns, everything expired at the call is gone from disk as well as from the table - as when the
+     * keeper queued every call.
+     */
+    async expire() {
+        while (this.sweeping)
+            await this.sweeping;
+        let done;
+        this.sweeping = new Promise(resolve => { done = resolve; });
+        try {
+            for (const upload of [...this.uploads.values()])
+                if (Date.now() - upload.touched >= this.ttl)
+                    await this.retire(upload);
+        }
+        finally {
+            this.sweeping = undefined;
+            done();
+        }
+    }
+    async dispose() {
+        while (this.sweeping)
+            await this.sweeping;
+        for (const upload of [...this.uploads.values()])
+            await this.retire(upload);
+    }
+    async retire(upload) {
+        await pinned(path.dirname(upload.target), async () => {
+            // Another caller may have finished, cancelled or retired it while this one waited for the pin.
+            if (this.uploads.get(upload.id) !== upload)
+                return;
+            const stat = await fs.stat('.');
+            if (stat.dev !== upload.parent.dev || stat.ino !== upload.parent.ino)
+                throw new Error('Upload parent changed');
+            await this.clean(upload);
+        }).catch(() => this.uploads.get(upload.id) === upload ? this.abandon(upload) : undefined);
+    }
+}

package/dist/workstation/journal.js

@@ -1,10 +1,21 @@
+/**
+ * **Legacy, read-only. Remove in axom-cli 0.5.0.**
+ *
+ * Until Task 20 (spec 2026-10-11 §5.3) the daemon recorded every outbound `agent_event` / `agent_turn_done` of a session in
+ * `<configDir>/agents/sessions/<encodeURIComponent(sessionRef)>.jsonl` before sending it (`SessionJournal`), replayed the tail on
+ * reconnect and truncated it on `agent_event_ack`. That job moved to the transport's outbox stream (keeper-acp, or the local
+ * fallback's `<configDir>/agents/local/<sessionRef>/`), so nothing writes these files any more.
+ *
+ * What is left is reading the files an older CLI left behind: on the first start of a new CLI the manager migrates each one into
+ * a local outbox under the same ref (`AgentSessionManager.migrateLegacyJournals`) — offered as an orphan and resent on a reopen
+ * exactly as the journal was — and deletes the file. The release after the one that ships keepers drops this module (every
+ * daemon that could have left a journal has started a migrating CLI by then; a file still there is simply ignored).
+ *
+ * File layout: one `{seq, frame, src?}` JSON object per line; a torn trailing line (a crash mid-append) is skipped.
+ */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-/** Default cap for one session's journal. Past this, the oldest half is dropped (see {@link SessionJournal.droppedOldest}). */
-export const DEFAULT_JOURNAL_MAX_BYTES = 64 * 1024 * 1024;
-function serializeEntry(entry) {
-    return `${JSON.stringify({ seq: entry.seq, frame: entry.frame })}\n`;
-}
+const SUFFIX = '.jsonl';
 function parseEntry(line) {
     try {
         const parsed = JSON.parse(line);
@@ -12,246 +23,64 @@ function parseEntry(line) {
             return null;
         if (typeof parsed.frame !== 'object' || parsed.frame === null)
             return null;
-        return { seq: parsed.seq, frame: parsed.frame };
+        const src = parsed.src;
+        const valid = src !== null && typeof src === 'object' && Number.isSafeInteger(src.o) && Number.isSafeInteger(src.i) &&
+            src.o >= 0 && src.i >= 0;
+        return { seq: parsed.seq, frame: parsed.frame, ...(valid ? { src: { o: src.o, i: src.i } } : {}) };
     }
     catch {
         return null;
     }
 }
-function isEnoent(err) {
-    return err?.code === 'ENOENT';
-}
-/**
- * Append-only record of everything one external agent session has streamed to the server, plus the
- * session's seq allocator.
- *
- * It exists because the tunnel is not reliable: the websocket can drop mid-turn and the daemon can
- * restart while the native agent keeps running. Every outbound `agent_event` / `agent_turn_done` is
- * written here *before* it is sent, so on reconnect the server can say "I have applied through N"
- * and get everything after N replayed verbatim. The server acks with `agent_event_ack`, which is
- * what keeps the file from growing without bound in the steady state.
- *
- * **Scope of the guarantee: process crash, not power loss.** Writes go through `appendFile` /
- * `writeFile` with no `fsync`, so an entry that has returned from {@link append} survives the daemon
- * being killed, but bytes still sitting in the OS page cache can be lost to a kernel panic or a
- * power cut. That is the right trade for streamed agent output — an fsync per event would dominate
- * the cost of the event — and the failure mode degrades to the same seq gap a dropped socket causes.
- *
- * The seq allocator lives here rather than in the manager for the daemon-restart case: seq must not
- * restart at 1 when the process comes back, or the server's `seq > bridgeSeq` de-duplication would
- * silently swallow the whole next turn. {@link init} recovers the high-water mark from disk *and*
- * takes the reopening server's watermark as a floor (the file can be empty precisely because
- * everything in it was acked), and {@link nextSeq} continues from there.
- *
- * File layout: `<dir>/<sessionRef>.jsonl`, one `{seq, frame}` JSON object per line. `dir` is the
- * directory that *directly* holds the files — `AgentSessionManager` passes its `sessionsDir`
- * (`<journalDir>/sessions`). The file is created on the first {@link append}, not by {@link init},
- * so a session that opens and is abandoned before producing anything leaves nothing behind.
- *
- * Every public method is serialized on an internal queue: a rewrite (ack truncation, overflow drop)
- * must never interleave with an append, and callers hand work in from unordered bridge callbacks.
- */
-export class SessionJournal {
-    /** Absolute path of the `.jsonl`. Exposed for logging and tests; nothing else should read it directly. */
-    filePath;
-    dir;
-    tmpPath;
-    maxBytes;
-    maxSeq = 0;
-    /** Byte size of the file as of the last write; kept in memory so append does not stat every time. */
-    bytes = 0;
-    dropped = false;
-    ready = false;
-    queue = Promise.resolve();
-    constructor(dir, sessionRef, maxBytes = DEFAULT_JOURNAL_MAX_BYTES) {
-        this.dir = dir;
-        // sessionRefs are server-supplied strings, not filenames: percent-encoding keeps '/' and '..'
-        // from steering the write out of the journal directory, and keeps the mapping reversible.
-        this.filePath = path.join(dir, `${encodeURIComponent(sessionRef)}.jsonl`);
-        this.tmpPath = `${this.filePath}.tmp`;
-        this.maxBytes = maxBytes;
-    }
-    /** True once an overflow has discarded entries. The manager turns this into a visible gap notice on resume. */
-    get droppedOldest() {
-        return this.dropped;
-    }
-    /** Highest seq ever handed out or recovered. `0` means nothing has been journaled for this session. */
-    get lastSeq() {
-        return this.maxSeq;
-    }
-    /**
-     * Creates the journal directory and recovers `maxSeq` (and the byte size) from any existing file.
-     * Must be awaited before {@link nextSeq} / {@link append}; both throw otherwise, because a missed
-     * init would restart seq at 1 and desynchronize the server's watermark.
-     *
-     * `resumeFromSeq` is the server's watermark from the `agent_open` that is (re)creating this
-     * session, and it is a **floor** under the recovered value — never a ceiling. The file alone is
-     * not a sufficient source for the allocator: acked entries are truncated away, so between turns
-     * the journal is legitimately empty. A daemon restart in that window recovers `maxSeq = 0` while
-     * the server is still at N, `nextSeq()` starts back at 1, and every event the session produces
-     * from then on is `<= lastSeenSeq` on the server — silently swallowed, no error, no recovery
-     * path, the run hangs forever. Seeding from the watermark closes that hole without asking the
-     * server to lower anything (its watermark is advance-only at the storage layer, deliberately).
-     *
-     * A trailing line torn by a crash mid-append is dropped and the file rewritten, so a later append
-     * cannot glue new bytes onto half a record.
-     */
-    async init(resumeFromSeq = 0) {
-        await this.serialize(async () => {
-            await fs.mkdir(this.dir, { recursive: true });
-            const { entries, bytes, clean } = await this.readEntries();
-            const recovered = entries.reduce((max, entry) => Math.max(max, entry.seq), 0);
-            this.maxSeq = Math.max(recovered, resumeFromSeq);
-            this.bytes = clean ? bytes : await this.rewrite(entries);
-            this.ready = true;
-        });
-    }
-    /** Next seq for this session. Synchronous by design: bridge callbacks must number events in arrival order. */
-    nextSeq() {
-        this.requireReady();
-        this.maxSeq += 1;
-        return this.maxSeq;
-    }
-    /** Writes the entry to disk. Resolves only once the bytes are handed to the OS — callers send after this. */
-    async append(entry) {
-        await this.serialize(async () => {
-            this.requireReady();
-            const line = serializeEntry(entry);
-            const size = Buffer.byteLength(line);
-            if (this.bytes + size > this.maxBytes)
-                await this.dropOldestHalf(size);
-            await fs.appendFile(this.filePath, line);
-            this.bytes += size;
-            if (entry.seq > this.maxSeq)
-                this.maxSeq = entry.seq;
-        });
-    }
-    /**
-     * Everything the server has not applied yet, in append order. `seq` is the server's watermark.
-     *
-     * This is the one method that parses the whole file, so it is O(file) in both time and peak
-     * memory. That is affordable only because it runs on the reconnect path — once per `agent_open` —
-     * and never on the append path. Keep it that way.
-     */
-    async entriesAfter(seq) {
-        return this.serialize(async () => {
-            const { entries } = await this.readEntries();
-            return entries.filter((entry) => entry.seq > seq);
-        });
-    }
-    /**
-     * Forgets everything the server has acknowledged (`seq <= throughSeq`) by rewriting the file.
-     * `maxSeq` is deliberately untouched: acking is not a reason to reissue seqs.
-     */
-    async truncateThrough(seq) {
-        await this.serialize(async () => {
-            if (seq <= 0)
-                return;
-            const { entries } = await this.readEntries();
-            const kept = entries.filter((entry) => entry.seq > seq);
-            if (kept.length === entries.length)
-                return; // nothing acked that we still hold; don't churn the file
-            this.bytes = await this.rewrite(kept);
-        });
-    }
-    /** Removes the file for good (agent_close). The journal is unusable afterwards. */
-    async destroy() {
-        await this.serialize(async () => {
-            await fs.rm(this.filePath, { force: true });
-            await fs.rm(this.tmpPath, { force: true });
-            this.bytes = 0;
-            this.ready = false;
-        });
-    }
-    // --- internals (never call from inside another serialized op except via the private helpers) ---
-    requireReady() {
-        if (!this.ready) {
-            throw new Error(`SessionJournal ${this.filePath} used before init() (or after destroy())`);
-        }
-    }
-    /**
-     * Chains `op` after whatever is already queued — including a failed predecessor, so one bad write
-     * does not wedge the session forever.
-     */
-    serialize(op) {
-        const run = this.queue.then(op, op);
-        this.queue = run.then(() => undefined, () => undefined);
-        return run;
-    }
-    /** `clean: false` means at least one line failed to parse and the file should be rewritten. */
-    async readEntries() {
-        let text;
-        try {
-            text = await fs.readFile(this.filePath, 'utf8');
-        }
-        catch (err) {
-            if (isEnoent(err))
-                return { entries: [], bytes: 0, clean: true };
-            throw err;
-        }
-        const entries = [];
-        let clean = true;
-        for (const line of text.split('\n')) {
-            if (line.length === 0)
-                continue;
-            const entry = parseEntry(line);
-            if (entry)
-                entries.push(entry);
-            else
-                clean = false;
-        }
-        return { entries, bytes: Buffer.byteLength(text), clean };
-    }
-    /** Replaces the file with exactly `entries`, atomically. Returns the new byte size. */
-    async rewrite(entries) {
-        return this.rewriteRaw(Buffer.from(entries.map(serializeEntry).join('')));
+const fileOf = (dir, sessionRef) => path.join(dir, `${encodeURIComponent(sessionRef)}${SUFFIX}`);
+/** The refs of the journal files in `dir` (`<journalDir>/sessions`), sorted. A missing directory is none. */
+export async function listLegacyJournalRefs(dir) {
+    let names;
+    try {
+        names = await fs.readdir(dir);
     }
-    /** Replaces the file with `data`, atomically. Returns the new byte size. */
-    async rewriteRaw(data) {
-        await fs.writeFile(this.tmpPath, data);
-        await fs.rename(this.tmpPath, this.filePath);
-        return data.length;
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return [];
+        throw error;
     }
-    /**
-     * Makes room for `incoming` bytes by discarding the oldest half, repeating until it fits. Dropping
-     * the *oldest* is the only safe direction: the newest output is what the user is watching, and the
-     * server can be told about the hole (a synthetic gap event) but cannot invent the missing bytes.
-     *
-     * This runs on the **append path**, so it deliberately never parses or re-serializes a record. It
-     * reads the file once as raw bytes, walks to a newline boundary past the half-way mark, and writes
-     * back a slice of that same buffer. At the 64MB cap that is one 64MB read plus one ≤32MB write —
-     * versus the several-hundred-MB transient and multi-second single-threaded stall an entry-level
-     * round-trip would cost, on a daemon that is also serving `exec_request` on the same loop.
-     *
-     * Halving by *bytes* rather than by record count is the same policy in a cheaper coordinate: the
-     * point is to reclaim about half the file in one pass so the trim is amortized over many appends.
-     */
-    async dropOldestHalf(incoming) {
-        let buf;
+    const refs = [];
+    for (const name of names) {
+        if (!name.endsWith(SUFFIX))
+            continue;
         try {
-            buf = await fs.readFile(this.filePath);
+            refs.push(decodeURIComponent(name.slice(0, -SUFFIX.length)));
         }
-        catch (err) {
-            if (isEnoent(err)) {
-                this.bytes = 0; // tracked size was stale; nothing on disk to drop
-                return;
-            }
-            throw err;
+        catch {
+            // Not a name a daemon wrote (`encodeURIComponent` never emits a malformed escape).
         }
-        let start = 0;
-        while (start < buf.length && buf.length - start + incoming > this.maxBytes) {
-            // Cut at the first record boundary at or after the half-way point of what is left. Every line
-            // ends in '\n', so the newline search can only land on a real boundary; if there is none left
-            // the remainder is a single oversized record and we drop all of it.
-            const half = start + Math.ceil((buf.length - start) / 2);
-            const newline = buf.indexOf(0x0a, half);
-            start = newline === -1 ? buf.length : newline + 1;
-        }
-        // Nothing to drop means a single record larger than the whole cap; write it anyway rather than
-        // lose it, and let the next append trim back down.
-        if (start === 0)
-            return;
-        this.dropped = true;
-        this.bytes = await this.rewriteRaw(buf.subarray(start));
     }
+    return refs.sort();
+}
+/** Every readable entry of `sessionRef`'s journal, in file order (unreadable lines skipped). A missing file is empty. */
+export async function readLegacyJournal(dir, sessionRef) {
+    let text;
+    try {
+        text = await fs.readFile(fileOf(dir, sessionRef), 'utf8');
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const entries = [];
+    for (const line of text.split('\n')) {
+        if (line.length === 0)
+            continue;
+        const entry = parseEntry(line);
+        if (entry)
+            entries.push(entry);
+    }
+    return entries;
+}
+/** Deletes `sessionRef`'s journal (and the `.tmp` a rewrite may have left). */
+export async function removeLegacyJournal(dir, sessionRef) {
+    const file = fileOf(dir, sessionRef);
+    await fs.rm(file, { force: true });
+    await fs.rm(`${file}.tmp`, { force: true });
 }