@awebai/oats 0.22.1 → 0.22.3

package/lib/session-input.mjs

@@ -0,0 +1,78 @@
+/** Host-local terminal transport. Delivery policy belongs to the caller. */
+import { execFileSync } from "node:child_process";
+import { basename } from "node:path";
+import { randomUUID } from "node:crypto";
+import { inspectHerdr, inputHerdr, herdrCommand } from "./herdr.mjs";
+
+const shells = new Set(["sh", "bash", "zsh", "fish", "dash", "ksh", "login"]);
+function tmux(target, args, { exec = execFileSync, input } = {}) {
+  return exec("tmux", ["-S", target.socket, ...args], {
+    encoding: "utf8", input, timeout: 10000, maxBuffer: 1024 * 1024,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+}
+export function inspectSessionTarget(target, io) {
+  if (target.backend === "herdr") {
+    const s = inspectHerdr(target, io);
+    let state = s.present ? s.status : "stopped";
+    if (s.present && !s.agent) {
+      const processes = herdrCommand(target, ["pane", "process-info", "--pane", target.paneId], io).process_info?.foreground_processes;
+      if (!Array.isArray(processes)) throw new Error("Herdr returned no process information");
+      if (!processes.length || processes.every((p) => shells.has(p.name))) state = "shell";
+    }
+    return { backend: "herdr", present: s.present, state, terminalId: target.terminalId };
+  }
+  let rows;
+  try {
+    rows = tmux(target, ["list-panes", "-t", `=${target.session}:=${target.window}`, "-F", "#{pane_id}\t#{pane_dead}\t#{pane_current_command}\t#{pane_pid}"], io).trim().split("\n").filter(Boolean);
+  } catch (e) {
+    // A missing window on a reachable server is absence. A lost socket is not.
+    if (/can't find (window|session)/i.test(String(e.stderr || ""))) return { backend: "tmux", present: false, state: "stopped" };
+    throw e;
+  }
+  if (!rows.length) return { backend: "tmux", present: false, state: "stopped" };
+  if (rows.length !== 1) throw new Error("session window has multiple panes; choose an unsplit agent window");
+  const [paneId, dead, command, panePid] = rows[0].split("\t");
+  if (!/^%\d+$/.test(paneId) || !["0", "1"].includes(dead)) throw new Error("invalid tmux pane response");
+  let state = dead === "1" ? "stopped" : "unknown";
+  if (dead === "0" && shells.has(command)) {
+    // macOS tmux can report the wrapper shell while the harness is its child.
+    // Only a shell with no non-shell descendants is a fallback prompt.
+    if (!/^\d+$/.test(panePid)) throw new Error("tmux returned no pane process id");
+    const output = (io?.exec || execFileSync)("ps", ["-axo", "pid=,ppid=,comm="], {
+      encoding: "utf8", timeout: 10000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"],
+    });
+    const processes = output.split("\n").map((line) => line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/)).filter(Boolean);
+    const descendants = new Set([panePid]);
+    let active = false;
+    for (let changed = true; changed;) {
+      changed = false;
+      for (const [, pid, parent, name] of processes) {
+        if (descendants.has(parent) && !descendants.has(pid)) {
+          descendants.add(pid); changed = true;
+          if (!shells.has(basename(name).replace(/^-/, ""))) active = true;
+        }
+      }
+    }
+    state = active ? "unknown" : "shell";
+  }
+  return { backend: "tmux", present: dead === "0", state, paneId };
+}
+export function inputSessionTarget(target, text, io) {
+  const state = inspectSessionTarget(target, io);
+  if (!state.present || state.state === "shell") throw new Error(`cannot submit input: session is ${state.state}`);
+  if (target.backend === "herdr") inputHerdr(target, text, io);
+  else {
+    // Bracketed paste preserves multiline input as one user message. No text
+    // is evaluated by a shell or interpreted as tmux key names.
+    const buffer = `oats-${randomUUID()}`;
+    try {
+      tmux(target, ["load-buffer", "-b", buffer, "-"], { ...io, input: text });
+      tmux(target, ["paste-buffer", "-p", "-b", buffer, "-t", state.paneId], io);
+      tmux(target, ["send-keys", "-t", state.paneId, "Enter"], io);
+    } finally {
+      try { tmux(target, ["delete-buffer", "-b", buffer], io); } catch { /* already consumed or disconnected */ }
+    }
+  }
+  return { ...state, submitted: true };
+}

package/lib/session-viewer.mjs

@@ -0,0 +1,51 @@
+/** Interactive host-local viewers. Closing a viewer leaves its agent alive. */
+import { execFileSync, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { inspectSessionTarget } from "./session-input.mjs";
+
+export function prepareSessionViewer(target, { exec = execFileSync } = {}) {
+  if (!inspectSessionTarget(target, { exec }).present) throw new Error("session no longer exists");
+  if (target.backend === "herdr") {
+    const env = { ...process.env, HERDR_SOCKET_PATH: target.socket };
+    delete env.HERDR_SESSION;
+    return { binary: target.binary, args: ["terminal", "attach", target.terminalId], env, cleanup() {} };
+  }
+  const run = (args) => exec("tmux", ["-S", target.socket, ...args], {
+    encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+  const viewer = `oatsview-${process.pid}-${randomUUID().slice(0, 8)}`;
+  const cleanup = () => { try { run(["kill-session", "-t", `=${viewer}`]); } catch { /* already detached/ended */ } };
+  try {
+    const placeholder = run(["new-session", "-d", "-s", viewer, "-P", "-F", "#{window_id}"]);
+    if (!/^@\d+$/.test(placeholder)) throw new Error("tmux returned no viewer window id");
+    run(["link-window", "-s", `=${target.session}:=${target.window}`, "-t", `=${viewer}:`]);
+    run(["kill-window", "-t", placeholder]);
+    // One linked window prevents a stale viewer from selecting a sibling agent
+    // when this agent retires. Disable window navigation in the viewer only.
+    for (const name of ["prefix", "prefix2"]) run(["set-option", "-t", viewer, name, "None"]);
+    run(["set-option", "-t", viewer, "key-table", "oatsview-locked"]);
+    run(["unbind-key", "-a", "-q", "-T", "oatsview-locked"]);
+    run(["bind-key", "-T", "oatsview-locked", "WheelUpPane", "if-shell", "-F", "#{||:#{pane_in_mode},#{mouse_any_flag}}", "send-keys -M", "copy-mode -e; send-keys -M"]);
+    run(["set-option", "-t", viewer, "mouse", "on"]);
+    const env = { ...process.env }; delete env.TMUX;
+    return { binary: "tmux", args: ["-S", target.socket, "attach-session", "-t", `=${viewer}`], env, cleanup };
+  } catch (e) { cleanup(); throw e; }
+}
+
+export async function attachSessionTarget(target) {
+  const viewer = prepareSessionViewer(target);
+  let child;
+  const stop = () => { viewer.cleanup(); child?.kill(); };
+  const signals = ["SIGHUP", "SIGTERM", "SIGINT"];
+  for (const sig of signals) process.on(sig, stop);
+  try {
+    return await new Promise((resolve, reject) => {
+      child = spawn(viewer.binary, viewer.args, { env: viewer.env, stdio: "inherit" });
+      child.once("error", reject);
+      child.once("exit", (code) => resolve(code ?? 1));
+    });
+  } finally {
+    for (const sig of signals) process.removeListener(sig, stop);
+    viewer.cleanup();
+  }
+}

package/package-catalog.json

@@ -2,12 +2,12 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v1.4.1",
+      "ref": "v1.5.0",
       "path": "oats-package"
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.8.0",
+      "ref": "v1.10.0",
       "path": "oats-package"
     },
     "oats.jira": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.22.1",
+  "version": "0.22.3",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",

package/packages/record/bin/capture.mjs

@@ -14,11 +14,12 @@
 
 import { watch } from "node:fs";
 import { homedir, hostname } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import process from "node:process";
 
 import { RecordStore } from "../lib/store.mjs";
-import { captureAllSessions } from "../lib/capture-cc.mjs";
+import { captureAllSessions, captureSessions } from "../lib/capture-cc.mjs";
+import { sessionsForHome } from "../lib/sessions-for-home.mjs";
 import { SESSION_FORMATS } from "../lib/formats.mjs";
 import { captureAwLogs, defaultCommLogDir } from "../lib/capture-aw.mjs";
 import { RecordIndex } from "../lib/index-db.mjs";
@@ -41,7 +42,7 @@ function loadIgnoreOrExit(recordRoot) {
 // hostname-derived owner, which forked the whole record into a second owner
 // namespace: 571 duplicate journals from one typo. Parsing must refuse what
 // it does not understand before anything can be written.
-const VALUE_FLAGS = new Set(["root", "owner"]);
+const VALUE_FLAGS = new Set(["root", "owner", "home"]);
 const BOOL_FLAGS = new Set([
   "watch",
   "status",
@@ -61,6 +62,12 @@ const USAGE = `capture — land sessions and aw client logs in the turn record.
   capture --watch              pass now, then re-pass on filesystem change
                                (debounced) and every 15 minutes regardless
   capture --status             show store/stream summary, capture nothing
+  capture --home <dir>         capture the sessions that ran inside <dir> (an
+                               OATS instance home) and print them as JSON:
+                               thread, stream, turn count, first/last turn id.
+                               Tombstoned turns are never a boundary. Codex
+                               keeps a day's rollouts in one directory, so the
+                               pass captures that day; the list is filtered.
   capture --install-hint       print the Claude Code hook snippet
   capture --help               this text
   capture --quiet              suppress per-pass progress
@@ -224,6 +231,55 @@ if (args.status) {
   process.exit(0);
 }
 
+// One instance home: capture its own sessions and report them with exact
+// sequence boundaries (first and last captured turn id), so a consumer such
+// as the OKF harvester can name what it read without timestamps, which tie
+// and which late capture appends behind. Output is JSON, always: this mode
+// exists for programs.
+if (args.home) {
+  warnOnStrangerOwner();
+  const ignore = loadIgnoreOrExit(root);
+  const unattributed = [];
+  const found = sessionsForHome(args.home, { onUnattributed: (source, path) => unattributed.push({ source, path }) });
+  const sessions = [];
+  const dirs = new Map(); // one capture pass per (format, directory)
+  for (const s of found) dirs.set(`${s.source}\0${dirname(s.path)}`, { format: s.source, dir: dirname(s.path) });
+  let appended = 0;
+  for (const { format, dir } of dirs.values()) {
+    appended += captureSessions(store, { owner, roots: [dir], format, ignore }).appended;
+  }
+  if (appended > 0 && !args["no-index"]) {
+    const index = new RecordIndex(store);
+    try {
+      index.update();
+    } finally {
+      index.close();
+    }
+  }
+  // A tombstoned turn is hidden everywhere; a boundary naming one would be
+  // refused by recall, so boundaries come from the visible turns only.
+  const claims = store.tombstoneClaims();
+  for (const s of found) {
+    const stream = `${owner}~${s.source}.${s.sessionId}`;
+    const turns = store.readStream(stream).filter((t) => !store.claimHides(claims, t));
+    if (!turns.length) continue; // ignored by rule, nothing capturable yet, or all hidden
+    sessions.push({
+      thread: s.thread,
+      source: s.source,
+      sessionId: s.sessionId,
+      path: s.path,
+      cwd: s.cwd,
+      stream,
+      turns: turns.length,
+      firstTurnId: turns[0].id,
+      lastTurnId: turns[turns.length - 1].id,
+      lastTs: turns[turns.length - 1].ts,
+    });
+  }
+  console.log(JSON.stringify({ home: args.home, owner, appended, sessions, ...(unattributed.length ? { unattributed } : {}) }, null, 2));
+  process.exit(0);
+}
+
 warnOnStrangerOwner();
 pass();
 

package/packages/record/bin/recall.mjs

@@ -4,6 +4,13 @@
 //   recall <query...>                 FTS5 query over mail, chat, sessions
 //   recall --kind mail <query...>     filter by kind (mail|chat|session|note)
 //   recall --thread <thread> [query]  filter/list by thread
+//   recall --thread <thread> --json   the thread's turns in journal order,
+//     [--after <id>] [--until <id>]   with extracted text; exact id bounds
+//     [--limit n] [--ids-only]        (after is exclusive, until inclusive);
+//                                     --ids-only lists id, ts and the bytes
+//                                     each turn occupies in the --json output
+//                                     (text extracted but not emitted), so a
+//                                     consumer can size a window it will read
 //   recall --from <name> <query...>   filter by speaker
 //   recall --limit N                  max results (default 20)
 //   recall --show <turn-id>           print one turn as JSON
@@ -22,7 +29,7 @@ function parseArgs(argv) {
   const args = { _: [] };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (["--root", "--kind", "--thread", "--from", "--role", "--limit", "--show"].includes(a)) {
+    if (["--root", "--kind", "--thread", "--from", "--role", "--limit", "--show", "--after", "--until"].includes(a)) {
       args[a.slice(2)] = argv[++i];
     } else if (a.startsWith("--")) args[a.slice(2)] = true;
     else args._.push(a);
@@ -65,6 +72,57 @@ try {
     process.exit(2);
   }
 
+  // Thread turns straight from the journal, in capture SEQUENCE: the order a
+  // consumer can bound exactly with turn ids. Timestamps tie within a turn
+  // and late capture appends older stamps behind newer ones, so a window
+  // named by ids is the only one two passes agree on. after is exclusive,
+  // until inclusive; an unknown id is an error, never an empty answer.
+  if (args.json && args.thread && !query) {
+    // Session streams are not in readAll(), so hiddenIds() cannot see them:
+    // resolve tombstone claims once and test each session turn directly
+    // (store.mjs, tombstoneClaims). A redacted line must never reach the
+    // harvester, which promotes what it reads into a durable soul.
+    const claims = store.tombstoneClaims();
+    const turns = [];
+    const sessionStreams = store.sessionStreamsFor(args.thread);
+    for (const streamId of sessionStreams) {
+      for (const t of store.readStream(streamId)) if (!store.claimHides(claims, t)) turns.push(t);
+    }
+    if (!sessionStreams.length) {
+      // not a session thread (mail, chat, note): the bulk read has them
+      for (const { turn } of store.readAll().values()) if (turn.thread === args.thread && !store.claimHides(claims, turn)) turns.push(turn);
+    }
+    const ids = turns.map((t) => t.id);
+    let start = 0;
+    let end = turns.length;
+    if (args.after) {
+      const i = ids.indexOf(args.after);
+      if (i < 0) { console.error(`--after: no turn ${args.after} in thread ${args.thread}`); process.exit(1); }
+      start = i + 1;
+    }
+    if (args.until) {
+      const i = ids.indexOf(args.until);
+      if (i < 0) { console.error(`--until: no turn ${args.until} in thread ${args.thread}`); process.exit(1); }
+      end = i + 1;
+    }
+    const cap = args.limit ? Number(args.limit) : Infinity;
+    const stop = Math.min(end, start + cap);
+    const window = turns.slice(start, stop);
+    // A window is a bounded read: a consumer that plans one (the OKF
+    // harvester) sizes it with --ids-only first, then reads exactly that.
+    const out = window.map((t) => {
+      const docs = index.extractText(t);
+      const base = { id: t.id, ts: t.ts, thread: t.thread, kind: t.kind, source: t.provenance?.source ?? null };
+      const full = { ...base, text: docs.map((d) => ({ role: d.role, text: d.text })) };
+      // bytes = what this turn occupies in the pretty-printed --json answer,
+      // so a consumer's byte cap bounds what it will actually receive.
+      if (args["ids-only"]) return { ...base, bytes: Buffer.byteLength(JSON.stringify(full, null, 2), "utf8") + 8 };
+      return full;
+    });
+    console.log(JSON.stringify({ thread: args.thread, total: turns.length, from: start, to: stop, remaining: end - stop, turns: out }, null, 2));
+    process.exit(0);
+  }
+
   const limit = args.limit ? Number(args.limit) : 20;
   let rows;
   if (query) {
@@ -86,10 +144,18 @@ try {
       .all(args.thread, limit);
   }
 
+  if (rows.length === 0 && args.json) {
+    console.log("[]");
+    process.exit(0);
+  }
   if (rows.length === 0) {
     console.error("no matches");
     process.exit(1);
   }
+  if (args.json) {
+    console.log(JSON.stringify(rows, null, 2));
+    process.exit(0);
+  }
   for (const r of rows) {
     const where = r.loc ? ` @${r.loc}` : "";
     const to = r.to_name ? ` -> ${r.to_name}` : "";

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

@@ -0,0 +1,130 @@
+// sessionsForHome — the session transcripts one OATS instance home produced.
+//
+// Nothing in a captured session turn names the instance that ran it: turns
+// carry owner, thread, kind and text. What every harness DOES record is the
+// working directory the session started in — Claude Code on each line, pi in
+// its session header, Codex in session_meta — and an OATS instance runs with
+// its home as that directory. So "the instance's own sessions" is exactly
+// "the session files whose recorded cwd is the home or a directory below it".
+//
+// The match is on canonical paths and is exact-or-descendant, never looser:
+// a home is disposable and unique, so anything that ran inside it is the
+// 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 { SESSION_FORMATS } from "./formats.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
+// line can sit past 100 KB of bookkeeping lines, so the scan is incremental:
+// whole lines only, chunk by chunk, until the first cwd or the byte bound.
+// A file whose bound is exhausted without a cwd is reported as unattributable
+// through the optional `onUnattributed` hook, never silently dropped.
+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);
+      }
+    }
+    // The remainder is a fragment unless the file ended exactly there.
+    if (carry && offset < bound) yield carry;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function cwdOfLine(source, line) {
+  if (!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;
+  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 } = {}) {
+  try {
+    for (const line of wholeLines(path, bound)) {
+      const cwd = cwdOfLine(source, line);
+      if (cwd) return cwd;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+function canonical(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p); // a retired home's cwd no longer exists; compare the lexical path
+  }
+}
+
+function within(child, parent) {
+  return child === parent || child.startsWith(parent + sep);
+}
+
+/** 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.
+ *  `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 } = {}) {
+  const target = canonical(home);
+  const out = [];
+  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 } : {});
+      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(),
+      });
+    }
+  }
+  return out.sort((a, b) => a.mtime.localeCompare(b.mtime) || a.path.localeCompare(b.path));
+}

package/skills/oats/SKILL.md

@@ -98,8 +98,12 @@ soul. Never put secrets, user data, or volatile task details in an instance
 name.
 
 To self-retire, first finish memory/commit/reporting requirements, report final
-status, then run `oats retire <own-instance> --self`. Never retire merely to
-clean up; retirement deletes the instance home.
+status, then run `oats retire <own-instance> --self`. That returns at once and
+a detached completion retires you a few seconds later exactly as an external
+`oats retire` would (quiesce, preserve work, hooks, remove the home). If the
+completion fails, your window stays, the failure shows in `oats status` with
+the retry command, and an operator retries. Never retire merely to clean up;
+retirement deletes the instance home.
 
 ## Canonical versus generated