@awebai/oats 0.22.1 → 0.22.2

package/capabilities/oats-okf/bin/oats-okf.mjs

@@ -11,6 +11,9 @@
  *   spawn          scaffold instance memory (STATE.md, log.md, notes/) + brief
  *   retire         no-op (promotion is continuous — see harvest)
  *   harvest        AGENT-INITIATED (not a kernel hook): run from an instance
+ *                  home; with no pending notes (or with --from-record) it
+ *                  harvests the instance's own captured session turns since
+ *                  the last harvest (watermark .okf-harvest-record.json)
  *                  home (`node <pkg>/capabilities/oats-okf/bin/oats-okf.mjs harvest`)
  *                  after committing with pending notes — spawns the memory-harvest
  *                  agent attached to this instance's work tree.
@@ -23,7 +26,7 @@
 import { existsSync, mkdirSync, mkdtempSync, writeFileSync, readFileSync, readdirSync, realpathSync, rmSync } from "node:fs";
 import { join, isAbsolute, dirname } from "node:path";
 import { tmpdir } from "node:os";
-import { execFile } from "node:child_process";
+import { execFile, spawnSync } from "node:child_process";
 
 const out = (o) => { process.stdout.write(JSON.stringify(o) + "\n"); process.exit(0); };
 const warn = (m) => out({ warning: `oats-okf: ${String(m).slice(0, 300)}` });
@@ -66,6 +69,97 @@ function packageRuntimeCli() {
   return cli;
 }
 
