@awebai/oats 0.22.1 → 0.22.2

package/docs/operating-team-migration.md

@@ -0,0 +1,217 @@
+# Full operating-team migration
+
+Planning record, 2026-09-05. 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.
+
+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
+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.
+Other teams' retained identities follow the same requirement where applicable.
+
+An isolated check against installed 0.22.1 confirmed that an explicit
+existing spawn destination is refused without changing its instructions or
+uncommitted notes. Purpose-based naming chooses an unused suffix. The old
+cjr respawn-clobber report therefore is not reproduced by this journey;
+identity adoption and concurrent handover still need their own tests.
+
+## Completion means operating teams
+
+Every continuing seat must have a supported OATS launch, composition,
+status, handover and retirement path. Its outstanding work, knowledge and
+required skills must survive a change of runtime session; identity/address
+continuity follows the explicit policy for that seat.
+Every remembering role must have a tested learning path; reviewers retain
+their explicit exclusion from accumulated memory. Config discovery alone
+establishes none of this.
+
+The published 0.22.1 release supports useful Pi/Claude worker work and
+notes-based harvest. Its observed qualifications included operator-assisted
+retirement. Standing-agent adoption, automatic service retirement and
+record-fed learning remain work, not shipped guarantees.
+
+## Scope inventory
+
+Reconfirm the live inventory with each owner at handover; process presence
+and old directories are evidence to investigate, not the authoritative list
+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` | Knowledge/config preparation landed at `5afb3e8b`; managed developer pilot running; legacy Merlin and Minerva observed live | Merlin owns pilot and safe handovers; preserve his DID and address; harvest acceptance remains pending |
+| `~/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. No OATS config/souls found | Lead coordinates with Zeus; cross-team handoff currently rejected by local identity routing; establish a supported route, then prepare souls/knowledge and safe handovers |
+| `~/prj/beadhub-all` | Live Codex session, despite stale offline roster | Lead sent handover request to Beadhub; preserve its established identity and current work; no billing/production changes |
+| `~/prj/docflow` | Live Claude session; credential workspace alias `alice` on `docflow:juan.aweb.ai` | Lead and Merlin establish responsible owner and handover; that alias is not proof of a globally routable address |
+| `ai.aweb` on `aweb-agents` | Athena last seen 53 days ago; remote legacy home exists in inventory | 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 |
+
+The live inventory above was checked on 2026-09-05 using harness process
+working directories, without interrupting them. Old aweb presence timestamps
+are insufficient to decide whether a harness is alive. A migration plan or
+new soul directory does not establish that the corresponding seat moved.
+
+Grace's missing old local path and the offline retirement, docs, bertha,
+cowork, federation, membership-review, aazb-reviewer, id-bugs, billing and
+claweb entries are archival investigations, not launch requests. Preserve
+homes until their work and authority have a recorded disposition. Do not
+bulk-delete aliases based on roster age; certificate cleanup belongs to the
+aweb lifecycle fix and its verified recovery procedure.
+
+## Shared prerequisites and owners
+
+Oats coordinates framework/package work and the machine-wide inventory.
+Lead independently reviews the design and concrete journey evidence. Merlin
+owns cjr's repository changes, task selection and eventual handovers. Other
+teams' owners control their work and handover sequence; oats records those
+owners before scheduling each migration. Oats accepted ownership of
+`aweb-abep` (service self-retirement), followed by `aweb-abfz` (record-fed
+learning). Self-retirement merged at 568eeae; record-fed learning is implemented
+and under independent review, with package publication pending. Lead owns
+the full-machine plan and runtime/wake qualification, including the Codex
+support requirement. The aweb coordinator owns identity continuity and route
+semantics, with oats coordinating the rehearsal and package changes.
+
+### Recreate or retain identities according to the actual requirement
+
+Cjr's default is a new OATS-minted identity and an explicit handover of
+outstanding work, knowledge, contacts and task responsibility. Old identities
+are retired only after that handover is accepted. Pilot identities remain
+uniquely named so no existing address has to be removed for the experiment.
+
+Merlin is the exception. Oats owns the explicit source-authority binding in the
+messaging capability; aweb supplied this supported handover:
+
+1. Rehearse using a disposable self-custodial global identity and a second-team
+   contact, checking DID, address, conversations and write attribution.
+2. Stop the old process. Copy authority only: signing.key, identity.yaml,
+   teams.yaml, team certificates, encryption.yaml and encryption keys. Keep
+   private files owner-only; exclude workspace.yaml and caches.
+3. In the new home run `aw workspace connect --service <url> --team <team>` to
+   rebind the existing identity. Do not mint or join as a new identity.
+4. Verify the same DID/address, host/path binding, heartbeat, message routes and
+   task writes. Preserve the old home for rollback until acceptance, then remove
+   its old credential copy. Never have two processes using the identity.
+
+Do not delete Merlin's global workspace as part of handover: aweb reports that
+this is unsupported and can release claims. Retiring a managed execution with
+retained authority must release the execution without destroying the identity.
+Never put credentials in Git or manufacture instance.json for adoption.
+
+### Make harvest finish without an operator
+
+Kernel issue `aweb-abep` is real in 0.22.1: bare `retire --self` is refused,
+while the harvester's instructions tell it to use that command. Oats owns
+the supported service-exit path, with lead review. A deferred external
+retirement is a candidate; the live agent must not inspect and delete its
+own working state. Completion requires an actual harvester to finish,
+report and clean up without operator retirement, with visible recoverable
+failure rather than silent loss. Do not release capabilities while the
+runtime can still act, or make the read-only status command delete homes.
+
+Review cjr's local `memory-harvest` override before the pilot: selected
+implementation, required skill, authenticated model, source worktree,
+promotion destination and self-harvest exclusion. The configured model is
+OpenAI via `openai-codex/gpt-5.5`, already used by the local record/mind setup.
+Pi is needed even for Claude workers. A model setting is not proof of a run.
+
+### Finish temporary identity retirement
+
+The aweb owner must resolve the remote lifecycle defect tracked under
+`aweb-aaum.6`; oats coordinates package integration. The five leaked release
+identities are a reproduction. 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.
+
+### Recover standing executions after reboot
+
+Tmux and Herdr keep agents alive when a viewer disconnects; a machine reboot
+ends those executions. Replaying `instance.json.command` manually does not
+refresh OATS's independent session receipt and is not a supported recovery.
+The first planned recovery reuses the tested retained-authority handover:
+preserve the stopped home, knowledge and identity, then create its replacement
+with a new receipt and one active holder. That capability binding is not built
+yet; until qualified, rebooted standing seats remain down. A terminal-only
+restart operation may follow; it must refresh the receipt without rerunning
+resource-provisioning hooks. No automatic supervisor is required for the first
+supported manual recovery.
+
+### Include noncoding learning and all actual runtimes
+
+`aweb-abfz` is the open record-fed learning epic. Its bounded acceptance is
+a standing session that wrote no notes and made no code commit producing a
+reviewed knowledge proposal with provenance to exact recorded turns, then a
+successor reading that knowledge. Notes-based harvest must continue working.
+Oats owns this after service self-retirement: select the source instance's
+own recorded turns through a record helper, feed them to existing OKF
+judgment, and deliver proposals through the same review path. Verify exact
+source provenance, correct soul destination and safe repeat processing.
+Storing transcripts or running the mind daemon alone does not satisfy this
+gate.
+
+The inventory includes Codex sessions. Main now includes reviewed native Codex launch (b7d4159), alongside Pi
+and Claude; released Codex launch/status/stop/composition support is required
+unless a seat's owner explicitly chooses a runtime change. No silent fallback
+to Pi. Test channel delivery with the installed runtime and selected config;
+manual polling is not wake-up. Establish any actual machine-policy change
+needed before making it. Include daemon health and restart/recovery behavior
+in the operating instructions.
+
+## Rollout sequence
+
+1. **Prepare without disturbing sessions.** Record each seat's identity,
+   home, work path/branch, outstanding tasks/messages, notes, skills and
+   launch mechanism. Review/commit the isolated config changes. Give every
+   knowledge store a disposition, preserving source material; migrate needed
+   context into indexed soul knowledge and team rules. Materialize required
+   skills explicitly instead of depending on a user's Claude skill links.
+2. **Rehearse required identity transitions on test identities.** Prove
+   temporary retirement and Merlin-style retained-authority handover, including
+   cross-team routing. If another team requires retained-key adoption, test
+   its write binding, exclusivity, failure recovery and retained-identity
+   retirement separately. Do not use the active Codex lead or a standing
+   coordinator as the initial experiment.
+3. **Run cjr's useful worker pilot.** Merlin selected extending
+   `kb/tools/kb-jobs-check.py` to cover the machine's launchd jobs. Limit the
+   task to health reporting; do not enable/disable jobs. Use a fresh named
+   developer in a worktree and a fresh code reviewer. Verify required skills,
+   aw communication, a reviewed task commit, a real harvested promotion on
+   the correct branch, and a second developer reading the promoted lesson
+   through the soul's index. Verify harvester and worker retirement. A
+   workaround-assisted run is recorded as partial, not automatic completion.
+4. **Transfer cjr seats at agreed safe boundaries.** Prove the never-run
+   roles with new managed workers. Then hand Hermione's and Dumbledore's work
+   to fresh identities, followed by Minerva's work; Merlin goes last using the
+   verified address-continuity procedure. Checkpoint work/mail/notes and
+   explicitly transfer responsibilities. Avoid duplicate owners of the same
+   task. Preserve old homes until successor acceptance; retire old identities
+   through the supported remote path. Every remembering role gets the learning
+   check; reviewers get the exclusion check.
+5. **Repeat across the inventory.** Prepare other scopes in parallel with
+   framework work; apply the proven handover with each team owner. Oats/aweb,
+   tsm, beadhub and docflow all need explicit outcomes. Offline homes receive
+   an explicit disposition. Retire old launch scripts only after no continuing
+   seat depends on them.
+6. **Qualify continuous operation.** Prove record-fed promotion for noncoding
+   sessions, successor knowledge use, wake-up and recovery, and working health
+   checks. Document one supported operator path to start, inspect, hand over,
+   harvest and retire each role. Close the full migration only then.
+
+## Evidence and progress
+
+Keep separate milestones per team: config ready; skills/knowledge ready;
+new workers qualified; standing seats transferred; learning qualified;
+retirement/recovery verified. Record exact published versions and relevant
+commits. Preserve failed-step evidence and outstanding limitations; do not
+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.

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

