@awebai/oats 0.22.1 → 0.22.3

package/docs/operating-team-migration.md

@@ -0,0 +1,269 @@
+# 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 installed baseline is OATS 0.22.2, including native Pi/Claude/Codex,
+tmux/Herdr, shared `yolo`, remote CLI launch/terminals and deferred retirement.
+The Mac Desktop app is installed and passed packaged renderer/PTY launch checks.
+Official oats.okf 1.5.0 provides record-fed harvesting. A source candidate for
+0.22.3 adds the retained-authority binding, remote Desktop roster/actions and
+retirement corrections; that candidate is not yet a published release.
+
+No standing seat has transferred yet. Cjr's worker pilot has landed reviewed
+code and knowledge; ordinary retirement passed using the next-patch candidate.
+A real harvester's automatic deferred completion, successor knowledge use and
+session-broker delivery remain explicit acceptance checks.
+
+## 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` | Preparation `5afb3e8b`; developer pilot landed on master `062e2c75`; legacy Merlin and Minerva live | Merlin owns safe handovers; preserve his DID/address; prove automatic harvest completion and successor use |
+| `~/awebai/aweb` | Live Claude coordinator and frontend in legacy homes | Oats owns coordinator handover; lead coordinates frontend with aweb after its current work; preserve identities and cover child repositories |
+| `~/tsm` | Five live seats: Zeus, Prometeo, Argos, Themis on Claude; Hermes on Codex. No OATS config/souls found | Zeus prepared the five-seat handover plan; begin with Themis at a safe boundary, Zeus last; preserve session-local 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` | 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 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
+those identified harnesses and read their replies; no coordination command
+was run as another seat. 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). Deferred retirement shipped in 0.22.2; record-fed learning shipped
+in oats.okf 1.5.0. Their presence does not replace the end-to-end acceptance
+checks below. 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 retains his identity; other continuing seats follow their accepted
+policy. Oats implemented explicit source-authority binding in oats.aweb 1.10.0,
+reviewed and pinned for the next kernel patch. A disposable rehearsal verified
+stable identity/address, existing conversations, heartbeat, exclusive holder
+refusal, rollback and authority-preserving retirement. 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
+
+The deferred external retirement mechanism shipped in 0.22.2. Completion
+still requires an actual harvester to finish, report and clean up without
+operator retirement, with visible recoverable failure. The detached worker
+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.
+
+### 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,
+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. The retained-binding rehearsal
+passed, but the installed standing-seat recovery journey remains to qualify. 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` tracks record-fed learning; oats.okf 1.5.0 ships its record path. 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. Native Codex launch/status/stop shipped
+in 0.22.2 alongside Pi and Claude; preserve each seat's selected runtime.
+The shared `yolo` default is enabled on this machine and maps to the runtime's
+permission flag. Aweb owns the per-host `aw wake` service; OATS supplies
+session inspection/input and capability registration, while Desktop is a
+client. Installing the broker service and proving mail/chat delivery after
+GUI closure is required before channel-free standing-seat adoption. Manual
+polling and successful terminal submission are not consumption evidence. 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.
+
+## Latest 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
+  retirement using candidate `b73918f` exited successfully in four seconds:
+  changed home bytes preserved, no redundant repository clone, worktree/home
+  removed, merged branch retained and temporary aweb alias retired. The
+  prior large-index failure led to the batch restore and home-only fixes.
+  Redundant failed repository copies were removed only after every file and
+  object was proven recoverable elsewhere; all home snapshots remain.
+- TSM's owner plan is `~/tsm/history/2026-09-06-tsm-oats-handover-plan.md`.
+  Preserve the five seats' worktrees, skills and knowledge; re-arm Zeus's
+  session-local schedules. Production credentials remain solely with the
+  authorized production operator. His plan reserves Zeus's final cutover
+  for Juan's presence; the other seats can prepare in the meantime.
+- BeadHub supplied its retained-identity and source-root brief through aweb
+  mail. It awaits the reviewed declarative binding and cutover recipe.
+  Its Stripe-account dependency and production cutover gates remain separate.
+- Docflow supplied its own identity and handover through its terminal. Its
+  backfill and register verification define the safe boundary. Preserve its
+  Claude memory and existing credentials in place; verify filesystem/TCC
+  access and the Minerva conversation before accepting the successor. Stop
+  the old harness before activating retained authority in the successor.
+- Local-scope aweb identities on different teams cannot contact one another
+  directly. Contacts require a globally resolvable target; the failed
+  lead/Zeus and lead/Docflow exchanges expose that intentional boundary.
+  Preparation proceeded through identified terminal coordination. Establish
+  the cross-team coordinator identity/contact policy explicitly before
+  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 are under independent
+  review for the next patch. Remote harvester completion remains blocked by
+  provider authentication, and no standing remote seat is declared migrated.

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/release-notes/v0.22.3.md