+/** Record-fed harvest (aweb-abfz). An instance that writes no notes still
+ *  leaves a record: every Claude Code, pi and Codex session on the machine is
+ *  captured as session turns, and the sessions that ran inside this home are
+ *  the instance's own. Ask the kernel to capture them and report exact
+ *  sequence boundaries, compare with the watermark of what was already
+ *  harvested, and return the windows that are new — or null when nothing is.
+ *  The watermark advances only when the harvester delivers (it writes the
+ *  file its briefing hands it), so a failed harvest re-reads the same window. */
+const RECORD_WATERMARK = ".okf-harvest-record.json";
+/** A window is what one harvester can actually read: a first harvest of a
+ *  long-lived session must not hand it the whole thread (tens of MB on real
+ *  homes) and then let it advance the watermark past what it never read. The
+ *  plan sizes each window with an ids-only listing and stops at the turn or
+ *  byte cap; the rest drains over later harvests, each with a truthful
+ *  watermark. Overridable through okf settings { "record-window-turns",
+ *  "record-window-bytes" }. */
+// Sized to ONE tool-output read: harnesses truncate a command's output well
+// under 100 KB (Claude Code around 30 KB), and the byte cap is measured on
+// the JSON the harvester receives, not on the text inside it. A backlog
+// drains over successive harvests; the caps are settings for operators
+// whose harness reads more.
+const DEFAULT_WINDOW_TURNS = 60;
+const DEFAULT_WINDOW_BYTES = 96_000;
+function sizeWindow(cli, thread, afterTurnId, caps) {
+  const list = (after) => {
+    const args = ["recall", "--thread", thread, "--json", "--ids-only", "--limit", String(caps.turns)];
+    if (after) args.push("--after", after);
+    const r = spawnSync(cli, args, { encoding: "utf8", env: process.env, timeout: 120000, maxBuffer: 64 * 1024 * 1024 });
+    if (r.status !== 0) return { error: String(r.stderr || r.error?.message || `recall exited ${r.status}`).trim().slice(0, 200) };
+    try { return { doc: JSON.parse(String(r.stdout || "").trim()) }; } catch (e) { return { error: `recall answered no JSON: ${String(e.message).slice(0, 100)}` }; }
+  };
+  let { doc, error } = list(afterTurnId);
+  let restarted = false;
+  // The watermark's boundary turn can leave the thread (a redaction hides it
+  // for good). That must not strand the thread: read from the start again,
+  // bounded as always, and say so. The harvester's own fallback covers the
+  // same case between plan and read.
+  if (error && afterTurnId && /--after: no turn/.test(error)) { ({ doc, error } = list(null)); restarted = true; }
+  if (error) return { error };
+  let bytes = 0; let n = 0;
+  for (const t of doc.turns || []) {
+    if (n > 0 && bytes + t.bytes > caps.bytes) break; // always at least one turn, so a single huge turn still drains
+    bytes += t.bytes; n++;
+  }
+  if (!n) return { empty: true };
+  return { untilTurnId: doc.turns[n - 1].id, newTurns: n, bytes, remaining: (doc.turns.length - n) + (doc.remaining || 0), restarted };
+}
+function planRecordHarvest(instanceHome) {
+  const watermarkPath = join(instanceHome, RECORD_WATERMARK);
+  let prior = {};
+  try { prior = JSON.parse(readFileSync(watermarkPath, "utf8")).threads || {}; } catch { prior = {}; }
+  let report;
+  try {
+    const r = spawnSync(packageRuntimeCli(), ["capture", "--home", instanceHome, "--quiet"], { encoding: "utf8", env: process.env, timeout: 120000, maxBuffer: 8 * 1024 * 1024 });
+    if (r.status !== 0) return { unavailable: String(r.stderr || r.error?.message || `capture exited ${r.status}`).trim().slice(0, 200) };
+    report = JSON.parse(String(r.stdout || "").trim());
+  } catch (e) { return { unavailable: String(e.message || e).slice(0, 200) }; }
+  const positive = (v, d) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Number(v) : d);
+  const caps = { turns: positive(settings["record-window-turns"], DEFAULT_WINDOW_TURNS), bytes: positive(settings["record-window-bytes"], DEFAULT_WINDOW_BYTES) };
+  const threads = [];
+  const problems = [];
+  for (const s of report.sessions || []) {
+    const seen = prior[s.thread];
+    // Nothing new when the last visible turn is the one already harvested;
+    // ids, not counts, so a redaction inside the harvested prefix neither
+    // hides genuinely new turns nor re-reads old ones.
+    if (seen && seen.untilTurnId === s.lastTurnId) continue;
+    const win = sizeWindow(packageRuntimeCli(), s.thread, seen?.untilTurnId || null, caps);
+    if (win.error) { problems.push(`${s.thread}: ${win.error}`); continue; }
+    if (win.empty) { problems.push(`${s.thread}: capture reports new turns after ${seen?.untilTurnId || "the start"} but recall lists none; the two views disagree, nothing planned for it`); continue; }
+    if (win.restarted) problems.push(`${s.thread}: the harvested boundary ${seen.untilTurnId} is no longer in the thread (redacted?); reading from the start again`);
+    threads.push({ thread: s.thread, source: s.source, afterTurnId: win.restarted ? null : (seen?.untilTurnId || null), untilTurnId: win.untilTurnId, turns: (win.restarted ? 0 : (seen?.turns || 0)) + win.newTurns, newTurns: win.newTurns, bytes: win.bytes, remaining: win.remaining });
+  }
+  if (!threads.length) return problems.length ? { unavailable: problems.join("; ") } : null;
+  const next = { threads: { ...prior } };
+  for (const t of threads) next.threads[t.thread] = { untilTurnId: t.untilTurnId, turns: t.turns, harvestedAt: new Date().toISOString() };
+  // The exact next watermark is written beside the current one by the
+  // package; the harvester's delivery is a rename, nothing retyped.
+  const nextPath = join(instanceHome, RECORD_WATERMARK.replace(/\.json$/, ".next.json"));
+  writeFileSync(nextPath, JSON.stringify(next, null, 2) + "\n");
+  return { threads, watermarkPath, nextPath, watermark: next, unattributed: (report.unattributed || []).length, problems };
+}
+
+/** Briefing block for record-fed candidates, appended to the harvest task. */
+function recordBrief(plan, cli) {
+  if (!plan?.threads?.length) return "";
+  const q = (v) => `'${String(v).replace(/'/g, `'\\''`)}'`;
+  const lines = plan.threads.map((t) => `  - ${t.thread} (${t.newTurns} turns, ~${Math.round(t.bytes / 1024)} KB of JSON${t.remaining ? `, ${t.remaining} more wait for the next harvest` : ""}): \`${cli} recall --thread ${q(t.thread)} --json${t.afterTurnId ? ` --after ${q(t.afterTurnId)}` : ""} --until ${q(t.untilTurnId)}\``);
+  return `\n- RECORD-FED CANDIDATES (the memory-harvest skill, section "Record-fed candidates"): this instance's own captured session turns since the last harvest, in windows sized for one reading (about ${Math.round(DEFAULT_WINDOW_BYTES / 1024)} KB at most). Read each window with the exact command given, never wider, and read it IN FULL. If your tool output truncates, redirect the command's output to a file in your home and read that file in parts: that is a complete reading, not a wider one. A window you could not read completely is a failed harvest, and a failed harvest leaves the watermark alone.\n${lines.join("\n")}\n  If a window command is rejected because its --after id is no longer in the thread, run it again without --after and read from the start; if its --until id is rejected, this harvest has failed (leave the watermark files alone; the next oats okf harvest replans). Extract candidate lessons from them in the same shape as notes (one candidate per insight, provenance = the turn ids it came from), then judge every candidate under the same promotion bar as a note. Session trivia, tool noise and anything derivable from the repo fail the bar; promoting nothing is a normal outcome.\n- When your judgement of every window is COMPLETE, whether or not anything was promoted, and after any delivery it needed, advance the watermark by renaming the prepared file (it records what you read, not what you promoted; a failed or abandoned harvest must leave both files as they are):\n  mv '${plan.nextPath}' '${plan.watermarkPath}'`;
+}
+
 /** Invoke the versioned package-runtime boundary. Task text crosses the
  * process boundary only through an owner-readable tempfile, removed on every
  * success/failure outcome. */
