@awebai/oats 0.22.7 → 0.22.8

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

@@ -27,9 +27,12 @@ import { existsSync, mkdirSync, mkdtempSync, writeFileSync, readFileSync, readdi
 import { join, isAbsolute, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { execFile, spawnSync } from "node:child_process";
+import { reclaimHarvestBranch } from "../lib/harvest-branch.mjs";
 
 const out = (o) => { process.stdout.write(JSON.stringify(o) + "\n"); process.exit(0); };
 const warn = (m) => out({ warning: `oats-okf: ${String(m).slice(0, 300)}` });
+// A reported failure must not exit 0: callers and hooks read the status.
+const warnFail = (m) => { process.stdout.write(JSON.stringify({ warning: `oats-okf: ${String(m).slice(0, 300)}` }) + "\n"); process.exit(1); };
 
 // Desktop CLI API v1: `oats okf harvest --json` emits EXACTLY ONE envelope
 // object on stdout — {schemaVersion:1,ok,result|error} — and a nonzero exit
@@ -38,6 +41,12 @@ const JSON_MODE = process.argv.includes("--json");
 const jsonOk = (result) => { process.stdout.write(JSON.stringify({ schemaVersion: 1, ok: true, result }) + "\n"); process.exit(0); };
 const jsonFail = (code, message) => { process.stdout.write(JSON.stringify({ schemaVersion: 1, ok: false, error: { code, message: String(message).slice(0, 300) } }) + "\n"); process.exit(1); };
 
+// --help/-h never runs a command here either (the kernel answers it from the
+// manifest since 0.22.6; this keeps an older kernel from spawning a harvester).
+if (process.argv.slice(2).some((a) => a === "--help" || a === "-h")) {
+  process.stdout.write("oats okf harvest [--json] [--from-record] [--force]  promote this instance's pending notes (and record windows) into its soul by spawning a memory-harvest worker; --help never spawns\noats okf status [--json]\n");
+  process.exit(0);
+}
 const event = process.env.OATS_EVENT || process.argv[2];
 const instance = process.env.OATS_INSTANCE;
 const home = process.env.OATS_HOME || process.cwd();
@@ -421,6 +430,10 @@ _(the single next action — keep this current; a fresh session on any model res
       const soulRepo = gitRootOf(realSoul);
       if (!soulRepo) skip("workspace-mode soul is not inside a git repo — nowhere to deliver a PR");
       const relSoul = realSoul.slice(soulRepo.length + 1);
+      // A leftover memory-harvest/<slug> branch from a merged promotion is
+      // deleted first; an unmerged one refuses the harvest with the remedy.
+      const reclaimed = reclaimHarvestBranch(soulRepo, `memory-harvest/${slug}`);
+      if (reclaimed.action === "deleted") process.stderr.write(`oats-okf: deleted stale harvest branch memory-harvest/${slug} (merged into ${reclaimed.base})\n`);
       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",
@@ -458,7 +471,7 @@ _(the single next action — keep this current; a fresh session on any model res
     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}`);
+    warnFail(`harvest spawn failed (notes are safe on disk): ${e.message || e}`);
   }
 } else if (event === "retire") {
   // Retirement is intentionally a no-op for knowledge (for now): promotion happens

package/capabilities/oats-okf/lib/harvest-branch.mjs

@@ -0,0 +1,43 @@
+// A workspace-mode harvest delivers its promotion as a PR from a branch named
+// memory-harvest/<slug> in the soul's repository. After that PR merges, the
+// local branch may still exist and the next harvest's spawn would refuse it.
+// A branch fully merged into the base is stale and is deleted before the
+// spawn; an unmerged one is the previous harvester's unfinished work and the
+// harvest refuses with the exact remedy instead of touching it.
+import { execFileSync } from "node:child_process";
+
+/** Single-quote shell escaping for the operator remedy: the repo path may hold spaces or shell metacharacters. */
+export function shellQuote(s) { return "'" + String(s).replace(/'/g, "'\\''") + "'"; }
+
+function git(repo, args) {
+  return execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+/** The repository's base branch: origin/HEAD's target when known, else main, else master. */
+export function baseBranchOf(repo) {
+  try { const ref = git(repo, ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"]); if (ref) return ref.replace(/^refs\/remotes\//, ""); } catch { /* no origin/HEAD */ }
+  for (const b of ["origin/main", "main", "origin/master", "master"]) {
+    try { git(repo, ["rev-parse", "--verify", "--quiet", b]); return b; } catch { /* next */ }
+  }
+  return undefined;
+}
+
+/** Returns { action: "absent" | "deleted", base } or throws E_HARVEST_BRANCH_EXISTS. */
+export function reclaimHarvestBranch(repo, branch) {
+  try { git(repo, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]); }
+  catch { return { action: "absent" }; }
+  const base = baseBranchOf(repo);
+  let merged = false;
+  if (base) { try { git(repo, ["merge-base", "--is-ancestor", branch, base]); merged = true; } catch { merged = false; } }
+  if (!merged) {
+    const err = new Error(`branch ${branch} already exists in ${repo} and is not merged into ${base || "any base branch"}: a previous harvest's promotion is unfinished — review and merge or delete it (git -C ${shellQuote(repo)} branch -D ${shellQuote(branch)}) before harvesting again`);
+    err.code = "E_HARVEST_BRANCH_EXISTS";
+    throw err;
+  }
+  // -D, not -d: the merge check above is against the BASE (origin/main when
+  // present). `branch -d` re-checks against the branch's upstream or the
+  // current HEAD instead, so with the soul's local main behind origin/main a
+  // branch fully merged upstream would still be refused as "not fully merged".
+  git(repo, ["branch", "-D", branch]);
+  return { action: "deleted", base };
+}

package/capabilities/oats-okf/oats.json

@@ -1,15 +1,21 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "1.5.1",
-  "compatibility": { "oats": ">=0.22.3" },
+  "version": "1.5.2",
+  "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"],
+      "values": [
+        "pi",
+        "claude",
+        "codex"
+      ],
       "description": "Harness for the memory harvester, independent of the source instance's runtime."
     },
     "harvest-model": {

package/docs/integrations.md

@@ -167,6 +167,14 @@ 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.okf 1.5.2
+
+`okf harvest` exits non-zero when it reports a failure (the plain and the
+`--json` forms alike). A leftover `memory-harvest/<slug>` branch from a merged
+promotion is deleted before the next workspace-mode harvest; an unmerged one
+refuses the harvest and names the remedy. `oats okf harvest --help` prints
+usage and never spawns.
+
 ## oats.aweb late joins (1.10.3)
 
 `aw team join` at spawn gets 120 s (a slow link is slow, not broken). If the

package/docs/operating-team-migration.md

@@ -33,24 +33,30 @@ 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.5 on this Mac and `aweb-agents`,
+The installed CLI baseline is published OATS 0.22.7 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.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
+The installed Mac Desktop 0.22.7 passed published ZIP checksum and strict deep
+codesign. Its controlled single-instance check passed and the app was closed
+afterwards, with all owned processes verified gone. The previous 0.22.6 app
+is preserved for rollback; earlier renderer/PTY checks remain version-specific.
+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.
+each earlier qualification. Follow-up 1.5.2 is now published with truthful
+failure exits, harmless help and repeat-harvest branch reuse. BeadHub's actual
+deployment has been updated and re-trusted at 1.5.2; its previous lock was 1.5.0.
 
 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;
+mail through the host wake path. Frontend also has a managed execution with
+separate mail/chat proof and reviewed knowledge promotion. This is not completion
+of all teams: TSM is held, Docflow still has a running backfill, and normal
+coordinator learning remains queued. The final lead handover is accepted.
+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)
@@ -70,22 +76,36 @@ 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.
+service definitions, raw records and learning state are preserved. Continue
+with one bounded operation at a time, checking memory between
+launches; declining swap alone does not prove sustained stability. Published
+0.22.6 prevents overlapping capture passes with a conservative lock that never
+steals an existing owner; interrupted owners require explicit recovery. Its
+measured full pass still exceeded a 2 GiB RSS budget during indexing and was
+stopped by the monitor. The follow-up streams journal entries instead of loading
+whole arrays. The independently reviewed candidate completed the real index of
+1.74 million turns in 41.6 seconds, at 809.5 MiB peak RSS with normal memory
+pressure, under a 256 MiB Node old-space budget. That fix is now published and
+installed in 0.22.7. The replacement launchd job runs one background pass every
+15 minutes, without per-tool hooks or a permanent watcher. Its first real pass
+completed in 101 seconds at 746 MiB peak RSS, with index completion and zero
+aw-log projection failures. The reviewed operator wrapper stops its own child
+on a 2 GiB RSS limit, two elevated memory-pressure samples, or a five-minute
+deadline. It records each run atomically in
+`~/.local/state/oats/capture/status.json`, retaining the previous success time
+through failures. Idle between passes is normal. Interrupted capture locks
+still need explicit owner-checked recovery; the wrapper reports the remedy.
+Experimental mind follow remains paused.
 
 | 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 |