@@ -0,0 +1,69 @@
+# OATS v0.22.2
+
+OATS now launches native Codex, supports Herdr alongside tmux, and routes
+agent lifecycle commands to registered SSH servers. This release also adds
+record-fed harvesting and lets agents finish their own retirement.
+
+## Native runtimes and one permission setting
+
+Choose Pi, Claude Code or Codex when creating or spawning an agent. Codex
+uses its native CLI, instructions and skill discovery. Unknown runtimes are
+rejected before provisioning.
+
+Set `yolo: true` in a scope's `oats-config.yaml`, override it in a soul, or
+use `oats spawn --yolo` / `--no-yolo`. Desktop offers the same launch choice.
+Codex receives `--yolo` and a launch-local trust setting for the generated
+home; Claude receives `--dangerously-skip-permissions`. Pi is unchanged.
+With no setting, OATS leaves native permission policy in place.
+
+## Persistent terminals and SSH execution
+
+Use `--backend tmux|herdr` at spawn. The instance's saved session receipt
+identifies its execution; inspect, input, attach and retirement use that
+original target. Closing a viewer leaves the agent running.
+
+`oats session inspect|input|attach --home <absolute-home>` provides the
+harness-neutral terminal interface. Input sends literal text and Enter;
+submission is not proof that the agent processed a message.
+
+Register an existing SSH host with `oats server add`, then use `--server`
+on spawn, status, retire and session inspect/attach. Saved routes keep
+retirement and attachment available if a registration changes. SSH retains
+responsibility for keys and host verification. Desktop includes a server
+selector and the remote terminal adapter; remote roster projection remains
+a follow-up, so use the CLI to attach to a remote instance in this release.
+
+Live checks covered native Codex launch and subsequent terminal input on
+both local backends. A real remote Claude session accepted input through
+the Desktop terminal helper, survived viewer closure, and ended its viewer
+on retirement. Herdr roster checks include public IDs beyond the ninth
+workspace. These checks do not establish reboot recovery.
+
+## Learning and retirement
+
+The official `oats.okf` 1.5.0 capability can feed harvest from an instance's
+captured turns even when it wrote no notes. It selects that home's sessions,
+reads bounded windows, and advances its watermark over the supplied record.
+Notes-based harvesting remains supported. Record commands require Node 22.5
+or later on the execution host.
+
+`oats retire --self` records retirement intent and starts detached completion.
+Completion stops the runtime before releasing capability resources and
+removing the home. Failed cleanup remains visible and recoverable through
+status. The roster also stops treating retirement bookkeeping directories
+as instances. Retiring an instance whose work tree is large no longer fails with
+`git ENOBUFS` during work preservation: every git call on the retirement path
+now runs with a buffer far above Node's 1 MiB default (found on a real
+~9,500-file tree).
+
+## Package versions and remaining work
+
+The catalog pins `oats.okf` v1.5.0 and `oats.aweb` v1.9.0. The latter updates
+native Codex's messaging instructions; its Pi and Claude channel delivery
+is unchanged. Native Codex has no automatic aweb delivery in this release.
+
+The aweb host wake broker, session-delivery capability glue, retained-identity
+handover and supported standing-seat reboot recovery are still being
+completed. Hosted temporary aliases also remain non-reusable until aweb's
+certificate-retirement fix ships; use fresh purpose names. A configured
+team or successful spawn does not mean its standing agents have migrated.