@@ -240,10 +334,15 @@ _(the single next action — keep this current; a fresh session on any model res
     const skip = (why) => (JSON_MODE ? jsonOk({ harvest: "skipped", reason: why }) : out({ meta: { harvestSpawn: "skipped", why } }));
     if (String(agName).startsWith("memory-harvest")) skip("self (loop guard)");
     const notes = existsSync(notesDir) ? readdirSync(notesDir).filter((f) => f.endsWith(".md")) : [];
-    if (notes.length === 0) skip("no pending notes");
-    if (!root || (!existsSync(root) && !existsSync(join(dirname(root), "local-agents")))) skip("no agents root found above this home");
-    if (!inst) skip("no instance identity (run from an instance home)");
-    if (!context) skip("no repository context (instance metadata has no repo)");
+
+    // With no notes the record path could still apply, but it needs the same
+    // root, identity and context as any spawn; a home missing them answers
+    // exactly as before ("no pending notes"), so nothing an operator scripted
+    // against that reason changes.
+    const prerequisite = (why) => skip(notes.length ? why : "no pending notes");
+    if (!root || (!existsSync(root) && !existsSync(join(dirname(root), "local-agents")))) prerequisite("no agents root found above this home");
+    if (!inst) prerequisite("no instance identity (run from an instance home)");
+    if (!context) prerequisite("no repository context (instance metadata has no repo)");
     const slug = String(inst).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 30);
     // Debounce: one harvester per source instance at a time (canonical sibling
     // local-agents/ plus legacy nested locations). The public spawn boundary
@@ -254,6 +353,23 @@ _(the single next action — keep this current; a fresh session on any model res
       join(root, "tmp-agents", "memory-harvest", "instances", `memory-harvest-${slug}`),
     ];
     if (harvesterHomes.some((h) => existsSync(h))) skip("harvester already running for this instance");
+    // No notes is no longer the end: the record may hold this instance's own
+    // sessions with turns nobody has judged yet (standing, non-coding roles
+    // write few notes). --from-record asks for the record even with notes.
+    // Planned only now, after every skip above: a capture pass is a real
+    // write and index, and "calling it too often is safe" must stay true.
+    let recordPlan = null;
+    if (notes.length === 0 || process.argv.includes("--from-record")) {
+      let planned = null;
+      try { planned = planRecordHarvest(home); } catch { planned = null; }
+      if (planned?.unavailable) {
+        process.stderr.write(`oats-okf: record unavailable${notes.length ? ", harvesting notes only" : ""}: ${planned.unavailable}\n`);
+        if (notes.length === 0) skip("no pending notes");
+      } else recordPlan = planned;
+      for (const line of recordPlan?.problems || []) process.stderr.write(`oats-okf: record: ${line}\n`);
+      if (recordPlan?.unattributed) process.stderr.write(`oats-okf: record: ${recordPlan.unattributed} session file(s) carry no working directory and cannot be attributed to any home (oats capture --home <home> lists them)\n`);
+      if (notes.length === 0 && !recordPlan) skip("no pending notes");
+    }
     // Effective command settings are injected by capability dispatch. No
     // resolved-config read crosses the public package boundary.
     const harvestModel = settings["harvest-model"] || DEFAULT_HARVEST_MODEL;
