@awebai/oats 0.22.19 → 0.23.1

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)

package/capabilities/oats-okf/lib/harvest-branch.mjs

@@ -1,43 +0,0 @@
-// A workspace-mode harvest delivers its promotion as a PR from a branch named
-// memory-harvest/<slug> in the soul's repository. After that PR merges, the
-// local branch may still exist and the next harvest's spawn would refuse it.
-// A branch fully merged into the base is stale and is deleted before the
-// spawn; an unmerged one is the previous harvester's unfinished work and the
-// harvest refuses with the exact remedy instead of touching it.
-import { execFileSync } from "node:child_process";
-
-/** Single-quote shell escaping for the operator remedy: the repo path may hold spaces or shell metacharacters. */
-export function shellQuote(s) { return "'" + String(s).replace(/'/g, "'\\''") + "'"; }
-
-function git(repo, args) {
-  return execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
-}
-
-/** The repository's base branch: origin/HEAD's target when known, else main, else master. */
-export function baseBranchOf(repo) {
-  try { const ref = git(repo, ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"]); if (ref) return ref.replace(/^refs\/remotes\//, ""); } catch { /* no origin/HEAD */ }
-  for (const b of ["origin/main", "main", "origin/master", "master"]) {
-    try { git(repo, ["rev-parse", "--verify", "--quiet", b]); return b; } catch { /* next */ }
-  }
-  return undefined;
-}
-
-/** Returns { action: "absent" | "deleted", base } or throws E_HARVEST_BRANCH_EXISTS. */
-export function reclaimHarvestBranch(repo, branch) {
-  try { git(repo, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]); }
-  catch { return { action: "absent" }; }
-  const base = baseBranchOf(repo);
-  let merged = false;
-  if (base) { try { git(repo, ["merge-base", "--is-ancestor", branch, base]); merged = true; } catch { merged = false; } }
-  if (!merged) {
-    const err = new Error(`branch ${branch} already exists in ${repo} and is not merged into ${base || "any base branch"}: a previous harvest's promotion is unfinished — review and merge or delete it (git -C ${shellQuote(repo)} branch -D ${shellQuote(branch)}) before harvesting again`);
-    err.code = "E_HARVEST_BRANCH_EXISTS";
-    throw err;
-  }
-  // -D, not -d: the merge check above is against the BASE (origin/main when
-  // present). `branch -d` re-checks against the branch's upstream or the
-  // current HEAD instead, so with the soul's local main behind origin/main a
-  // branch fully merged upstream would still be refused as "not fully merged".
-  git(repo, ["branch", "-D", branch]);
-  return { action: "deleted", base };
-}