@tangle-network/harness-sessions 0.1.3 → 0.1.4

package/README.md

@@ -22,10 +22,19 @@ npm install @tangle-network/harness-sessions
 | Harness | Format | Store under HOME | Served model from | Usage |
 |---|---|---|---|---|
 | `claude-code` | `claude-code.projects-jsonl` | `.claude/projects/*/{id}.jsonl`, subagents at `*/{id}/subagents/**/*.jsonl` | provider response (`message.model`) | per response, counted once per `message.id` |
-| `codex` | `codex.rollout-jsonl` | `.codex/sessions/*/*/*/rollout-*-{id}.jsonl` | turn context (the configured model) | per response (`last_token_usage`); session total from `total_token_usage` |
+| `codex` | `codex.rollout-jsonl` | `rollout-*-{id}.jsonl` under `sessions/` and `archived_sessions/` of every Codex home (below) | turn context (the configured model) | per response (`last_token_usage`); session total from `total_token_usage` |
 | `opencode` | `opencode.sqlite` | `.local/share/opencode/opencode.db` (shared by every session) | session record (`providerID/modelID`) | per step (`step-finish`) |
 | `pi` | `pi.session-jsonl` | `.pi/agent/sessions/**/*_{id}.jsonl` | session record (`provider/model`) | per assistant message |
 
+A HOME can hold several Codex homes, and `codexReader.locate` reads all of them (`codexHomes(home)` lists them):
+
+- `.codex` and each sibling `.codex-<name>`;
+- each acct account home, `.config/agent-accounts/codex/<account>`;
+- `home` itself when it is a Codex home by its path (`isCodexHome`), such as a fleet seat's `codex` directory passed as a store root;
+- for this process's own HOME only, `$CODEX_HOME` and `$ACCT_CONFIG/codex/<account>` in place of the default accounts directory. Another HOME, such as an archived host's store root or a capture, is read by its layout alone.
+
+Homes that resolve to one directory count once. A session copied into several homes (`acct move`) is one ref, its largest copy. A lookup by id takes the rollout whose name ends in the id; when no name does, it reads the `session_meta` of each rollout modified since the id's UUIDv7 time.
+
 Readers for Kimi, Factory, Gemini, Amp, Qwen, Copilot, Forge, Hermes, Prime and OpenClaw are added with the same real-data proof.
 
 ## Use
@@ -61,9 +70,10 @@ harness-sessions read <file|home|capture> [--harness h] [--session id] [--summar
 - The served model comes only from the provider response or the session record, never from the profile or the request. A failed request has no served model; `requestedModel` says which model it was sent to.
 - `usage` is `null` when the harness recorded none; it is never reported as zero. `input` excludes cache reads and cache writes, which have their own fields.
 - A session with zero model calls is not the trace of a turn.
+- `locate(home, { cwd })` keeps a session whose recorded cwd is `cwd` or lies under it on a path boundary (`withinPath`): `/w/agent` matches `/w/agent/sub`, never `/w/agent-dev-container`. Every store is resolved against the `home` given; only the Codex environment overrides above depend on the process.
 - An unparsable record is counted in `integrity.unparsedRecords` and never stops a read (`corruption: 'strict'` throws instead). A record cut off at the end of a live copy is reported as a torn tail, not as corruption.
 - `ending.status` is `completed`, `error`, `aborted` or `open`. `open` means the records stop mid-turn: the turn was still running or the process died.
-- An OpenCode store is read from a private copy, never in place.
+- An OpenCode store is opened read-only where it lies, with no copy: SQLite never writes the store or its write-ahead log. With a log present it reads the log's committed rows and keeps only its own shared-memory index (`-shm`) current; without one the store is opened immutable and nothing is created beside it. A store SQLite cannot open in place (a log with no `-shm` in a directory it cannot write, such as a capture on read-only storage, or any store under Node before 22.15, whose `node:sqlite` takes no URI file names) is read from a private copy. `integrity.sourceFiles` names the session as `<store>#session=<id>` with a digest of the rows read for it.
 
 ## Tests
 

package/dist/catalog.d.ts

@@ -153,6 +153,33 @@ export declare const EVIDENCE: {
         readonly endingError: 'none';
     };
 };
