@awebai/oats 0.22.17 → 0.23.0

package/packages/record/lib/capture-cc.mjs

@@ -20,12 +20,14 @@
 // ignore.mjs) are skipped before being opened: no turn, no offset entry —
 // un-ignoring a file later makes the next pass capture it normally.
 
-import { closeSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from "node:fs";
+import { isUtf8 } from "node:buffer";
+import { closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
 import { finishTurn } from "./canonical.mjs";
 import { jsonlLines, SESSION_FORMATS } from "./formats.mjs";
 import { loadIgnore } from "./ignore.mjs";
+import { assertIdentity, digest, identity, readRange, verifySnapshot } from "./session-snapshot.mjs";
 
 export const SESSION_STREAM_SOURCE = "cc";
 
@@ -49,7 +51,7 @@ export function scanTranscript(bytes) {
     if (text === null) continue;
     try {
       const d = JSON.parse(text);
-      if (typeof d.timestamp === "string") ts = d.timestamp;
+      if (typeof d?.timestamp === "string") ts = d.timestamp;
     } catch {
       /* verbatim content; nothing to extract */
     }
@@ -83,8 +85,11 @@ function offsetsPath(store) {
 function loadOffsets(store) {
   try {
     return JSON.parse(readFileSync(offsetsPath(store), "utf8"));
-  } catch {
-    return {};
+  } catch (err) {
+    // This cache is derived, so malformed JSON can be rebuilt. An I/O
+    // failure is different: never hide an unreadable cache as missing.
+    if (err.code === "ENOENT" || err instanceof SyntaxError) return {};
+    throw err;
   }
 }
 
@@ -102,7 +107,7 @@ function readFrom(path, start, size) {
     let done = 0;
     while (done < buf.length) {
       const n = readSync(fd, buf, done, buf.length - done, start + done);
-      if (n === 0) break;
+      if (n === 0) throw new Error(`short read of session/journal source: ${path}`);
       done += n;
     }
     return buf.subarray(0, done);
@@ -119,8 +124,9 @@ function lastJournalLine(store, streamId) {
   let size;
   try {
     size = statSync(path).size;
-  } catch {
-    return 0;
+  } catch (err) {
+    if (err.code === "ENOENT") return 0;
+    throw err;
   }
   let window = 64 * 1024;
   while (true) {
@@ -152,12 +158,12 @@ function lastJournalLine(store, streamId) {
 // Honest limit: an in-place REWRITE of already-captured lines is not
 // detected (only growth is; a shrink triggers a rescan via the size
 // check in the caller). Transcript writers are append-only in practice.
-function offsetFromJournal(store, streamId, sourcePath) {
+function offsetFromJournal(store, streamId, sourcePath, final, sourceBytes) {
   const turns = store.readStream(streamId);
   if (turns.length === 0) return { bytes: 0, line: 0, lastTs: "" };
   const last = turns[turns.length - 1];
   const lastLine = last.provenance?.origin?.line ?? 0;
-  const bytes = readFileSync(sourcePath);
+  const bytes = sourceBytes ?? readFileSync(sourcePath);
   let line = 0;
   let offset = 0;
   while (line < lastLine && offset < bytes.length) {
@@ -166,6 +172,7 @@ function offsetFromJournal(store, streamId, sourcePath) {
     line++;
     offset = nl + 1;
   }
+  if (final && line < lastLine) throw new Error(`session source is shorter than its captured journal: ${sourcePath}`);
   return { bytes: offset, line, lastTs: last.ts ?? "" };
 }
 
@@ -173,7 +180,14 @@ function offsetFromJournal(store, streamId, sourcePath) {
 // of every session file under `roots`. Unstamped leading lines are held
 // until the file shows its first timestamp (then they carry it forward),
 // so every turn is stamped and ts stays a pure function of the source.
-export function captureSessions(store, { owner, roots, format = "cc", ignore = null }) {
+// `files` accepts discovery entries (including their attribution snapshot) or
+// explicit paths for callers not making home-attribution claims. It pins a set,
+// rather than rescanning directories
+// and silently losing disappeared sources (or sweeping in other homes).
+// `final` also verifies unchanged offsets against journals and checks source
+// stability through the pass. The caller must quiesce writers for retirement;
+// a performed pass is a snapshot, not a promise about future writes.
+export function captureSessions(store, { owner, roots, files, format = "cc", ignore = null, final = false }) {
   const fmt = SESSION_FORMATS[format];
   if (!fmt) throw new Error(`unknown session format ${format}`);
   const ign = ignore ?? loadIgnore(store.root);
@@ -183,21 +197,35 @@ export function captureSessions(store, { owner, roots, format = "cc", ignore = n
   let unchanged = 0;
   let held = 0;
   let ignored = 0;
+  let incomplete = 0;
+  const issues = []; // source metadata only, never native record contents
   const streams = new Set();
 
-  for (const path of fmt.listFiles(roots)) {
+  for (const file of files ?? fmt.listFiles(roots)) {
+    const path = typeof file === "string" ? file : file.path;
+    const expected = typeof file === "string" ? null : file.snapshot;
     sessions++;
     const sessionId = fmt.sessionId(path);
-    if (ign.ignores(path, [basename(path), sessionId])) {
+    if (ign.ignores(path, [basename(path), sessionId, ...(fmt.ignoreKeys?.(path) ?? [])])) {
       ignored++;
       continue; // never opened: nothing stored, nothing remembered
     }
-    let stat;
+    const fd = openSync(path, "r");
     try {
-      stat = statSync(path);
-    } catch {
-      continue; // vanished between listing and stat; next pass catches it
+    const stat = fstatSync(fd);
+    const snapshot = identity(stat);
+    if (expected) assertIdentity(stat, expected, path); // BEFORE reading bytes
+    // Final home capture stages a descriptor-pinned snapshot. All attribution
+    // and stability checks precede the first append, never a post-write alarm.
+    const sourceBytes = final || expected ? readRange(fd, 0, stat.size, path) : undefined;
+    if (expected && digest(sourceBytes.subarray(0, expected.size)) !== expected.hash) {
+      throw new Error(`session source content changed since attribution: ${path}`);
     }
+    if (sourceBytes) snapshot.hash = digest(sourceBytes);
+    const verifySource = () => {
+      if (sourceBytes) verifySnapshot(fd, path, snapshot);
+    };
+    verifySource();
     const streamId = `${owner}~${fmt.source}.${sessionId}`;
     // Keyed by stream, not by source path: the same source captured under
     // two owners must not share offset state (owner is part of the stream).
@@ -210,31 +238,44 @@ export function captureSessions(store, { owner, roots, format = "cc", ignore = n
     // saved offsets for appends that landed in an unlinked inode (skipping
     // would lose lines — this happened during the live migration). The
     // journal is the truth; before appending anything, any disagreement
-    // rebuilds the offset from it (checked only when the source grew:
-    // an unchanged file appends nothing, so its cache cannot mislead).
-    if (state && stat.size > state.bytes && state.line !== lastJournalLine(store, streamId)) {
+    // rebuilds the offset from it. Background passes check on growth;
+    // final passes also verify unchanged files before confirming capture.
+    if (state && (final || stat.size > state.bytes) && state.line !== lastJournalLine(store, streamId)) {
       state = null;
     }
-    if (!state) state = offsetFromJournal(store, streamId, path);
+    if (!state) state = offsetFromJournal(store, streamId, path, final, sourceBytes);
     if (stat.size <= state.bytes) {
       unchanged++;
       offsets[offKey] = state;
+      verifySource();
       continue;
     }
 
-    const chunk = readFrom(path, state.bytes, stat.size);
+    const chunk = sourceBytes ? sourceBytes.subarray(state.bytes) : readRange(fd, state.bytes, stat.size, path);
     // Phase 1: collect the COMPLETE lines of the chunk with their stamps.
     const lines = [];
     let scanned = 0;
-    for (const { text } of jsonlLines(chunk)) {
-      if (text === null) break; // over-string-limit line: retry later
-      const lineBytes = Buffer.byteLength(text, "utf8") + 1;
-      if (scanned + lineBytes > chunk.length) break; // no trailing newline yet
+    let reason;
+    while (scanned < chunk.length) {
+      const nl = chunk.indexOf(10, scanned);
+      if (nl === -1) { reason = "torn-tail"; break; }
+      const bytes = chunk.subarray(scanned, nl);
+      // Decoding replacement characters would change both the verbatim line
+      // and its byte offset, possibly treating a later fragment as a record.
+      if (!isUtf8(bytes)) { reason = "invalid-utf8"; break; }
+      let text;
+      try { text = bytes.toString("utf8"); }
+      catch (err) {
+        if (err.code !== "ERR_STRING_TOO_LONG") throw err;
+        reason = "oversized-line";
+        break;
+      }
+      const lineBytes = nl - scanned + 1;
       let ts = "";
       if (text.trim() !== "") {
         try {
           const d = JSON.parse(text);
-          if (typeof d.timestamp === "string") ts = d.timestamp;
+          if (typeof d?.timestamp === "string") ts = d.timestamp;
         } catch {
           /* unparseable native line: captured verbatim below */
         }
@@ -242,6 +283,10 @@ export function captureSessions(store, { owner, roots, format = "cc", ignore = n
       lines.push({ text, ts, bytes: lineBytes });
       scanned += lineBytes;
     }
+    if (reason) {
+      incomplete++;
+      issues.push({ source: fmt.source, path, reason, offset: state.bytes + scanned });
+    }
     // Phase 2: every turn needs a stamp. Leading lines before the file's
     // first stamp carry it backward (deterministic: the file's first
     // stamp is invariant however capture is scheduled); if the file has
@@ -250,11 +295,16 @@ export function captureSessions(store, { owner, roots, format = "cc", ignore = n
     if (!lastTs) {
       const first = lines.find((l) => l.ts);
       if (!first) {
-        if (lines.length > 0) held++;
+        if (lines.length > 0) {
+          held++;
+          issues.push({ source: fmt.source, path, reason: "unstamped", offset: state.bytes });
+        }
+        verifySource();
         continue; // do not advance; retry when a stamp exists
       }
       lastTs = first.ts;
     }
+    verifySource(); // parsing/recovery may take time; still no journal write yet
     // Turns flush to the journal in bounded batches, so memory stays flat
     // however large the backlog (a first capture of a huge transcript is
     // one file's worth of NEW lines). A crash between flushes cannot
@@ -295,6 +345,8 @@ export function captureSessions(store, { owner, roots, format = "cc", ignore = n
     // re-appends duplicate turn lines — logically deduped by id, but
     // wasted append-only bytes).
     if (grew) saveOffsets(store, offsets);
+    verifySource();
+    } finally { closeSync(fd); }
   }
   saveOffsets(store, offsets);
   return {
@@ -303,6 +355,9 @@ export function captureSessions(store, { owner, roots, format = "cc", ignore = n
     unchanged,
     held,
     ignored,
+    incomplete,
+    complete: held === 0 && incomplete === 0,
+    issues,
     streams: streams.size,
     stream: `${owner}~${fmt.source}.*`,
   };

package/packages/record/lib/capture-lock.mjs

@@ -12,7 +12,8 @@
 // message says exactly that. (A reclaim protocol was reviewed and rejected:
 // rename is not compare-and-swap, and stealing from a stalled live
 // initializer under memory pressure is the failure we are preventing.)
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 
 export function captureLockPath(root) { return join(root, ".capture.lock"); }
@@ -41,8 +42,28 @@ export function recoveryInstruction(dir, owner, liveness) {
 
 /** Try to take the root's capture lock. Returns { path, release } when
  *  taken, or { path, held: { pid, startedAt, liveness, recovery } } when any
- *  lock exists. Never removes a lock it did not create. */
-export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, liveness = holderLiveness } = {}) {
+ *  lock exists. Never removes a lock it did not create.
+ *
+ *  Two failure points are reported rather than left behind. If the owner
+ *  record cannot be written after THIS call created the directory (a full
+ *  disk, say), the directory is removed only while it is still the very
+ *  directory this call created (same inode) and carries no other owner's
+ *  record; a replacement that appeared meanwhile (operator recovery, then a
+ *  newer pass) is left alone. The original error is rethrown with
+ *  `lockCleanup: { path, removed, reason?, owner?, error?, recovery? }`
+ *  saying what happened. And `release()` never throws: it answers
+ *  `{ released: true }` only when the lock is verifiably gone, otherwise
+ *  `{ released: false, reason: "gone" | "unknown-owner" | "not-owner" |
+ *  "remove-failed", ... }` with the actual observation, never a guess.
+ *
+ *  The owner record carries a per-acquisition nonce, so a release kept from
+ *  an earlier acquisition cannot erase a later one by the same pid (an
+ *  operator recovery followed by a new pass in the same long-lived process).
+ *  That is ownership checking; no lock is ever reclaimed.
+ *
+ *  `io` exists for fault injection in tests only. */
+export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, liveness = holderLiveness, io = {} } = {}) {
+  const fs = { writeFileSync, rmSync, openSync, closeSync, lstatSync, ...io };
   const dir = captureLockPath(root);
   mkdirSync(root, { recursive: true }); // the store creates the root lazily; the lock may come first
   try {
@@ -53,12 +74,67 @@ export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, li
     const live = owner ? (owner.pid === pid ? "alive" : liveness(owner.pid)) : "unknown";
     return { path: dir, held: { pid: owner?.pid, startedAt: owner?.startedAt, liveness: live, recovery: recoveryInstruction(dir, owner, live) } };
   }
-  writeFileSync(join(dir, "owner.json"), JSON.stringify({ pid, startedAt: new Date(now()).toISOString() }));
+  const nonce = randomBytes(8).toString("hex");
+  let directoryFd, identity;
+  try {
+    // Keep the directory alive until initialization or its cleanup finishes.
+    // Otherwise Linux can reuse its inode immediately after an unlink, making
+    // a record-less replacement look like the directory we created.
+    directoryFd = fs.openSync(dir, "r");
+    identity = fstatSync(directoryFd);
+    fs.writeFileSync(join(dir, "owner.json"), JSON.stringify({ pid, nonce, startedAt: new Date(now()).toISOString() }));
+  } catch (err) {
+    // Ownership was proven by the mkdir, not by the moment of cleanup: the
+    // directory is removed only if it is still ours (same inode) and holds
+    // no other pass's record. Anything else is reported, not deleted.
+    let cleanupError, reason;
+    const cur = readOwner(dir);
+    const same = (() => { try { const current = lstatSync(dir); return identity && current.dev === identity.dev && current.ino === identity.ino; } catch { return false; } })();
+    if (!existsSync(dir)) reason = "gone";
+    else if (!identity) reason = "unverified";
+    else if (!same || (cur && (cur.pid !== pid || cur.nonce !== nonce))) reason = "replaced";
+    else { try { fs.rmSync(dir, { recursive: true, force: true }); } catch (e2) { cleanupError = e2; } }
+    const removed = reason === undefined && !existsSync(dir);
+    err.lockCleanup = {
+      path: dir,
+      removed,
+      ...(reason ? { reason } : {}),
+      ...(reason === "replaced" && cur ? { owner: cur } : {}),
+      ...(cleanupError ? { error: cleanupError.message } : {}),
+      ...(removed || reason === "gone" || reason === "replaced" ? {} : { recovery: recoveryInstruction(dir, undefined, "unknown") }),
+    };
+    throw err;
+  } finally {
+    if (directoryFd !== undefined) fs.closeSync(directoryFd);
+  }
   return {
     path: dir,
     release: () => {
+      if (!existsSync(dir)) return { released: false, reason: "gone" };
       const cur = readOwner(dir);
-      if (cur && cur.pid === pid) { try { rmSync(dir, { recursive: true, force: true }); } catch { /* already gone */ } }
+      if (!cur) return { released: false, reason: "unknown-owner", recovery: recoveryInstruction(dir, undefined, "unknown") };
+      if (cur.pid !== pid || cur.nonce !== nonce) return { released: false, reason: "not-owner", owner: cur };
+      let error;
+      try { fs.rmSync(dir, { recursive: true, force: true }); } catch (e) { error = e; }
+      let remains;
+      try { fs.lstatSync(dir); remains = true; }
+      catch (err) {
+        if (err.code === "ENOENT") remains = false;
+        else return { released: false, reason: "remove-failed", error: err.message,
+          recovery: "could not verify capture lock removal; inspect the filesystem error and rerun capture" };
+      }
+      if (!remains) {
+        // A removal may throw after changing the filesystem. Absence does
+        // not erase that failure from a final-capture receipt.
+        if (error) return { released: false, reason: "remove-failed", error: error.message,
+          recovery: "the lock is now absent, but removal reported an error; inspect the failure and rerun capture" };
+        return { released: true };
+      }
+      // Our own lock could not be removed. We are the holder and, as far as
+      // this process can tell, alive; the operator gets a conditional line.
+      const live = pid === process.pid ? "alive" : liveness(pid);
+      const recovery = `${dir} is still held by pid ${pid} (this pass, ${live} when it reported this); its removal failed${error ? ` (${error.message})` : ""}; once that process has exited (ps -p ${pid}), remove the lock with: rm -r -- ${shellQuote(dir)}  and rerun`;
+      return { released: false, reason: "remove-failed", liveness: live, ...(error ? { error: error.message } : {}), recovery };
     },
   };
 }

package/packages/record/lib/formats.mjs

@@ -16,9 +16,10 @@
 // snapshots, queue operations, mode flips) yields no docs — but its
 // native line is still stored verbatim in the turn, so nothing is lost.
 
-import { existsSync, readdirSync } from "node:fs";
-import { basename, join } from "node:path";
+import { lstatSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { homedir } from "node:os";
+import { nativeDirectory } from "./session-roots.mjs";
 
 // Iterate JSONL lines of a buffer without materializing the whole file as
 // one string — real transcripts reach hundreds of MB (a 789 MB Codex
@@ -53,21 +54,24 @@ function* parsedLines(bytes) {
   }
 }
 
-function listJsonlFiles(root, maxDepth) {
+function listJsonlFiles(root, maxDepth, { strict = false } = {}) {
   const out = [];
   const walk = (dir, depth) => {
     let names;
     try {
       names = readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
+    } catch (err) {
+      // An optional, absent root is normal; an unreadable directory or a
+      // subtree that disappeared during discovery is not an empty scan.
+      if (!strict && depth === 0 && err.code === "ENOENT") return;
+      throw err;
     }
     for (const entry of names.sort((a, b) => a.name.localeCompare(b.name))) {
       const path = join(dir, entry.name);
-      if (entry.isDirectory()) {
+      if (entry.name.endsWith(".jsonl") && !entry.isDirectory()) {
+        out.push(path); // privacy rules precede opening/statting source links
+      } else if (entry.isDirectory() || (entry.isSymbolicLink() && statSync(path).isDirectory())) {
         if (depth < maxDepth) walk(path, depth + 1);
-      } else if (entry.name.endsWith(".jsonl")) {
-        out.push(path);
       }
     }
   };
@@ -75,18 +79,97 @@ function listJsonlFiles(root, maxDepth) {
   return out;
 }
 
+// Only absence makes a default root optional. existsSync also hides access
+// failures, which would turn an unperformed scan into a false empty result.
+function directoryExists(path) {
+  try {
+    if (!statSync(path).isDirectory()) throw new Error(`session root is not a directory: ${path}`);
+    return true;
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      // ENOENT through a dangling directory link is not an absent runtime.
+      for (let part = path; ; part = dirname(part)) {
+        try {
+          if (lstatSync(part).isSymbolicLink()) throw new Error(`unresolvable session root: ${path}`);
+          break;
+        } catch (e) { if (e.code !== "ENOENT") throw e; }
+        if (dirname(part) === part) break;
+      }
+      return false;
+    }
+    throw err;
+  }
+}
+
 // ------------------------------------------------------------ claude code
 
-function ccRoots(home = homedir()) {
+function configuredRoot(value, suffix, options) {
+  const root = join(nativeDirectory(value, options), suffix);
+  // Explicitly relocated storage is not an optional absent default. A
+  // missing/unreadable root means we cannot certify its evidence inventory.
+  if (!directoryExists(root)) throw new Error(`configured session root does not exist: ${root}`);
+  return [root];
+}
+
+function ccRoots(home = homedir(), env = process.env, options = {}) {
+  if (env.CLAUDE_CONFIG_DIR) return configuredRoot(env.CLAUDE_CONFIG_DIR, "projects", { home, ...options });
   const roots = [];
-  for (const name of readdirSync(home).sort()) {
-    if (!name.startsWith(".claude")) continue;
-    const projects = join(home, name, "projects");
-    if (existsSync(projects)) roots.push(projects);
+  for (const entry of readdirSync(home, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.name.startsWith(".claude")) continue;
+    // ~/.claude.json and its backups are normal config FILES, not roots.
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (entry.isSymbolicLink() && !statSync(join(home, entry.name)).isDirectory()) continue;
+    const projects = join(home, entry.name, "projects");
+    if (directoryExists(projects)) roots.push(projects);
   }
   return roots;
 }
 
+// Native Claude child transcripts live at
+// projects/<project>/<sessionId>/subagents/agent-*.jsonl, not beside the
+// parent's file. Enumerate only this layout, never arbitrary project files.
+function listCcFiles(root, { strict = false } = {}) {
+  const out = [];
+  const entries = (dir, optional = false) => {
+    try { return readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)); }
+    catch (err) { if (optional && err.code === "ENOENT") return []; throw err; }
+  };
+  const directory = (entry, path) => entry.isDirectory() || (entry.isSymbolicLink() && !entry.name.endsWith(".jsonl") && statSync(path).isDirectory());
+  for (const project of entries(root, !strict)) {
+    const projectPath = join(root, project.name);
+    if (!directory(project, projectPath)) {
+      if (project.name.endsWith(".jsonl")) out.push(projectPath);
+      continue;
+    }
+    for (const entry of entries(projectPath)) {
+      const path = join(projectPath, entry.name);
+      if (!directory(entry, path)) {
+        if (entry.name.endsWith(".jsonl")) out.push(path);
+        continue;
+      }
+      // Listing the session directory (rather than treating ENOENT at an
+      // assumed subagents path as optional) preserves disappearance errors.
+      for (const childDir of entries(path)) {
+        if (childDir.name !== "subagents") continue;
+        const children = join(path, childDir.name);
+        if (!directory(childDir, children)) throw new Error(`session subagents root is not a directory: ${children}`);
+        for (const child of entries(children)) {
+          if (child.name.endsWith(".jsonl")) out.push(join(children, child.name));
+        }
+      }
+    }
+  }
+  return out;
+}
+
+function ccParentId(path) {
+  return basename(dirname(path)) === "subagents" ? basename(dirname(dirname(path))) : null;
+}
+function ccSessionId(path) {
+  const parent = ccParentId(path), id = basename(path, ".jsonl");
+  return parent ? `${parent}.${id}` : id;
+}
+
 // Cap for the unknown-part fallback: prefix stays searchable, the full
 // bytes are always in the verbatim blob — this bounds the index, it does
 // not strip the record.
@@ -178,9 +261,11 @@ export function extractCcText(bytes) {
 
 // --------------------------------------------------------------------- pi
 
-function piRoots(home = homedir()) {
+function piRoots(home = homedir(), env = process.env, options = {}) {
+  if (env.PI_CODING_AGENT_SESSION_DIR) return configuredRoot(env.PI_CODING_AGENT_SESSION_DIR, "", { home, ...options, tilde: true });
+  if (env.PI_CODING_AGENT_DIR) return configuredRoot(env.PI_CODING_AGENT_DIR, "sessions", { home, ...options, tilde: true });
   const root = join(home, ".pi", "agent", "sessions");
-  return existsSync(root) ? [root] : [];
+  return directoryExists(root) ? [root] : [];
 }
 
 export function extractPiText(bytes) {
@@ -214,9 +299,10 @@ function piSessionId(path) {
 
 // ------------------------------------------------------------------ codex
 
-function codexRoots(home = homedir()) {
+function codexRoots(home = homedir(), env = process.env, options = {}) {
+  if (env.CODEX_HOME) return configuredRoot(env.CODEX_HOME, "sessions", { home, ...options });
   const root = join(home, ".codex", "sessions");
-  return existsSync(root) ? [root] : [];
+  return directoryExists(root) ? [root] : [];
 }
 
 export function extractCodexText(bytes) {
@@ -268,21 +354,22 @@ export const SESSION_FORMATS = {
   cc: {
     source: "cc",
     defaultRoots: ccRoots,
-    listFiles: (roots) => roots.flatMap((r) => listJsonlFiles(r, 1)),
-    sessionId: (path) => basename(path, ".jsonl"),
+    listFiles: (roots, options) => roots.flatMap((r) => listCcFiles(r, options)),
+    sessionId: ccSessionId,
+    ignoreKeys: (path) => [basename(path, ".jsonl"), ccParentId(path)].filter(Boolean),
     extractText: extractCcText,
   },
   pi: {
     source: "pi",
     defaultRoots: piRoots,
-    listFiles: (roots) => roots.flatMap((r) => listJsonlFiles(r, 1)),
+    listFiles: (roots, options) => roots.flatMap((r) => listJsonlFiles(r, 1, options)),
     sessionId: piSessionId,
     extractText: extractPiText,
   },
   codex: {
     source: "codex",
     defaultRoots: codexRoots,
-    listFiles: (roots) => roots.flatMap((r) => listJsonlFiles(r, 3)),
+    listFiles: (roots, options) => roots.flatMap((r) => listJsonlFiles(r, 3, options)),
     sessionId: codexSessionId,
     extractText: extractCodexText,
   },

package/packages/record/lib/native-history.mjs

@@ -0,0 +1,87 @@
+// Independent native record custody. Recipes are relaunch templates, not proof
+// of where a past process wrote. Only the execution-side recorder resolves env.
+import { createHash, randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { nativeLaunchLocations } from "./session-roots.mjs";
+
+function canonical(home) {
+  try { return realpathSync(home); }
+  catch (e) {
+    if (e.code !== "ENOENT") throw e;
+    home = resolve(home);
+    return dirname(home) === home ? home : join(canonical(dirname(home)), basename(home));
+  }
+}
+// The source-home leaf is an identity, not a redirectable lookup hint. Resolve
+// parent aliases (e.g. /tmp), but never select another home's authority by
+// following a substituted leaf. Retired homes may legitimately be absent.
+function sourceHome(home) {
+  const absolute = resolve(home);
+  try {
+    const stat = lstatSync(absolute);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("native record source home was substituted; refusing redirected history authority");
+  } catch (e) { if (e.code !== "ENOENT") throw e; }
+  return join(canonical(dirname(absolute)), basename(absolute));
+}
+export function nativeHistoryPath(home) {
+  home = sourceHome(home);
+  return join(dirname(home), ".oats-native-record", createHash("sha256").update(home).digest("hex"));
+}
+function atomic(path, value) {
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value) + "\n", { mode: 0o600, flag: "wx" });
+  renameSync(tmp, path);
+}
+function manifest(home) {
+  const value = JSON.parse(readFileSync(join(nativeHistoryPath(home), "history.json"), "utf8"));
+  if (value.version !== 1 || value.home !== sourceHome(home) || typeof value.completeHistory !== "boolean") throw new Error("invalid native record history authority");
+  return value;
+}
+// Called only for a newly scaffolded home, before capability hooks. A legacy
+// start can record new locations but cannot invent authority for earlier starts.
+export function initializeNativeHistory(home, { completeHistory = true } = {}) {
+  const dir = nativeHistoryPath(home);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try { writeFileSync(join(dir, "history.json"), JSON.stringify({ version: 1, home: sourceHome(home), completeHistory }) + "\n", { mode: 0o600, flag: "wx" }); }
+  catch (e) { if (e.code !== "EEXIST") throw e; manifest(home); } // retain earlier launches if a name is reused
+}
+export function prepareNativeStart(home, runtime) {
+  try { manifest(home); }
+  catch (e) {
+    if (e.code !== "ENOENT") throw e;
+    initializeNativeHistory(home, { completeHistory: false });
+  }
+  const id = randomUUID();
+  atomic(join(nativeHistoryPath(home), `${id}.json`), { version: 1, id, home: sourceHome(home), runtime, state: "pending" });
+  return id;
+}
+// Executed under the SAME environment prefix, cwd and native argv as the
+// harness, after the backend shell's startup. No environment map or argv is
+// serialized. Failure leaves pending evidence and prevents the native exec.
+export function recordNativeStart(home, id, runtime, args, env = process.env) {
+  manifest(home);
+  if (!/^[a-f0-9-]{36}$/.test(id)) throw new Error("invalid native record start id");
+  const path = join(nativeHistoryPath(home), `${id}.json`);
+  const pending = JSON.parse(readFileSync(path, "utf8"));
+  if (pending.version !== 1 || pending.id !== id || pending.home !== sourceHome(home) || pending.runtime !== runtime || pending.state !== "pending") throw new Error("invalid native record start receipt");
+  const locations = nativeLaunchLocations(runtime, { cwd: home, env, args }).map(canonical);
+  atomic(path, { version: 1, id, home: sourceHome(home), runtime, state: "started", startedAt: new Date().toISOString(), locations });
+}
+export function historicalSessionRoots(home) {
+  const authority = manifest(home);
+  if (!authority.completeHistory) throw new Error("native record roots for earlier launches are unknown; legacy history cannot certify complete capture");
+  const roots = { cc: [], pi: [], codex: [] };
+  for (const name of readdirSync(nativeHistoryPath(home)).sort()) {
+    if (name === "history.json") continue;
+    if (!/^[a-f0-9-]{36}\.json$/.test(name)) throw new Error("unrecognized or unfinished native record receipt");
+    const row = JSON.parse(readFileSync(join(nativeHistoryPath(home), name), "utf8"));
+    const source = { claude: "cc", pi: "pi", codex: "codex" }[row.runtime];
+    if (row.version !== 1 || row.id !== basename(name, ".json") || row.home !== authority.home || !source || row.state !== "started" || !Array.isArray(row.locations) || row.locations.length === 0) throw new Error("native record launch is pending or its location receipt is invalid");
+    for (const path of row.locations) {
+      if (typeof path !== "string" || !path.startsWith("/") || path.includes("\0") || resolve(path) !== path) throw new Error("invalid historical native record location");
+      if (!roots[source].includes(path)) roots[source].push(path);
+    }
+  }
+  return roots;
+}