@awebai/oats 0.22.19 → 0.23.0

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;
+}

package/packages/record/lib/session-roots.mjs

@@ -0,0 +1,90 @@
+// Explicit observer-time fallback only; managed capture uses native-history.
+// Resolve only transcript-location inputs. Never execute recorded launch
+// commands or disclose unrelated environment values (which may be secrets).
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+
+const LOCATION_ENV = ["HOME", "CLAUDE_CONFIG_DIR", "PI_CODING_AGENT_DIR", "PI_CODING_AGENT_SESSION_DIR", "CODEX_HOME"];
+
+export function sourceSessionEnvironment(home, base = process.env) {
+  const env = { ...base };
+  let meta;
+  try { meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); }
+  catch (err) {
+    if (err.code !== "ENOENT") throw new Error(`cannot resolve source transcript roots from instance.json (${err.code || "invalid JSON"})`);
+  }
+  const recipe = meta?.launch;
+  if (recipe !== undefined) {
+    if (!recipe || recipe.version !== 1 || !["claude", "pi", "codex"].includes(recipe.runtime)) {
+      throw new Error("cannot resolve source transcript roots: unsupported recorded launch recipe");
+    }
+    for (const layer of [recipe.hooks?.env, recipe.env]) {
+      if (layer === undefined) continue;
+      if (!layer || typeof layer !== "object" || Array.isArray(layer)) throw new Error("cannot resolve source transcript roots: invalid launch environment");
+      for (const name of LOCATION_ENV) {
+        if (!Object.hasOwn(layer, name)) continue;
+        const value = layer[name];
+        if (typeof value === "string") env[name] = value;
+        else if (value && typeof value.fromEnv === "string" && typeof base[value.fromEnv] === "string") env[name] = base[value.fromEnv];
+        else throw new Error(`cannot resolve source transcript roots: unresolved recorded ${name}`);
+      }
+    }
+    // Pi also supports a direct session-directory override. Do not certify
+    // default roots when native options direct evidence somewhere else.
+    if (recipe.runtime === "pi") {
+      const args = recipe.args ?? [];
+      if (!Array.isArray(args) || args.some((a) => typeof a !== "string")) throw new Error("cannot resolve source transcript roots: invalid launch arguments");
+      for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--session-dir" || args[i].startsWith("--session-dir=")) {
+          const value = args[i] === "--session-dir" ? args[++i] : args[i].slice("--session-dir=".length);
+          if (!value || value.startsWith("--")) throw new Error("cannot resolve source transcript roots: invalid --session-dir");
+          env.PI_CODING_AGENT_SESSION_DIR = value;
+        } else if (args[i] === "--session" || args[i].startsWith("--session=")) {
+          throw new Error("cannot certify transcript roots for a recorded explicit --session; capture its source directory explicitly");
+        }
+      }
+      if (/--session(?:-dir)?(?:[=\s]|$)/.test(recipe.hooks?.launch?.pi ?? "")) {
+        throw new Error("cannot resolve source transcript roots from shell-form session options in launch hooks");
+      }
+    }
+  } else if (typeof meta?.command === "string" && /(?:^|\s)(?:CLAUDE_CONFIG_DIR|PI_CODING_AGENT_(?:SESSION_)?DIR|CODEX_HOME|HOME)=|--session(?:-dir)?(?:[=\s]|$)/.test(meta.command)) {
+    // Old command strings cannot safely be interpreted as environment maps.
+    throw new Error("cannot resolve source transcript roots from a legacy launch command; a recorded launch environment is required");
+  }
+  const userHome = env.HOME ?? homedir();
+  if (!userHome || !isAbsolute(userHome)) throw new Error("cannot resolve source transcript roots: HOME must be absolute");
+  return { env, home: userHome };
+}
+
+export function nativeDirectory(value, { home = homedir(), cwd = process.cwd(), tilde = false } = {}) {
+  if (typeof value !== "string" || !value || value.includes("\0")) throw new Error("cannot resolve native transcript directory");
+  if (value.startsWith("~")) {
+    if (!tilde || !(value === "~" || value.startsWith("~/"))) throw new Error("cannot resolve unexpanded native transcript directory");
+    value = join(home, value.slice(2));
+  }
+  return resolve(cwd, value);
+}
+
+/** Native execution-side locations, without existence filtering. Unlike a
+ * background observer scan, Claude's native default is exactly ~/.claude,
+ * not every .claude* profile found under an observer's HOME. */
+export function nativeLaunchLocations(runtime, { cwd, env = process.env, args = [] } = {}) {
+  const home = env.HOME || homedir();
+  if (!isAbsolute(home)) throw new Error("native launch HOME must be absolute");
+  if (!Array.isArray(args) || args.some(a => typeof a !== "string")) throw new Error("invalid native launch arguments");
+  if (runtime === "claude") return [join(nativeDirectory(env.CLAUDE_CONFIG_DIR || join(home, ".claude"), { home, cwd }), "projects")];
+  if (runtime === "codex") return [join(nativeDirectory(env.CODEX_HOME || join(home, ".codex"), { home, cwd }), "sessions")];
+  if (runtime !== "pi") throw new Error("unsupported native record runtime");
+  let sessionDir = env.PI_CODING_AGENT_SESSION_DIR;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--session" || arg.startsWith("--session=")) throw new Error("explicit Pi --session has no supported directory custody; capture explicit roots instead");
+    if (arg === "--session-dir" || arg.startsWith("--session-dir=")) {
+      sessionDir = arg === "--session-dir" ? args[++i] : arg.slice("--session-dir=".length);
+      if (!sessionDir || sessionDir.startsWith("--")) throw new Error("invalid native --session-dir");
+    }
+  }
+  return [sessionDir ? nativeDirectory(sessionDir, { home, cwd, tilde: true })
+    : join(nativeDirectory(env.PI_CODING_AGENT_DIR || join(home, ".pi", "agent"), { home, cwd, tilde: true }), "sessions")];
+}