+/**
+ * Codex writes to whichever Codex home it runs with, so one HOME can hold several: `~/.codex`, a
+ * sibling such as `~/.codex-lane`, the `$CODEX_HOME` a process set, one acct home per account under
+ * `${ACCT_CONFIG:-~/.config/agent-accounts}/codex/<account>`, and on a fleet host a seat's `codex`
+ * directory. Every home keeps live rollouts in `sessions/` and archived ones in
+ * `archived_sessions/`. `STORES` declares the default home's live store, which is what a sandbox
+ * captures; the readers search every home. The same rule as tangle-tools
+ * `trace-archive/catalog.py` `classify`.
+ */
+export declare const CODEX_HOME_RULE: {
+    /** Directory names directly under HOME that are Codex homes: `.codex` and `.codex-<name>`. */
+    readonly siblings: RegExp;
+    /** Under HOME, unless `$ACCT_CONFIG` names it: each child is one account's Codex home. */
+    readonly accounts: '.config/agent-accounts/codex';
+    readonly sessionDirs: readonly ['sessions', 'archived_sessions'];
+    /** A rollout's file name, at any depth under a session dir (`sessions/` nests by date). */
+    readonly rollout: 'rollout-*.jsonl';
+    /** The name Codex gives a rollout, ending in its thread id. */
+    readonly named: 'rollout-*-{id}.jsonl';
+};
+/**
+ * True when `dir` is itself a Codex home by its path: `.codex`, `.codex-<name>`, an acct account
+ * home (`agent-accounts/codex/<account>`), or a fleet seat's `codex` directory.
+ */
+export declare function isCodexHome(dir: string): boolean;
+/** True when `path` is `root` or lies under it on a path boundary: `/x/agent` is not under `/x/age`. */
+export declare function withinPath(path: string, root: string): boolean;
 /**
  * Compile one store glob. `*` matches within a path segment, `**` matches any number of
  * segments, and `{id}` matches the native session id: the literal id when one is given, any

package/dist/catalog.js

@@ -120,6 +120,45 @@ export const EVIDENCE = {
     'prime.session-jsonl': { servedModel: 'session-record', usage: 'per-response', endingError: 'session-record' },
     'openclaw.session-jsonl': { servedModel: 'session-record', usage: 'per-response', endingError: 'none' },
 };
+/**
+ * Codex writes to whichever Codex home it runs with, so one HOME can hold several: `~/.codex`, a
+ * sibling such as `~/.codex-lane`, the `$CODEX_HOME` a process set, one acct home per account under
+ * `${ACCT_CONFIG:-~/.config/agent-accounts}/codex/<account>`, and on a fleet host a seat's `codex`
+ * directory. Every home keeps live rollouts in `sessions/` and archived ones in
+ * `archived_sessions/`. `STORES` declares the default home's live store, which is what a sandbox
+ * captures; the readers search every home. The same rule as tangle-tools
+ * `trace-archive/catalog.py` `classify`.
+ */
+export const CODEX_HOME_RULE = {
+    /** Directory names directly under HOME that are Codex homes: `.codex` and `.codex-<name>`. */
+    siblings: /^\.codex(?:-.+)?$/u,
+    /** Under HOME, unless `$ACCT_CONFIG` names it: each child is one account's Codex home. */
+    accounts: '.config/agent-accounts/codex',
+    sessionDirs: ['sessions', 'archived_sessions'],
+    /** A rollout's file name, at any depth under a session dir (`sessions/` nests by date). */
+    rollout: 'rollout-*.jsonl',
+    /** The name Codex gives a rollout, ending in its thread id. */
+    named: 'rollout-*-{id}.jsonl',
+};
+/**
+ * True when `dir` is itself a Codex home by its path: `.codex`, `.codex-<name>`, an acct account
+ * home (`agent-accounts/codex/<account>`), or a fleet seat's `codex` directory.
+ */
+export function isCodexHome(dir) {
+    const parts = dir.replace(/\/+$/u, '').split('/');
+    const [name, parent, grandparent] = [parts.at(-1) ?? '', parts.at(-2) ?? '', parts.at(-3) ?? ''];
+    if (CODEX_HOME_RULE.siblings.test(name))
+        return true;
+    if (grandparent === 'agent-accounts' && parent === 'codex')
+        return true;
+    return name === 'codex' && parent !== 'agent-accounts';
+}
+/** True when `path` is `root` or lies under it on a path boundary: `/x/agent` is not under `/x/age`. */
+export function withinPath(path, root) {
+    const p = path.replace(/\/+$/u, '');
+    const r = root.replace(/\/+$/u, '');
+    return p === r || p.startsWith(`${r}/`);
+}
 const REGEX_SPECIALS = /[.+^$()|[\]\\]/gu;
 /**
  * Compile one store glob. `*` matches within a path segment, `**` matches any number of

package/dist/formats/claude-code.js

@@ -12,7 +12,7 @@ import { basename, join } from 'node:path';
 import { SessionBuilder, count, isRecord, sessionError, str, textOf, usageOrNull } from '../builder.js';
 import { fileRecords } from '../source.js';
 import { runFold } from './fold.js';
-import { EVIDENCE, STORES, mtimeMs, storeGlob, walkFiles } from '../stores.js';
+import { EVIDENCE, STORES, mtimeMs, storeGlob, walkFiles, withinPath } from '../stores.js';
 import { headRecord } from './head.js';
 import { claudeRecordIsMachine, claudeTypedPromptText } from './claude-records.js';
 const FORMAT = 'claude-code.projects-jsonl';
@@ -265,7 +265,7 @@ async function locate(home, opts) {
             continue;
         const head = await headRecord(path, (r) => typeof r.cwd === 'string');
         const cwd = head ? str(head.cwd) : null;
-        if (opts.cwd && (cwd === null || !cwd.startsWith(opts.cwd)))
+        if (opts.cwd && (cwd === null || !withinPath(cwd, opts.cwd)))
             continue;
         const subagents = subagentsBySession.get(`${rel.split('/')[0]}/${id}`) ?? [];
         refs.push({ harness: HARNESS, format: FORMAT, nativeSessionId: id, path, files: [path, ...subagents], home, cwd, mtimeMs: mtime, parentNativeSessionId: null });

package/dist/formats/codex.js

@@ -11,10 +11,11 @@
  */
 import { basename } from 'node:path';
 import { SessionBuilder, argumentsOf, count, isRecord, sessionError, str, textOf, usageOrNull, } from '../builder.js';