package/docs/servers.md

@@ -0,0 +1,94 @@
+# Servers: running instances on another machine
+
+A **server** is another machine with its own installed OATS, reached over an
+OpenSSH host alias. Registering one lets `oats spawn`, `oats retire` and
+`oats status` run there with the same flags and the same JSON envelope as
+locally, and lets the Desktop offer it at spawn time. The contract behind
+this is the execution-targets contract (`docs/execution-targets.md`, landing
+with the transport work).
+
+## Register
+
+```bash
+oats server add build --ssh build-host --workspace /srv/team --oats /usr/local/bin/oats
+oats server check build      # ssh reachability, remote oats version, workspace roster; no mutation
+oats server list
+```
+
+- `--ssh` is an OpenSSH host alias or host name. Keys, users, ports and host
+  verification live in your `~/.ssh/config`; the registry stores none of it and
+  refuses `user@host` or option-shaped values. Connections are non-interactive
+  (`BatchMode=yes`): a host that would prompt fails fast with ssh's message.
+- `--workspace` is the absolute path of an OATS workspace on the server: the
+  same team repository checked out there, with its own `agents/`.
+- `--oats` is the remote executable (default `oats` on the login shell's PATH).
+- `--path` names directories to prepend to the remote PATH for every routed
+  command (`~/.local/bin:/opt/pi/bin`). A non-interactive ssh command runs in
+  the login shell's minimal PATH, and the remote kernel's spawn preflight looks
+  for the runtime binary (`claude`, `pi`, `codex`) there; without this, a
+  runtime installed under the user's home is "not found" even though it runs
+  fine in an interactive shell on that host.
+- Registrations live in `~/.oats/servers.json` on this machine, never in a
+  repository scope.
+
+## Run there
+
+```bash
+oats spawn dev --server build --purpose fix-123 --task-file task.md
+oats status --server build
+oats retire dev-fix-123 --server build
+```
+
+The remote kernel does the work in its registered workspace: composition,
+worktree, identity, launch, retirement. The local side only routes: a local
+`--task-file` travels as text, every argument is quoted for the remote login
+shell, and the remote's version and envelope are checked before either
+mutation (spawn and retire). A spawn is also held to what the remote
+advertises: a runtime it does not list (including the soul's own default as
+the remote roster reports it), a session backend it lacks, or a launch option
+such as `--yolo` it does not know is refused with `E_REMOTE_INCOMPATIBLE`
+saying what was established. A remote that advertises nothing (any kernel
+before 0.22.2) is assumed to run pi and claude on tmux with no options, and
+the refusal says so rather than claiming the remote lacks the feature; a soul
+the remote roster does not list with a runtime is validated by the remote
+kernel itself at spawn. `--dir` and `--server` do not combine; the remote
+workspace comes from the registration.
+
+```bash
+oats session attach --server build --instance dev-fix-123   # viewer through an ssh PTY
+```
+
+The viewer runs the execution host's own `oats session attach` (Herdr terminal
+or an isolated tmux linked viewer) over `ssh -t`, addressed by the saved route:
+the remote binary and path come from the snapshot, never from the caller. The
+`oats session` commands ship in kernel 0.22.2: against an older server both
+session routes refuse with `E_REMOTE_INCOMPATIBLE` before connecting a viewer,
+and `ssh -t <host> tmux attach -t oats` remains the way in.
+
+## What this machine keeps
+
+A **route snapshot** per remote instance under `~/.oats/remote/<server>/`,
+taken at spawn: the ssh host, workspace and oats path the instance was spawned
+through, plus the remote home. Later `retire --server` uses the snapshot, not
+today's registry, so editing or removing a registration never orphans a remote
+home; the snapshot is removed only when the remote kernel reports the home
+gone. Remote state is never cached: `status --server` pulls it every time and
+appends this machine's snapshots for that server.
+
+## Limits
+
+- Routed: `spawn`, `retire`, `status`, and, against a 0.22.2 or later
+  server, `session inspect` (the execution host's envelope, relayed; a Desktop
+  preflight before attaching) and `session attach`. Session input runs on the
+  execution host, where the wake broker calls it.
+  Desktop projection of remote instances and remote viewer attachment are in
+  progress on the execution-targets work.
+- No Git over SSH: repository operations always run on the server, by its
+  kernel, in its workspace.
+- A remote needs an OATS at least 0.22.1 (`MIN_REMOTE_VERSION`) for spawn,
+  retire and status, and 0.22.2 for the session routes; the record commands
+  (`capture`, `recall`) need Node 22.5+ there for `node:sqlite`, which
+  lifecycle routing does not.
+- After a remote spawn the Desktop reports the server and remote home; the
+  instance does not appear in the local roster (projection of remote instances
+  is the next step of the execution-targets work).