@@ -0,0 +1,80 @@
+# OATS v0.22.3
+
+OATS now shows every registered server's roster in one place, runs the
+knowledge harvest on a remote instance from here, retires exactly the home
+you name, and recovers large worktrees on retirement without copying what
+the clone already holds. The bundled aweb capability keeps an existing
+identity across a re-spawn.
+
+## Remote roster and remote harvest
+
+`oats server roster [--server <id>] [--json]` groups every registered server
+and saved route by host and workspace, pulls each group's status once within
+a total budget (45 s, 20 s per target; `--budget`, `--per-target`), and
+reports what it could not reach instead of waiting for it. Rows carry the
+saved route, the running state (true, false, or unknown), pending or failed
+retirements, quarantined homes, and routes the host no longer lists.
+
+`oats okf harvest --server <id> --instance <name>` runs the knowledge
+package's harvest in that instance's saved home on the host and relays the
+package's answer. A registration edited to another target while saved routes
+still point at the old one is refused at spawn; `oats server forget` drops a
+route whose instance is gone on the host. A routed spawn never overwrites
+an existing saved route: an explicit name that has one is refused, and a
+generated name that collides reports the new instance without a route.
+
+## Retire the home you mean
+
+Instance names are unique per agent only, so two agents can own an instance
+of the same name. `oats retire <name>` now refuses such a name and
+`oats retire <name> --home <path>` retires exactly that home. Self-retire and
+its deferred completion carry the calling instance's own home. A retire
+routed to a server sends the saved route's home when that server's kernel
+advertises `retire-home` in its version probe; against an older kernel the
+route refuses to retire a name that has twins there.
+
+## Retirement recovery at scale
+
+Recovering an uncommitted worktree used to copy every staged object into
+the recovery clone one Git process at a time; a clean 9,500-file tree took
+about 19,000 launches and looked hung. Recovery now asks the clone once
+which staged objects it lacks and copies only those, and proves at the end
+that nothing staged is missing. When independent inspection finds that only
+instance-home bytes changed and the worktree carries no work state, the home
+is preserved without a repository clone, and the report says so
+(`repoCopy.copied: false` with the reason).
+
+## Desktop
+
+Registered servers appear as remote workspaces, projected from the CLI
+roster: their souls and instances, spawn with a per-host handoff, terminals
+addressed by the exact remote home, and harvest and retire only for
+instances with a saved route from this machine. Unknown runtime state is
+shown as unknown everywhere it is counted. Retirement reports every
+preserved-work path and class, and a spawn whose name collided with an
+existing saved route is shown as launched without a route, with the
+host-side remedy. The Desktop requires the CLI's `retire-home` feature for
+every retirement and never admits a remote home into its local file roots.
+
+## oats.aweb 1.10.0
+
+A soul can declare `identity: { source, takeOver }` and its spawned instance
+becomes the retained seat of an existing aweb identity (same did and
+address); the legacy home's binding is restored on failure and released on
+retirement. The `delivery` setting chooses channel or session wake delivery.
+Capability manifests can declare settings with defaults, environment
+namespaces, and conditional requirements (`when`, `minVersion`,
+`ifInstalled`). The retire report says honestly that a retired alias is not
+reusable yet.
+
+## Also
+
+- The version probe's `remote` list gains `roster` and `harvest`; a new
+  `features` list carries `retire-home`.
+- `oats retire --json` keeps stdout to the envelope (the cross-repo note goes
+  to stderr).
+- Goldens carry `environmentNamespaces` in the resolved capability projection.
+- Viewers for remote instances resolve by home: `session inspect|attach
+  --server <id> --home <remote home>` uses the saved route that owns the home
+  and refuses a name paired with a different one.
+- Deferred retirement retry hints name the exact home.

