@playola-radio/slipstream 0.1.0 → 0.3.0

package/dist/store-reader.js

@@ -25,14 +25,16 @@ export function tombstonePath(storeDir, id) {
 export function blobPath(storeDir, hex) {
     return join(storeDir, 'blobs', 'sha256', hex.slice(0, 2), hex);
 }
-export async function onDiskHighWater(logPath) {
+/** The last complete record's seq, time, type and data; undefined for a missing log or
+ * one with no complete line. Torn trailing bytes are ignored. */
+export async function finalRecord(logPath) {
     let handle;
     try {
         handle = await open(logPath, 'r');
     }
     catch (err) {
         if (err.code === 'ENOENT')
-            return 0n;
+            return undefined;
         throw err;
     }
     let lastLine;
@@ -62,7 +64,7 @@ export async function onDiskHighWater(logPath) {
                 break;
         }
         if (!foundEnd)
-            return 0n;
+            return undefined;
         lastLine = Buffer.concat(pieces.reverse()).toString('utf8');
     }
     finally {
@@ -70,17 +72,23 @@ export async function onDiskHighWater(logPath) {
     }
     if (lastLine === '')
         throw new LogCorruptError('high-water: blank final record');
-    let seq;
+    let parsed;
     try {
-        seq = JSON.parse(lastLine).seq;
+        parsed = JSON.parse(lastLine);
     }
     catch {
         throw new LogCorruptError('high-water: invalid JSON in final record');
     }
-    if (typeof seq !== 'string' || !SEQ_RE.test(seq)) {
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new LogCorruptError('high-water: final record is not an object');
+    }
+    if (typeof parsed.seq !== 'string' || !SEQ_RE.test(parsed.seq)) {
         throw new LogCorruptError('high-water: final record has no valid decimal-string seq');
     }
-    return BigInt(seq);
+    return { seq: BigInt(parsed.seq), time: parsed.time, type: parsed.type, data: parsed.data };
+}
+export async function onDiskHighWater(logPath) {
+    return (await finalRecord(logPath))?.seq ?? 0n;
 }
 export async function readTombstone(storeDir, id) {
     try {
@@ -125,6 +133,103 @@ export async function listSessions(storeDir) {
     out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
     return out;
 }
+/** A session recorded for this workspace whose history cannot be read. Attach
+ * must fail closed on it rather than start a second stream for the workspace. */
+export class WorkspaceLookupError extends Error {
+    sessionId;
+    /** Whether the log itself is damaged (or gone), as opposed to a transient read
+     * failure such as EMFILE; only corruption justifies advising deletion. */
+    corrupt;
+    constructor(sessionId, cause) {
+        super(`session ${sessionId} records this workspace but its log cannot be read: ${cause.message}`, { cause });
+        this.name = 'WorkspaceLookupError';
+        this.sessionId = sessionId;
+        this.corrupt = cause instanceof LogCorruptError || cause.code === 'ENOENT';
+    }
+}
+const FIRST_RECORD_LIMIT = 64 * 1024;
+/** The `root` of a log's first record, which must be `session.started`. */
+async function startedRoot(logPath) {
+    // Lookup opens every session's log on every attach; one FIFO must not wedge it.
+    const handle = await open(logPath, constants.O_RDONLY | constants.O_NONBLOCK);
+    let line;
+    try {
+        if (!(await handle.stat()).isFile())
+            throw new LogCorruptError('log is not a regular file');
+        const buffer = Buffer.allocUnsafe(FIRST_RECORD_LIMIT);
+        const { bytesRead } = await handle.read(buffer, 0, FIRST_RECORD_LIMIT, 0);
+        const end = buffer.subarray(0, bytesRead).indexOf(0x0a);
+        if (end < 0)
+            throw new LogCorruptError('first record is torn or larger than 64 KiB');
+        line = buffer.subarray(0, end).toString('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        throw new LogCorruptError('first record is not valid JSON');
+    }
+    if (typeof parsed !== 'object' || parsed === null
+        || parsed.type !== 'slipstream.session.started.v1' || typeof parsed.data?.root !== 'string') {
+        throw new LogCorruptError('first record is not a session.started record');
+    }
+    return parsed.data.root;
+}
+/** The non-removed session recorded for `canonicalRoot`, derived from the logs
+ * alone. Duplicates resolve to the newest last record, then the smallest id. A
+ * session whose first record cannot be read is skipped and reported. */
+export async function findWorkspaceSession(storeDir, canonicalRoot) {
+    let entries;
+    try {
+        entries = await readdir(sessionsDir(storeDir));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { match: undefined, skipped: [] };
+        throw err;
+    }
+    const skipped = [];
+    let best;
+    for (const id of entries.filter(isValidSessionId).sort()) {
+        if ((await readTombstone(storeDir, id)) !== null)
+            continue;
+        const logPath = sessionLogPath(storeDir, id);
+        let root;
+        try {
+            root = await startedRoot(logPath);
+        }
+        catch (err) {
+            const unreadable = err instanceof LogCorruptError || err.code === 'ENOENT';
+            if (!unreadable)
+                throw err;
+            skipped.push({ id, reason: err.message });
+            continue;
+        }
+        if (root !== canonicalRoot)
+            continue;
+        let last;
+        let ms;
+        try {
+            const final = await finalRecord(logPath);
+            if (!final)
+                throw new LogCorruptError('log has no complete record');
+            last = final;
+            ms = typeof last.time === 'string' ? Date.parse(last.time) : Number.NaN;
+            if (Number.isNaN(ms))
+                throw new LogCorruptError('final record has no valid time');
+        }
+        catch (err) {
+            throw new WorkspaceLookupError(id, err);
+        }
+        if (!best || ms > best.ms)
+            best = { id, durableSeq: last.seq, ms };
+    }
+    return { match: best && { id: best.id, durableSeq: best.durableSeq }, skipped };
+}
 export async function schemaBytes(type) {
     if (!EVENT_TYPES.includes(type))
         return null;

package/dist/task-forwarder.js

@@ -15,16 +15,16 @@
  *     {@link shouldAutoResend}); a generic ambiguous request is never blindly
  *     retried.
  *
- *     KNOWN LIMIT (at-least-once): the forwarder omits session_id (it never
+ *     KNOWN LIMIT: the forwarder omits session_id (it never
  *     attaches, so it cannot know the capture UUID), so idempotency is scoped to
  *     the selected capture session. If the SAME identity triple is detached and
- *     reattached between the first send and the resend, the resend lands in a NEW
- *     capture session whose `committedTasks` does not yet hold this request_id,
- *     and the task is recorded a second time (in the new session). The success we
- *     then report is truthful — a task WAS declared — but the intent is recorded
- *     twice across the two sessions. This is the accepted cost of the locked
- *     at-least-once auto-resend; closing it needs store-level request_id dedup
- *     (P3 idempotency scope), which is a design decision, not a forwarder fix.
+ *     reattached between the first send and the resend, re-attaching resumes the
+ *     SAME session and rebuilds its request_id index from the log, so the resend
+ *     replays the first send's result instead of recording the task twice. But
+ *     a resume deliberately clears the current task (spec D1), and a replay does
+ *     not reactivate it: the success we report is truthful (the task WAS
+ *     declared), yet later changes stay ungrouped until the agent declares a
+ *     task again under a new request_id.
  *
  *  2. When the resend cannot definitively resolve the first send, we must not
  *     imply "nothing committed." A structurally-rejected resend (INVALID_TITLE /

package/dist/transcript/discovery.js

@@ -42,8 +42,9 @@ function segmentsOf(path) {
     return path.split('/').filter((s) => s !== '' && s !== '.');
 }
 /**
- * True when an UNRESOLVABLE cwd could still sit inside the capture root, so it is
- * an in-root candidate we failed to read rather than a genuine non-candidate.
+ * Place an UNRESOLVABLE cwd so each capture root can tell whether it could still
+ * sit inside it: an in-root candidate we failed to read rather than a genuine
+ * non-candidate.
  *
  * A textual check is unreliable both ways: the raw string may be in the root's
  * alias namespace (cwd `/tmp/proj/gone` for canonical root `/private/tmp/proj`)
@@ -67,7 +68,7 @@ function segmentsOf(path) {
  * Undecidable cases (an uninspectable component, a symlink cycle past the hop
  * cap) fail toward disclosure: never claim non-membership we did not establish.
  */
-async function unresolvedCwdMayBeInRoot(io, root, cwd) {
+async function placeUnresolvedCwd(io, cwd) {
     const queue = segmentsOf(cwd);
     let cursor = 0;
     let base = '/';
@@ -103,15 +104,37 @@ async function unresolvedCwdMayBeInRoot(io, root, cwd) {
             // against the target and the target's living parts get canonicalized above.
             symlinkHops += 1;
             if (symlinkHops > MAX_UNRESOLVED_HOPS)
-                return true; // cycle: disclose
+                return { kind: 'undecidable' }; // cycle: disclose
             if (isAbsolute(probe.target))
                 base = '/';
             queue.splice(cursor, 0, ...segmentsOf(probe.target));
             continue;
         }
-        return true; // uninspectable (e.g. permissions): cannot rule out membership
+        return { kind: 'undecidable' }; // uninspectable (e.g. permissions): cannot rule out membership
     }
-    return isWithinRoot(root, base);
+    return { kind: 'placed', path: base };
+}
+function createCwdResolver(io) {
+    const real = new Map();
+    const placed = new Map();
+    const memoIO = {
+        probe: (path) => io.probe(path),
+        realpath: (path) => {
+            let p = real.get(path);
+            if (!p)
+                real.set(path, (p = io.realpath(path)));
+            return p;
+        },
+    };
+    return {
+        realpath: memoIO.realpath,
+        placeUnresolved: (cwd) => {
+            let p = placed.get(cwd);
+            if (!p)
+                placed.set(cwd, (p = placeUnresolvedCwd(memoIO, cwd)));
+            return p;
+        },
+    };
 }
 /**
  * Classify a recorded cwd against the capture root, the single membership rule
@@ -120,10 +143,11 @@ async function unresolvedCwdMayBeInRoot(io, root, cwd) {
  * (Claude) or a shared global sessions dir (Codex) cannot bind another worktree's
  * session to this root.
  */
-async function classifyCwd(io, root, cwd) {
-    const canonicalCwd = await io.realpath(cwd);
+async function classifyCwd(resolver, root, cwd) {
+    const canonicalCwd = await resolver.realpath(cwd);
     if (canonicalCwd === undefined) {
-        return (await unresolvedCwdMayBeInRoot(io, root, cwd))
+        const placed = await resolver.placeUnresolved(cwd);
+        return placed.kind === 'undecidable' || isWithinRoot(root, placed.path)
             ? { kind: 'unresolved-in-root' }
             : { kind: 'out-of-root' };
     }
@@ -137,7 +161,7 @@ async function classifyCwd(io, root, cwd) {
     let rootAliases;
     if (cwd !== canonicalCwd) {
         const aliasRoot = resolve(cwd, relative(canonicalCwd, root));
-        if ((await io.realpath(aliasRoot)) === root)
+        if ((await resolver.realpath(aliasRoot)) === root)
             rootAliases = [aliasRoot];
     }
     return { kind: 'in-root', cwd: canonicalCwd, ...(rootAliases !== undefined ? { rootAliases } : {}) };
@@ -209,69 +233,147 @@ async function resolveClaudeCwd(io, path, firstLine, firstId) {
     }
     return { kind: 'none' };
 }
-export async function discoverClaude(io, home, root) {
-    const dir = `${home}/projects/${claudeSlug(root)}`;
-    const listed = await io.listDir(dir);
-    if (!listed.ok) {
-        return { bindings: [], issues: [{ kind: listed.reason, detail: `claude project dir ${dir}` }] };
+export function createDiscoveryMemory() {
+    return { codex: new Map(), claude: new Map() };
+}
+function sameFile(a, b) {
+    return a.dev === b.dev && a.ino === b.ino;
+}
+/**
+ * `read`'s result for `path`, or the remembered header if the file is unchanged.
+ * A permission change keeps the header: the bytes it came from are unchanged,
+ * and a bound transcript that turns unreadable is still disclosed by its reader.
+ */
+async function readRemembered(io, memory, path, read) {
+    if (memory === undefined)
+        return read();
+    // Stat BEFORE reading, so the remembered size is never larger than the
+    // generation that was actually read.
+    const now = await io.stat(path);
+    const known = memory.get(path);
+    if (now !== undefined && known !== undefined && sameFile(now.id, known.id) && now.size >= known.size) {
+        known.size = now.size;
+        return { ok: true, header: known.header, id: known.id };
     }
-    const bindings = [];
-    const issues = [];
-    for (const path of listed.paths) {
-        const sessionId = baseName(path).slice(0, -'.jsonl'.length);
-        // The slug directory alone cannot establish membership: two distinct roots can
-        // collide onto one slug (e.g. /work/a-b and /work/a/b). So a transcript is bound
-        // ONLY once its recorded cwd has been read and confirmed in-root — it is never
-        // slug-trusted. Until confirmation:
-        //   - an empty or still-preamble transcript is withheld with no issue (pending
-        //     coverage); it is re-checked next tick once more is written, and no record
-        //     is ingested under an unconfirmed binding (so a colliding sibling's records
-        //     landing before confirmation can never be credited to this root);
-        //   - a transcript whose membership cannot be confirmed (unreadable/oversized or
-        //     truncated head, or an in-root cwd that will not resolve) is disclosed.
-        const head = await io.readFirstLine(path);
-        if (!head.ok) {
-            if (head.reason === 'empty')
-                continue; // not yet written: withhold, stays pending
-            // A first line that exists but could not be read (malformed, e.g. invalid
-            // UTF-8 or an unbounded line; or inaccessible): disclose the gap.
-            issues.push({ kind: head.reason, detail: `claude transcript ${path}` });
-            continue;
-        }
-        const resolution = await resolveClaudeCwd(io, path, head.line, head.id);
-        if (resolution.kind === 'none')
-            continue; // a cwd-less preamble so far: withhold, pending
-        if (resolution.kind === 'unconfirmed') {
-            issues.push({
-                kind: resolution.reason,
-                detail: `claude transcript ${path} membership unconfirmed: ${resolution.detail}`,
-            });
+    const result = await read();
+    if (result.ok && now !== undefined && sameFile(now.id, result.id)) {
+        memory.set(path, { id: result.id, size: now.size, header: result.header });
+    }
+    else {
+        memory.delete(path);
+    }
+    return result;
+}
+function forgetUnlisted(memory, listed) {
+    if (memory === undefined)
+        return;
+    for (const path of memory.keys())
+        if (!listed.has(path))
+            memory.delete(path);
+}
+/** One result per distinct root, each with its own arrays. */
+function emptyResults(roots) {
+    return new Map([...new Set(roots)].map((root) => [root, { bindings: [], issues: [] }]));
+}
+/** Disclose one issue to every root it concerns, each getting its own copy. */
+function discloseTo(results, roots, issue) {
+    for (const root of roots)
+        results.get(root).issues.push({ ...issue });
+}
+/**
+ * Claude discovery for several capture roots in one pass. Each Claude project
+ * directory is listed once and each transcript head read once, however many roots
+ * slug onto it; the recorded cwd then decides, per root, whether it is a member.
+ */
+export async function discoverClaudeRoots(io, home, roots, memory) {
+    const results = emptyResults(roots);
+    const resolver = createCwdResolver(io);
+    const listedPaths = new Set();
+    const byDir = new Map();
+    for (const root of results.keys()) {
+        const dir = `${home}/projects/${claudeSlug(root)}`;
+        byDir.set(dir, [...(byDir.get(dir) ?? []), root]);
+    }
+    for (const [dir, group] of byDir) {
+        const listed = await io.listDir(dir);
+        if (!listed.ok) {
+            discloseTo(results, group, { kind: listed.reason, detail: `claude project dir ${dir}` });
             continue;
         }
-        const cls = await classifyCwd(io, root, resolution.cwd);
-        if (cls.kind === 'out-of-root')
-            continue; // a slug-colliding other worktree
-        if (cls.kind === 'unresolved-in-root') {
-            issues.push({
-                kind: 'inaccessible',
-                detail: `claude transcript ${path} cwd ${resolution.cwd} could not be resolved`,
-            });
-            continue;
+        for (const path of listed.paths) {
+            listedPaths.add(path);
+            const sessionId = baseName(path).slice(0, -'.jsonl'.length);
+            // The slug directory alone cannot establish membership: two distinct roots can
+            // collide onto one slug (e.g. /work/a-b and /work/a/b). So a transcript is bound
+            // ONLY once its recorded cwd has been read and confirmed in-root — it is never
+            // slug-trusted. Until confirmation:
+            //   - an empty or still-preamble transcript is withheld with no issue (pending
+            //     coverage); it is re-checked next tick once more is written, and no record
+            //     is ingested under an unconfirmed binding (so a colliding sibling's records
+            //     landing before confirmation can never be credited to this root);
+            //   - a transcript whose membership cannot be confirmed (unreadable/oversized or
+            //     truncated head, or an in-root cwd that will not resolve) is disclosed.
+            const resolution = await readRemembered(io, memory?.claude, path, () => readClaudeHeader(io, path));
+            if (!resolution.ok) {
+                if (resolution.issue !== undefined)
+                    discloseTo(results, group, resolution.issue);
+                continue;
+            }
+            const cwd = resolution.header;
+            for (const root of group) {
+                const result = results.get(root);
+                const cls = await classifyCwd(resolver, root, cwd);
+                if (cls.kind === 'out-of-root')
+                    continue; // a slug-colliding other worktree
+                if (cls.kind === 'unresolved-in-root') {
+                    result.issues.push({
+                        kind: 'inaccessible',
+                        detail: `claude transcript ${path} cwd ${cwd} could not be resolved`,
+                    });
+                    continue;
+                }
+                result.bindings.push({
+                    path,
+                    ctx: {
+                        harness: 'claude-code',
+                        harnessSessionId: sessionId,
+                        root,
+                        cwd: cls.cwd,
+                        adapterVersion: CLAUDE_ADAPTER_VERSION,
+                        ...(cls.rootAliases !== undefined ? { rootAliases: cls.rootAliases } : {}),
+                    },
+                    generation: resolution.id,
+                });
+            }
         }
-        bindings.push({
-            path,
-            ctx: {
-                harness: 'claude-code',
-                harnessSessionId: sessionId,
-                root,
-                cwd: cls.cwd,
-                adapterVersion: CLAUDE_ADAPTER_VERSION,
-                ...(cls.rootAliases !== undefined ? { rootAliases: cls.rootAliases } : {}),
-            },
-            generation: resolution.id,
-        });
     }
-    return { bindings, issues };
+    forgetUnlisted(memory?.claude, listedPaths);
+    return results;
+}
+/** A Claude transcript's recorded cwd, or the issue to disclose (none: withhold it
+ * as pending, to be re-checked next cycle). */
+async function readClaudeHeader(io, path) {
+    const head = await io.readFirstLine(path);
+    if (!head.ok) {
+        if (head.reason === 'empty')
+            return { ok: false }; // not yet written: withhold, stays pending
+        // A first line that exists but could not be read (malformed, e.g. invalid
+        // UTF-8 or an unbounded line; or inaccessible): disclose the gap.
+        return { ok: false, issue: { kind: head.reason, detail: `claude transcript ${path}` } };
+    }
+    const resolution = await resolveClaudeCwd(io, path, head.line, head.id);
+    if (resolution.kind === 'none')
+        return { ok: false }; // a cwd-less preamble so far: withhold, pending
+    if (resolution.kind === 'unconfirmed') {
+        return {
+            ok: false,
+            issue: { kind: resolution.reason, detail: `claude transcript ${path} membership unconfirmed: ${resolution.detail}` },
+        };
+    }
+    return { ok: true, header: resolution.cwd, id: resolution.id };
+}
+export async function discoverClaude(io, home, root) {
+    return (await discoverClaudeRoots(io, home, [root])).get(root);
 }
 function parseSessionMeta(line) {
     try {
@@ -293,73 +395,102 @@ function parseSessionMeta(line) {
         return undefined;
     }
 }
-export async function discoverCodex(io, home, root, limit) {
+/**
+ * Codex discovery for several capture roots in one pass. The global sessions tree
+ * is enumerated once and each rollout's `session_meta` read once; its cwd then
+ * decides, per root, whether it is a member. A scan-wide gap (the file cap, an
+ * unreadable subdirectory, a rollout we cannot read) could hide any root's
+ * session, so it is disclosed to every root, exactly as a lone scan would.
+ */
+export async function discoverCodexRoots(io, home, roots, limit, memory) {
+    const results = emptyResults(roots);
+    const all = [...results.keys()];
     const dir = `${home}/sessions`;
     const listed = await io.listTreeJsonl(dir, limit);
     if ('ok' in listed && listed.ok === false) {
-        return { bindings: [], issues: [{ kind: listed.reason, detail: `codex sessions dir ${dir}` }] };
+        memory?.codex.clear();
+        discloseTo(results, all, { kind: listed.reason, detail: `codex sessions dir ${dir}` });
+        return results;
     }
     const { paths, truncated, incomplete } = listed;
-    const issues = [];
     if (truncated) {
-        issues.push({
+        discloseTo(results, all, {
             kind: 'discovery-limited',
             detail: `codex session scan hit the ${limit}-file cap; some transcripts may be unread`,
         });
     }
     if (incomplete) {
-        issues.push({
+        discloseTo(results, all, {
             kind: 'inaccessible',
             detail: `some codex session subdirectories under ${dir} were unreadable`,
         });
     }
-    const bindings = [];
+    forgetUnlisted(memory?.codex, new Set(paths));
+    const resolver = createCwdResolver(io);
     for (const path of paths) {
         // A file we cannot read or parse is a candidate we cannot rule out, so it is
         // disclosed as an issue — never silently skipped (which would let a readable
         // sibling conceal it and report coverage as clean).
-        const head = await io.readFirstLine(path);
+        const head = await readRemembered(io, memory?.codex, path, () => readCodexHeader(io, path));
         if (!head.ok) {
-            issues.push({
-                kind: head.reason === 'inaccessible' ? 'inaccessible' : 'malformed',
-                detail: `codex rollout ${path}`,
-            });
-            continue;
-        }
-        const meta = parseSessionMeta(head.line);
-        if (!meta) {
-            issues.push({ kind: 'malformed', detail: `codex rollout ${path} has no session_meta` });
+            discloseTo(results, all, head.issue);
             continue;
         }
-        const cls = await classifyCwd(io, root, meta.cwd);
-        if (cls.kind === 'out-of-root')
-            continue;
-        if (cls.kind === 'unresolved-in-root') {
-            // An in-root candidate we failed to read: disclose the gap rather than let a
-            // readable sibling report clean coverage. A cwd whose nearest living ancestor
-            // is outside the root is a different worktree's session, skipped silently.
-            issues.push({ kind: 'inaccessible', detail: `codex rollout ${path} cwd ${meta.cwd} could not be resolved` });
-            continue;
+        const meta = head.header;
+        for (const root of all) {
+            const result = results.get(root);
+            const cls = await classifyCwd(resolver, root, meta.cwd);
+            if (cls.kind === 'out-of-root')
+                continue;
+            if (cls.kind === 'unresolved-in-root') {
+                // An in-root candidate we failed to read: disclose the gap rather than let a
+                // readable sibling report clean coverage. A cwd whose nearest living ancestor
+                // is outside the root is a different worktree's session, skipped silently.
+                result.issues.push({ kind: 'inaccessible', detail: `codex rollout ${path} cwd ${meta.cwd} could not be resolved` });
+                continue;
+            }
+            result.bindings.push({
+                path,
+                ctx: {
+                    harness: 'codex',
+                    harnessSessionId: meta.id,
+                    root,
+                    cwd: cls.cwd,
+                    adapterVersion: CODEX_ADAPTER_VERSION,
+                    ...(cls.rootAliases !== undefined ? { rootAliases: cls.rootAliases } : {}),
+                },
+                // The Codex ctx derives entirely from line 1 (session_meta), so the generation
+                // is the first-line read that produced it.
+                generation: head.id,
+            });
         }
-        bindings.push({
-            path,
-            ctx: {
-                harness: 'codex',
-                harnessSessionId: meta.id,
-                root,
-                cwd: cls.cwd,
-                adapterVersion: CODEX_ADAPTER_VERSION,
-                ...(cls.rootAliases !== undefined ? { rootAliases: cls.rootAliases } : {}),
-            },
-            // The Codex ctx derives entirely from line 1 (session_meta), so the generation
-            // is the first-line read that produced it.
-            generation: head.id,
-        });
     }
-    return { bindings, issues };
+    return results;
 }
-export async function discover(harness, io, home, root, codexScanLimit) {
+/** A Codex rollout's `session_meta`, or the issue to disclose. */
+async function readCodexHeader(io, path) {
+    const head = await io.readFirstLine(path);
+    if (!head.ok) {
+        return {
+            ok: false,
+            issue: { kind: head.reason === 'inaccessible' ? 'inaccessible' : 'malformed', detail: `codex rollout ${path}` },
+        };
+    }
+    const meta = parseSessionMeta(head.line);
+    if (!meta)
+        return { ok: false, issue: { kind: 'malformed', detail: `codex rollout ${path} has no session_meta` } };
+    return { ok: true, header: meta, id: head.id };
+}
+export async function discoverCodex(io, home, root, limit) {
+    return (await discoverCodexRoots(io, home, [root], limit)).get(root);
+}
+/** One harness's discovery for every given capture root, sharing enumeration and
+ * header reads across them, and with `memory`, across cycles. */
+export async function discoverRoots(harness, io, home, roots, codexScanLimit, memory) {
     return harness === 'claude-code'
-        ? discoverClaude(io, home, root)
-        : discoverCodex(io, home, root, codexScanLimit);
+        ? discoverClaudeRoots(io, home, roots, memory)
+        : discoverCodexRoots(io, home, roots, codexScanLimit, memory);
+}
+export async function discover(harness, io, home, root, codexScanLimit) {
+    return (await discoverRoots(harness, io, home, [root], codexScanLimit)).get(root);
 }

package/dist/transcript/fs-io.js

@@ -1,4 +1,4 @@
-import { lstat as fsLstat, open, readdir, readlink as fsReadlink, realpath as fsRealpath, } from 'node:fs/promises';
+import { lstat as fsLstat, open, readdir, readlink as fsReadlink, realpath as fsRealpath, stat as fsStat, } from 'node:fs/promises';
 import { join } from 'node:path';
 /** The real filesystem IO for transcript files. Missing → `missing`; any other
  * open/read error → `inaccessible` (disclosed, never a silent empty read). The
@@ -253,6 +253,15 @@ export const nodeDiscoveryIO = {
             await handle.close();
         }
     },
+    async stat(path) {
+        try {
+            const s = await fsStat(path, { bigint: true });
+            return { id: { dev: s.dev, ino: s.ino }, size: Number(s.size) };
+        }
+        catch {
+            return undefined;
+        }
+    },
     async realpath(path) {
         try {
             return await fsRealpath(path);