@awebai/oats 0.22.0 → 0.22.2

package/docs/migration-from-oas.md

@@ -1,122 +1,86 @@
 # Migrating from OAS to OATS
 
-Status: **the migration path exists in the kernel** — `oats migrate
---from-oas`, one transactional conversion per scope (plan steps 1–3 below,
-all landed 2026-08-21). What remains is distribution: end users get the
-command with the v0.22.0 release (steps 4–6). This document keeps the facts
-in one place; the work is tracked as epic `aweb-abfy` in this team's aw
-tasks. Audited 2026-08-21 against a live OAS deployment
-(`@oas-framework/oas@0.20.0-aweb.1`).
-
-OATS was published as **OAS** (`@oas-framework/oas`, `@oas-framework/pi`)
-until the 2026-08-13 rename (commit `fa1e646`), which was a deliberate
-clean break: no compatibility shims, and no code in this repo recognizes
-`oas-*` names.
-
-## Do not migrate by hand yet
-
-The dangerous property of the original state was that it failed **quietly**:
-
-- On a scope with `oas-config.yaml`/`oas-lock.json`, `oats status` works
-  (the `agents/` layout is unchanged) — everything looks healthy.
-- But `oats doctor` finds no config, all layers are unresolved, and a spawn
-  produces instances **without the knowledge (`oas.okf`) and messaging
-  (`oas.aweb`) injections**. The compounding-memory and team-comms value
-  disappears with no error.
-- `oats migrate --official --dry-run` on such a scope reported "nothing to
-  migrate" and exited 0 — false success.
-
-Since plan step 1 landed (below), the silence is closed: `oats doctor` names
-an un-migrated OAS scope with the remedy, and every `oats migrate` form —
-plain or guided, dry run or apply — exits nonzero when `oas-config.yaml` /
-`oas-lock.json` are visible from the scope (detection is by name only; the
-kernel never parses OAS files).
-
-## Migrating: `oats migrate --from-oas`
+OATS is the successor to OAS. **OATS 0.22.0 was published on 2026-09-03**:
+the kernel, Pi adapter, and Desktop assets are available. The published
+kernel acquired the official OKF, aweb, authoring, and development packages
+from its catalog during the 2026-09-05 qualification. You no longer need a
+framework checkout to migrate.
+
+Use the migration command rather than renaming files by hand. The OATS
+kernel does not read `oas-*` configuration names or `oas.*` capability IDs.
+An unchanged agent-directory layout can make an old scope look familiar
+while its knowledge and messaging configuration remains unmigrated.
+
+## Upgrade one scope
+
+Finish or preserve active work before changing a daily-use deployment.
+Install OATS alongside the old CLI, then inspect the plan for the exact
+scope you intend to convert:
+
+```bash
+npm install -g @awebai/oats@latest
+pi install npm:@awebai/oats-pi@latest
+oats migrate --from-oas --dry-run --dir /path/to/scope
+```
+
+Read any held or unmapped package rows before applying. A dry run reports
+what can be converted; it is not a guarantee that every historical package
+version has a supported replacement. When the plan is correct:
 
 ```bash
-oats migrate --from-oas --dry-run --dir <scope>   # full per-scope plan, touches nothing
-oats migrate --from-oas --dir <scope>             # convert this scope
-oats migrate --from-oas --recursive --dir <root>  # every visible OAS scope
+oats migrate --from-oas --dir /path/to/scope
+oats doctor /path/to/scope
 ```
 