package/docs/souls-and-instances.md

@@ -108,6 +108,24 @@ the same work tree. The harvester promotes, merges, or drops notes, commits a
 `memory-harvest:` change, deletes processed notes, and retires itself. This is
 how long-lived instances feed their souls while still alive.
 
+Instances that write few notes still feed their souls. With no notes pending,
+`oats okf harvest` asks the turn record for the instance's own captured
+sessions (the transcripts whose working directory is the instance home), and
+spawns the harvester on the turns captured since the last harvest, bounded by
+exact turn ids. The harvester extracts candidates from them, judges each under
+the same promotion bar as a note, and once its judgement is complete writes the
+watermark `.okf-harvest-record.json` in the instance home, whether or not it
+promoted anything; only a failed harvest leaves the watermark alone, so the same
+window is read again. `oats okf harvest --from-record` consults the record even
+when notes are pending. Windows are sized to one tool-output read (60 turns
+or 96 KB of JSON by default; okf settings `record-window-turns` and
+`record-window-bytes`), so a long backlog drains over several harvests, each
+advancing the watermark only over what was read; the package prepares the next
+watermark as `.okf-harvest-record.next.json` and the harvester's delivery is
+one rename, so an abandoned harvest leaves that file beside the current one.
+oats.okf 1.5.0 requires kernel 0.22.2 (the `capture --home` and `recall --json`
+surfaces); the compatibility floor refuses to activate it on an older kernel.
+
 ### Spawning and coordinating with other agents
 
 OATS agents can run `oats spawn` when their instructions or the
@@ -156,9 +174,18 @@ integration self-deletes the instance identity here. For oats-okf, retirement
 is a knowledge no-op because harvest already happens after commits.
 
 `oats retire <instance> --self` lets an instance retire itself when the human
-or briefing says it is done. It runs hooks and removes the home first, then
-delays the tmux window kill for a few seconds so the instance can report
-final status.
+or briefing says it is done. A live runtime cannot give a stable final
+inspection of its own work, so the calling process inspects, runs, and removes
+nothing: it records the intent beside its home as
+`.oats-retire-pending-<instance>.json` and starts a detached completion, then returns so the instance can report final
+status before its tmux window dies a few seconds later. The completion then
+retires the instance exactly as an external `oats retire` would: quiesce the
+runtime, preserve uncommitted work, run retire hooks, repair lineage, remove
+the worktree and the home. Success leaves nothing behind: the home and the
+marker are gone. A failure writes `.oats-retired-<instance>.json` beside the
+retained home (plus the usual quarantine marker when hooks reported incomplete
+cleanup), shows in `oats status` and the Desktop as a failed deferred
+retirement, and is retried and cleared with `oats retire <instance>`.
 
 ## Work modes