@awebai/oats 0.22.5 → 0.22.7

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
@@ -2957,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).
@@ -3391,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") {
@@ -3435,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
@@ -3588,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/docs/integrations.md

@@ -167,6 +167,26 @@ 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.
@@ -33,24 +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 CLI baseline is published OATS 0.22.4 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 installed Mac Desktop 0.22.4 passed published ZIP checksum, strict deep
-codesign, packaged renderer and PTY launch checks; the previous 0.22.3 app
-is preserved for rollback. 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 workers have landed reviewed
-code and knowledge. Two ordinary cycles on published 0.22.3 completed automatic
-harvester retirement, independent knowledge review, integration and home-only
-worker retirement. A successor read promoted indexed knowledge at startup and
-identified how it shaped its implementation; both acceptance checks passed.
-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
 
@@ -63,14 +114,14 @@ of continuing seats.
 | `~/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. Themis and Argos config/souls integrated, official capabilities installed and trusted | Zeus prepared the five-seat handover plan; begin with Themis at a safe boundary, Zeus last; preserve session-local schedules and production authority |
+| `~/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
@@ -143,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.
@@ -245,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
@@ -262,8 +314,10 @@ the shared rollout record.
   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. The other three
-  specialist briefs are being prepared at their work checkpoints.
+  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
@@ -286,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,
@@ -325,7 +379,7 @@ the shared rollout record.
   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 owner is integrating and acquiring official packages. The running backfill
+  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
@@ -337,8 +391,13 @@ the shared rollout record.
   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. Aweb 1.36.1 publication is still pending
-  a gateway build dependency download; the private candidate broker is not
+  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
@@ -350,12 +409,35 @@ the shared rollout record.
 - 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 and prepare
-  their continuation briefs; their legacy channels had not delivered those
-  requests reliably.
-- A locked-selector update gap found during actual team setup is corrected
-  on main at `d95018e` (two independently reviewed commits). The next kernel
-  patch supports `oats update <package> --to <ref>` or a positional catalog
+  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. This change is not yet part of installed 0.22.4.
+  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/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/docs/release-notes/v0.22.7.md

@@ -0,0 +1,33 @@
+# OATS v0.22.7
+
+Two resource fixes: index reconciliation streams journals instead of
+reading each one whole, so a full capture pass fits in memory on a store
+with very large session journals, and the packaged Desktop backend runs as
+Node rather than a second Electron runtime.
+
+## Record index: streamed reconciliation
+
+`RecordIndex.update()` used to materialize every journal as a buffer plus a
+parsed array before consulting its per-stream cursor; on a real store with
+an 887 MiB journal the indexing phase peaked above 2.3 GiB and had to be
+stopped. The store now offers `iterateStream()`, which reads 64 KiB chunks
+and yields one turn at a time with the same rules as `readStream()`:
+whitespace lines are skipped, an unparseable or `null` interior line is a
+corruption error carrying its absolute byte offset, and an unterminated
+final fragment is a torn tail left for the owner's append repair. The
+cursor, the single transaction and its rollback on corruption are
+unchanged. Measured on the same store: a full pass completes in 42 s with a
+peak of about 810 MiB under a 256 MB Node old-space budget.
+
+`readStream()` is unchanged for callers that need arrays.
+
+## Desktop backend runs as Node
+
+The packaged Desktop app spawns its backend server with its own
+executable, which is Electron. The child now runs with
+`ELECTRON_RUN_AS_NODE=1`, so the backend and the collector processes it
+starts run as plain Node instead of relaunching the app (verified headless
+against the signed 0.22.6 executable: the backend served `/api/version` at
+about 70 MiB). This does not explain the earlier GUI memory incident, whose
+snapshot held no Desktop process; it removes one way to multiply app
+runtimes.

package/package-catalog.json

@@ -7,7 +7,7 @@
     },
     "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.5",
+  "version": "0.22.7",
   "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 */ } }
+    },
+  };
+}

package/packages/record/lib/index-db.mjs

@@ -163,12 +163,13 @@ export class RecordIndex {
         "INSERT INTO index_state (stream, indexed_count) VALUES (?, ?) ON CONFLICT(stream) DO UPDATE SET indexed_count = excluded.indexed_count",
       );
       for (const streamId of this.store.listStreams()) {
-        const turns = this.store.readStream(streamId);
         const done = Number(getState.get(streamId)?.indexed_count ?? 0);
-        for (let i = done; i < turns.length; i++) {
-          this.addTurn(turns[i], streamId, effectiveOwner);
+        let count = 0;
+        for (const turn of this.store.iterateStream(streamId)) {
+          if (count >= done) this.addTurn(turn, streamId, effectiveOwner);
+          count++;
         }
-        setState.run(streamId, turns.length);
+        setState.run(streamId, count);
       }
       this.db.exec("COMMIT");
     } catch (err) {

package/packages/record/lib/store.mjs

@@ -404,6 +404,43 @@ export class RecordStore {
     return parseJournal(readFileSync(path)).turns;
   }
 
+  // Bulk consumers need one turn at a time, not a buffer and parsed array
+  // for an entire historical journal (some exceed 800 MB). Keep at most
+  // one complete line plus read chunks, with the same corruption/torn-tail
+  // rules as readStream. Joining fragments only at a newline avoids
+  // repeatedly copying long lines as each chunk arrives.
+  *iterateStream(streamId) {
+    let fd;
+    try { fd = openSync(this.journalPath(streamId), "r"); }
+    catch (e) { if (e.code === "ENOENT") return; throw e; }
+    let pieces = [], size = 0, lineStart = 0;
+    try {
+      for (;;) {
+        const chunk = Buffer.allocUnsafe(65536);
+        const n = readSync(fd, chunk, 0, chunk.length, null);
+        if (n === 0) break;
+        let from = 0;
+        for (let nl = chunk.indexOf(10, from); nl >= 0 && nl < n; nl = chunk.indexOf(10, from)) {
+          pieces.push(chunk.subarray(from, nl + 1));
+          size += nl + 1 - from;
+          const line = pieces.length === 1 ? pieces[0] : Buffer.concat(pieces, size);
+          let parsed;
+          try { parsed = parseJournal(line); }
+          catch (e) {
+            if (e instanceof StoreError) throw new StoreError(`corrupt interior journal line at byte ${lineStart}`);
+            throw e;
+          }
+          lineStart += size;
+          pieces = []; size = 0; from = nl + 1;
+          yield* parsed.turns;
+        }
+        if (from < n) { pieces.push(chunk.subarray(from, n)); size += n - from; }
+      }
+      // A final fragment without a newline is a torn tail, even if its
+      // JSON is valid. Readers leave it for the owner's append repair.
+    } finally { closeSync(fd); }
+  }
+
   // Is this a session-content stream (`<owner>~<source>.<session-id>`)?
   // Their journals hold whole conversations and can be large, so bulk
   // reads exclude them unless asked; access them per-thread instead.