@@ -268,7 +384,7 @@ _(the single next action — keep this current; a fresh session on any model res
       // harvester judges notes exactly as usual, but the deliverable is DIRECT
       // edits to the canonical soul — no commit, no PR: there is nothing to
       // version. It must not touch the owner's work tree.
-      const task = `Harvest the pending notes of live LOCAL-SOUL instance "${inst}" (agent "${agName}") into its soul — by direct edits, no commit.\n\n- Source notes: ${notesDir} (${notes.join(", ")})\n- Soul knowledge bundle to update: ${join(realSoul, "knowledge")}\n- Soul skills dir (for procedure-shaped notes): ${join(realSoul, "skills")}\n- This soul is LOCAL (uncommitted, gitignored): edit those soul files IN PLACE. Do NOT run git commit — not for the soul, and not in ./work (the shared tree belongs to the working instance; leave it untouched).\n- Follow your memory-harvest skill for everything else: promote/merge/drop each note, knowledge vs skill routing, index + log discipline, validate the bundle, DELETE processed notes from the source notes/ dir.\n- Then run \`oats retire ${harvName} --self\`.`;
+      const task = `Harvest the pending notes of live LOCAL-SOUL instance "${inst}" (agent "${agName}") into its soul — by direct edits, no commit.\n\n- Source notes: ${notes.length ? `${notesDir} (${notes.join(", ")})` : "none pending"}\n- Soul knowledge bundle to update: ${join(realSoul, "knowledge")}\n- Soul skills dir (for procedure-shaped notes): ${join(realSoul, "skills")}\n- This soul is LOCAL (uncommitted, gitignored): edit those soul files IN PLACE. Do NOT run git commit — not for the soul, and not in ./work (the shared tree belongs to the working instance; leave it untouched).\n- Follow your memory-harvest skill for everything else: promote/merge/drop each note, knowledge vs skill routing, index + log discipline, validate the bundle, DELETE processed notes from the source notes/ dir.\n${recordBrief(recordPlan, packageRuntimeCli())}\n- Then run \`oats retire ${harvName} --self\`.`;
       r = await spawnHarvester(harvestSpawnArgs({
         slug, parent: inst, repo: context, work: "attached", workDir, model: harvestModel,
       }), task);
@@ -280,7 +396,7 @@ _(the single next action — keep this current; a fresh session on any model res
       const soulRepo = gitRootOf(realSoul);
       if (!soulRepo) skip("workspace-mode soul is not inside a git repo — nowhere to deliver a PR");
       const relSoul = realSoul.slice(soulRepo.length + 1);
-      const task = `Harvest the pending notes of live WORKSPACE-MODE instance "${inst}" (agent "${agName}") into its soul — delivered as a PR.\n\n- Source notes: ${notesDir} (${notes.join(", ")})\n- Your ./work is a dedicated worktree of the soul's home repo (${soulRepo}), branch memory-harvest/${slug}.\n- Soul knowledge bundle to update: ./work/${join(relSoul, "knowledge")}\n- Soul skills dir (for procedure-shaped notes): ./work/${join(relSoul, "skills")}\n- Follow your memory-harvest skill: promote/merge/drop each note, knowledge vs skill routing, index + log discipline, validate the bundle, DELETE processed notes from the source notes/ dir, commit once (prefixed "memory-harvest:").\n- Then push the branch and open a PR (\`git push -u origin memory-harvest/${slug}\` then \`gh pr create --fill\`). Do NOT merge it; the humans/owners of ${soulRepo} review soul changes. If gh is unavailable, push the branch and report the compare URL.\n- Finally run \`oats retire ${harvName} --self\` (keep the branch: --self only).`;
+      const task = `Harvest the pending notes of live WORKSPACE-MODE instance "${inst}" (agent "${agName}") into its soul — delivered as a PR.\n\n- Source notes: ${notes.length ? `${notesDir} (${notes.join(", ")})` : "none pending"}\n- Your ./work is a dedicated worktree of the soul's home repo (${soulRepo}), branch memory-harvest/${slug}.\n- Soul knowledge bundle to update: ./work/${join(relSoul, "knowledge")}\n- Soul skills dir (for procedure-shaped notes): ./work/${join(relSoul, "skills")}\n- Follow your memory-harvest skill: promote/merge/drop each note, knowledge vs skill routing, index + log discipline, validate the bundle, DELETE processed notes from the source notes/ dir, and commit once (prefixed "memory-harvest:") if anything changed.${recordBrief(recordPlan, packageRuntimeCli())}\n- If you changed anything: push the branch and open a PR (\`git push -u origin memory-harvest/${slug}\` then \`gh pr create --fill\`). Do NOT merge it; the humans/owners of ${soulRepo} review soul changes. If gh is unavailable, push the branch and report the compare URL. A harvest that promoted nothing has nothing to commit, push or open; that is a completed harvest, not a failed one.\n- Finally run \`oats retire ${harvName} --self\` (keep the branch: --self only).`;
       r = await spawnHarvester(harvestSpawnArgs({
         slug, parent: inst, repo: soulRepo, work: "worktree",
         branch: `memory-harvest/${slug}`, model: harvestModel,
@@ -292,12 +408,12 @@ _(the single next action — keep this current; a fresh session on any model res
       const soulTarget = realSoul.startsWith(realRepo + "/")
         ? join(workDir, realSoul.slice(realRepo.length + 1))
         : realSoul;
-      const task = `Harvest the pending notes of live instance "${inst}" (agent "${agName}") into its soul.\n\n- Source notes: ${notesDir} (${notes.join(", ")})\n- Soul knowledge bundle to update: ${join(soulTarget, "knowledge")}\n- Soul skills dir (for procedure-shaped notes): ${join(soulTarget, "skills")}\n- You are ATTACHED to the instance's work tree (./work) — commit your promotions there as a single commit, prefixed "memory-harvest:".\n- Follow your memory-harvest skill: promote/merge/drop each note, knowledge vs skill routing, index + log discipline, validate the bundle, DELETE processed notes from the source notes/ dir (so they are not re-harvested), commit, then run \`oats retire ${harvName} --self\`.`;
+      const task = `Harvest the pending notes of live instance "${inst}" (agent "${agName}") into its soul.\n\n- Source notes: ${notes.length ? `${notesDir} (${notes.join(", ")})` : "none pending"}\n- Soul knowledge bundle to update: ${join(soulTarget, "knowledge")}\n- Soul skills dir (for procedure-shaped notes): ${join(soulTarget, "skills")}\n- You are ATTACHED to the instance's work tree (./work) — commit your promotions there as a single commit, prefixed "memory-harvest:".\n- Follow your memory-harvest skill: promote/merge/drop each note, knowledge vs skill routing, index + log discipline, validate the bundle, DELETE processed notes from the source notes/ dir (so they are not re-harvested).${recordBrief(recordPlan, packageRuntimeCli())}\n- Commit if you changed anything (a harvest that promoted nothing has nothing to commit), then run \`oats retire ${harvName} --self\`.`;
       r = await spawnHarvester(harvestSpawnArgs({
         slug, parent: inst, repo: context, work: "attached", workDir, model: harvestModel,
       }), task);
     }
-    if (JSON_MODE) jsonOk({ harvest: "spawned", instance: r.instance, window: r.tmux?.window || null });
+    if (JSON_MODE) jsonOk({ harvest: "spawned", instance: r.instance, window: r.tmux?.window || null, ...(recordPlan ? { record: { threads: recordPlan.threads.map((t) => t.thread), ...(recordPlan.unattributed ? { unattributed: recordPlan.unattributed } : {}), ...(recordPlan.problems?.length ? { problems: recordPlan.problems } : {}) } } : {}) });
     out({ meta: { harvestSpawn: r.instance, window: r.tmux?.window } });
   } catch (e) {
     if (JSON_MODE) jsonFail(e.code || "E_HARVEST_FAILED", `harvest spawn failed (notes are safe on disk): ${e.message || e}`);

package/capabilities/oats-okf/injects/okf.md

@@ -43,6 +43,13 @@ are no notes or a harvester is already running — calling it "too often" is
 safe; not calling it means your insights never reach the soul, and unwritten
 or unharvested notes are lost when your home is retired).
 
+**If you write few notes** (a coordinating or reviewing role, a standing
+session): still run `oats okf harvest` at task boundaries, and at least once
+a day. With no notes pending it harvests your own captured session turns
+since the last harvest instead; the harvester judges them under the same
+bar. It skips when nothing is new. `oats okf harvest --from-record` asks for
+the record even when notes are pending.
+
 **Workspace-mode instances**: your soul lives in its own home repo, and your
 `./work` (the workspace) is not where it commits. `oats okf harvest` handles
 this — it promotes your notes in a worktree of the soul's home repo and

package/capabilities/oats-okf/oats.json

@@ -1,8 +1,8 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "1.4.1",
-  "compatibility": { "oats": ">=0.19.0" },
+  "version": "1.5.0",
+  "compatibility": { "oats": ">=0.22.2" },
   "layer": "knowledge",
   "description": "Knowledge layer via OKF: soul bundles, instance memory (STATE.md/log.md/notes/), continuous post-commit harvest into the soul (commit, PR, or direct-edit for local souls), craft + memory skills, validator.",
   "requires": [],

package/capabilities/oats-okf/skills/memory-harvest/SKILL.md

@@ -68,6 +68,45 @@ knowledge; if instances should RUN it the same way every time, it wants to
 be a skill instead. Souls also grow role-specific types and sections — list
 new sections in the bundle index and log the growth.
 
+## Record-fed candidates
+
+Your briefing may name **record windows** beside (or instead of) notes: the
+source instance's own captured session turns since the last harvest, each
+window given as an exact `oats recall --thread <t> --json --after <id>
+--until <id>` command. Standing roles that write few notes still learn; this
+is how what they learned reaches the soul.
+
+- Run each command exactly as given, never wider: the ids are the boundary
+  two harvests agree on, and each window is sized for one full reading (the
+  rest of a long backlog comes in later harvests). Read every window in full.
+  If your tool output truncates, redirect the command's output to a file in
+  your home and read the file in parts; that is a complete reading, not a
+  wider one. If you still could not read a window completely, this harvest
+  has FAILED: judge nothing from it and leave the watermark files untouched. If a command is rejected because its
+  `--after` id is no longer in the thread (a pruned or redacted record), run
+  it again without `--after` and read from the start; if its `--until` id is
+  rejected, this harvest has failed (leave the watermark files alone; the next
+  `oats okf harvest` replans). Read the `text` parts;
+  `tool_use` and `tool_result` are context, not lessons.
+- Extract **candidates** in the shape of notes: one candidate per insight, a
+  one-line title, the claim, and its provenance as the turn ids it came from.
+  A candidate is something the instance learned or decided, stated in the
+  turns, not something you infer it should have learned.
+- Then judge every candidate exactly as a note: promote, merge, or drop
+  against the same bar. Expect most to drop: session trivia, tool noise,
+  restated repo facts and task-scoped decisions all fail it. Promoted
+  concepts cite the turn ids in their frontmatter or body so the claim can be
+  traced back.
+- **The watermark records what you read, not what you promoted.** The
+  package prepared the exact next watermark beside the current one; your
+  briefing gives the one `mv` that advances it. Run it once your judgement of
+  every window is complete: after the commit, PR, or direct edit when
+  something was promoted, and just the same when everything dropped, which
+  is the normal outcome. Never retype it. Only a harvest that fails or is
+  abandoned leaves both files untouched, so the next harvester reads the same
+  window again; a completed judgement that never advanced the watermark would
+  be re-read forever.
+
 ## Bookkeeping (non-negotiable)
 
 1. Every promoted concept: correct frontmatter, listed in its section's
@@ -92,7 +131,9 @@ what your custody allows:
    `memory-harvest: 2 lessons + 1 skill gotcha from worker-x notes`.
 2. **Worktree of the soul's home repo** (workspace-mode source): the same single
    commit on your own branch, then push it and open a PR. Never merge it, and
-   never push to that repo's main branch — its owners review soul changes.
+   never push to that repo's main branch — its owners review soul changes. A
+   harvest that promoted nothing has no commit, push or PR to make; it is
+   complete, not failed, and still advances the watermark.
 3. **Uncommitted local soul**: nothing to commit. Your edits to the soul ARE the
    delivery; they take effect for the next instance immediately.
 

package/docs/execution-targets.md

@@ -0,0 +1,181 @@
+# Execution targets and shared wake delivery
+
+Implementation agreement, 2026-09-05. Lead owns native runtime launch,
+local tmux/Herdr adapters and terminal input; oats owns server registration,
+remote CLI routing and Desktop target selection. Aweb owns the event listener,
+notification state and delivery policy through OATS terminal input. This is the implementation
+contract, not a claim that these features have shipped.
+
+OATS manages composition, worktrees, capability lifecycle and retirement on the execution
+host. A session backend manages the persistent terminal. Desktop is a client;
+closing it must stop neither the agent nor notification delivery.
+
+```mermaid
+flowchart LR
+  UI[Desktop] --> CLI[OATS CLI]
+  CLI --> Local[Local OATS]
+  CLI --> SSH[OpenSSH]
+  SSH --> Remote[Remote OATS]
+  Local --> Sessions[tmux or Herdr]
+  Remote --> RemoteSessions[tmux or Herdr]
+  Events[aweb SSE] --> Wake[aweb wake service on execution host]
+  Wake --> Local
+  RemoteWake[aweb wake service on remote host] --> Remote
+```
+
+Server registrations live in the operator's machine configuration, outside
+repository configuration. Each entry has an id, label, OpenSSH host alias,
+absolute workspace path and OATS/Herdr executable paths. SSH owns key selection,
+host verification and authentication. Registration stores no private keys.
+Remote lifecycle calls invoke the remote installed OATS CLI with argument-safe
+quoting and the same JSON envelope as local calls. Version/envelope compatibility
+is checked before mutation. Repository operations always run on that host.
+
+The local representation of a remote instance snapshots its route:
+
+```json
+{
+  "serverId": "build-server",
+  "target": {
+    "sshHost": "build-server",
+    "workspace": "/srv/team",
+    "oatsPath": "/usr/local/bin/oats",
+    "herdrPath": "/usr/local/bin/herdr"
+  },
+  "instance": "developer-fix",
+  "home": "/srv/team/agents/developer/instances/developer-fix"
+}
+```
+
+`serverId` is for display. Later inspect/retire operations use the snapshot,
+never silently resolve a changed registry entry. A local cache is not authority
+for the remote instance's state. Remote status is pulled from its owning kernel.
+
+The host's instance and independent retirement baseline retain the same local
+session receipt. Existing `tmux: {session, window, socket}` remains readable.
+New Herdr instances use:
+
+```json
+{
+  "backend": "herdr",
+  "binary": "/usr/local/bin/herdr",
+  "socket": "/home/operator/.config/herdr/sessions/oats/herdr.sock",
+  "workspaceId": "w1",
+  "paneId": "w1:p1",
+  "terminalId": "term_65ab9108c6c301",
+  "protocol": 20
+}
+```
+
+The terminal id distinguishes a replacement occupant after a server restart.
+Backend operations allocate, start, inspect, stop and attach a viewer. Retirement
+compares the receipt with its baseline and proves the original session absent.
+An unavailable server or failed inspection is not proof of absence. The same
+rule applies to spawn compensation and detached self-retirement. Lifecycle
+operations run on the target host, so the local backend does not implement SSH.
+
+Herdr 0.8.2 exposes snapshots, socket commands, agent-state inspection and JSONL
+terminal observation/control. Its protocol is versioned. Agent prompts reject
+approval-blocked agents, but prompting a working agent does not prove the new
+message was processed. The adapter must retain this distinction. See the
+[Herdr socket API](https://herdr.dev/docs/socket-api/) and
+[remote connections](https://herdr.dev/docs/persistence-remote/).
+
+An aweb host service owns event streams for managed instances; the GUI displays
+and controls it. Reuse aweb's existing authenticated event/run loop rather than copying credential
+and SSE parsing into OATS or Desktop. OATS exposes backend-neutral session
+inspection and literal terminal input; aweb supplies delivery policy. Current authorization is
+per identity: one long-lived stream per active identity, coalesced per instance,
+with bounded retries. A single team stream requires an explicit server API.
+Reconnect also checks pending state so a lost edge does not strand unread work.
+
+Delivery is a fixed instruction to check `aw` mail/chat from the instance home,
+not arbitrary sender content typed into a shell. The service never acknowledges
+mail or chat on the agent's behalf. Aweb pending hints survive reconnect and service
+restart, coalesce while busy and defer at approval prompts. A stopped harness,
+an unknown occupant or a fallback shell is not a delivery target. Do not call a
+successful terminal write an agent acknowledgement.
+
+Native channels remain selectable during qualification; session delivery must
+be exclusive with them for each instance. Removal follows real tests of Pi,
+Claude and Codex receiving mail/chat, a busy turn, an approval prompt, reconnect,
+service restart, GUI closure and a stopped runtime. The OATS Pi tool extension
+and the aweb Pi channel are separate packages; replacing notification transport
+does not silently remove unrelated tools.
+
+Acceptance includes local CLI/Desktop spawn, reattach, preserved work and
+retirement through both backends; then the same operations on a user-designated
+SSH target. Registering a host without a successful remote agent run does not
+qualify remote support.
+
+## Session CLI contract
+
+Run on the execution host:
+
+```sh
+oats session attach --home /absolute/instance
+oats session inspect --home /absolute/instance --json
+oats session input --home /absolute/instance --text-file /path/to/message --json
+printf '%s' 'Check your pending work.' | oats session input --home /absolute/instance --json
+```
+
+`attach` is interactive and does not accept `--json`. It validates the saved
+endpoint on the execution host, then opens a Herdr terminal viewer or an
+isolated tmux session linked to that agent's window alone. Closing its terminal
+cleans the viewer without stopping the agent; retiring the agent ends the viewer
+instead of switching it to a sibling. This host-local command is also the
+remote Desktop attachment seam over an SSH PTY.
+
+Input accepts UTF-8 text up to 256 KiB, with no NUL bytes. The CLI uses the
+independent lifecycle receipt and refuses metadata disagreement. Tmux uses
+literal bracketed paste followed by Enter. Herdr uses pane input followed by
+Enter. Neither path interprets message text as a shell command. A fallback
+shell or ambiguous split tmux window refuses automatic input.
+
+Success uses the existing envelope:
+
+```json
+{"schemaVersion":1,"ok":true,"result":{"home":"/absolute/instance","backend":"herdr","present":true,"state":"idle","submitted":true}}
+```
+
+Inspect omits `submitted`; optional backend identifiers describe the observed
+terminal. `state` is the Herdr agent state when available, `unknown` for a live
+unclassified harness, `shell` for a fallback shell, `stopped` for an absent/dead
+terminal, or `not-launched`. Errors use `ok:false,error:{code,message}` and a
+nonzero exit. An unavailable backend is an error, never a stopped result.
+Tmux receipts identify socket/session/window; automatic input requires one live
+pane in that exact window. Herdr additionally verifies the original terminal ID.
+The broker owns busy/approval policy and must not interpret `submitted` as
+processing acknowledgement.
+
+Capability spawn hooks register a pending home before runtime allocation;
+inspection becomes available once its receipt is persisted. Retire hooks
+unregister after quiescence. The broker must tolerate this lifecycle order and
+missing homes, and persist pending hints until handled. Kernel session operations
+contain no aweb identity, credentials, stream or notification logic.
+
+The portable integration belongs to the official `oats.aweb` capability.
+The aweb development deployment currently selects its owned `aweb.identity`
+capability; that deployment-specific choice does not change the broker interface
+and needs equivalent registration glue when switched to session delivery.
+
+## Shared permission setting
+
+Set `yolo: true` in an `oats-config.yaml` to apply it to that scope. The closest
+scope wins; an optional `yolo` in soul.yaml overrides it; `oats spawn --yolo` or
+`--no-yolo` overrides both. `oats create` accepts those flags too. Desktop offers
+the same per-launch choice. With no setting, native policy is retained.
+
+Codex receives `--yolo` plus a launch-local trust setting for the generated
+instance home; Claude receives `--dangerously-skip-permissions`. Pi's existing
+project trust behavior is unchanged. `--no-yolo` removes the OATS bypass flags;
+it leaves the operator's native harness settings in force. Instance metadata
+records an explicitly resolved setting. This choice applies when starting an
+agent, not retroactively to running sessions.
+
+Desktop remote terminal requests contain only the server id and instance name.
+The selected installed CLI resolves the saved route and performs remote
+inspection before attaching over SSH. Pending inspections share the terminal
+resource limit and duplicate requests share one inspection. Remote status and
+instance keys must include the server so identical paths on different hosts
+remain distinct.

package/docs/implementation.md

@@ -158,7 +158,20 @@ instance homed inside a repository with its own `.claude/skills` sees those
 too. Project *settings* — hooks, plugins, permissions, custom agents — resolve
 from the instance home rather than from ancestors.
 
-Both runtimes record what they actually expose in `instance.json` under
+Codex is available with `--runtime codex`. It starts in the instance home,
+reads `AGENTS.md` and `.agents/skills` natively, and receives `TASK.md` as its
+initial prompt. User configuration, approval policy, ancestor instructions and
+ambient skill sources remain native. Worktrees are already below the instance
+home; checkout/attached paths outside it use Codex's normal approval handling
+and may require approval for writes, depending on the operator's policy.
+OATS does not pass `--add-dir`, which Codex refuses under some native policies.
+OpenAI-prefixed model preferences are translated to
+Codex ids; other provider preferences fall back to its configured default.
+The Desktop model field accepts a native id without using Pi's model catalog.
+This launch support does not supply an aweb channel for Codex: agents can use
+`aw` from their home, with automatic wake delivery tracked separately.
+
+All runtimes record what they actually expose in `instance.json` under
 `composition.materialized.runtimePosture`: the OATS-composed set, what is
 curtailed, and what remains ambient. The deviation from strict composition is
 auditable rather than implied.

package/docs/migration-from-oas.md

@@ -29,7 +29,7 @@ version has a supported replacement. When the plan is correct:
 
 ```bash
 oats migrate --from-oas --dir /path/to/scope
-oats doctor --dir /path/to/scope
+oats doctor /path/to/scope
 ```
 
 Run the exact `oats trust <capability> --dir <scope>` commands printed by

package/docs/oats-config.schema.json

@@ -72,6 +72,7 @@
   },
   "type": "object",
   "properties": {
+    "yolo": { "type": "boolean", "description": "Skip Codex/Claude permission prompts. Closest scope wins; soul and launch overrides take precedence." },
     "name": { "type": "string" },
     "team": {
       "type": "object",