-One transaction per scope, two phases under one journal:
-
-1. **Rename phase** — `oas-config.yaml` → `oats-config.yaml` (line
-   transform: the `oas:` defaults key becomes `oats:` and capability ids
-   with catalog renames become their successors; comments and every other
-   byte survive), `oas-lock.json` → `oats-lock.json` verbatim, `oas.json` →
-   `oats.json` inside each installed capability dir, and
-   `.oas-scaffold-owners.json` → `.oats-scaffold-owners.json` in `agents/`
-   and `local-agents/` souls with owner ids mapped to their successors.
-2. **Chained guided conversion** — the existing v1→v2 official migration
-   runs on the renamed lock; the catalog's renaming aliases map each
-   `oas.*` entry onto the `oats.*` package that replaces it, re-acquiring
-   the artifacts (stale v1 integrity is resolved by re-acquisition, never
-   recomputed) and cleaning the superseded `oas`-named artifact dirs.
-
-Any failure in either phase restores the scope's original OAS-named bytes.
-A second run finds nothing and exits 0. Executable trust is re-earned after
-conversion (`oats trust` commands are printed), and comments inside your
-config that mention `oas` paths are left untouched — comments are yours.
-
-## The four breaks
-
-1. **File names.** The kernel reads only `oats-config.yaml`
-   (`lib/core.mjs:326`) and `oats-lock.json` (`lib/core.mjs:643`). OAS
-   scopes have `oas-config.yaml`, `oas-lock.json`, `oas.json` inside each
-   installed capability dir, and `.oas-scaffold-owners.json` in souls.
-2. **The config key.** The schema (`docs/oats-config.schema.json`,
-   `additionalProperties: false`) accepts an `oats:` defaults block and
-   rejects the `oas:` block an OAS config carries — renaming the file is
-   not enough.
-3. **Capability ids.** `oas.okf` / `oas.aweb` appear in the config, the
-   lock, and the `.agents/capabilities/installed/<id>/` directory names.
-4. **No catalog aliases.** `package-catalog.json` maps only `oats.*` ids;
-   a hand-renamed lock naming `marketplace:oas.okf` resolves to
-   `available: false` and the guided migration **holds the whole scope**
-   (`lib/core.mjs:3251-3262`, `:1416`).
-
-## Why an OAS user cannot even find OATS
-
-- `@awebai/oats` and `@awebai/oats-pi` are **not yet published**. The
-  v0.22.0 release notes exist and the three manifests are aligned; what
-  remains is the tag and the publish (`.github/workflows/release.yml`, or
-  the runnerless lane in `scripts/release-lane.mjs`).
-- `@oas-framework/oas` is still live on npm (0.21.2 as of 2026-09-03) and
-  **not deprecated**, so the old CLI's `oas update` (which checks that
-  package) never learns OATS exists.
-- The old OAS desktop probes for `@oas-framework/oas`; the new desktop
-  requires `@awebai/oats >=0.22.0 <0.23.0` — old app and new CLI are
-  mutually invisible, so desktop must ship in the same release.
-
-## The plan (epic `aweb-abfy`)
-
-1. **Done.** `oats migrate` / `oats doctor` detect an OAS scope and fail
-   **loud** with the exact remedy (never exit 0 on "nothing to migrate" when
-   `oas-*` siblings exist). `detectOasScopes` in `lib/core.mjs`,
-   `discoverOasScopes` in `lib/packages.mjs`, wired in `bin/oats.mjs`;
-   tests in `test/oas-scope-detection.test.mjs`.
-2. **Done.** Catalog aliases `oas.*` → `oats.*` so legacy locks map instead
-   of holding — as *renaming* aliases (`{ "package": "oats.okf",
-   "capability": "oats.okf" }`), because the replacement packages export the
-   successor ids, never the legacy ones. All seven 0.20 ids are mapped in
-   `package-catalog.json`.
-3. **Done.** `oats migrate --from-oas`: one transactional command covering
-   all four breaks (section above), fixture built from the real deployment
-   shape, idempotent, byte-identical rollback on failure, with a migrated
-   scope reaching green `oats doctor` and spawns composing the knowledge and
-   messaging injections again (`test/from-oas-migration.test.mjs`).
-4. v0.22.0 release: notes and version alignment are **done**; remaining are
-   the tag, npm publish of `@awebai/oats` + `@awebai/oats-pi`, and the
-   desktop GitHub Release.
-5. `npm deprecate` the `@oas-framework/*` packages with a pointer here.
-6. Close the `oats-okf` / `oats-aweb` publication gates so migrated scopes
-   can restore their capabilities under the new ids.
-
-Until 4–6 are done, OAS users (this includes real daily users) should stay
-on `@oas-framework/oas` — it keeps working and loses nothing by
-waiting. The conversion command exists, but until the v0.22.0 release it is
-only reachable from a repo checkout, and until the satellite publication
-gates close the catalog's package refs are not a supported acquisition
-source for migrated scopes.
+Run the exact `oats trust <capability> --dir <scope>` commands printed by
+migration for the executable capabilities you approve. Trust does not
+transfer automatically. Verify the team ID and messaging membership with
+`oats aweb setup --dir /path/to/scope`, then exercise a real task, harvest,
+and retirement as described in [Run your first team](first-team.md).
+
+For a multi-repository deployment, start with one scope. The explicit
+`--recursive --dir /path/to/workspace` form converts every discovered OAS
+scope, with a separate transaction for each; it is not one transaction for
+the whole workspace.
+
+If you use Desktop, install [OATS Desktop](desktop.md) too. The old OAS
+Desktop discovers the old package name and cannot operate the new CLI.
+OATS Desktop 0.22.0 accepts kernel versions `>=0.22.0 <0.23.0`.
+
+## What the command converts
+
+One transaction covers two phases within a scope:
+
+1. Rename `oas-config.yaml` and `oas-lock.json` to their `oats-` names;
+   convert the `oas:` defaults key and catalog-mapped capability IDs;
+   rename installed `oas.json` manifests and soul scaffold-owner files.
+2. Convert the old lock to official package lockfile version 2, acquiring
+   the replacement artifacts and removing superseded installed directories.
+
+The catalog includes aliases for the seven OAS 0.20 capability IDs, mapping
+`oas.*` names to the corresponding `oats.*` packages and capabilities.
+Aliases guide migration; they are not runtime compatibility shims.
+Comments and unrelated configuration text are preserved, including old
+names in comments. Those comments can be updated separately.
+
+A failure in either phase restores that scope's original OAS bytes. A
+second successful run finds nothing to convert. `oats doctor` and migration
+commands identify visible OAS-named scopes and give a remedy rather than
+silently declaring an unmigrated deployment ready.
+
+## Compatibility and remaining transition work
+
+The migration fixtures were built from an OAS 0.20.x deployment. OAS
+0.21.x uses the same file names and configuration keys, but may lock package
+versions outside the OATS catalog's mapped line. Inspect the dry run before
+converting those scopes; do not replace an unmapped version by guessing.
+
+The old `@oas-framework/*` packages have not been deprecated as part of
+this rollout. Their update checks therefore do not announce the OATS
+rename; deprecation belongs to their maintainer. An existing OAS deployment
+can keep running until its own migration plan is ready. This is no longer a
+requirement to wait for OATS publication.
+
+See the [0.22.0 release notes](release-notes/v0.22.0.md) for the rename,
+package versions, and compatibility changes, and the
+[first-team qualification](first-team-demo.md) for current operating evidence.

