@awebai/oats 0.22.17 → 0.23.0

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)