package/packages/record/lib/session-snapshot.mjs

@@ -0,0 +1,61 @@
+// File witnesses cross the discovery -> capture-lock boundary. Paths alone
+// are not attribution: a renamed/replaced source must never donate bytes to
+// the previous source's stream. Reads and validation use the SAME descriptor.
+import { createHash } from "node:crypto";
+import { fstatSync, readSync, statSync } from "node:fs";
+
+export function identity(stat) {
+  if (!stat.isFile()) throw new Error("session source is not a regular file");
+  return { dev: stat.dev, ino: stat.ino, size: stat.size, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs };
+}
+
+export function sameFile(a, b) { return a.dev === b.dev && a.ino === b.ino; }
+export function sameVersion(a, b) {
+  return sameFile(a, b) && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+}
+export function digest(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+
+export function readRange(fd, start, size, path) {
+  const buf = Buffer.alloc(size - start);
+  let done = 0;
+  while (done < buf.length) {
+    const n = readSync(fd, buf, done, buf.length - done, start + done);
+    if (n === 0) throw new Error(`short read of session source: ${path}`);
+    done += n;
+  }
+  return buf;
+}
+
+export function hashPrefix(fd, size, path) {
+  const hash = createHash("sha256"), buf = Buffer.alloc(64 * 1024);
+  for (let pos = 0; pos < size;) {
+    const n = readSync(fd, buf, 0, Math.min(buf.length, size - pos), pos);
+    if (n === 0) throw new Error(`short read of session source: ${path}`);
+    hash.update(buf.subarray(0, n)); pos += n;
+  }
+  return hash.digest("hex");
+}
+
+export function assertIdentity(stat, expected, path) {
+  if (!stat.isFile() || !sameFile(stat, expected) || stat.size < expected.size) {
+    throw new Error(`session source identity changed or shrank since attribution: ${path}`);
+  }
+}
+
+// Append growth is allowed, but only with an identical witnessed prefix.
+// A changed same-size file is not append growth. Verification happens before
+// journal writes; afterwards the buffer to append is independent of the path.
+export function verifySnapshot(fd, path, snapshot) {
+  const after = fstatSync(fd), named = statSync(path);
+  assertIdentity(after, snapshot, path);
+  assertIdentity(named, snapshot, path);
+  if (!sameVersion(after, named)) throw new Error(`session source changed during capture: ${path}`);
+  if (sameVersion(after, snapshot)) return;
+  if (after.size <= snapshot.size || hashPrefix(fd, snapshot.size, path) !== snapshot.hash) {
+    throw new Error(`session source changed during capture: ${path}`);
+  }
+  // A second change while validating is uncertain, not absence of evidence.
+  if (!sameVersion(after, fstatSync(fd)) || !sameVersion(after, statSync(path))) {
+    throw new Error(`session source changed during verification: ${path}`);
+  }
+}

package/packages/record/lib/sessions-for-home.mjs

@@ -12,11 +12,14 @@
 // instance's own, and nothing outside it — not the parent workspace, not a
 // sibling home — is ever swept in.
 
-import { closeSync, openSync, readSync, realpathSync, statSync } from "node:fs";
-import { resolve, sep } from "node:path";
-import { StringDecoder } from "node:string_decoder";
+import { closeSync, fstatSync, openSync, readSync, realpathSync } from "node:fs";
+import { basename, resolve, sep } from "node:path";
+import { isUtf8 } from "node:buffer";
 
 import { SESSION_FORMATS } from "./formats.mjs";
+import { hashPrefix, identity, sameVersion, verifySnapshot } from "./session-snapshot.mjs";
+import { sourceSessionEnvironment } from "./session-roots.mjs";
+import { historicalSessionRoots } from "./native-history.mjs";
 
 // A session's first lines can be large (Claude Code queue operations and
 // file-history snapshots run to 100 KB and more) and the first cwd-bearing
@@ -27,64 +30,82 @@ import { SESSION_FORMATS } from "./formats.mjs";
 const CHUNK_BYTES = 64 * 1024;
 export const CWD_SCAN_BOUND_BYTES = 8 * 1024 * 1024;
 
-function* wholeLines(path, bound) {
-  const fd = openSync(path, "r");
-  try {
-    const buf = Buffer.alloc(CHUNK_BYTES);
-    const decoder = new StringDecoder("utf8"); // a multi-byte character may straddle two chunks
-    let carry = "";
-    let offset = 0;
-    while (offset < bound) {
-      const n = readSync(fd, buf, 0, Math.min(CHUNK_BYTES, bound - offset), offset);
-      if (n === 0) break;
-      offset += n;
-      carry += decoder.write(buf.subarray(0, n));
-      let nl;
-      while ((nl = carry.indexOf("\n")) >= 0) {
-        yield carry.slice(0, nl);
-        carry = carry.slice(nl + 1);
-      }
+function* wholeLines(fd, bound) {
+  const buf = Buffer.alloc(CHUNK_BYTES);
+  let pieces = [], size = 0; // keep raw bytes across UTF-8/chunk boundaries
+  let offset = 0;
+  while (offset < bound) {
+    const n = readSync(fd, buf, 0, Math.min(CHUNK_BYTES, bound - offset), offset);
+    if (n === 0) break;
+    offset += n;
+    let from = 0;
+    for (let nl = buf.indexOf(10, from); nl >= 0 && nl < n; nl = buf.indexOf(10, from)) {
+      const tail = buf.subarray(from, nl);
+      const bytes = pieces.length ? Buffer.concat([...pieces, tail], size + tail.length) : tail;
+      // Replacement decoding could fabricate a cwd. Leave corrupt lines
+      // unattributed; capture will report incomplete bytes if a later
+      // valid line supplies the attribution.
+      yield isUtf8(bytes) ? bytes.toString("utf8") : null;
+      pieces = []; size = 0; from = nl + 1;
+    }
+    if (from < n) {
+      const piece = Buffer.from(buf.subarray(from, n)); // buf is reused
+      pieces.push(piece); size += piece.length;
     }
-    // The remainder is a fragment unless the file ended exactly there.
-    if (carry && offset < bound) yield carry;
-  } finally {
-    closeSync(fd);
   }
+  // A JSON-shaped EOF fragment is still an uncommitted native record.
+  // Never attribute a source using a line its writer has not terminated.
 }
 
 function cwdOfLine(source, line) {
-  if (!line.trim()) return undefined;
+  if (line === null || !line.trim()) return undefined;
   let d;
   try {
     d = JSON.parse(line);
   } catch {
     return undefined; // a non-JSON native line
   }
-  if (source === "cc" && typeof d.cwd === "string") return d.cwd;
-  if (source === "pi" && d.type === "session" && typeof d.cwd === "string") return d.cwd;
-  if (source === "codex" && d.type === "session_meta" && typeof d.payload?.cwd === "string") return d.payload.cwd;
+  if (source === "cc" && typeof d?.cwd === "string") return d.cwd;
+  if (source === "pi" && d?.type === "session" && typeof d?.cwd === "string") return d.cwd;
+  if (source === "codex" && d?.type === "session_meta" && typeof d.payload?.cwd === "string") return d.payload.cwd;
   return undefined;
 }
 
-/** The working directory a session file records, scanning whole lines from
- *  the start until the first one that carries it, or undefined when none
- *  does within `bound` bytes (unknown format, torn file, no cwd at all). */
-export function sessionCwd(source, path, { bound = CWD_SCAN_BOUND_BYTES } = {}) {
+/** Descriptor-derived attribution and (for accepted cwd) content witness.
+ *  No cwd within `bound` means unknown format, torn input or no attribution. */
+export function sessionAttribution(source, path, { bound = CWD_SCAN_BOUND_BYTES, acceptCwd = () => true } = {}) {
+  const fd = openSync(path, "r");
   try {
-    for (const line of wholeLines(path, bound)) {
-      const cwd = cwdOfLine(source, line);
-      if (cwd) return cwd;
+    const snapshot = identity(fstatSync(fd));
+    let cwd;
+    for (const line of wholeLines(fd, Math.min(bound, snapshot.size))) {
+      cwd = cwdOfLine(source, line);
+      if (cwd) break;
     }
-  } catch {
-    return undefined;
-  }
-  return undefined;
+    // Never hash/read the body of an unrelated or unattributable session.
+    if (cwd && acceptCwd(cwd)) snapshot.hash = hashPrefix(fd, snapshot.size, path);
+    // Never combine attribution read from an old prefix with a new witness.
+    // Discovery requires a stable read; append growth between discovery and
+    // capture is supported by the witness's prefix hash.
+    const after = identity(fstatSync(fd));
+    if (!sameVersion(after, snapshot)) {
+      throw new Error(`session source changed during attribution: ${path}`);
+    }
+    verifySnapshot(fd, path, snapshot);
+    return { cwd, snapshot };
+  } finally { closeSync(fd); }
+}
+
+/** Scan complete lines for the first native cwd; never attribute EOF fragments. */
+export function sessionCwd(source, path, options) {
+  return sessionAttribution(source, path, { ...options, acceptCwd: () => false }).cwd;
 }
 
 function canonical(p) {
   try {
     return realpathSync(p);
-  } catch {
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
     return resolve(p); // a retired home's cwd no longer exists; compare the lexical path
   }
 }
@@ -94,35 +115,46 @@ function within(child, parent) {
 }
 
 /** Session files whose recorded cwd is `home` or below it, oldest first.
- *  `roots` may override the per-format search roots ({ cc, pi, codex }),
- *  otherwise each format's default roots under the current HOME are used.
+ *  By default uses independent managed-launch history, never observer env.
+ *  `roots` is an explicit inventory ({ cc, pi, codex }; omitted formats are
+ *  excluded). `fallback: "current-env"` explicitly chooses observer-time
+ *  recipe/env discovery for standalone or legacy sources. All supplied or
+ *  historical roots must be readable; missing roots are not optional.
  *  `onUnattributed(source, path)` is called for a file that carries no cwd
  *  within the scan bound, so a caller can report it instead of losing it.
- *  Each entry: { source, sessionId, thread, path, cwd, bytes, mtime }. */
-export function sessionsForHome(home, { roots, onUnattributed, bound } = {}) {
+ *  Read/scan failures throw; they are not unattributed or empty scans.
+ *  `ignore` excludes files BEFORE reading, with optional `onIgnored`.
+ *  Each entry includes a descriptor-derived `snapshot` witness; pass the
+ *  entries intact as captureSessions({ files }) to retain attribution. */
+export function sessionsForHome(home, { roots, onUnattributed, bound, ignore, onIgnored, env = process.env, fallback } = {}) {
   const target = canonical(home);
   const out = [];
+  // Explicit roots are a caller-owned inventory; unspecified formats are
+  // excluded, not filled from an unrelated observer. The opt-in fallback is
+  // for standalone/legacy inventories, never proof of historical completeness.
+  let context;
+  if (!roots && fallback !== "current-env") roots = historicalSessionRoots(home);
+  if (!roots) context = sourceSessionEnvironment(home, env);
   for (const fmt of Object.values(SESSION_FORMATS)) {
-    const rs = roots?.[fmt.source] ?? fmt.defaultRoots();
-    for (const path of fmt.listFiles(rs)) {
-      const cwd = sessionCwd(fmt.source, path, bound ? { bound } : {});
+    const rs = roots ? (roots[fmt.source] ?? []) : fmt.defaultRoots(context.home, context.env, { cwd: home });
+    for (const path of fmt.listFiles(rs, { strict: true })) {
+      const sessionId = fmt.sessionId(path);
+      if (ignore?.ignores(path, [basename(path), sessionId, ...(fmt.ignoreKeys?.(path) ?? [])])) {
+        onIgnored?.(fmt.source, path);
+        continue;
+      }
+      const { cwd, snapshot } = sessionAttribution(fmt.source, path, { bound, acceptCwd: cwd => within(canonical(cwd), target) });
       if (!cwd) { if (onUnattributed) onUnattributed(fmt.source, path); continue; }
       if (!within(canonical(cwd), target)) continue;
-      let stat;
-      try {
-        stat = statSync(path);
-      } catch {
-        continue; // vanished between listing and stat
-      }
-      const sessionId = fmt.sessionId(path);
       out.push({
         source: fmt.source,
         sessionId,
         thread: `${fmt.source}:session:${sessionId}`,
         path,
         cwd,
-        bytes: stat.size,
-        mtime: stat.mtime.toISOString(),
+        bytes: snapshot.size,
+        mtime: new Date(snapshot.mtimeMs).toISOString(),
+        snapshot,
       });
     }
   }

package/skills/oats/SKILL.md

@@ -38,7 +38,9 @@ oats status [--json]
 oats status --team [--json]   # whole-team roster when config declares team: (all repos in the team scope)
 # with the aweb messaging integration active, `oats aweb roster` adds the
 # cross-machine view: aweb team members, where OATS aliases are instance names
-oats create <name> [--description ...] [--type <agent-type>] [--repo ...] [--work worktree|checkout|attached|workspace]
+oats create <name> [--description ...] [--type <agent-type>] [--repo ...] [--work worktree|checkout|attached|workspace|directory]
+# directory mode = owned execution directory; repo is config context (no Git
+# required); --work-dir and --branch are rejected; retirement preserves work.
 # workspace mode = cross-repo coordinator: ./work is the whole team scope; read
 # all member repos, edit none; if a knowledge layer is active, IT defines how
 # soul updates are delivered (see that capability's own instructions)