@awebai/oats 0.22.4 → 0.22.6

package/bin/oats.mjs

@@ -674,7 +674,8 @@ function use() {
   let entry;
   if (manifest.layer) {
     const existing = caps.layers[manifest.layer];
-    entry = existing && existing !== "none" && existing.capability === manifest.capability ? existing : { capability: manifest.capability };
+    var entryExisted = !!(existing && existing !== "none" && existing.capability === manifest.capability);
+    entry = entryExisted ? existing : { capability: manifest.capability };
     if (existing && existing !== "none" && existing.capability !== manifest.capability && enabled) {
       die(`fundamental layer ${manifest.layer} already binds ${existing.capability} at this level — disable it first`);
     }
@@ -713,9 +714,12 @@ function use() {
   }
   if (targetKind === "global") entry.global = enabled;
   else {
-    // A layer entry with no explicit targets is implicitly global — materialize that
-    // before narrowing, so adding a soul/type binding doesn't silently drop everyone else.
-    if (manifest.layer && entry.global === undefined && !entry["agent-types"] && !entry.souls) entry.global = true;
+    // An EXISTING layer entry with no explicit targets is implicitly global:
+    // materialize that before narrowing, so adding a soul/type binding does not
+    // silently drop everyone else. An entry this command just created (the
+    // layer was `none` or another capability) has no implicit global to keep:
+    // a targeted first binding is written as global: false, explicitly.
+    if (manifest.layer && entry.global === undefined && !entry["agent-types"] && !entry.souls) entry.global = entryExisted;
     entry[targetKind] = entry[targetKind] && typeof entry[targetKind] === "object" ? entry[targetKind] : {};
     // Same write-side refusal, and for the same two reasons: `--soul
     // __proto__` was swallowed by the inherited setter and reported as
@@ -2206,8 +2210,20 @@ function migrateCmd() {
 /** oats update <package> — transactional package update with diff + trust reset. */
 function updatePackageCmd(id) {
   const dir = dirFlag();
+  // --to <selector>: move a catalog-sourced lock to another catalog ref
+  // (tag) through the same transactional update. A lock with an explicit
+  // selector keeps it on a plain update by design; this is the operator's
+  // way to advance it without remove + reinstall.
+  // Two spellings: `oats update <id> <id>@<selector>` (the engine's own spec
+  // form) or `oats update <id> --to <selector>`.
+  const to = flag("to");
+  if (to === true) { cmdFail("E_BAD_ARGS", "--to needs a catalog selector, e.g. --to v1.10.1"); return; }
+  if (to !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(to)) { cmdFail("E_BAD_ARGS", `--to selector ${JSON.stringify(to)} is not a catalog ref`); return; }
+  const positional = args[2] && !args[2].startsWith("--") ? args[2] : undefined;
+  if (positional && to !== undefined) { cmdFail("E_BAD_ARGS", "give either <id>@<selector> or --to <selector>, not both"); return; }
+  const spec = positional || (to !== undefined ? `${id}@${to}` : undefined);
   let r;
-  try { r = updatePackage(dir, id); } catch (e) { cmdFail(e.code || "invalid-lock", e.message || e); return; }
+  try { r = updatePackage(dir, id, spec ? { spec } : {}); } catch (e) { cmdFail(e.code || "invalid-lock", e.message || e); return; }
   if (JSON_MODE) { jsonOk(r); return; }
   // A moved package root is reported even when the bytes are identical: the
   // lock now points somewhere else in the repository, and that is exactly the
@@ -2945,6 +2961,17 @@ function capabilityCommand() {
     if (!trust.trusted) bail("E_CAPABILITY_BLOCKED", `${m.capability} executable command is blocked: ${trust.reason}`);
     const sub = args[1];
     const cmds = Object.keys(m.commands);
+    // `oats <ns> --help` and `oats <ns> <cmd> --help` answer from the manifest
+    // and never run the executable: the command's own help, if it has one,
+    // is not worth a side effect (harvest --help once spawned a harvester).
+    if (HELP_WORDS.has(sub) || args.slice(2).some((a) => a === "--help" || a === "-h")) {
+      const known = sub && !HELP_WORDS.has(sub) && Object.prototype.hasOwnProperty.call(m.commands, sub);
+      if (JSON_MODE) { jsonOk({ capability: m.capability, namespace: cmd, command: known ? sub : null, commands: cmds, description: m.description || null, help: "printed from the manifest; the executable was not run" }); return; }
+      console.log(`oats ${cmd}${known ? ` ${sub}` : ""} — ${m.capability}${m.description ? `: ${m.description}` : ""}`);
+      console.log(`  commands: ${cmds.join(", ") || "(none)"}`);
+      console.log(`  (help printed from the manifest; the executable was not run)`);
+      process.exit(0);
+    }
     // Distinguish an ABSENT key from a declared-but-invalid value: a manifest
     // entry of "" / 0 / false / null is a broken capability, not an unknown
     // command (it is listed in cmds).
@@ -3379,6 +3406,13 @@ function serverRouteCmd() {
 // blame` pointing at the commit that last changed each command.
 const TYPED_CLI_FAILURES = new Set(["unsafe-config-key", "unsafe-config-value"]);
 try {
+// `--help`/`-h` anywhere after a kernel command prints that command's usage
+// and exits 0 BEFORE any dispatch: a fresh operator inspects --help before
+// using a command, and `install --help` once ran the bare restore while
+// `okf harvest --help` spawned a harvester (BeadHub, 2026-09-05).
+const KERNEL_COMMANDS = new Set(["capture", "config", "create", "doctor", "experimental", "init", "inject", "install", "list", "migrate", "pane", "recall", "remove", "retire", "root", "server", "session", "setup", "spawn", "status", "trust", "type", "update", "use", "version"]);
+const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
+if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
 if (flag("server") !== undefined && ["spawn", "retire", "status", "session", "okf"].includes(cmd)) serverRouteCmd();
 else if (cmd === "server") serverCmd();
 else if (cmd === "doctor") {
@@ -3386,7 +3420,13 @@ else if (cmd === "doctor") {
   args.includes("--json") ? doctorJson(doctorDir) : doctor(doctorDir);
 }
 else if (cmd === "use") use();
-else if (cmd === "update") { const t = args[1] && !args[1].startsWith("--") ? args[1] : undefined; t ? updatePackageCmd(t) : updateCmd(); }
+else if (cmd === "update") {
+  const t = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
+  // A selector without a package must never fall through to the kernel
+  // self-update (a different product) with the flag silently ignored.
+  if (!t && flag("to") !== undefined) { cmdFail("E_BAD_ARGS", "oats update --to needs a package: oats update <package> --to <ref> (or <package> <package>@<ref>)"); process.exit(1); }
+  t ? updatePackageCmd(t) : updateCmd();
+}
 else if (cmd === "type") typeCmd();
 else if (cmd === "inject") injectCmd();
 else if (cmd === "install") install();
@@ -3417,7 +3457,29 @@ else if (cmd && !cmd.startsWith("--") && !HELP_WORDS.has(cmd) && capabilityComma
 // text must NOT contaminate stdout — still one envelope object, nonzero exit.
 else if (cmd && !cmd.startsWith("--") && !HELP_WORDS.has(cmd) && JSON_MODE) jsonFail("E_UNKNOWN_COMMAND", `unknown command "${cmd}" — no kernel subcommand or active capability namespace matches`);
 else {
-  console.log(`oats — Open Agent Team Specification
+  console.log(usageText());
+  process.exit(cmd && !HELP_WORDS.has(cmd) ? 1 : 0);
+}
+
+/** The usage lines for one kernel command (its `oats <cmd> ...` lines and
+ *  their indented continuations), or the whole usage when none match. */
+function usageLinesFor(name) {
+  const out = [];
+  let inside = false;
+  for (const line of usageText().split("\n")) {
+    if (new RegExp(`^  oats ${name}(\\s|$)`).test(line)) { out.push(line); inside = true; continue; }
+    if (inside && /^ {6}/.test(line) && !/^  oats /.test(line)) { out.push(line); continue; }
+    inside = false;
+  }
+  return out;
+}
+function usageFor(name) {
+  const out = usageLinesFor(name);
+  console.log(out.length ? `Usage:\n${out.join("\n")}` : usageText());
+}
+
+function usageText() {
+  return `oats — Open Agent Team Specification
 
 Usage:
   oats version [--json]                      kernel version; --json emits the
@@ -3488,9 +3550,10 @@ Usage:
                                             report under error.details)
   oats list [--dir <d>] [--json]             installed packages, exported capabilities,
                                             scopes, trust state
-  oats update <package> [--dir <d>]          transactional package update: temp fetch,
-                                            closure validation, diff, lock replace,
-                                            all capability approvals invalidated
+  oats update <package> [<package>@<ref>]    transactional package update: temp fetch,
+      [--to <ref>] [--dir <d>]              closure validation, diff, lock replace,
+                                            all capability approvals invalidated; a
+                                            spec or --to moves a catalog lock to <ref>
   oats remove <package> [--dir <d>]          remove a package (refuses while config or
                                             dependent packages reference it)
   oats migrate [--dry-run] [--dir <d>]       map this scope's v1 capability locks to
@@ -3569,8 +3632,7 @@ The turn record (core — every conversation captured, searchable, replicated):
   oats <namespace> <command> [args…]         run an operational command only when its
                                             capability is active (e.g. oats okf harvest)
 
-Layers: ${LAYERS.join(", ")}. Level detection: ~ → laptop, .git → repo, else workspace.`);
-  process.exit(cmd && !HELP_WORDS.has(cmd) ? 1 : 0);
+Layers: ${LAYERS.join(", ")}. Level detection: ~ → laptop, .git → repo, else workspace.`;
 }
 } catch (e) {
   if (!TYPED_CLI_FAILURES.has(e?.code)) throw e;

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

@@ -85,6 +85,17 @@ const parseSecretJson = (text, what) => {
  * `command -v`, which is a SHELL BUILTIN — spawning it as a program depends on
  * a /usr/bin/command binary that many systems do not ship, and its absence
  * would read as "aw is missing" on every such host. */
+/** The installed aw's version from `aw version` ("aw 1.36.1 ..."), or
+ *  undefined when it cannot be read; compared as numeric triples. */
+function awAtLeast(floor) {
+  let v;
+  try { v = /aw\s+v?(\d+)\.(\d+)\.(\d+)/.exec(run(["aw", "version"], undefined, 10000)); } catch { return false; }
+  if (!v) return false;
+  const a = v.slice(1, 4).map(Number), b = floor.split(".").map(Number);
+  for (let i = 0; i < 3; i++) { if (a[i] !== b[i]) return a[i] > b[i]; }
+  return true;
+}
+
 function onPath(cmd) {
   for (const dir of String(process.env.PATH || "").split(delimiter)) {
     if (!dir) continue;
@@ -195,6 +206,17 @@ 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");
+/** The alias a home's .aw/workspace.yaml records under memberships (indented),
+ *  or undefined. Read only when the hook has no alias of its own. */
+const workspaceAliasOf = (homeDir) => {
+  try { const m = readFileSync(join(homeDir, ".aw", "workspace.yaml"), "utf8").match(/^\s*alias:\s*["']?([a-z0-9][a-z0-9._-]{0,127})["']?\s*$/mi); return m ? m[1] : undefined; }
+  catch { return undefined; }
+};
+/** A join that the CLI reported as failed (or that this hook killed on
+ *  timeout) may still have completed server-side: the home then holds a
+ *  signing key, a team certificate and a workspace binding. */
+const joinedLate = (homeDir) => existsSync(join(homeDir, ".aw", "signing.key")) && existsSync(join(homeDir, ".aw", "team-certs")) && !!workspaceAliasOf(homeDir);
+const JOIN_TIMEOUT_MS = Number(process.env.OATS_AWEB_JOIN_TIMEOUT_MS) > 0 ? Number(process.env.OATS_AWEB_JOIN_TIMEOUT_MS) : 120000;
 const yamlScalar = (text, key) => {
   const m = String(text).match(new RegExp(`^${key}:\\s*["']?([^"'\\n#]+)["']?\\s*$`, "m"));
   return m ? m[1].trim() : undefined;
@@ -349,8 +371,18 @@ if (event === "spawn") {
     if (!inv?.token || typeof inv.token !== "string") fatal("aw team invite returned no usable token, so no identity could be minted");
     let raw;
     try {
-      raw = parseSecretJson(run(["aw", "team", "join", inv.token, "--name", instance, "--json"], home, 45000, { secrets: [inv.token], secretSafe: true }), "aw team join");
+      // 120 s: a join on a slow or flapping link is slow, not broken; a killed
+      // join that completed server-side is caught below.
+      raw = parseSecretJson(run(["aw", "team", "join", inv.token, "--name", instance, "--json"], home, JOIN_TIMEOUT_MS, { secrets: [inv.token], secretSafe: true }), "aw team join");
     } catch (e) {
+      // The join may have completed after the CLI was killed or reported a
+      // failure: if the home now holds a bound identity, that identity EXISTS
+      // and must be reported so compensation retires it instead of orphaning it.
+      if (joinedLate(home)) {
+        const late = workspaceAliasOf(home);
+        minted = { team, alias: late };
+        fatal(`aw team join was reported failed (${e.message || e}) but the home now holds a bound identity "${late}" on ${team}; reported for compensation so it is retired, not orphaned`, minted);
+      }
       // 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.
@@ -413,7 +445,7 @@ if (event === "spawn") {
     fatal(`identity minting failed: ${e.message || e}`, minted);
   }
 } else if (event === "retire") {
-  const meta = JSON.parse(process.env.OATS_META || "{}");
+  let 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.
@@ -426,6 +458,10 @@ if (event === "spawn") {
   // 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
   // authenticated and the cleanup is incomplete, not vacuous (reviewer-602627c).
+  // A home whose spawn hook could not report its alias (a join killed on
+  // timeout that completed anyway) still carries the alias in its workspace
+  // binding: use it rather than leaving the workspace orphaned.
+  if (!meta.alias) { const late = workspaceAliasOf(home); if (late) meta = { ...meta, alias: late, aliasFromHome: true }; }
   if (!meta.alias) out({ meta: { retired: false, reason: "nothing-to-delete" } });
   if (!existsSync(join(home, ".aw"))) {
     out({ meta: { retired: false, reason: "no-local-identity-key" }, warning: `oats-aweb: alias "${meta.alias}" was minted but ${join(home, ".aw")} is gone, so the remote record cannot be self-deleted and will linger until stale` }, 1);
@@ -433,6 +469,19 @@ if (event === "spawn") {
   try {
     // Self-delete from inside the home, authenticated by its own key — a remote
     // delete would 409 until the server marks the workspace stale.
+    // aw 1.36.1 (aweb-abim) revokes the member's certificate on delete and
+    // says so: `--json` prints alias_released true|false with a reason, and
+    // a released alias may be reused by a later spawn. An older aw cannot
+    // revoke, so the alias stays unusable and the report says that instead.
+    if (awAtLeast("1.36.1")) {
+      const raw = run(["aw", "workspace", "delete", meta.alias, "--json"], home);
+      let doc; try { doc = JSON.parse(raw); } catch { doc = undefined; }
+      const released = doc?.alias_released === true;
+      // aw 1.36.1 prints the cause as alias_released_reason (workspace.go,
+      // workspace_self_retire.go); `reason` is tolerated for a later rename.
+      const reason = typeof doc?.alias_released_reason === "string" ? doc.alias_released_reason : typeof doc?.reason === "string" ? doc.reason : (doc ? "unstated" : "no JSON answer");
+      out({ meta: { retired: true, aliasReusable: released, aliasReason: reason }, ...(released ? {} : { warning: `oats-aweb: workspace "${meta.alias}" deleted but its alias was not released (${reason}); spawn successors with a fresh --purpose until it is` }) });
+    }
     run(["aw", "workspace", "delete", meta.alias], home);
     // Honest: the workspace row is deleted, but a hosted local member cannot
     // revoke its own AWID certificate (aweb-abim), so the alias is NOT

package/capabilities/oats-aweb/oats.json

@@ -1,7 +1,7 @@
 {
   "capability": "oats.aweb",
   "command": "aweb",
-  "version": "1.10.1",
+  "version": "1.10.3",
   "compatibility": {
     "oats": ">=0.22.3"
   },

package/capabilities/oats-okf/agents/memory-harvest/soul.yaml

@@ -2,5 +2,4 @@ name: memory-harvest
 kind: capability
 work: attached
 runtime: pi
-model: github-copilot/gpt-5.5
 description: Ephemeral OKF service agent that promotes one live instance's pending notes into its soul.

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

@@ -52,10 +52,6 @@ catch (e) {
   if (JSON_MODE) jsonFail("E_HARVEST_FAILED", `malformed OATS_SETTINGS: ${e.message || e}`);
   process.stderr.write(`oats-okf: malformed OATS_SETTINGS (ignoring): ${e.message || e}\n`);
 }
-/** Model for the memory-harvest agent — promotion judgment is cheap-but-good
- *  work; default gpt-5.5, overridable via okf settings { "harvest-model": ... }. */
-const DEFAULT_HARVEST_MODEL = "github-copilot/gpt-5.5";
-
 function runtimeError(code, message) {
   return Object.assign(new Error(message), { code });
 }
@@ -148,8 +144,19 @@ function planRecordHarvest(instanceHome) {
   // 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 };
+  const windows = threads.map(({ thread, afterTurnId, untilTurnId }) => ({ thread, afterTurnId, untilTurnId }));
+  let pending;
+  try { pending = JSON.parse(readFileSync(nextPath, "utf8")).pendingHarvest; } catch { /* no prior plan */ }
+  const sameWindows = pending?.instance && JSON.stringify(pending.windows) === JSON.stringify(windows);
+  const warnings = sameWindows ? [
+    `previous harvester ${pending.instance} did not advance the watermark for ${windows.map((w) => `${w.thread} (${w.afterTurnId || "start"} -> ${w.untilTurnId})`).join(", ")}; inspect its outcome and use oats okf harvest --from-record --force to retry`,
+  ] : [];
+  // Reuse the existing prepared watermark; no extra journal. Stamp it only
+  // after a successful spawn, and never overwrite a stalled plan on a skip.
+  if (sameWindows && !process.argv.includes("--force")) return { stalled: true, warnings };
+  const prepared = JSON.stringify(next, null, 2) + "\n";
+  writeFileSync(nextPath, prepared);
+  return { threads, windows, watermarkPath, nextPath, watermark: next, prepared, unattributed: (report.unattributed || []).length, problems, warnings };
 }
 
 /** Briefing block for record-fed candidates, appended to the harvest task. */
@@ -198,11 +205,27 @@ async function spawnHarvester(spawnArgs, task) {
   }
 }
 
-function harvestSpawnArgs({ slug, parent, repo, work, workDir, branch, model }) {
-  const args = ["--purpose", slug, "--parent", parent, "--repo", repo, "--work", work];
+function harvestRuntime() {
+  const runtime = settings["harvest-runtime"] ?? "pi";
+  if (!["pi", "claude", "codex"].includes(runtime)) {
+    throw runtimeError("E_HARVEST_SETTINGS", "harvest-runtime must be pi, claude or codex");
+  }
+  const configured = settings["harvest-model"];
+  if (configured != null && (typeof configured !== "string" || !configured.trim())) {
+    throw runtimeError("E_HARVEST_SETTINGS", "harvest-model must be a nonempty model name");
+  }
+  const model = configured?.trim() || undefined;
+  if (runtime !== "pi" && model?.includes("/")) {
+    throw runtimeError("E_HARVEST_SETTINGS", `harvest-model for ${runtime} must be a native model name, without a Pi provider/ prefix`);
+  }
+  return { runtime, model };
+}
+
+function harvestSpawnArgs({ slug, parent, repo, work, workDir, branch, runtime, model }) {
+  const args = ["--purpose", slug, "--parent", parent, "--repo", repo, "--work", work, "--runtime", runtime];
   if (workDir) args.push("--work-dir", workDir);
   if (branch) args.push("--branch", branch);
-  args.push("--model", model);
+  if (model) args.push("--model", model);
   return args;
 }
 
@@ -331,7 +354,7 @@ _(the single next action — keep this current; a fresh session on any model res
       }
     }
     const notesDir = join(home, "notes");
-    const skip = (why) => (JSON_MODE ? jsonOk({ harvest: "skipped", reason: why }) : out({ meta: { harvestSpawn: "skipped", why } }));
+    const skip = (why, warnings = []) => (JSON_MODE ? jsonOk({ harvest: "skipped", reason: why, ...(warnings.length ? { warnings } : {}) }) : out({ meta: { harvestSpawn: "skipped", why }, ...(warnings.length ? { warnings } : {}) }));
     if (String(agName).startsWith("memory-harvest")) skip("self (loop guard)");
     const notes = existsSync(notesDir) ? readdirSync(notesDir).filter((f) => f.endsWith(".md")) : [];
 
@@ -358,6 +381,7 @@ _(the single next action — keep this current; a fresh session on any model res
     // 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.
+    const execution = harvestRuntime();
     let recordPlan = null;
     if (notes.length === 0 || process.argv.includes("--from-record")) {
       let planned = null;
@@ -366,13 +390,14 @@ _(the single next action — keep this current; a fresh session on any model res
         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 warning of recordPlan?.warnings || []) process.stderr.write(`oats-okf: record: ${warning}\n`);
+      if (recordPlan?.stalled) skip("previous harvester did not advance the watermark", recordPlan.warnings);
       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;
     const workDir = realpathSync(join(home, "work"));
     const realSoul = realpathSync(sDir);
     const harvName = `memory-harvest-${slug}`;
@@ -386,7 +411,7 @@ _(the single next action — keep this current; a fresh session on any model res
       // 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: ${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,
+        slug, parent: inst, repo: context, work: "attached", workDir, ...execution,
       }), task);
     } else if ((process.env.OATS_WORK || meta.work) === "workspace") {
       // WORKSPACE-MODE instance: ./work is the whole workspace, not a git repo —
@@ -399,7 +424,7 @@ _(the single next action — keep this current; a fresh session on any model res
       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,
+        branch: `memory-harvest/${slug}`, ...execution,
       }), task);
     } else {
       // Repo-resident souls: write to the soul AS SEEN FROM THE WORK TREE, so the
@@ -410,11 +435,27 @@ _(the single next action — keep this current; a fresh session on any model res
         : realSoul;
       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,
+        slug, parent: inst, repo: context, work: "attached", workDir, ...execution,
       }), task);
     }
-    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 } });
+    if (recordPlan) {
+      try {
+        // A fast harvester may already have renamed the prepared file. Never
+        // recreate that consumed plan or replace a different plan's contents.
+        if (readFileSync(recordPlan.nextPath, "utf8") === recordPlan.prepared) {
+          writeFileSync(recordPlan.nextPath, JSON.stringify({ ...recordPlan.watermark, pendingHarvest: { instance: r.instance, windows: recordPlan.windows } }, null, 2) + "\n");
+        }
+      } catch (e) {
+        if (e.code !== "ENOENT") {
+          const warning = `harvester ${r.instance} spawned but its retry marker could not be recorded: ${e.message}`;
+          recordPlan.warnings.push(warning);
+          process.stderr.write(`oats-okf: ${warning}\n`);
+        }
+      }
+    }
+    const warnings = recordPlan?.warnings?.length ? { warnings: recordPlan.warnings } : {};
+    if (JSON_MODE) jsonOk({ harvest: "spawned", instance: r.instance, window: r.tmux?.window || null, ...warnings, ...(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 }, ...warnings });
   } catch (e) {
     if (JSON_MODE) jsonFail(e.code || "E_HARVEST_FAILED", `harvest spawn failed (notes are safe on disk): ${e.message || e}`);
     warn(`harvest spawn failed (notes are safe on disk): ${e.message || e}`);

package/capabilities/oats-okf/oats.json

@@ -1,11 +1,21 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "1.5.0",
-  "compatibility": { "oats": ">=0.22.2" },
+  "version": "1.5.1",
+  "compatibility": { "oats": ">=0.22.3" },
   "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": [],
+  "settings": {
+    "harvest-runtime": {
+      "default": "pi",
+      "values": ["pi", "claude", "codex"],
+      "description": "Harness for the memory harvester, independent of the source instance's runtime."
+    },
+    "harvest-model": {
+      "description": "Optional model pin for the selected harvest runtime, for example to use a cheaper model: a Pi provider/model or a native Claude/Codex model. When omitted, each harness uses its configured default."
+    }
+  },
   "agents": [
     "agents/memory-harvest"
   ],

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

@@ -92,6 +92,9 @@ is how what they learned reaches the soul.
   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.
+- Never promote a secret or credential, however it appears in the record.
+- Never promote third-party message content verbatim. A lesson may be about a
+  received message; unverified sender content is not soul knowledge by transcription.
 - 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

package/docs/integrations.md

@@ -140,6 +140,53 @@ Test an integration as a capability package: acquire, lock, trust, activate,
 spawn, retire, with the golden fixtures as the behavior oracle for the kernel
 side.
 
+## oats.okf harvest settings (1.5.1)
+
+The harvester can use a different harness from the source instance. Select one
+that is installed and authenticated on the host where the harvest runs:
+
+```bash
+oats use oats.okf --settings harvest-runtime=claude
+```
+
+- `harvest-runtime: pi | claude | codex` defaults to `pi`.
+- `harvest-model` is an optional pin, for example to use a cheaper model.
+  When omitted, each harness uses its configured default. Pi accepts
+  provider/model patterns. Claude and Codex require a native model name
+  (for example `sonnet` or `gpt-5.5`), without a Pi provider prefix.
+
+These settings apply to note and record harvests, including deferred retirement
+and remote harvests. For a remote instance, configure its host's knowledge
+binding; the local viewer does not supply its own provider credentials.
+
+If a record harvester was spawned but did not advance its watermark, planning
+the same windows again warns with that instance and the boundary IDs and skips
+another spawn. Inspect the previous attempt first. `oats okf harvest
+--from-record --force` retries those windows explicitly; it still refuses to
+start a second harvester while the first one's home exists. The check uses the
+existing prepared watermark file and does not treat a successful spawn as
+completed learning.
+
+## oats.aweb late joins (1.10.3)
+
+`aw team join` at spawn gets 120 s (a slow link is slow, not broken). If the
+join is reported failed or is killed on timeout but the home then holds a
+bound identity (signing key, team certificate, workspace alias), the hook
+reports that alias in its meta so the kernel's compensation retires it
+instead of orphaning it. The retire hook likewise reads the alias from the
+home's `.aw/workspace.yaml` when its meta carries none.
+
+## oats.aweb retire report (1.10.2)
+
+On a host whose installed `aw` is 1.36.1 or later, the retire hook deletes
+the workspace with `aw workspace delete <alias> --json` and reports what the
+platform answered: `meta.aliasReusable` is true when `alias_released` is
+true (the certificate was revoked and a later spawn may reuse the slug),
+false otherwise with `meta.aliasReason` carrying the platform's reason and a
+warning naming the fresh-purpose remedy. On an older `aw` the pre-1.36.1
+report stands (`aliasReusable: false`, warning naming aweb-abim), because
+that CLI cannot revoke the certificate.
+
 ## oats.aweb settings (1.10.0)
 
 Set with `oats use oats.aweb --settings <key>=<value>` at a scope, or per

package/docs/operating-team-migration.md

@@ -1,6 +1,6 @@
 # Full operating-team migration
 
-Planning record, 2026-09-05. Juan asked lead to discuss the migration with
+Operating record, updated 2026-09-06. Juan asked lead to discuss the migration with
 Merlin and plan for all teams on this machine to be managed by OATS, with
 harvesting fully working. This expands the earlier release/configuration
 rollout. It does not describe an already completed migration.
@@ -9,7 +9,9 @@ The cjr runbook is owned by Merlin at
 `~/cjr/agents/docs/2026-09-05-oats-migration.md`. This document records the
 shared framework work and the wider rollout.
 
-Fresh identities are authorized for specialists and reviewers. Merlin retains
+Fresh identities are authorized for continuing seats as well as specialists and
+reviewers. Preserve the accepted retained-identity choice where it is useful.
+Merlin retains
 both `cjr.aweb.ai/merlin` and his existing durable DID. Aweb clarified that
 re-minting the same address changes identity and breaks continuity; the supported
 path is an explicit transfer of his existing authority with one live process.
@@ -31,21 +33,75 @@ Every remembering role must have a tested learning path. Preserve each role's
 explicit policy: Cjr reviewers exclude accumulated memory; Themis uses
 reviewed learning. Config discovery alone establishes none of this.
 
-The installed baseline is published OATS 0.22.3 on this Mac and `aweb-agents`,
+The installed CLI baseline is published OATS 0.22.5 on this Mac and `aweb-agents`,
 including native Pi/Claude/Codex, tmux/Herdr, shared `yolo`, remote Desktop
 roster/actions, retained-authority binding and corrected deferred retirement.
-The downloaded Mac Desktop app passed codesign, packaged renderer and PTY
-launch checks. Official oats.okf 1.5.0 provides record-fed harvesting; each
-deployment must select its authenticated provider. Version 1.5.1, adding
-harvest-runtime selection and detection of unadvanced record plans, remains
-under independent review and is not yet published.
-
-No standing seat has transferred yet. Cjr's worker pilot has landed reviewed
-code and knowledge; ordinary retirement passed using the next-patch candidate.
-A real harvester's automatic deferred completion and successor knowledge use
-remain explicit acceptance checks. The reviewed aweb broker candidate passed
-real harness delivery; installation of its published release as the normal
-host service remains a prerequisite for standing cutover.
+The installed Mac Desktop 0.22.5 passed published ZIP checksum, strict deep
+codesign, packaged renderer and PTY launch checks; the previous 0.22.4 app
+is preserved for rollback. Official oats.okf 1.5.1 is published after independent
+review, adding harvest-runtime selection and detection of unadvanced record
+plans. Each deployment selects an authenticated harness; without an explicit
+harvest-model, that harness uses its own configured default. Some prepared
+teams still use the compatible 1.5.0 package; preserve the exact versions of
+each earlier qualification.
+
+BeadHub, Minerva and Merlin now have managed standing executions with retained
+identities. BeadHub and Minerva passed separate mail/chat checks; Merlin verified
+his identity and preserved claims, then received and replied to Minerva's real
+mail through the host wake path. This is not completion of all teams: frontend
+and Themis encountered failed setup, Docflow still has a running backfill, and
+the coordinator handovers remain outstanding. See the current status below;
+older evidence records keep the version and outcome of each earlier check.
+
+## Current status and operating limits (2026-09-06)
+
+Juan requires completion without exhausting the machine again. **Do not disturb
+TSM until its deployment is finished.** No TSM runtime, configuration, identity,
+or handover operation is authorized during that boundary. Wait for Zeus's
+explicit deployment-complete report; earlier cutover sequencing below is
+superseded by this condition.
+
+The first broad rollout produced overlapping record-capture processes: each
+could index the large local store, with individual processes exceeding 2 GB
+RSS. The capture watcher was about 1.7 GB. The experimental mind follow service
+also consumed substantial CPU/memory and launched model runs. These are observed
+contributors, not a complete accounting of the reported GUI memory incident;
+no OATS Desktop process remained when lead took the incident snapshot.
+
+Lead stopped the capture watcher and residual capture passes, disabled their
+exact Claude hooks, and stopped the experimental mind follow service. Settings,
+service definitions, raw records and learning state are preserved. GUI launch
+is paused. Resume with one bounded operation at a time, checking memory between
+launches; declining swap alone does not prove sustained stability. Capture stays
+disabled until its concurrency fix is independently reviewed and measured. The
+first proposed lock was rejected because age-based stealing and initialization
+races could still permit overlapping passes.
+
+| Scope | Verified state | Next boundary |
+| --- | --- | --- |
+| Host services | Published aw 1.36.1 installed; normal launchd wake service on Mac and enabled user service on `aweb-agents`; private broker stopped | Investigate repeated reconnect hints and reported read timing without assuming the broker acknowledged mail |
+| BeadHub | `beadhub-seat`, retained DID/address and claims; native Codex; independent mail/chat; first reviewed knowledge PR merged at `70c839e` | Repeat harvest exposed a retained merged-branch collision; operator updated the linked soul and removed only the verified merged branch; next cycle waits for a bounded launch slot |
+| Cjr | `accountant-minerva` and `coordinator-merlin` live on retained identities; old holders stopped first; claims preserved; real delivery and reviewed learning recorded | Complete the existing log worker's fresh review, one reviewer at a time; no financial authority changes |
+| Aweb | Coordinator remains live; old frontend stopped; replacement failed during a timed-out join that completed server-side | Supported cleanup of the retained failed home/orphan binding, then one successor with independent delivery checks |
+| TSM | Prepared souls and owner checkpoints; Themis setup failed before the current hold | **No migration work until Zeus reports deployment finished**; re-inventory with its owner afterwards |
+| Docflow | Legacy seat and actual mail backfill remain running | Finish backfill and register checks; owner restores mail-ingest afterwards; accountant-sync remains unloaded under its separate export fence |
+| Oats/lead | Existing coordinators remain active | Last handovers, with actual stop receipts and all unresolved work carried forward |
+| Remote qualification | Published host service delivered native Claude mail/chat through Herdr; corrected knowledge independently reviewed; source retired with `aliasReusable: true` | Earlier separate fresh-reader cycle passed; latest corrected wake-specific retrieval is still pending |
+
+Published aw 1.36.1 is tagged at `bfdb20886080e4ffe1f02b266f6116d12bd100fd`.
+All 46 release targets have passing results for that source: targets 1–41 in
+one run, followed by an explicitly accepted continuation of 42–46 after a Go
+download failure. This was not one atomic run. Evidence is archived under
+`~/awebai/bookshelf/records/2026-09-05-aw-1.36.1-split-gate/`.
+Production same-alias join/delete/rejoin passed, and official oats.aweb 1.10.2
+reports the released alias result truthfully. Retained standing-seat retirement
+must still preserve authority.
+
+Desktop 0.22.5 has six validated team roots saved as workspace suggestions,
+not six running GUI instances. It starts with one workspace and can add others.
+It is currently closed; visual QA and sustained multi-workspace memory behavior
+are not claimed. Native remote Pi authentication and remote Codex remain
+unqualified; the accepted remote harness is Claude.
 
 ## Scope inventory
 
@@ -55,17 +111,17 @@ of continuing seats.
 
 | Scope | Starting point | Required disposition |
 | --- | --- | --- |
-| `~/awebai/oats` | Live Claude coordinator and Codex lead; managed review workers also running | Oats owns coordinator handover; lead owns lead handover; preserve established identities |
-| `~/cjr` | Preparation `5afb3e8b`; developer pilot landed on master `062e2c75`; legacy Merlin and Minerva live | Merlin owns safe handovers; preserve his DID/address; prove automatic harvest completion and successor use |
-| `~/awebai/aweb` | Live Claude coordinator and frontend in legacy homes | Oats owns coordinator handover; lead coordinates frontend with aweb after its current work; preserve identities and cover child repositories |
-| `~/tsm` | Five live seats: Zeus, Prometeo, Argos, Themis on Claude; Hermes on Codex. First-seat Themis config/soul packet under owner review | Zeus prepared the five-seat handover plan; begin with Themis at a safe boundary, Zeus last; preserve session-local schedules and production authority |
+| `~/awebai/oats` | Live Claude coordinator and Codex lead; managed review workers also running | Oats owns coordinator handover; lead owns lead handover; follow the explicit fresh or retained identity choice |
+| `~/cjr` | Preparation `5afb3e8b`; developer pilot landed on master `062e2c75`; legacy Merlin and Minerva live | Merlin owns safe handovers; preserve his DID/address; automatic harvest completion and successor use are proven; prepare standing seats |
+| `~/awebai/aweb` | Live Claude coordinator and frontend in legacy homes | Oats owns coordinator handover; lead coordinates frontend with aweb after its current work; handover task responsibility and cover child repositories |
+| `~/tsm` | Five live seats: Zeus, Prometeo, Argos, Themis on Claude; Hermes on Codex. All five souls integrated, official capabilities installed and trusted, owner checkpoints prepared | Paused by Juan until deployment complete; owner rechecks all seats afterwards; preserve schedules and production authority |
 | `~/prj/beadhub-all` | Live Codex session, despite stale offline roster | Beadhub accepted preparation and is at a safe boundary; retain its global identity, native Codex and separate canonical code roots under `~/awebai/beadhub`; billing remains separately gated |
 | `~/prj/docflow` | Live Claude seat identified itself as local `juan.aweb.ai/alice` on `docflow:juan.aweb.ai` | Owner Juan; finish running mail backfill and register checks before transfer; retain identity, memory and Minerva route; accountant-sync remains deliberately unloaded |
 | `ai.aweb` on `aweb-agents` | Aweb confirms Athena intentionally inactive; remote legacy home retained | Aweb and oats own archival inspection; do not resurrect as a continuing seat |
 | `~/awebai/demo-aweb/bob` | Live Pi demo | Aweb owns safe stop and archival disposition; it is not an operating-team migration |
-| `~/.turn-record` | Live Pi capture service under launchd | Retain as infrastructure; qualify record capture separately from standing seats |
+| `~/.turn-record` | Capture and experimental mind services paused after memory incident | Preserve records; review and measure resource fixes before resuming |
 
-The live inventory above was checked on 2026-09-05 using harness process
+The starting inventory above was checked on 2026-09-05 using harness process
 working directories and exact custom tmux sockets, without interrupting them.
 TSM uses its aweb tmux socket, BeadHub the awebai socket, and Docflow the
 main socket. Lead delivered explicitly attributed coordination messages to
@@ -138,17 +194,18 @@ stops the runtime before releasing capabilities; status remains read-only.
 Cjr archived its local harvester override and uses official oats.okf 1.5.0.
 Its authenticated Pi model is `openai-codex/gpt-5.5`. The remote qualification
 host's equivalent provider login fails refresh with `invalid_refresh_token`;
-spawning that harvester is not successful learning. Both failed test sessions
-were retired normally. Do not copy rotating login tokens from another host.
-An explicit `harvest-runtime` setting is planned in oats.okf 1.5.1 so an
-already authenticated Claude or Codex runtime can do the same work.
+both failed Pi tests were retired normally. No rotating login tokens were copied.
+Official oats.okf 1.5.1 now selects the already authenticated native Claude
+runtime on that host. A real note-fed harvest promoted an operational lesson,
+self-retired, and a fresh successor retrieved and used the lesson. This proves
+that alternative harness path; it does not claim the Pi login was repaired.
 
 ### Finish temporary identity retirement
 
 The aweb owner must resolve the remote lifecycle defect tracked under
 `aweb-aaum.6`; oats coordinates package integration. The leaked release identities are a reproduction; reconcile the exact
 owner-side list before naming or deleting them. Alias-release fixes are in
-aweb source; production same-alias join/delete/rejoin acceptance is pending. Independently verify coordination cleanup,
+aweb source; production same-alias join/delete/rejoin acceptance passed on published aw 1.36.1. Independently verify coordination cleanup,
 claims and certificate state. Admin cleanup is a recovery procedure, not
 proof of automatic retirement. This gates temporary-worker completion;
 adopted standing executions instead must preserve their durable identity.
@@ -240,7 +297,7 @@ substitute a green `doctor`, a roster row or a successful hook report for
 the corresponding live check. Keep credentials and private case data out of
 the shared rollout record.
 
-## Latest operating evidence (2026-09-05)
+## Earlier operating evidence (2026-09-05)
 
 - Cjr's pilot landed five useful task commits and eleven promoted concepts
   from four harvests, with independent code and knowledge reviews. Ordinary
@@ -253,16 +310,23 @@ the shared rollout record.
 - TSM's owner plan is `~/tsm/history/2026-09-06-tsm-oats-handover-plan.md`.
   Preserve the five seats' worktrees, skills and knowledge; re-arm Zeus's
   session-local schedules. Production credentials remain solely with the
-  authorized production operator. His plan reserves Zeus's final cutover
-  for Juan's presence; the other seats can prepare in the meantime.
+  authorized production operator. Zeus remains last. Juan's current direction
+  authorizes completing the migration while he is away; the earlier
+  presence-only pause does not override it. Actual job and production boundaries
+  remain. Themis's ten-commit packet landed at `46cf2083`; its installed
+  oats.aweb 1.10.1 and oats.okf 1.5.0 passed the actual doctor. All five souls
+  are now integrated through Prometeo's `103e534c`, with owner-approved private
+  startup briefs and checkpoints. Those checkpoints must be refreshed at the
+  actual stop; Zeus's deployment and scheduled-job boundaries remain binding.
 - BeadHub configuration/soul commit `3ee13a8` in `awebai/beadhub-saas`
   (`~/awebai/beadhub/beadhub-saas`) was independently ACKed by lead and
   landed on `main`. Its tracked deployment template is materialized at the canonical
   parent workspace, with trusted official capabilities and a clean actual
   doctor result. The soul retains SaaS Git provenance and uses workspace mode
   as a coordinator across the three canonical repositories. Its legacy holder
-  remains live; authenticated harvest-model configuration and the published
-  broker service precede activation. Stripe and production gates remain separate.
+  remains live; authenticated harvest-model configuration is installed and
+  verified. The published broker service precedes activation. Stripe and
+  production gates remain separate.
 - Docflow supplied its own identity and handover through its terminal. Its
   backfill and register verification define the safe boundary. Preserve its
   Claude memory and existing credentials in place; verify filesystem/TCC
@@ -276,9 +340,9 @@ the shared rollout record.
   relying on those routes; do not silently replace retained identities.
 - Real remote Claude launch, terminal input and detach survival passed.
   Remote Desktop projection and exact-home lifecycle shipped in 0.22.3; the
-  installed remote CLI serves the real registered roster. Remote harvester
-  completion remains blocked by provider authentication, and no standing
-  remote seat is declared migrated.
+  installed remote CLI serves the real registered roster. Native Claude
+  harvesting subsequently completed with official oats.okf 1.5.1, as recorded
+  below. No standing remote seat is declared migrated.
 - The aweb broker candidate `30469e22` ran as a private launchd service against
   published OATS 0.22.3. Real Claude and Codex sessions in tmux and Pi
   in Herdr, with Claude channel 1.7.9 and Pi extension 0.3.10, fetched mail and replied with exact qualification tokens,
@@ -291,7 +355,89 @@ the shared rollout record.
   Published aw installation and standing-seat acceptance are still separate.
 - Qualification found that tmux output loses tab separators in a minimal
   launchd environment without a UTF-8 locale. Independently reviewed kernel
-  fix `a0b0e14` adds tmux UTF-8 mode; until it ships, the host service specifies
+  fixes `a0b0e14` and `0260ea9` shipped in 0.22.4, adding UTF-8 mode to
+  lifecycle/input and viewer calls. The host service also specifies
   `LC_ALL=en_US.UTF-8`. Existing Claude plugin 1.7.8 also consumed mail before
   the broker wake; updating to 1.7.9 eliminated that competing delivery path.
   The deployed oats.aweb 1.10.1 floor now rejects the incompatible version.
+
+- Cjr's second and third worker cycles completed on published kernel 0.22.3
+  and oats.okf 1.4.1 (note-fed). The
+  second promoted three reviewed concepts; the third read them before working,
+  produced the normal host-service health reader (`3dfe3acf`) and completed
+  its own reviewed harvest. Both harvesters self-retired without operator
+  completion. Each worker's ordinary retirement took four seconds and removed
+  its temporary alias. A post-merge fixture mismatch was corrected forward in
+  `e8a87c71`, with 47 tests green on a clean export. The reader's real service
+  check awaits installation of `ai.aweb.wake`.
+- A record-only harvest of the fresh Claude wake-test session completed with
+  official oats.okf 1.5.0. It read its 27-turn source window, found no durable
+  lesson to promote, advanced the completed watermark and self-retired. The
+  first attempt exposed an unnecessary SQLite index write during pure journal
+  reads; reviewed fix `f100320` shipped in 0.22.4. The shared capture service
+  and its large index were preserved. Completion is proven; this run does not
+  claim a knowledge promotion.
+- Docflow's two-commit preparation at `4458097` is independently ACKed: native
+  Claude, retained authority, session delivery and 18 valid curated OKF concepts.
+  Its role and package preparation is integrated. The running backfill
+  and FY2025 register checks still determine its activation boundary.
+- The tracked aweb coordinator soul at `0a3a9a91` is independently ACKed; the
+  frontend soul at `b3985edb` is owner-reviewed and landed. They preserve the
+  coordinator's workspace and the frontend's managed primary SaaS worktree plus
+  explicitly assigned secondary OSS tree. Lead and Oats coordinator souls are
+  also reviewed and landed. Concrete deployment configuration and final
+  checkpoints precede each launch.
+- OATS 0.22.4 is published at tag `0260ea9`, with npm packages and six Desktop
+  installers. CI retried once after a disappearing Git maintenance lock in a
+  fixture; kernel and Desktop gates then passed. A manual reviewed version-bump
+  PR completed the bot's permission-blocked post-publication step. Published
+  npm JavaScript bytes match the tag. OATS 0.22.5 subsequently shipped the
+  package-selector CLI and oats.okf 1.5.1 pin; its manual version-bump PR #5
+  completed at `91ef541`. Aweb 1.36.1 remains unpublished: candidate `bfdb2088`
+  passed targets 1–41, then a Go dependency download failed in target 42.
+  Its coordinator explicitly accepted completing targets 42–46 on that same
+  candidate and environment, preserving both logs and recording the loss of
+  single-run atomicity. The remainder is running; the private broker is not
+  being represented as the permanent published service.
+
+- Cjr's retained declaration/runbook packet is independently ACKed through
+  `6dc6efc8` (three commits); its source authority remains in place and operator
+  stop-before-start applies to rollback as well as cutover. Its two soul startup
+  corrections also landed after independent review at `bd981b3a`. Official
+  oats.aweb 1.10.1 and oats.okf 1.5.0 are now installed and trusted for both
+  standing souls. These newer pins do not relabel the earlier worker proofs.
+- TSM's Argos packet is integrated at `f20c54bb` after both independent and
+  owner ACKs; actual doctor resolves the two retained reviewer seats. BeadHub
+  and Themis supplied final private startup briefings and idle checkpoints.
+  Hermes and Prometeo were explicitly woken to read unseen followups; their
+  legacy channels had not delivered those requests reliably. Both subsequently
+  approved their souls and final handover checkpoints.
+- A locked-selector update gap found during actual team setup was corrected
+  at `d95018e` (two independently reviewed commits) and shipped in 0.22.5.
+  It supports `oats update <package> --to <ref>` or a positional catalog
+  spec. A hermetic CLI test exercises the version transition, trust reset and
+  invalid arguments, including refusal to enter the kernel self-updater when
+  a package is missing. The installed remote 0.22.5 CLI accepted the selector
+  and preserved the already-correct 1.5.1 lock and its trust.
+
+- Herdr 0.8.2 is installed on both hosts. Published OATS 0.22.4 launched a
+  real remote Claude session through the saved server route; a separate
+  session-input request elicited an actual reply. The source and its successor
+  then completed native Claude harvesting and knowledge use with official OKF
+  1.5.1. The harvester consumed its source note, promoted one PATH-resolution
+  lesson, passed strict validation, and self-retired. A fresh instance read the
+  indexed lesson before checking every resolved tool path and comparing runtime
+  and login shells. Both source instances were retired normally with their
+  changed home files preserved. This is local-soul promotion and retrieval,
+  not a repository PR cycle or remote broker-wake acceptance.
+- The remote host now has shared `yolo: true`, updated Pi installations,
+  Claude channel 1.7.9, and the published OATS 0.22.5 capture hooks and enabled
+  user service. Its existing record-owner name was preserved and the initial
+  capture/index pass completed. The Mac capture service was left in place.
+- Coordinator scope is explicit: Oats and Aweb retain their global identities
+  through the rehearsed authority-transfer path. Fresh local lead/frontend
+  identities relay cross-team requests through a verified global coordinator;
+  an alias containing a domain does not itself establish global reach. The
+  final briefs preserve conversations or hand off unresolved threads according
+  to that identity choice, require an actual old-process stop, and distinguish
+  startup context from a separate incoming-message wake check.

package/docs/packages.md

@@ -30,7 +30,11 @@ default. Only the selected subtree is installed and hashed, so repository docs,
 CI configuration, owner souls, and sibling packages stay outside the package's
 payload and integrity. One repository may ship several packages at different
 paths. The lock pins the selected root in its own `path` field, and only an
-explicit `oats update <package>` may move it. See
+explicit `oats update <package>` may move it. A catalog lock with an explicit
+selector (`catalog:oats.aweb@v1.8.0`) keeps that selector on a plain update;
+to advance it to another published ref, give the spec or `--to`:
+`oats update oats.aweb oats.aweb@v1.10.1` or `oats update oats.aweb --to v1.10.1`
+(same transactional path, approvals invalidated, then `oats trust`). See
 [`design/package-engine-contract.md` §1.1](design/package-engine-contract.md).
 
 Ground truth for the contract: [`oats-package.schema.json`](oats-package.schema.json),

package/docs/release-notes/v0.22.5.md

@@ -0,0 +1,36 @@
+# OATS v0.22.5
+
+A small release: the knowledge package 1.5.1 pin, a way to move a pinned
+package lock from the CLI, and the operating records from the first team
+rollouts.
+
+## Bundled: oats.okf 1.5.1
+
+`harvest-runtime` chooses the harness that runs the memory harvester (pi,
+claude or codex; default pi), so a host authenticated for one harness need
+not authenticate another. No harness gets a vendor default: with no
+`harvest-model` set, the harvester inherits the harness's own configured
+model; `harvest-model` remains the way to pin a cheaper one. The promotion
+instructions exclude secrets, credentials and verbatim third-party message
+content from promotion. `okf harvest` warns instead of respawning when a
+plan's window boundaries did not move since the previous harvester was
+spawned.
+
+## Move a pinned package lock
+
+`oats update <package> <package>@<ref>` or `oats update <package> --to <ref>`
+moves a catalog-sourced lock to another published ref through the same
+transactional update (closure validation, lock replace, approvals
+invalidated, then `oats trust`). A plain `oats update <package>` keeps an
+explicit selector, as before, and `--to` without a package is refused rather
+than falling through to the kernel self-update (`oats update` with no
+package).
+
+## Also
+
+- The managed oats coordinator soul (`agents/oats-coordinator/soul`) is
+  tracked, with playbooks for the release lane, payload publication and
+  review routing.
+- `docs/operating-team-migration.md` records the installed 0.22.4 rollout,
+  the completed record-fed and note-fed harvest cycles, and the standing
+  seats prepared for cutover.

package/docs/release-notes/v0.22.6.md

@@ -0,0 +1,53 @@
+# OATS v0.22.6
+
+A resource-safety patch after the first full team rollout exhausted the
+machine: record capture runs one pass per root, the Desktop app runs once,
+and `--help` never executes a command. Plus the oats.aweb 1.10.3 pin.
+
+## Record capture: one pass per root
+
+Hook-triggered capture passes, one per agent event across every live agent,
+used to overlap, each opening the multi-gigabyte search index. A capture pass
+now takes a per-root lock directory (`<root>/.capture.lock`). A second pass
+finding it skips at once and the next pass catches up, since reconciliation
+is idempotent. The lock is never stolen: a live, dead, unknowable or
+still-initializing holder all refuse the pass, and the refusal names the
+holder's pid, start time and liveness together with the exact operator
+recovery (verify the pid is gone, remove the lock directory with the printed
+shell-safe command, rerun). A killed pass therefore needs one explicit
+cleanup, which is the accepted trade against any automatic reclaim protocol.
+
+An indexing-enabled pass reconciles the index even when it appended nothing,
+so turns left by append-only passes (`--sessions-only --no-index --quiet`,
+the recommended hook form from `capture --install-hint`) become searchable at
+the next plain pass.
+
+## Desktop runs once
+
+A repeated launch of OATS Desktop no longer starts a second backend, viewer
+set and window. The secondary process exits before any startup work, and the
+running app restores and focuses its existing window (waiting for its own
+startup to finish first). Switching workspaces stays with the validated
+switcher inside the running window.
+
+## `--help` never executes
+
+`oats <command> --help` (and `-h`) prints usage for every kernel builtin and,
+for capability commands, answers from the manifest without running the
+capability executable. Previously several commands ran with `--help` as an
+argument.
+
+## Bundled: oats.aweb 1.10.3
+
+The join wait after spawn is 120 s (`OATS_AWEB_JOIN_TIMEOUT_MS`), a join that
+completes server-side after the client timed out is recovered instead of
+leaving a bound alias behind, retirement reads the alias from the home's
+`.aw/workspace.yaml`, and on aw 1.36.1 `aliasReusable` reflects the server's
+`alias_released_reason` truthfully (1.10.2).
+
+## Also
+
+- `oats use` from no binding writes a targeted binding with `global: false`.
+- `docs/operating-team-migration.md` records the live rollout, the memory
+  incident and its mitigation, the serial launch constraint and the TSM
+  deployment hold.

package/lib/core.mjs

@@ -3343,6 +3343,8 @@ export function updatePackage(startDir, packageId, opts = {}) {
   // the user's own selection, so it is re-appended and stays sticky across
   // updates; a catalog entry OWNS its path, so an update deliberately re-reads it
   // and may adopt a moved root (reported below).
+  if (opts.spec && src.kind !== "catalog") throw oatsError("invalid-source", `package "${packageId}" is locked from a ${src.kind} source; a selector (--to) applies to catalog-sourced packages only (its source is ${entry.source})`);
+  if (opts.spec && parsePackageSource(opts.spec).id !== src.id) throw oatsError("invalid-source", `selector spec "${opts.spec}" names a different catalog package than the lock's ${src.id}`);
   const spec = opts.spec || (src.kind === "catalog" ? (src.selector ? `${src.id}@${src.selector}` : src.id)
     : src.kind === "git" ? `${src.ref && !/^[0-9a-f]{40}$/.test(src.ref) ? `${src.url}@${src.ref}` : src.url}#${entry.path}`
       : src.path);

package/package-catalog.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.22.4",
+  "version": "0.22.6",
   "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

@@ -24,6 +24,7 @@ import { SESSION_FORMATS } from "../lib/formats.mjs";
 import { captureAwLogs, defaultCommLogDir } from "../lib/capture-aw.mjs";
 import { RecordIndex } from "../lib/index-db.mjs";
 import { IgnoreError, ignoreFilePath, loadIgnore } from "../lib/ignore.mjs";
+import { acquireCaptureLock } from "../lib/capture-lock.mjs";
 
 // Fail closed but actionably: an unreadable ignore file must stop capture,
 // as one clear line naming the file — never an uncaught stack trace.
@@ -157,7 +158,23 @@ function log(...parts) {
   if (!quiet) console.log(...parts);
 }
 
+/** Take the root's single-run lock, or say who holds it. A hook-triggered
+ *  pass that finds it held exits 0: the holder's pass, or the next one,
+ *  reconciles the same sessions. */
+function withCaptureLock(fn) {
+  const lock = acquireCaptureLock(root);
+  if (lock.held) {
+    // Never quiet: a stale lock after a killed pass needs the operator, and
+    // the line says exactly what to check and what to remove.
+    const line = `capture: another pass holds ${root}: ${lock.held.recovery}; skipping this pass`;
+    if (lock.held.liveness === "alive") log(line); else console.error(line);
+    return { appended: 0, skipped: true };
+  }
+  try { return fn(); } finally { lock.release(); }
+}
+
 function pass() {
+  return withCaptureLock(() => {
   const out = { appended: 0 };
   const ignore = loadIgnoreOrExit(root);
   if (!args["aw-only"]) {
@@ -192,7 +209,11 @@ function pass() {
     const ignored = awIgnored ? `, ${awIgnored} ignored` : "";
     log(`aw-logs: ${awFiles} files, ${awEntries} entries, ${awAppended} new, ${awFailed} failed${ignored}`);
   }
-  if (out.appended > 0 && !args["no-index"]) {
+  // Index whenever this pass may index, not only when THIS pass appended:
+  // an append-only pass (--no-index, the hook form) leaves turns behind
+  // that the next indexing pass must pick up. index.update() walks
+  // per-stream cursors, so a pass with nothing new is cheap.
+  if (!args["no-index"]) {
     const index = new RecordIndex(store);
     try {
       index.update();
@@ -202,6 +223,7 @@ function pass() {
     }
   }
   return out;
+  });
 }
 
 if (args["install-hint"]) {
@@ -210,12 +232,15 @@ if (args["install-hint"]) {
 
 {
   "hooks": {
-    "Stop":       [{"hooks": [{"type": "command", "command": "node ${self} --sessions-only --quiet"}]}],
-    "SessionEnd": [{"hooks": [{"type": "command", "command": "node ${self} --sessions-only --quiet"}]}]
+    "Stop":       [{"hooks": [{"type": "command", "command": "node ${self} --sessions-only --no-index --quiet"}]}],
+    "SessionEnd": [{"hooks": [{"type": "command", "command": "node ${self} --sessions-only --no-index --quiet"}]}]
   }
 }
 
-A dropped hook is recovered by any later pass (capture, or capture --watch).`);
+Hook passes append turns only (--no-index); the search index is updated by
+capture --watch (every 15 minutes and on change) or by a plain capture pass.
+One pass runs per record root at a time: a hook pass that finds another
+running exits at once, and a dropped hook is recovered by any later pass.`);
   process.exit(0);
 }
 
@@ -245,17 +270,22 @@ if (args.home) {
   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();
+  const homePass = withCaptureLock(() => {
+    let n = 0;
+    for (const { format, dir } of dirs.values()) {
+      n += captureSessions(store, { owner, roots: [dir], format, ignore }).appended;
     }
-  }
+    if (!args["no-index"]) { // same as pass(): an earlier append-only pass may have left unindexed turns
+      const index = new RecordIndex(store);
+      try {
+        index.update();
+      } finally {
+        index.close();
+      }
+    }
+    return { appended: n };
+  });
+  appended = homePass.appended;
   // 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();

package/packages/record/lib/capture-lock.mjs

@@ -0,0 +1,64 @@
+// One capture pass per record root at a time. Hook-triggered passes (one per
+// agent event, across every live agent) used to overlap, each opening the
+// multi-gigabyte search index; a second pass finding the lock exits at once
+// and the next pass catches up, since reconciliation is idempotent.
+//
+// The lock is a DIRECTORY: mkdir is atomic and a directory is never
+// observable half-created. The owner record (pid, start time) is written
+// inside it after the mkdir. Nothing here ever steals a lock: any existing
+// lock, live, dead, unknowable or still initializing, refuses the pass and
+// names the holder and the operator recovery. A stale lock after a killed
+// pass is removed by the operator once the pid is verified gone; the
+// message says exactly that. (A reclaim protocol was reviewed and rejected:
+// rename is not compare-and-swap, and stealing from a stalled live
+// initializer under memory pressure is the failure we are preventing.)
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function captureLockPath(root) { return join(root, ".capture.lock"); }
+
+/** "alive" | "dead" | "unknown" for an owner pid ("unknown" = exists but not signalable). */
+export function holderLiveness(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return "unknown";
+  try { process.kill(pid, 0); return "alive"; } catch (e) { return e.code === "EPERM" ? "unknown" : "dead"; }
+}
+
+function readOwner(dir) {
+  try { return JSON.parse(readFileSync(join(dir, "owner.json"), "utf8")); } catch { return undefined; }
+}
+
+/** Single-quote shell escaping: safe to paste whatever the path contains. */
+export function shellQuote(s) { return "'" + String(s).replace(/'/g, "'\\''") + "'"; }
+
+/** The operator's recovery line for a lock that is not ours. */
+export function recoveryInstruction(dir, owner, liveness) {
+  const remove = `rm -r -- ${shellQuote(dir)}`;
+  if (!owner?.pid) return `${dir} is held by a pass that has not written its owner record yet (initializing, or killed before it could); stop capture triggers (hooks, launchd), verify no capture process is running (pgrep -f capture.mjs), then remove the lock with: ${remove}  and rerun`;
+  const who = `pid ${owner.pid} (started ${owner.startedAt || "?"}, now ${liveness})`;
+  if (liveness === "alive") return `${dir} is held by ${who}; let it finish, the next pass catches up`;
+  return `${dir} is held by ${who}; if that process is gone (ps -p ${owner.pid}), remove the lock with: ${remove}  and rerun`;
+}
+
+/** Try to take the root's capture lock. Returns { path, release } when
+ *  taken, or { path, held: { pid, startedAt, liveness, recovery } } when any
+ *  lock exists. Never removes a lock it did not create. */
+export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, liveness = holderLiveness } = {}) {
+  const dir = captureLockPath(root);
+  mkdirSync(root, { recursive: true }); // the store creates the root lazily; the lock may come first
+  try {
+    mkdirSync(dir);
+  } catch (e) {
+    if (e.code !== "EEXIST") throw e;
+    const owner = readOwner(dir);
+    const live = owner ? (owner.pid === pid ? "alive" : liveness(owner.pid)) : "unknown";
+    return { path: dir, held: { pid: owner?.pid, startedAt: owner?.startedAt, liveness: live, recovery: recoveryInstruction(dir, owner, live) } };
+  }
+  writeFileSync(join(dir, "owner.json"), JSON.stringify({ pid, startedAt: new Date(now()).toISOString() }));
+  return {
+    path: dir,
+    release: () => {
+      const cur = readOwner(dir);
+      if (cur && cur.pid === pid) { try { rmSync(dir, { recursive: true, force: true }); } catch { /* already gone */ } }
+    },
+  };
+}