-import { fileRecords } from '../source.js';
+import { fileRecords, isMissing } from '../source.js';
 import { runFold } from './fold.js';
-import { EVIDENCE, STORES, mtimeMs, storeGlob, walkFiles } from '../stores.js';
+import { CODEX_HOME_RULE, EVIDENCE, STORES, codexHomes, storeGlob, walkFiles, withinPath } from '../stores.js';
 import { headRecord } from './head.js';
+import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
 const FORMAT = 'codex.rollout-jsonl';
 const STORE = STORES[FORMAT];
@@ -316,38 +317,92 @@ function httpStatusOf(payload) {
     }
     return null;
 }
-async function locate(home, opts) {
-    const root = join(home, STORE.root);
-    const pattern = storeGlob(STORE.files[0], opts.nativeSessionId);
-    const refs = [];
-    for (const rel of await walkFiles(root)) {
-        if (!pattern.test(rel))
-            continue;
-        const path = join(root, rel);
-        const mtime = await mtimeMs(path);
-        if (opts.sinceMs && mtime < opts.sinceMs)
+const ROLLOUT = storeGlob(CODEX_HOME_RULE.rollout);
+const UUID_V7 = /^([0-9a-f]{8})-([0-9a-f]{4})-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+/** Every rollout file, live and archived, in every Codex home under `home`. */
+async function rollouts(home) {
+    const files = [];
+    for (const codexHome of await codexHomes(home)) {
+        for (const dir of CODEX_HOME_RULE.sessionDirs) {
+            const root = join(codexHome, dir);
+            for (const rel of await walkFiles(root))
+                if (ROLLOUT.test(basename(rel)))
+                    files.push(join(root, rel));
+        }
+    }
+    return files;
+}
+/** A UUIDv7's creation time: a session's rollout is written at or after its thread id is made. */
+function uuidV7Ms(id) {
+    const match = UUID_V7.exec(id);
+    return match ? Number.parseInt(`${match[1]}${match[2]}`, 16) : 0;
+}
+/** A ref for each of `files` that passes the filters, from its `session_meta`, with the file's bytes. */
+async function refsOf(files, home, opts) {
+    const found = [];
+    for (const path of files) {
+        let info;
+        try {
+            info = await stat(path);
+        }
+        catch (error) {
+            if (isMissing(error))
+                continue;
+            throw error;
+        }
+        if (opts.sinceMs && info.mtimeMs < opts.sinceMs)
             continue;
         const meta = await headRecord(path, (r) => r.type === 'session_meta', 4);
         const payload = meta && isRecord(meta.payload) ? meta.payload : {};
         const cwd = str(payload.cwd);
-        if (opts.cwd && (cwd === null || !cwd.startsWith(opts.cwd)))
+        if (opts.cwd && (cwd === null || !withinPath(cwd, opts.cwd)))
             continue;
-        const id = str(payload.id) ?? ID_IN_NAME.exec(rel)?.[1] ?? basename(rel, '.jsonl');
         const source = isRecord(payload.source) ? payload.source : {};
         const spawn = isRecord(source.subagent) && isRecord(source.subagent.thread_spawn) ? source.subagent.thread_spawn : {};
-        refs.push({
-            harness: HARNESS,
-            format: FORMAT,
-            nativeSessionId: id,
-            path,
-            files: [path],
-            home,
-            cwd,
-            mtimeMs: mtime,
-            parentNativeSessionId: str(payload.parent_thread_id) ?? str(spawn.parent_thread_id),
+        found.push({
+            bytes: info.size,
+            ref: {
+                harness: HARNESS,
+                format: FORMAT,
+                nativeSessionId: str(payload.id) ?? ID_IN_NAME.exec(path)?.[1] ?? basename(path, '.jsonl'),
+                path,
+                files: [path],
+                home,
+                cwd,
+                mtimeMs: info.mtimeMs,
+                parentNativeSessionId: str(payload.parent_thread_id) ?? str(spawn.parent_thread_id),
+            },
         });
     }
-    return refs.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return found;
+}
+/**
+ * Sessions in every Codex home under `home`. A lookup by id takes the rollout named for it; when no
+ * name carries the id, it reads the `session_meta` of each rollout written since the id was made.
+ * A session copied into several homes (`acct move`) is one ref, its largest copy, which holds
+ * every record.
+ */
+async function locate(home, opts) {
+    const files = await rollouts(home);
+    const id = opts.nativeSessionId;
+    let found;
+    if (id === undefined) {
+        found = await refsOf(files, home, opts);
+    }
+    else {
+        const named = storeGlob(CODEX_HOME_RULE.named, id);
+        const byName = files.filter((path) => named.test(basename(path)));
+        found = byName.length > 0
+            ? await refsOf(byName, home, opts)
+            : (await refsOf(files, home, { ...opts, sinceMs: Math.max(opts.sinceMs ?? 0, uuidV7Ms(id)) })).filter((r) => r.ref.nativeSessionId === id);
+    }
+    const largest = new Map();
+    for (const copy of found) {
+        const kept = largest.get(copy.ref.nativeSessionId);
+        if (!kept || copy.bytes > kept.bytes || (copy.bytes === kept.bytes && copy.ref.mtimeMs > kept.ref.mtimeMs))
+            largest.set(copy.ref.nativeSessionId, copy);
+    }
+    return [...largest.values()].map((c) => c.ref).sort((a, b) => b.mtimeMs - a.mtimeMs);
 }
 export const codexReader = {
     harness: HARNESS,

package/dist/formats/factory.js

@@ -12,7 +12,7 @@ import { readFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { SessionBuilder, count, isRecord, str, textOf, usageOrNull } from '../builder.js';
 import { fileRecords, isMissing } from '../source.js';
-import { EVIDENCE, STORES, mtimeMs, storeGlob, walkFiles } from '../stores.js';
+import { EVIDENCE, STORES, mtimeMs, storeGlob, walkFiles, withinPath } from '../stores.js';
 import { runFold } from './fold.js';
 import { headRecord } from './head.js';
 const FORMAT = 'factory.session-jsonl';
@@ -128,7 +128,7 @@ async function locate(home, opts) {
             const head = await headRecord(ref.path, (r) => r.type === 'session_start', 1);
             const cwd = head ? str(head.cwd) : null;
             ref.cwd = cwd;
-            if (!cwd || !cwd.startsWith(opts.cwd))
+            if (!cwd || !withinPath(cwd, opts.cwd))
                 continue;
         }
         filtered.push(ref);

package/dist/formats/opencode.d.ts

@@ -1,4 +1,4 @@
 import type { HarnessSessionReader, LocateOptions, SessionRef } from '../schema.js';
-/** Every session in one store file, without opening the live store. */
+/** Every session in one store file, read in place without writing it. */
 export declare function opencodeSessionsInStore(path: string, home: string | null, opts?: LocateOptions): Promise<SessionRef[]>;
 export declare const opencodeReader: HarnessSessionReader;

package/dist/formats/opencode.js

@@ -6,13 +6,15 @@
  * `data` blob: role, the provider and model the message was sent to, tokens, cost, finish and the
  * error that ended it. `part` rows carry the content: `text`, `reasoning`, `tool` (the call and
  * its result in one row), `step-start` and `step-finish` (one model response, with its tokens and
- * cost), `retry` (a failed attempt) and bookkeeping parts. The store is read from a private copy,
- * never in place: opening it can checkpoint the write-ahead log of a store a capture is keeping.
+ * cost), `retry` (a failed attempt) and bookkeeping parts. The store is opened read-only where it
+ * lies, so a read sees the rows a running OpenCode has committed to its write-ahead log and never
+ * writes the store, its log or a copy of it.
  */
+import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { SessionBuilder, count, isRecord, isoTime, sessionError, str, usageOrNull } from '../builder.js';
-import { isMissing, withSqliteCopy } from '../source.js';
-import { EVIDENCE, STORES, mtimeMs } from '../stores.js';
+import { isMissing, withSqlite } from '../source.js';
+import { EVIDENCE, STORES, mtimeMs, withinPath } from '../stores.js';
 const FORMAT = 'opencode.sqlite';
 const STORE = STORES[FORMAT];
 const HARNESS = 'opencode';
@@ -55,11 +57,21 @@ function foldSession(db, ref, mode, builder) {
     builder.cwd = session.directory;
     builder.parentNativeSessionId = session.parent_id ?? null;
     builder.seen(session.time_created);
+    // The session's source is the rows this fold reads, not the whole store: a digest of the store
+    // file would read every other session in it and change whenever any of them did.
+    const digest = createHash('sha256').update(JSON.stringify(session));
+    let bytes = 0;
+    const note = (row) => {
+        const data = String(row.data);
+        digest.update(`\n${row.id}\t${row.time_created}\t`).update(data);
+        bytes += Buffer.byteLength(data);
+    };
     const messages = db.prepare('SELECT id, time_created, data FROM message WHERE session_id = ? ORDER BY time_created, id').all(ref.nativeSessionId);
     const partsOf = db.prepare('SELECT id, time_created, data FROM part WHERE message_id = ? ORDER BY id');
     let unparsed = 0;
     let aborted = null;
     for (const row of messages) {
+        note(row);
         const data = parse(row.data);
         if (data === null) {
             unparsed += 1;
@@ -70,6 +82,7 @@ function foldSession(db, ref, mode, builder) {
         builder.seen(time.completed);
         const parts = [];
         for (const partRow of partsOf.iterate(row.id)) {
+            note(partRow);
             const part = parse(partRow.data);
             if (part === null)
                 unparsed += 1;
@@ -177,10 +190,11 @@ function foldSession(db, ref, mode, builder) {
         aborted = messageError?.kind === 'MessageAbortedError' ? { at: messageError.at, error: messageError } : null;
     }
     const children = db.prepare('SELECT id FROM session WHERE parent_id = ? ORDER BY time_created, id').all(ref.nativeSessionId);
-    for (const child of children)
+    for (const child of children) {
+        digest.update(`\n${child.id}`);
         builder.child(child.id, null);
-    if (unparsed > 0)
-        builder.source({ path: `${ref.path}#session=${ref.nativeSessionId}`, sha256: '', bytes: 0, unparsed });
+    }
+    builder.source({ path: `${ref.path}#session=${ref.nativeSessionId}`, sha256: `sha256:${digest.digest('hex')}`, bytes, unparsed });
     const last = builder.modelCalls[builder.modelCalls.length - 1];
     if (aborted && last?.error?.kind === 'MessageAbortedError')
         last.error = null;
@@ -189,27 +203,23 @@ function foldSession(db, ref, mode, builder) {
 async function fold(ref, mode, options) {
     options.signal?.throwIfAborted();
     const builder = new SessionBuilder(HARNESS, FORMAT, EVIDENCE[FORMAT].servedModel, mode, ref.nativeSessionId, ref.parentNativeSessionId);
-    await withSqliteCopy(ref.path, (db, sources) => {
-        for (const source of sources)
-            builder.source(source);
-        foldSession(db, ref, mode, builder);
-    });
+    await withSqlite(ref.path, (db) => foldSession(db, ref, mode, builder));
     if (ref.truncated)
         builder.markTruncated(`${ref.path}: the store copy was cut short`);
     return builder;
 }
-/** Every session in one store file, without opening the live store. */
+/** Every session in one store file, read in place without writing it. */
 export async function opencodeSessionsInStore(path, home, opts = {}) {
     const mtime = await mtimeMs(path);
     const files = [path];
     for (const suffix of ['-wal', '-shm'])
         if ((await mtimeMs(`${path}${suffix}`)) > 0)
             files.push(`${path}${suffix}`);
-    return withSqliteCopy(path, (db) => {
+    return withSqlite(path, (db) => {
         const rows = db.prepare('SELECT id, parent_id, directory, time_updated FROM session ORDER BY time_updated DESC').all();
         return rows
             .filter((row) => (!opts.nativeSessionId || row.id === opts.nativeSessionId)
-            && (!opts.cwd || row.directory.startsWith(opts.cwd))
+            && (!opts.cwd || withinPath(row.directory, opts.cwd))
             && (!opts.sinceMs || row.time_updated >= opts.sinceMs))
             .map((row) => ({ harness: HARNESS, format: FORMAT, nativeSessionId: row.id, path, files, home, cwd: row.directory, mtimeMs: row.time_updated || mtime, parentNativeSessionId: row.parent_id }));
     });

package/dist/formats/pi.js

@@ -12,7 +12,7 @@ import { basename, join } from 'node:path';
 import { SessionBuilder, count, isRecord, sessionError, str, textOf, usageOrNull } from '../builder.js';
 import { fileRecords } from '../source.js';
 import { runFold } from './fold.js';
-import { EVIDENCE, STORES, mtimeMs, storeGlob, walkFiles } from '../stores.js';
+import { EVIDENCE, STORES, mtimeMs, storeGlob, walkFiles, withinPath } from '../stores.js';
 import { headRecord } from './head.js';
 const FORMAT = 'pi.session-jsonl';
 const STORE = STORES[FORMAT];
@@ -172,7 +172,7 @@ async function locate(home, opts) {
             continue;
         const header = await headRecord(path, (r) => r.type === 'session', 1);
         const cwd = header ? str(header.cwd) : null;
-        if (opts.cwd && (cwd === null || !cwd.startsWith(opts.cwd)))
+        if (opts.cwd && (cwd === null || !withinPath(cwd, opts.cwd)))
             continue;
         const id = (header && str(header.id)) ?? idFromName(rel);
         if (opts.nativeSessionId && id !== opts.nativeSessionId && idFromName(rel) !== opts.nativeSessionId)

package/dist/index.d.ts

@@ -10,7 +10,8 @@
  */
 export type { HarnessSession, HarnessSessionReader, LocateOptions, ModelCall, NativeSessionCopy, NativeSessionStore, Part, RawEvidenceArchiveManifestV2, ReadOptions, SessionEnding, SessionError, SessionEvidenceSources, SessionFormatId, SessionIntegrity, SessionMessage, SessionRef, SessionSummary, SessionToolCall, TokenUsage, } from './schema.js';
 export { HARNESS_SESSION_SCHEMA } from './schema.js';
-export { EVIDENCE, SESSION_FORMAT_IDS, STORES, assertStoreRoot, storeGlob } from './catalog.js';
+export { CODEX_HOME_RULE, EVIDENCE, SESSION_FORMAT_IDS, STORES, assertStoreRoot, isCodexHome, storeGlob, withinPath } from './catalog.js';
+export { codexHomes } from './stores.js';
 export { knownHarnesses, listReaders, maybeReaderFor, readerFor, readerForFormat } from './registry.js';
 export { claudeCodeReader, claudeCodeRefForFile } from './formats/claude-code.js';
 export { claudeRecordIsMachine, claudeTypedPromptText, type ClaudeRecordFacts } from './formats/claude-records.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { HARNESS_SESSION_SCHEMA } from './schema.js';
-export { EVIDENCE, SESSION_FORMAT_IDS, STORES, assertStoreRoot, storeGlob } from './catalog.js';
+export { CODEX_HOME_RULE, EVIDENCE, SESSION_FORMAT_IDS, STORES, assertStoreRoot, isCodexHome, storeGlob, withinPath } from './catalog.js';
+export { codexHomes } from './stores.js';
 export { knownHarnesses, listReaders, maybeReaderFor, readerFor, readerForFormat } from './registry.js';
 export { claudeCodeReader, claudeCodeRefForFile } from './formats/claude-code.js';
 export { claudeRecordIsMachine, claudeTypedPromptText } from './formats/claude-records.js';

package/dist/schema.d.ts

@@ -201,7 +201,7 @@ export interface SessionRef {
 }
 export interface LocateOptions {
     nativeSessionId?: string;
-    /** Sessions whose recorded cwd equals or starts with this path. */
+    /** Sessions whose recorded cwd is this path or lies under it on a path boundary (`/x/agent` excludes `/x/agent-dev-container`). */
     cwd?: string;
     /** Sessions modified at or after this epoch ms. */
     sinceMs?: number;

package/dist/source.d.ts

@@ -46,22 +46,11 @@ export declare function textRecordsSync(text: string, stats: SourceStats, option
 }): Generator<Record<string, unknown>>;
 /** Records a caller already parsed (one per line, in order). Non-objects count as unparsed. */
 export declare function arrayRecordsSync(values: readonly unknown[], stats: SourceStats): Generator<Record<string, unknown>>;
-/** Hash a file without parsing it. */
-export declare function hashFile(path: string): Promise<{
-    sha256: string;
-    bytes: number;
-}>;
 /**
- * Run `use` against a private copy of a SQLite store. Opening a live store can checkpoint its
- * write-ahead log and change the bytes a capture is keeping, so the store and its -wal and -shm
- * siblings are copied first and only the copy is opened. `use` is synchronous so no other read can
- * replace the copy while it runs.
+ * Run `use` against a SQLite store opened read-only in place ({@link openSqlite}). A store SQLite
+ * cannot open in place is read from a private copy instead: a write-ahead log with no `-shm` in a
+ * directory SQLite cannot write (a capture on read-only storage), or a Node whose `node:sqlite`
+ * does not accept URI file names (before 22.15).
  */
-export declare function withSqliteCopy<T>(path: string, use: (db: DatabaseSync, sources: Array<{
-    path: string;
-    sha256: string;
-    bytes: number;
-}>) => T): Promise<T>;
-/** Remove the private store copy now instead of at process exit. */
-export declare function releaseSqliteCopy(): void;
+export declare function withSqlite<T>(path: string, use: (db: DatabaseSync) => T): Promise<T>;
 export declare function isMissing(error: unknown): boolean;

package/dist/source.js

@@ -1,9 +1,10 @@
 import { createHash } from 'node:crypto';
 import { createReadStream, rmSync } from 'node:fs';
-import { copyFile, mkdtemp, stat } from 'node:fs/promises';
+import { copyFile, mkdtemp, realpath, stat } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 const MAX_UNPARSED_LINES = 50;
 function noteUnparsed(stats, line) {
     stats.unparsed += 1;
@@ -157,25 +158,79 @@ export function* arrayRecordsSync(values, stats) {
         yield value;
     }
 }
-/** Hash a file without parsing it. */
-export async function hashFile(path) {
-    const hash = createHash('sha256');
-    let bytes = 0;
-    for await (const chunk of createReadStream(path)) {
-        hash.update(chunk);
-        bytes += chunk.length;
-    }
-    return { sha256: `sha256:${hash.digest('hex')}`, bytes };
-}
 // `node:sqlite` is loaded through `createRequire`: bundlers rewrite a dynamic `import()` of a
 // `node:` builtin under some targets, and a require obtained this way is not analyzable by them.
 function loadSqlite() {
     const nodeRequire = createRequire(import.meta.url);
     return nodeRequire('node:sqlite');
 }
-// One private copy is kept per process: reading every session of one store (a 4 GB opencode.db
-// holding 26 sessions) copies it once, not once per session. It is replaced when a different
-// store, or a store that changed, is read, and removed when the process exits.
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
+    }
+}
+/**
+ * Open a SQLite store read-only where it lies. A store with a write-ahead log beside it is opened
+ * `mode=ro`: SQLite reads the log's committed tail and coordinates with a live writer through the
+ * store's shared-memory index (`-shm`), and never writes the store or its log or checkpoints it. A
+ * store without a log is opened `immutable=1`: no connection holds it open, the file holds every
+ * committed row, and SQLite creates no `-wal` or `-shm` beside it. Throws when SQLite cannot read
+ * the store in place.
+ */
+async function openSqlite(path) {
+    const mode = (await exists(`${path}-wal`)) ? 'mode=ro' : 'immutable=1';
+    const { DatabaseSync } = loadSqlite();
+    // `readOnly` as well: a Node that treated the URI as a file name would fail to open, not create it.
+    const db = new DatabaseSync(`${pathToFileURL(path).href}?${mode}`, { readOnly: true });
+    try {
+        db.exec('PRAGMA busy_timeout = 5000');
+        // The first read opens the log and its index, so a store SQLite cannot read in place fails here.
+        db.prepare('PRAGMA schema_version').get();
+        return db;
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+}
+/** SQLite's primary result code `SQLITE_CANTOPEN`, which `node:sqlite` errors carry in `errcode`. */
+function cannotOpen(error) {
+    const code = error?.errcode;
+    return typeof code === 'number' && (code & 0xff) === 14;
+}
+/**
+ * Run `use` against a SQLite store opened read-only in place ({@link openSqlite}). A store SQLite
+ * cannot open in place is read from a private copy instead: a write-ahead log with no `-shm` in a
+ * directory SQLite cannot write (a capture on read-only storage), or a Node whose `node:sqlite`
+ * does not accept URI file names (before 22.15).
+ */
+export async function withSqlite(path, use) {
+    // SQLite follows a symlinked store to its target and keeps the log there, so the log is looked
+    // for there too. A missing store throws ENOENT here, which callers read as "no sessions".
+    const store = await realpath(path);
+    const db = await openSqlite(store).catch((error) => {
+        if (cannotOpen(error))
+            return null;
+        throw error;
+    });
+    if (db === null)
+        return withSqliteCopy(store, use);
+    try {
+        return use(db);
+    }
+    finally {
+        db.close();
+    }
+}
+// One private copy is kept per process: reading every session of a store SQLite cannot open in
+// place copies it once, not once per session. It is replaced when a different store, or a store
+// that changed, is read, and removed when the process exits.
 let current = null;
 function dropCopy() {
     if (current === null)
@@ -206,47 +261,35 @@ async function storeKey(path) {
     return `${path}|${parts.join('|')}`;
 }
 /**
- * Run `use` against a private copy of a SQLite store. Opening a live store can checkpoint its
- * write-ahead log and change the bytes a capture is keeping, so the store and its -wal and -shm
- * siblings are copied first and only the copy is opened. `use` is synchronous so no other read can
- * replace the copy while it runs.
+ * Run `use` against a private copy of a SQLite store: the store and its `-wal` and `-shm` siblings
+ * are copied and only the copy is opened, writable, so SQLite replays the copied log into it. `use`
+ * is synchronous so no other read can replace the copy while it runs.
  */
-export async function withSqliteCopy(path, use) {
+async function withSqliteCopy(path, use) {
     const key = await storeKey(path);
     if (current?.key !== key) {
         const { DatabaseSync } = loadSqlite();
         const dir = await mkdtemp(join(tmpdir(), 'harness-sessions-sqlite-'));
         try {
-            const sources = [];
             for (const suffix of ['', '-wal', '-shm']) {
-                const copy = join(dir, `store.db${suffix}`);
                 try {
-                    await copyFile(`${path}${suffix}`, copy);
+                    await copyFile(`${path}${suffix}`, join(dir, `store.db${suffix}`));
                 }
                 catch (error) {
                     if (suffix === '' || !isMissing(error))
                         throw error;
-                    continue;
                 }
-                // The shared-memory index is rebuilt from the WAL; only the store and its log carry data.
-                if (suffix !== '-shm')
-                    sources.push({ path: `${path}${suffix}`, ...(await hashFile(copy)) });
             }
-            // Opened writable so SQLite replays the copied write-ahead log into the private copy.
             const db = new DatabaseSync(join(dir, 'store.db'));
             dropCopy();
-            current = { key, dir, db, sources };
+            current = { key, dir, db };
         }
         catch (error) {
             rmSync(dir, { recursive: true, force: true });
             throw error;
         }
     }
-    return use(current.db, current.sources);
-}
-/** Remove the private store copy now instead of at process exit. */
-export function releaseSqliteCopy() {
-    dropCopy();
+    return use(current.db);
 }
 export function isMissing(error) {
     const code = error?.code;

package/dist/stores.d.ts

@@ -1,7 +1,15 @@
 import type { NativeSessionStore } from './schema.js';
-export { assertStoreRoot, EVIDENCE, SESSION_FORMAT_IDS, STORES, storeGlob } from './catalog.js';
+export { assertStoreRoot, CODEX_HOME_RULE, EVIDENCE, isCodexHome, SESSION_FORMAT_IDS, STORES, storeGlob, withinPath } from './catalog.js';
 /** Every file under `dir`, as paths relative to it with `/` separators. Missing dirs yield none. */
 export declare function walkFiles(dir: string, signal?: AbortSignal): Promise<string[]>;
 /** Files under `home` that one store glob matches, as absolute paths. */
 export declare function storeFiles(home: string, store: NativeSessionStore, glob: string, nativeSessionId?: string): Promise<string[]>;
 export declare function mtimeMs(path: string): Promise<number>;
+/**
+ * Every Codex home under `home`, by `CODEX_HOME_RULE`: `home` itself when it is one (a fleet seat's
+ * `codex` passed as a store root), `.codex` and each `.codex-<name>` in it, and each acct account
+ * home. `$CODEX_HOME` and `$ACCT_CONFIG` describe this process's own HOME, so they apply only when
+ * `home` is that HOME; another HOME (a store root, a capture) is read by its layout alone. Homes
+ * that resolve to one directory, such as an account home linked to `~/.codex`, count once.
+ */
+export declare function codexHomes(home: string): Promise<string[]>;

package/dist/stores.js

@@ -1,8 +1,9 @@
-import { readdir, stat } from 'node:fs/promises';
-import { join, relative, sep } from 'node:path';
-import { storeGlob } from './catalog.js';
+import { readdir, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, relative, resolve, sep } from 'node:path';
+import { CODEX_HOME_RULE, isCodexHome, storeGlob } from './catalog.js';
 import { isMissing } from './source.js';
-export { assertStoreRoot, EVIDENCE, SESSION_FORMAT_IDS, STORES, storeGlob } from './catalog.js';
+export { assertStoreRoot, CODEX_HOME_RULE, EVIDENCE, isCodexHome, SESSION_FORMAT_IDS, STORES, storeGlob, withinPath } from './catalog.js';
 /** Every file under `dir`, as paths relative to it with `/` separators. Missing dirs yield none. */
 export async function walkFiles(dir, signal) {
     const out = [];
@@ -44,3 +45,53 @@ export async function mtimeMs(path) {
         throw error;
     }
 }
+/** Names of the directories (or links to them) directly in `dir`. A missing dir has none. */
+async function childDirs(dir) {
+    try {
+        return (await readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory() || e.isSymbolicLink()).map((e) => e.name).sort();
+    }
+    catch (error) {
+        if (isMissing(error))
+            return [];
+        throw error;
+    }
+}
+/**
+ * Every Codex home under `home`, by `CODEX_HOME_RULE`: `home` itself when it is one (a fleet seat's
+ * `codex` passed as a store root), `.codex` and each `.codex-<name>` in it, and each acct account
+ * home. `$CODEX_HOME` and `$ACCT_CONFIG` describe this process's own HOME, so they apply only when
+ * `home` is that HOME; another HOME (a store root, a capture) is read by its layout alone. Homes
+ * that resolve to one directory, such as an account home linked to `~/.codex`, count once.
+ */
+export async function codexHomes(home) {
+    const own = resolve(home) === resolve(process.env.HOME || homedir());
+    const candidates = isCodexHome(home) ? [home] : [];
+    for (const name of await childDirs(home))
+        if (CODEX_HOME_RULE.siblings.test(name))
+            candidates.push(join(home, name));
+    if (own && process.env.CODEX_HOME)
+        candidates.push(resolve(process.env.CODEX_HOME));
+    const accounts = own && process.env.ACCT_CONFIG ? join(resolve(process.env.ACCT_CONFIG), 'codex') : join(home, CODEX_HOME_RULE.accounts);
+    for (const name of await childDirs(accounts))
+        candidates.push(join(accounts, name));
+    const seen = new Set();
+    const homes = [];
+    for (const dir of candidates) {
+        let real;
+        try {
+            real = await realpath(dir);
+            if (!(await stat(real)).isDirectory())
+                continue;
+        }
+        catch (error) {
+            if (isMissing(error))
+                continue;
+            throw error;
+        }
+        if (seen.has(real))
+            continue;
+        seen.add(real);
+        homes.push(dir);
+    }
+    return homes;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/harness-sessions",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "One reader for every coding-agent harness's native session (Claude Code, Codex, OpenCode, Pi): store layouts, a normalized session with messages, tool calls, served models, usage and ending errors, and projections to chat messages, OTLP spans and turns",
   "type": "module",
   "sideEffects": false,