@awebai/oats 0.22.1 → 0.22.3

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

@@ -37,7 +37,8 @@
  * identity joined moments before the failure must still be deletable.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, statSync } from "node:fs";
+import { chmodSync, cpSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
 import { join, dirname, resolve, delimiter } from "node:path";
 
 /** Run a command as ARGV — never a shell string. Team ids, aliases, instance
@@ -66,6 +67,10 @@ const run = (argv, cwd, timeout = 45000, { secrets = [], secretSafe = false } =
     const why = secretSafe ? "" : (scrub(e.stderr).trim() || (e.status === undefined ? String(e.code || "failed") : ""));
     const err = new Error(`${where} failed${e.status === undefined ? "" : ` (exit ${e.status})`}${why ? `: ${why}` : ""}${secretSafe ? " (output withheld: this command handles credentials)" : ""}`);
     err.status = e.status;
+    // A classification, never the text: the caller may name a KNOWN failure
+    // class (an alias that still holds a certificate) without any output of a
+    // credential-handling command reaching a log.
+    err.aliasConflict = /already|exists|conflict|422|active certificate/i.test(String(e.stderr ?? "") + String(e.stdout ?? ""));
     throw err;
   }
 };
@@ -97,6 +102,17 @@ const fatal = (m, meta) => out({ ...(meta ? { meta } : {}), warning: `oats-aweb:
 const event = process.env.OATS_EVENT || process.argv[2];
 const instance = process.env.OATS_INSTANCE;
 const home = process.env.OATS_HOME || process.cwd();
+// Effective capability settings, injected by kernel dispatch (OATS_SETTINGS).
+// delivery: "channel" (default) keeps the native channel packages waking the
+// instance; "session" hands delivery to the host wake broker (aweb-abil):
+// AWEB_DELIVERY=session goes into the launch environment, the Claude channel
+// flag is omitted, and nothing wakes the instance until the broker exists.
+let settings = {};
+try { settings = JSON.parse(process.env.OATS_SETTINGS || "{}"); } catch { settings = {}; }
+const deliveryMode = (() => {
+  const v = settings.delivery === undefined || settings.delivery === null || settings.delivery === "" ? "channel" : String(settings.delivery);
+  return v === "session" ? "session" : "channel";
+})();
 
 /**
  * The aweb root (minting authority). BOUNDED candidates — the deployment's team
@@ -148,7 +164,165 @@ if (!onPath("aw")) {
   warn(`aw CLI not on PATH — no identity minted; ${AW_INSTALL}`);
 }
 
+// ---------------------------------------------------------------------------
+// Retained identity (explicit per-soul opt-in): a standing seat keeps its
+// did:aw and address when re-seated as an OATS instance. Per aweb's contract
+// (2026-09-05): copy exactly the identity-authority files from the source
+// .aw into the home's .aw, reconnect the coordination binding with
+// `aw workspace connect`, verify online, heartbeat and status show the new
+// path, and hold a lock BESIDE the source so no second seat can take it.
+// Never copy workspace.yaml, caches or locks; never delete the source; never
+// team-join (that is the mint path, which would try to create the alias
+// again). Retire releases the lock and leaves the identity alone.
+const IDENTITY_AUTHORITY = ["signing.key", "identity.yaml", "teams.yaml", "team-certs", "encryption.yaml", "encryption-keys"];
+// Session delivery registers the home with the host wake broker (aweb-abil:
+// `aw wake register --home <abs> --identity-home <abs> --delivery session
+// [--backend tmux|herdr]`, durable even when the daemon is down). An aw
+// without `aw wake` cannot deliver in session mode: refuse, never silently
+// turn a working channel into a poll-only instance.
+// Throws, never exits: both callers run it inside a try whose catch performs
+// the rollback (the seat path restores the binding; the mint path hands the
+// minted identity to compensation).
+function wakeRegister(instanceHome, identityHome) {
+  const backend = process.env.OATS_BACKEND;
+  try {
+    run(["aw", "wake", "register", "--home", instanceHome, "--identity-home", identityHome, "--delivery", "session", ...(backend ? ["--backend", backend] : [])], instanceHome, 60000);
+  } catch (e) {
+    throw new Error(`delivery: session needs an aw with the wake broker CLI (aw wake register), which this aw does not provide (${e.message || e}); install the aweb release that ships aw wake, or use delivery: channel`);
+  }
+}
+function wakeDeregister(instanceHome) {
+  try { run(["aw", "wake", "deregister", "--home", instanceHome], instanceHome, 60000); return true; } catch { return false; }
+}
+const seatLockPath = (source) => join(dirname(source), ".aw-retained-seat.json");
+const yamlScalar = (text, key) => {
+  const m = String(text).match(new RegExp(`^${key}:\\s*["']?([^"'\\n#]+)["']?\\s*$`, "m"));
+  return m ? m[1].trim() : undefined;
+};
+function retainedSeatSpawn(source, takeOver) {
+  if (typeof source !== "string" || !source.startsWith("/")) fatal("identity.source must be the absolute path of the legacy .aw directory to retain");
+  if (!existsSync(join(source, "signing.key"))) fatal(`identity.source ${source} holds no signing.key, so there is no identity to retain`);
+  const lockPath = seatLockPath(source);
+  let takenOver;
+  if (existsSync(lockPath)) {
+    let held; try { held = JSON.parse(readFileSync(lockPath, "utf8")); } catch { held = {}; }
+    const holderHome = held.home;
+    // Held means the holder's home still exists: retire removes both the lock
+    // and the home, so a home that is there is a seat that was never retired.
+    // No process liveness is inferred (the spawner's pid says nothing about the
+    // runtime). The only escape is the explicit, warned take-over for a seat
+    // whose runtime is known to be dead.
+    if (holderHome && existsSync(holderHome)) {
+      if (takeOver !== true) fatal(`identity at ${source} is already held by ${holderHome} (${lockPath}); a seat is never taken from a holder whose home exists — retire that instance first, or set identity.takeOver: true only if you know its runtime is dead`);
+      takenOver = holderHome;
+    }
+  }
+  const srcWorkspace = existsSync(join(source, "workspace.yaml")) ? readFileSync(join(source, "workspace.yaml"), "utf8") : "";
+  const service = process.env.OATS_AWEB_URL || yamlScalar(srcWorkspace, "aweb_url");
+  if (!service) fatal(`cannot determine the aweb service for ${source} (no aweb_url in its workspace.yaml)`);
+  const role = yamlScalar(srcWorkspace, "role_name");
+  let team = process.env.OATS_TEAM_ID;
+  if (!team && existsSync(join(source, "teams.yaml"))) team = yamlScalar(readFileSync(join(source, "teams.yaml"), "utf8"), "active_team") || yamlScalar(readFileSync(join(source, "teams.yaml"), "utf8"), "active");
+  if (!team || !team.includes(":")) fatal(`cannot determine the team for the retained identity (set team.id in oats-config.yaml, or an active team in ${join(source, "teams.yaml")})`);
+  const dest = join(home, ".aw");
+  const legacyHome = dirname(source);
+  // The lock is taken FIRST: a concurrent second spawn must see it before any
+  // byte of the identity is copied.
+  // Exclusive creation (wx): two concurrent spawns cannot both pass the
+  // existence check and overwrite each other; the loser fails here having
+  // copied nothing. A take-over replaces the stale lock first, deliberately.
+  if (takenOver) { try { rmSync(lockPath, { force: true }); } catch { /* replaced below */ } }
+  try {
+    writeFileSync(lockPath, JSON.stringify({ home, instance, team, takenAt: new Date().toISOString(), host: hostname(), ...(takenOver ? { tookOverFrom: takenOver } : {}) }, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+  } catch (e) {
+    fatal(`identity at ${source} was taken by another spawn a moment ago (${lockPath} exists); nothing copied`);
+  }
+  let connected = false;
+  const rollback = () => {
+    // After `aw workspace connect` the server binding points at the new home;
+    // deleting the copy alone would leave the identity bound to nothing. Put
+    // the binding back where it was, from the legacy home, then remove the
+    // copy; if the restore fails, KEEP the copy so the seat stays recoverable.
+    let restored = !connected;
+    if (connected) {
+      try { run(["aw", "workspace", "connect", "--service", service, "--team", team, ...(role ? ["--role", role] : [])], legacyHome, 60000); restored = true; }
+      catch { restored = false; }
+    }
+    if (restored) { try { rmSync(dest, { recursive: true, force: true }); } catch { /* best effort */ } try { rmSync(lockPath, { force: true }); } catch { /* best effort */ } }
+    return restored;
+  };
+  try {
+    mkdirSync(dest, { recursive: true, mode: 0o700 });
+    chmodSync(dest, 0o700);
+    for (const name of IDENTITY_AUTHORITY) {
+      const from = join(source, name);
+      if (!existsSync(from)) continue; // encryption material may be absent on an identity that never had it
+      const to = join(dest, name);
+      if (statSync(from).isDirectory()) {
+        cpSync(from, to, { recursive: true }); chmodSync(to, 0o700);
+        for (const f of readdirSync(to)) { const p = join(to, f); if (statSync(p).isFile()) chmodSync(p, 0o600); } // private keys inside, whatever the source modes were
+      } else { copyFileSync(from, to); chmodSync(to, 0o600); }
+    }
+    for (const forbidden of ["workspace.yaml", "context", "interaction-log.jsonl", "channel-delivered-ids.json", "chat-delivered-ids.json"]) {
+      if (existsSync(join(dest, forbidden))) rmSync(join(dest, forbidden), { recursive: true, force: true });
+    }
+    run(["aw", "workspace", "connect", "--service", service, "--team", team, ...(role ? ["--role", role] : [])], home, 60000);
+    connected = true;
+    run(["aw", "check", "--online"], home, 60000);
+    run(["aw", "heartbeat"], home, 60000);
+    const status = run(["aw", "workspace", "status", "--json"], home, 60000);
+    // Thrown, not fatal: the catch below rolls the copy and the lock back first.
+    // Verified by parsing: the workspace row's path must be this home. The
+    // hostname the row records is whatever the binding stored (on hosted
+    // teams it need not equal this OS hostname), so it is reported, not judged.
+    let st; try { st = JSON.parse(String(status)); } catch { throw new Error(`aw workspace status from ${home} answered no JSON, so the seat is not connected; nothing is briefed`); }
+    const ws = st.workspace && typeof st.workspace === "object" ? st.workspace : st;
+    const shownPath = String(ws.workspace_path || ws.path || "");
+    const same = (a, b) => { try { return realpathSync(a) === realpathSync(b); } catch { return resolve(a) === resolve(b); } };
+    if (!shownPath || !same(shownPath, home)) throw new Error(`aw workspace status from ${home} shows workspace_path ${JSON.stringify(shownPath)} not this home, so the seat is not connected; nothing is briefed`);
+    const hostNote = ws.hostname && ws.hostname !== hostname() && ws.hostname.split(".")[0] !== hostname().split(".")[0] ? ` (workspace row hostname ${ws.hostname}, this host ${hostname()})` : "";
+    const identityText = readFileSync(join(dest, "identity.yaml"), "utf8");
+    const expectedDid = yamlScalar(identityText, "did");
+    const expectedAddress = yamlScalar(identityText, "address");
+    // The same-identity check the contract is for: `aw whoami --json` from the
+    // new home reports the did and address the CLI now acts as (workspace
+    // status carries no did); both must equal the copied identity.yaml.
+    let who; try { who = JSON.parse(String(run(["aw", "whoami", "--json"], home, 60000))); } catch (e) { throw new Error(`aw whoami from ${home} answered no JSON (${e.message || e}); the seat is not verified`); }
+    const shownDid = who.did || who.identity?.did;
+    const shownAddress = who.address || who.identity?.address;
+    if (expectedDid && shownDid !== expectedDid) throw new Error(`aw whoami shows did ${shownDid || "(none)"}, not the retained identity's ${expectedDid}; the seat is not the same identity`);
+    if (expectedAddress && shownAddress !== expectedAddress) throw new Error(`aw whoami shows address ${shownAddress || "(none)"}, not the retained identity's ${expectedAddress}; the seat is not the same identity`);
+    const aliasRaw = String(ws.alias || st.alias || (expectedAddress || "").split("/").pop() || instance);
+    if (!/^[a-z0-9][a-z0-9._-]{0,127}$/i.test(aliasRaw)) throw new Error(`aw workspace status reports an alias that is not a plausible alias; the seat is not briefed`);
+    const alias = aliasRaw;
+    if (expectedAddress && !expectedAddress.endsWith(`/${alias}`)) throw new Error(`aw workspace status shows alias ${alias}, not the retained identity's address ${expectedAddress}; the seat is not the same identity`);
+    writeFileSync(lockPath, JSON.stringify({ home, instance, alias, team, takenAt: new Date().toISOString(), host: hostname(), ...(takenOver ? { tookOverFrom: takenOver } : {}) }, null, 2) + "\n", { mode: 0o600 });
+    const launch = (process.env.OATS_RUNTIME || "") === "claude" && deliveryMode === "channel"
+      ? { claude: "--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace" }
+      : undefined;
+    const env = deliveryMode === "session" ? { AWEB_DELIVERY: "session" } : undefined;
+    const deliveryBrief = deliveryMode === "session"
+      ? ` Notification delivery: external (AWEB_DELIVERY=session); until the host wake broker registers this instance NOTHING wakes you: check \`aw mail inbox\` and \`aw chat pending\` at every task boundary.`
+      : "";
+    if (deliveryMode === "session") wakeRegister(home, dest);
+    const warnings = [];
+    if (takenOver) warnings.push(`oats-aweb: took over the retained identity from ${takenOver} on identity.takeOver: true; if that runtime was still alive there are now two seats with one key — stop the old one`);
+    if (hostNote) warnings.push(`oats-aweb: seated${hostNote}`);
+    out({
+      meta: { team, alias, retained: true, source, lock: lockPath, delivery: deliveryMode, ...(takenOver ? { tookOverFrom: takenOver } : {}) },
+      ...(env ? { env } : {}),
+      brief: `Comms: you are the retained seat of the existing aweb identity "${alias}" on team ${team} (same did and address as the seat you replace; its contacts, routes and conversations are yours).${deliveryBrief} Use \`aw mail\`/\`aw chat\` for messaging (see the aweb-messaging skill).`,
+      ...(launch ? { launch } : {}),
+      ...(warnings.length ? { warning: warnings.join(" | ") } : {}),
+    });
+  } catch (e) {
+    const restored = rollback();
+    fatal(`retained identity could not be seated from ${source}: ${e.message || e}${connected ? (restored ? " (the server binding was restored to the legacy home and the copy removed)" : ` (the server binding still points at ${home} and the copy was KEPT there so the seat is recoverable: run aw workspace connect from ${legacyHome} to restore it, or retry the spawn)`) : ""}`);
+  }
+}
+
 if (event === "spawn") {
+  if (settings.identity && typeof settings.identity === "object" && settings.identity.source) retainedSeatSpawn(String(settings.identity.source), settings.identity.takeOver === true);
   let minted;                 // external identity, once `aw team join` succeeds
   const root = awebRoot();
   if (!root) fatal(`no initialized aweb root (.aw) among the bounded candidates (home, its git repo, context repo, workspace ${process.env.OATS_WORKSPACE || "?"}), so no identity could be minted and this instance would have no messaging — run \`oats aweb setup\` for guided onboarding`);
@@ -173,7 +347,18 @@ if (event === "spawn") {
     // so neither their output nor their diagnostics may reach a log.
     const inv = parseSecretJson(run(["aw", "team", "invite", "--team-id", team, "--json"], root, 45000, { secretSafe: true }), "aw team invite");
     if (!inv?.token || typeof inv.token !== "string") fatal("aw team invite returned no usable token, so no identity could be minted");
-    const raw = parseSecretJson(run(["aw", "team", "join", inv.token, "--name", instance, "--json"], home, 45000, { secrets: [inv.token], secretSafe: true }), "aw team join");
+    let raw;
+    try {
+      raw = parseSecretJson(run(["aw", "team", "join", inv.token, "--name", instance, "--json"], home, 45000, { secrets: [inv.token], secretSafe: true }), "aw team join");
+    } catch (e) {
+      // A retired alias keeps its certificate until aweb-abim ships, so a
+      // re-spawn under the same name is refused by AWID. Say that, and the
+      // remedy, instead of relaying a bare join error.
+      if (e.aliasConflict) {
+        fatal(`alias "${instance}" already holds a certificate on ${team} (a retired instance of that name is not reusable until aweb-abim ships), so no identity could be minted — spawn with a fresh --purpose instead`);
+      }
+      throw e;
+    }
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) fatal("aw team join returned no usable result, so no identity could be minted", minted);
     // The RESPONSE is not a safe place to take strings from. Suppressing the
     // failure paths does nothing if a successful reply is copied into meta and
@@ -203,13 +388,21 @@ if (event === "spawn") {
     // spawn, which is exactly the silent host mutation the consent gate exists
     // to prevent. By the time this runs the kernel has already proven the plugin
     // is present and enabled, so contributing the flag is safe.
-    const launch = (process.env.OATS_RUNTIME || "") === "claude"
+    // Session delivery: no channel flag, AWEB_DELIVERY=session in the launch
+    // environment (declared in the manifest), and the truth about waking.
+    const launch = (process.env.OATS_RUNTIME || "") === "claude" && deliveryMode === "channel"
       ? { claude: "--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace" }
       : undefined;
+    const env = deliveryMode === "session" ? { AWEB_DELIVERY: "session" } : undefined;
     const channelWarning = undefined;
+    if (deliveryMode === "session") wakeRegister(home, join(home, ".aw"));
+    const deliveryBrief = deliveryMode === "session"
+      ? ` Notification delivery: external (AWEB_DELIVERY=session): the host wake broker (aw wake) is registered for this home and nudges you when mail or chat arrives; the native aweb channel is not running. If you have waited long with nothing arriving, check \`aw mail inbox\` and \`aw chat pending\` yourself at task boundaries.`
+      : "";
     out({
-      meta: { team: joined.team_id, alias },
-      brief: `Comms: you have an aweb identity — alias "${alias}" on team ${joined.team_id}.${mismatch} Use \`aw mail\`/\`aw chat\` for messaging (see the aweb-messaging skill); coordination stays in your deployment's task layer.`,
+      meta: { team: joined.team_id, alias, delivery: deliveryMode },
+      ...(env ? { env } : {}),
+      brief: `Comms: you have an aweb identity — alias "${alias}" on team ${joined.team_id}.${mismatch}${deliveryBrief} Use \`aw mail\`/\`aw chat\` for messaging (see the aweb-messaging skill); coordination stays in your deployment's task layer.`,
       ...(launch ? { launch } : {}),
       ...(mismatch ? { warning: `oats-aweb: team mismatch — joined ${joined.team_id}, expected ${team}` } : channelWarning ? { warning: channelWarning } : {}),
     });
@@ -221,6 +414,14 @@ if (event === "spawn") {
   }
 } else if (event === "retire") {
   const meta = JSON.parse(process.env.OATS_META || "{}");
+  // A retained seat: release the lock and leave the identity alone. Never
+  // aw workspace delete (it would soft-delete the standing identity's row)
+  // and never team retire; the source .aw stays until a human removes it.
+  if (meta.delivery === "session") { if (!wakeDeregister(home)) process.stderr.write("oats-aweb: aw wake deregister failed; the broker treats a retired home as inactive on its own\n"); }
+  if (meta.retained) {
+    if (meta.lock) { try { rmSync(meta.lock, { force: true }); } catch { /* the lock may already be gone */ } }
+    out({ meta: { retired: true, retained: true, identityReleased: true, ...(meta.tookOverFrom ? { tookOverFrom: meta.tookOverFrom } : {}) }, warning: `oats-aweb: released the retained identity "${meta.alias}" (lock ${meta.lock || "?"} removed); the identity itself and ${meta.source || "its source"} are untouched${meta.tookOverFrom ? `; this seat had taken over from ${meta.tookOverFrom}` : ""}` });
+  }
   // No alias means the spawn hook never reported an identity: nothing exists to
   // undo, which is completion. An alias WITH no local `.aw` is the opposite —
   // the remote record exists and its key is gone, so the self-delete cannot be
@@ -233,7 +434,11 @@ if (event === "spawn") {
     // Self-delete from inside the home, authenticated by its own key — a remote
     // delete would 409 until the server marks the workspace stale.
     run(["aw", "workspace", "delete", meta.alias], home);
-    out({ meta: { retired: true } });
+    // Honest: the workspace row is deleted, but a hosted local member cannot
+    // revoke its own AWID certificate (aweb-abim), so the alias is NOT
+    // reusable. retired stays true because the cleanup is as complete as the
+    // platform allows; the field and the line carry the truth.
+    out({ meta: { retired: true, aliasReusable: false }, warning: `oats-aweb: workspace "${meta.alias}" deleted; its certificate is not revoked (aweb-abim), so the alias is not reusable — spawn successors with a fresh --purpose` });
   } catch (e) {
     // Exit nonzero: during a required-hook rollback this is the signal that
     // compensation did NOT complete, so the spawn is not reported as cleanly

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

@@ -40,10 +40,17 @@ Aliases are instance names (e.g. `dev-coordinator-1`). Discovery:
 `oats status --team` lists this machine's live instances; `oats aweb roster`
 lists the aweb team across machines.
 
+**Notification delivery.** Your instance briefing (TASK.md, the Comms line)
+says how messages reach you. If it carries "Notification delivery: external",
+the native channel is NOT running in this session and, until the host wake
+broker registers you, nothing wakes you: check `aw mail inbox` and
+`aw chat pending` at every task boundary. Otherwise the rule below applies.
+
 **Never sleep, poll, or busy-wait for another agent's reply.** Send your
-message, finish your turn, and go idle — the aweb channel awakens your
-session the moment mail or chat arrives (you saw `✓ aweb connected` at
-startup). A `sleep N; aw mail inbox` loop burns tokens, delays the reply,
+message, finish your turn, and go idle when a delivery channel is configured
+(you saw `✓ aweb connected` at startup). Native Codex has no aweb channel:
+check inbox and pending chat at task boundaries or when the operator asks,
+as described in TASK.md; incoming messages alone will not wake that session. A `sleep N; aw mail inbox` loop burns tokens, delays the reply,
 and adds nothing. An empty `aw mail inbox` means no UNREAD mail — not that
 messages were lost.
 

package/capabilities/oats-aweb/oats.json

@@ -1,9 +1,9 @@
 {
   "capability": "oats.aweb",
   "command": "aweb",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "compatibility": {
-    "oats": ">=0.19.0"
+    "oats": ">=0.22.3"
   },
   "layer": "messaging",
   "description": "Messaging layer via aweb: per-instance team identities + native aw mail/chat skills + cross-machine team roster.",
@@ -16,15 +16,32 @@
     {
       "runtime": "pi",
       "package": "npm:@awebai/pi",
-      "why": "the aweb channel extension for pi sessions — real-time mail/chat awakenings; without it a pi instance can send with `aw` but is never woken by incoming messages",
-      "install": "https://aweb.ai/docs (installed into pi with `pi install npm:@awebai/pi`)"
+      "why": "the aweb channel extension for pi sessions \u2014 real-time mail/chat awakenings; without it a pi instance can send with `aw` but is never woken by incoming messages",
+      "install": "https://aweb.ai/docs (installed into pi with `pi install npm:@awebai/pi`)",
+      "when": {
+        "delivery": "channel"
+      }
     },
     {
       "runtime": "claude",
       "package": "aweb-channel@awebai-marketplace",
       "marketplace": "awebai/claude-plugins",
-      "why": "the aweb channel plugin for Claude Code sessions — real-time mail/chat awakenings; without it a Claude instance can send with `aw` but is never woken by incoming messages",
-      "install": "https://aweb.ai/docs (installs the awebai marketplace and the aweb-channel plugin into Claude Code)"
+      "why": "the aweb channel plugin for Claude Code sessions \u2014 real-time mail/chat awakenings; without it a Claude instance can send with `aw` but is never woken by incoming messages",
+      "install": "https://aweb.ai/docs (installs the awebai marketplace and the aweb-channel plugin into Claude Code)",
+      "when": {
+        "delivery": "channel"
+      }
+    },
+    {
+      "runtime": "pi",
+      "package": "npm:@awebai/pi",
+      "minVersion": "0.3.10",
+      "when": {
+        "delivery": "session"
+      },
+      "why": "an ambient aweb pi extension, if one is installed, must honour AWEB_DELIVERY=session (0.3.10 and later); an older one would open a second event stream beside the wake broker; no extension at all is fine",
+      "install": "pi install npm:@awebai/pi@latest",
+      "ifInstalled": true
     }
   ],
   "skills": [
@@ -43,5 +60,21 @@
       "required": true
     },
     "retire": "bin/oats-aweb.mjs retire"
-  }
+  },
+  "environment": [
+    "AWEB_DELIVERY"
+  ],
+  "settings": {
+    "delivery": {
+      "default": "channel",
+      "values": [
+        "channel",
+        "session"
+      ],
+      "description": "channel: the native aweb channel packages wake the instance (default). session: delivery is external (AWEB_DELIVERY=session), no channel flag; the host wake broker registers the instance once it exists."
+    }
+  },
+  "environmentNamespaces": [
+    "AWEB_"
+  ]
 }

package/capabilities/oats-okf/agents/memory-harvest/AGENTS.md

@@ -1,7 +1,9 @@
 # memory-harvest — soul promotion from live instances
 
 You are a memory-harvest instance. You were spawned because a live agent
-instance committed work while holding pending notes.
+instance committed work while holding pending notes, or because its own
+captured session turns hold candidates nobody has judged yet (your briefing
+says which, and names the exact record windows when it is the latter).
 
 **Your briefing (TASK.md) is the authority on your situation**: the source
 notes dir, the soul to update, the work tree you were given, and how your

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": [],