package/docs/oats-config.schema.json

@@ -72,6 +72,7 @@
   },
   "type": "object",
   "properties": {
+    "yolo": { "type": "boolean", "description": "Skip Codex/Claude permission prompts. Closest scope wins; soul and launch overrides take precedence." },
     "name": { "type": "string" },
     "team": {
       "type": "object",

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.1.md

@@ -0,0 +1,106 @@
+# OATS v0.22.1
+
+A bounded reliability release, made from the first day of operating OATS on
+its own repository from the published 0.22.0 artifacts. Every item below was
+either reproduced during that run or found by the independent review that
+preceded it, plus the golden fixtures that guard the kernel's outputs and a
+release-workflow correction (a release with nothing to bump finishes rather
+than fails). The Desktop compatibility band (`>=0.22.0 <0.23.0`) already
+covers this kernel; no Desktop rebuild is needed.
+
+## Fixes
+
+- **`oats create` in a fresh scope no longer crashes.** After `oats init`,
+  the first `oats create` died with a raw stack trace because it demanded the
+  `agents/` directory that only `create` itself populates. It now bootstraps
+  the roster root at the enclosing repository, reports that once (and as
+  `agentsRoot` in `--json`), and the 0.22.0 workaround `mkdir agents` is no
+  longer needed.
+- **Spawn preflights executables and compensates every post-hook failure.**
+  A missing runtime binary or tmux was detected only after the home, worktree,
+  branch, and required capability hooks (an aweb identity) had been created,
+  and those throws bypassed compensation, leaving a branch, a worktree, and
+  remote state with no `instance.json` and no quarantine. The runtime binary,
+  tmux (when launching), and the task input are now checked before any
+  mutation, and one compensation path owns every failure after the spawn
+  hooks: retire hooks run once, Git topology is removed and verified, a
+  window that may have been created is stopped and verified before
+  credentials are touched, and unresolvable cleanup retains the home with
+  its receipt for a retryable `oats retire`. Six fault-injection tests cover
+  the paths.
+- **The turn record's stream lock is ownership-safe and bounded.** A late
+  contender could judge a live holder's lock stale by age and enter the same
+  critical section, and the old holder then unlinked whatever lock was in
+  place. The lock now carries an owner token; staleness is proven from the
+  holder's liveness, with age only as the fallback for a foreign-host or
+  tokenless lock; release removes only a lock the releaser owns; and every
+  failed acquire iteration passes one deadline check, so an unreadable lock
+  or a lock that cannot be removed fails with the underlying code and path
+  instead of spinning forever. Known limit, documented: a pid reused after a
+  reboot makes an abandoned lock read as held until an operator removes it.
+- **README claims match the implementation.** Native captured turns are
+  content-addressed, not signed; projected aweb mail and chat keep their
+  original signatures; capture covers Claude Code, Pi, and Codex transcripts
+  plus aw client logs on machines where `oats setup` ran, subject to the
+  ignore list. The contracts document and the turn-record specification say
+  the same.
+- **Bundled capabilities match their published tags.** The copies of the
+  official packages bundled under `capabilities/` claimed the published
+  version numbers but differed from the published payloads; the bundled
+  `oats.okf` still imported kernel internals and shipped an older harvester
+  layout. All six are now byte-identical to the tagged payloads (`oats.okf`
+  1.4.1, `oats.aweb` 1.8.0, `oats.jira` 1.0.0, `oats.linear` 1.0.0,
+  `oats.authoring` 1.0.0, `oats.review` 1.2.0 from `oats.dev` 1.0.0). Two
+  new tests guard it: no file under `capabilities/` may name kernel internals
+  or shell out to `oats root`, and every bundled manifest must carry the
+  version the catalog pins. The clean-room smoke asserts the same pin before
+  wrapping the bundled package, so it now proves the released package and
+  kernel combination. The bundled `oats.linear` README and test moved with
+  their package.
+
+## Documentation
+
+- **Run your first OATS team** (`docs/first-team.md`) is the tested path from
+  install to a real task, harvest, retirement, and a successor, with the
+  caveats the run met: the harvester runs in Pi even for Claude Code workers,
+  a Claude Code spawn needs two interactive confirmations today, and a
+  messaging layer entry that excludes a soul must state `global: true`.
+- **First-team example** (`docs/first-team-demo.md`) records what actually
+  happened on 2026-09-05: two workers, two promotions, one successor that
+  read its predecessor's promoted lesson.
+- **Migration from OAS** is rewritten from shipped state: the packages are
+  published, the seven catalog aliases exist, and the OAS npm deprecation
+  remains with its maintainer.
+- `docs/layers.md` is now the OATS contracts and `docs/integrations.md` the
+  binding guide; `docs/2026-09-03-architecture-proposal.md` records the
+  component model and the migration plan agreed with the framework's author.
+
+## Known operating limits and issues, not fixed here
+
+- The qualified `oats.okf` 1.4.1 configuration runs its harvester in Pi, so
+  a Pi-runnable model is required even for Claude Code workers.
+- A Claude Code worker's first launch can stop on Claude's folder-trust
+  prompt and on the aweb channel plugin's development-channels
+  confirmation; attach to the tmux session and answer them. A created
+  window is not evidence that the agent has started.
+- Retiring an instance reports its aweb identity deleted while the server
+  keeps the alias (aweb-aaum.6). Local cleanup is complete; the name cannot
+  be reused until an administrator removes the alias. Use a fresh
+  `--purpose` for successors.
+- The OKF harvester's default model assumes the `github-copilot` provider;
+  set `harvest-model` under the knowledge layer settings to a model your Pi
+  can run. A package change is proposed.
+- `oats spawn` resolves the roster root from the working directory, so from
+  a workspace root pass `--dir <repo>` even though `oats status --team`
+  lists the souls.
+- `oats status` lists the retirement-baselines directory as a phantom
+  instance, retire leaves that baseline file behind, and `oats retire --json`
+  prints a bare object rather than the schema-v1 envelope. Tracked; each
+  changes a golden fixture deliberately.
+
+## Install
+
+```bash
+npm install -g @awebai/oats@0.22.1
+pi install npm:@awebai/oats-pi@0.22.1
+```

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.