package/docs/servers.md

@@ -0,0 +1,145 @@
+# 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.
+Address the home rather than the name (`--home </remote/home>`) when two
+souls on the host own an instance of the same name: the home is the identity,
+the saved route that owns it supplies the target, and a name given together
+with a home that is not its saved route is refused. 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.
+
+```bash
+oats server roster --json                                  # every remote group, one status pull each
+oats okf harvest --server build --instance dev-fix-123     # the knowledge harvest, run in the saved home
+```
+
+The **roster** is what the Desktop projects: one group per server id and
+route target (host and workspace), each with the registration (present or
+not), the probe (`ok`, or the error that stopped it), the souls the remote
+reports with their `agentsRoot`, the instances joined with this machine's
+saved routes (`savedRoute`; `running` true/false, or `null` when the remote
+could not be asked; `retirePending`; `rollbackIncomplete` for a quarantined
+home; `missingRemotely` when a saved route names an instance the reachable
+remote no longer lists), and `retireFailures` (deferred self-retirements
+that failed there and need `oats retire` again). A registration that was
+removed or edited keeps its group from the saved routes alone, so nothing
+spawned through it disappears from view. Remote state is pulled every time,
+never cached, within a budget: each group gets at most `--per-target` (20 s)
+of a `--budget` (45 s) total, and groups the budget cannot reach are reported
+with `E_ROSTER_BUDGET` rather than dropped or waited for. **Harvest** runs
+the knowledge package's own `okf harvest --json` in the instance's saved home
+on the host (a route that outlives the registration, like retire): the home
+comes from the route saved at spawn, never from the caller, the remote must
+advertise `harvest` in its version probe (0.22.3), and the package's envelope
+is relayed as is. **Retire** through a saved route sends that route's home as
+`--home` when the remote advertises `retire-home` in its probe `features`, so
+a same-named twin under another agent on the host is never the one retired;
+locally, `oats retire <name> --home <path>` does the same and a bare name that
+resolves to several homes is refused.
+
+## 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.
+
+A registration edited to a different host or workspace (`server add
+--replace`) while saved routes still point at the old target is refused at
+the next `spawn --server` with `E_ROUTE_CHANGED`: a new snapshot under the
+same server id would silently retarget them. Register the new target under a
+new id, or retire the old instances first; the roster shows both targets
+until then. A saved route whose instance is gone on the host (the roster
+shows it `missingRemotely`) cannot be retired away: drop it on purpose with
+`oats server forget <id> --instance <name>`. Saved routes are keyed by name
+under their server id: spawning an explicit `--instance` name that already
+has a route there is refused (`E_ROUTE_EXISTS`), and a generated name that
+collides with another soul's route on the same host leaves the new instance
+without a saved route (`routeConflict` in the result, a warning naming the
+host-side retire), never overwriting the existing one. The roster gives a
+route to the remote row with the same name and home only; a same-named twin
+under another soul is observed only.
+
+## Limits
+
+- Routed: `spawn`, `retire`, `status`, `okf harvest`, 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. `server roster`
+  is local (registrations and saved routes, one status pull per group). The
+  version probe's `remote` list names this kernel's remote-side surface
+  (`roster` and `harvest` from 0.22.3).
+- 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, 0.22.2 for the session routes, and 0.22.3 for harvest
+  and for the exact-home retire; the record commands
+  (`capture`, `recall`) need Node 22.5+ there for `node:sqlite`, which
+  lifecycle routing does not.
+- Lifecycle actions on a remote instance need a saved route from this
+  machine; an instance the remote reports that was spawned elsewhere shows in
+  the roster without one (`savedRoute: false`) and is read-only here.

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