+| BeadHub | `beadhub-seat`, retained DID/address and claims; native Codex; independent mail/chat; trusted OKF 1.5.2 and aweb 1.10.3; repeat harvest promoted all four notes and retired cleanly | PR #2 at `a111a222` independently reviewed and merged; canonical deployment checkout fast-forwarded with untracked data preserved, so the live soul sees the six-concept bundle |
+| Cjr | `accountant-minerva` and `coordinator-merlin` live on retained identities; old holders stopped first; claims preserved; real delivery and reviewed learning recorded | Log `5bfeefd1` and corrected librarian knowledge `6c91f986` landed with user edits preserved; librarian retired with alias reusable; Merlin's own harvest and health-reader follow-up remain queued |
+| Aweb | Retained `coordinator-aweb` and fresh `frontend-oats` both passed independent mail/chat; frontend knowledge `d649d729` reviewed and landed | Old holders stopped with their channel children before replacement; metadata repair and encryption-key findings tracked separately, with repeated wake-hint diagnosis in progress |
 | 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 |
+| Oats/lead | Retained `oats-coordinator-coordinator` passed independent mail wake; fresh team-local `lead-operating-lead` passed separate idle-to-wake mail fetch/reply after verified predecessor stop; root packages trusted at OKF 1.5.2 and aweb 1.10.3 | BeadHub accepted the lead and transferred the still-open rollout epic; Oats's provider capacity, historical lead claim reconciliation, coordinator learning and preserved recovery lessons remain follow-ups; cross-team updates use retained global relays |
 | 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`.
@@ -97,10 +117,17 @@ 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,
+Desktop 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
+are not claimed. Version 0.22.6 added a single-instance guard and 0.22.7 runs the
+packaged backend as Node. An installed 0.22.7 check served the Oats workspace API;
+a second launch exited successfully while the primary remained, with both
+owned process groups peaking at 589 MiB and normal memory pressure. All test
+processes were stopped and verified absent. The full release gate and all three
+Desktop builds passed on hosted runners; publication succeeded, and the bot's
+version-bump PR permission failure was resolved through reviewed manual PR #8.
+Native remote Pi authentication and remote Codex remain
 unqualified; the accepted remote harness is Claude.
 
 ## Scope inventory
@@ -119,7 +146,7 @@ of continuing seats.
 | `~/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` | Capture and experimental mind services paused after memory incident | Preserve records; review and measure resource fixes before resuming |
+| `~/.turn-record` | Guarded periodic capture enabled and measured; per-tool hooks and experimental mind follow remain disabled | Preserve records; monitor the run artifact; no blind watcher restart |
 
 The starting inventory above was checked on 2026-09-05 using harness process
 working directories and exact custom tmux sockets, without interrupting them.

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

@@ -0,0 +1,40 @@
+# OATS v0.22.8
+
+Two fixes an operator meets directly: picking a remote workspace in Desktop
+now works, and the bundled catalog pin for the knowledge package catches up
+with what is published.
+
+## Desktop: selecting a discovered remote workspace
+
+A registered SSH server's workspaces are discovered after the app starts, so
+the main process's record of what the backend advertises could be seeded
+before that discovery finished. Clicking the remote workspace in the menu then
+looked like nothing happened: the request carried a workspace id the record
+did not recognize, and an unrecognized selection is deliberately pinned back
+to the verified local scope. The workaround was to open Add workspace and
+cancel, whose own refresh repaired the record as a side effect.
+
+The main process now learns that record from the successful `/api/panel`
+responses it is already making, which are the same server-owned choices the
+menu is built from, so a workspace that appears late is selectable as soon as
+the menu can show it. No request is added, including for a selection that
+stays unrecognized. Only a successful panel response teaches it: error
+replies and other endpoints cannot. Nothing learned from an outgoing backend
+can survive its replacement: a request that begins while the backend is being
+replaced never teaches, and one that began earlier is refused if a replacement
+started before its reply arrived, so the workspaces a stopped server
+advertised cannot come back. Off-origin resolution is still rejected before
+anything is fetched, and a selection the backend does not advertise is still
+pinned to the local scope.
+
+## Bundled: oats.okf 1.5.2 pin
+
+The catalog shipped with the kernel now pins oats.okf v1.5.2, so
+`oats update oats.okf` resolves it without an explicit selector. Until now a
+bare update resolved the pin baked into the installed kernel, which was
+v1.5.1, and reaching 1.5.2 needed `oats update oats.okf --to v1.5.2`.
+Deployments that moved early with the explicit selector are already on the
+same payload and need nothing. 1.5.2 makes a failed harvest exit non-zero,
+stops `okf harvest --help` from running a harvest, and reclaims a leftover
+`memory-harvest/<slug>` branch whose promotion is already merged into the
+base, including when the base is a remote main ahead of the local one.

package/package-catalog.json

@@ -2,7 +2,7 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v1.5.1",
+      "ref": "v1.5.2",
       "path": "oats-package"
     },
     "oats.aweb": {

package/package.json

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