@awebai/oats 0.29.4 → 0.30.1

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

@@ -24,16 +24,15 @@ bundled `capabilities/oats-aweb` is the tag's tree.
 - **An agent playbook.** The new `oats-aweb` skill carries the playbook, and
   the inject is shorter and points to it. `oats aweb roster --label <label>`
   is new.
-- **Deferred to 1.16: per-workspace personal-team enrollment.** It needs a
-  per-deployment login and a recorded owner. 1.15 makes no `aw auth` or
+- **No per-workspace personal-team enrollment.** 1.15 makes no `aw auth` or
   `aw team ensure` call, and the primary team resolves as in 1.14.2. A
   host-set `settings.oats.aweb.roots.personal` is ignored with the readiness
   warning `personal-root-deferred`.
 
 ## Desktop
 
-- **Line counts on the Changes rows** (#245, #246). The server passes kernel
-  #238's per-file counts through, and each W6 Changes row ends with "+84 −3",
+- **Line counts on the Changes rows** (#245, #246). The server passes the kernel's
+  per-file counts (#238) through, and each Git & GitHub Changes row ends with "+84 −3",
   or "binary". An unknown count (untracked, submodule) and older kernels show
   nothing, never "+0".
 - **The Git & GitHub tab counts unresolved review threads** (#247). The tab and

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

@@ -0,0 +1,205 @@
+# OATS 0.30.0
+
+## Upgrade
+
+> **BREAKING: 0.30.0, oats.aweb 1.17 and oats.framework 1.4.0 move in
+> lockstep.** oats.aweb 1.17 and oats.core / oats.setup 2.2.0 require
+> `oats >=0.30.0` (`E_CAPABILITY_INCOMPATIBLE` on an older kernel), and 0.30
+> refuses the 0.29 team keys.
+
+**The workspace** (by PR). 0.30 refuses these keys with `E_WORKSPACE_SCHEMA`
+(reason `removed-key`, naming the replacement): `messaging.byTeam`,
+`defaults.byTeam`, `external[].team`, `soul.yaml` `team:` and
+`oats-membership.yaml` `team`. 0.29.4 accepts their removal, so remove them
+first. Then move the pins to `oats.framework: v1.4.0`, `oats.aweb: v1.17.1`,
+`oats.okf: v4.0.4`, and replace `oats.dev` with `oats.engineering: v1.1.0`.
+
+**Each deployment:**
+
+1. **Upgrade the CLI**: the npm package `@awebai/oats`, the pi adapter and the
+   Desktop, all 0.30.0. Then run `oats sync`.
+2. **Remove `settings.oats.aweb.team`** from `oats-local.yaml`: teams are
+   now `oats teams` and `oats soul teams`, and oats.aweb 1.17 refuses the
+   setting.
+3. **Run setup** from the deployment: `oats aweb setup --soul <soul>`, with
+   any soul that has messaging. Plain `oats aweb setup` outside an instance
+   home is refused. With an existing messaging root, setup names the team the
+   root is in: record it with `oats teams add <label> --team <id>` (the first
+   team becomes `defaultTeam`). With no account:
+   `oats aweb setup --soul <soul> --username <u>`.
+4. **Join the teams you share**: ask the owner for an invite, then
+   `oats aweb setup --soul <soul> --join <label> --invite <token>
+   [--service <url>] [--name <alias>]`. A half-finished join resumes with
+   `--join <label> --service <url>` and no new invite. Until the flag day,
+   declare the team here as a local team: `oats teams add <label> --team <id>`.
+5. **Put souls in teams here**, in place of the removed `team:`:
+   `oats soul teams '*' --add <label>` or `oats soul teams <soul> --add <label>`.
+6. **Trust the workspace automations this host runs** (a host that runs
+   workspace triggers or schedules): add them to `oats-local.yaml`
+   `automations.trust` (`<member>/<id>` entries, or `"*"`). Until then they
+   do not run; `oats workspace status` names each missing line.
+7. **Check**: `oats teams`, and `oats readiness --soul <soul>` shows no team
+   problem in `checks.configured`.
+
+**The flag day.** Commit a shared team's id in `oats-workspace.yaml`, and add
+`launch:` to a committed soul, only once every deployment of the workspace
+runs 0.30. 0.29.4 refuses both: members are read at their latest commit, and
+its schemas reject the unknown keys.
+
+**A deployment still on 0.29.4** has a bundled catalog that does not know
+`oats.engineering`, so its bare-version pin is `E_PACKAGE_MISSING`. Until it
+upgrades, set `OATS_PACKAGE_CATALOG` to a catalog file that lists it, such as
+0.30.0's `package-catalog.json`.
+
+## Team model v2
+
+- **Teams are local to each deployment.** `oats-local.yaml` holds the local
+  teams (`teams.<label>: { team, description? }`), `defaultTeam`, and which
+  teams each soul may join here (`souls.teams`, `"*"` for every soul, plus an
+  optional `souls.default` per soul). Nothing committed says who is in a team.
+- **A shared team is committed** in `oats-workspace.yaml` `teams:` **with its
+  provider id**. One declared without an id is `team-unmapped`: its owner
+  creates it and commits the id. A label in both files is
+  `team-label-collision`, a warning, and the shared definition wins.
+- **A spawn joins the default team only.** Every other eligible team is opt-in
+  per instance: `--provider oats.aweb join=<labels>` at spawn, the Desktop's
+  checkboxes, or the provider's join and leave verbs later.
+- **A leave is never silent.** A joined team that is no longer eligible is
+  left on the next live read; a newly eligible team is offered, never joined.
+  A team a soul no longer lists is left automatically on hosted teams. On a
+  team you control (BYOT, namespace-controlled), aw cannot release the member
+  from the instance, so the leave is reported (a launch warning and an
+  `aweb-team-leave-failed` instance event) and the team's owner removes the
+  member.
+- **`oats teams`** lists this deployment's teams, ids, default and problems;
+  `add <label> --team <id>`, `remove <label>` and `default <label>` edit
+  `oats-local.yaml` only. `remove` refuses a referenced label
+  (`E_TEAM_IN_USE`) or a shared one (`E_TEAM_SHARED`).
+  **`oats soul teams <soul>|'*'`** takes `--add`, `--remove`, `--default` and
+  `--clear-default`. Neither verb calls the provider.
+- **`oats aweb setup`** creates and joins provider teams:
+  `--soul <soul> --create <label> --namespace <domain>` creates a team you
+  control and records it as a local team; `--soul <soul> --join <label>
+  --invite <token>` joins an existing one. Each team gets its own messaging
+  root (`settings.oats.aweb.roots.<team id>`).
+- **Readiness** reports team problems in `checks.configured`:
+  `E_TEAM_UNCONFIGURED`, `team-unmapped`, `team-label-collision`, and
+  `default-team-changed` for a running instance. An undeclared label is
+  `E_TEAM_UNKNOWN`.
+- **Providers** receive `OATS_DEFAULT_TEAM`, `OATS_DEFAULT_TEAM_ID`,
+  `OATS_DEFAULT_TEAM_FROM`, `OATS_TEAMS` and `OATS_TEAMS_SOURCE`. The 0.29
+  names `OATS_TEAM_LABEL`, `OATS_TEAM_LABELS` and `OATS_TEAM_ID` are unset.
+
+## Soul launch preferences
+
+- **A soul may declare `launch: { harness, model? }`** in `soul.yaml`
+  (`pi`, `claude` or `codex`); only a harness and a model.
+- **`oats-local.yaml` `souls.launch` overrides it on this machine**: `"*"` for
+  every soul or one soul's entry, each a launch configuration's name or an
+  inline `{ harness, model? }`.
+- **Precedence for a new launch:** `--launch-config` or `--harness`, then
+  `souls.launch.<soul>`, then `souls.launch."*"`, then the soul's `launch:`,
+  then `pi` with its defaults. `--model` alone keeps the deciding layer's
+  harness. A missing harness is `E_HARNESS_UNAVAILABLE`, naming the layer
+  and the fix; there is no fallback.
+- **A home's recorded launch stays frozen.** A changed preference reaches it
+  only with `oats session start|restart --reselect-launch` or a respawn;
+  `oats readiness --home` warns `launch-changed`. `session start|restart
+  --model` keeps the recorded harness and replaces only the model (#294).
+- `oats souls`, `oats inspect --soul` and `oats spawn … --preview` show each
+  soul's `launch` and which layer decided it.
+
+## Changed
+
+- **A host runs a workspace trigger or schedule only when its
+  `oats-local.yaml` trusts it** (`automations.trust: [<member>/<id>]` or
+  `"*"`). Hosts that ran workspace automations must add their trust lines;
+  `oats workspace status` names each missing line (#300).
+- **`key` on `oats souls` rows and `oats status` agent rows**: the soul's name
+  as `souls.teams` and `souls.launch` take it (`<package>/<soul>` for a
+  package soul).
+- **A team id must be safe**: no leading `-`, no whitespace or control
+  characters, at most 256 characters.
+- **The teams verbs edit only their own entries** in `oats-local.yaml`;
+  comments survive.
+
+## Fixed
+
+- **An opted-in second team (`join=`) now yields a connected, usable
+  identity** (oats.aweb 1.17.1). It never did against a real aw before.
+- **A newcomer can join a shared team** (oats.aweb 1.17.1): `oats aweb setup
+  --join <label> --invite <token>` takes `--service <url>` and `--name <alias>`,
+  and a half-finished join resumes without a new invite.
+- **A lost team, or a retire, on a team you control hands the owner the exact
+  cleanup command** (oats.aweb 1.17.1), in place of a silent leftover member.
+- **Knowledge readiness is answered.** oats.okf 4.0.4 answers the kernel's
+  documented readiness check; on 0.29.x it was `unknown`.
+- **`oats session start` and `restart` show the launch hooks' warnings**, as
+  spawn does (#295): JSON `warnings`, always present, and each is kept as a
+  `launch-warning` instance event.
+- **`oats readiness --soul` and `oats inspect --soul` materialise the soul's
+  copy at the resolved commit first**, as spawn does, so a soul not yet
+  spawned at this commit no longer reads as a missing declaration (#298).
+- **`oats retire` can retire a home from before 0.25.9 whose session is
+  gone**: only when the recorded window or server is gone AND no live process
+  works in the home; anything live or unclear still refuses, `--force`
+  included (#299).
+
+## Known in 0.30.0
+
+The first two are fixed in 0.30.1; the last is how aw works on a team you
+control.
+
+- With no teams configured, a spawn is refused by the provider
+  (`E_SPAWN_FAILED`, relaying "no teams configured: run `oats aweb setup`"),
+  not by the kernel's `E_TEAM_UNCONFIGURED`.
+- A capability operator command run from a deployment needs `--soul <soul>`.
+- On a team you control (BYOT, namespace-controlled), retiring an instance, or
+  a spawn that rolls back, deletes its workspace but cannot revoke its
+  membership; its alias stays on the team, and the retire prints the owner's
+  exact `aw id team remove-member` command (and records it as
+  `pendingControllerCleanup`). Hosted teams release automatically.
+
+## Packages
+
+- **oats.framework `oats-framework/v1.4.0`**: oats.core 2.2.0 and oats.setup
+  2.2.0 require `>=0.30.0` and teach the team model v2 and onboarding through
+  `oats aweb setup`.
+- **oats.aweb `v1.17.1`** (from 1.16.0): one aw floor, `>=1.36.13` (1.16.1);
+  the kernel's teams, with no provider `team` setting (a stale one is refused)
+  and one root per team; setup's `--create` and `--join`; the teams
+  document's shared/local `from`, `warnings[]` and recently left teams; the
+  newcomer's first `--join`, `--soul` on operator commands, the
+  `aweb-team-leave-failed` event and the second-team fix (1.17.1); in 1.17.1
+  also the resumable `--join` with `--service`/`--name`, the owner's cleanup
+  command on a team you control, and a stale `team` setting refused only
+  where teams are chosen, so retire still cleans up.
+- **oats.okf `v4.0.4`** (from 4.0.1): the harvester and maintainer live in the
+  default team, with no `okf` team (4.0.2); consultation works with harvest
+  off (4.0.3); readiness is answered (4.0.4).
+- **oats.engineering `v1.1.0` replaces oats.dev**, which is retired along with
+  its catalog aliases (`oats.review`). It ships `oats.engineering-expert`,
+  `oats.developer`, `oats.code-review` and the `code-reviewer` package soul.
+
+## Desktop
+
+- **A Workspace Teams tab** (#270), before Souls: this computer's teams and
+  default, with add, remove and default. A soul page has Teams here (#277),
+  the spawn dialog shows the fixed default team and unchecked opt-in boxes,
+  and an unmapped default team blocks the spawn with its fix.
+- **The teams panel** shows each team as shared or local, the provider's
+  warnings (#286), recently left teams (#270), and a join or leave warning
+  under its row (#282). Readiness team items say where the team is declared.
+- **The Spawn view groups souls by their default team** and chips their
+  teams, the default first (#285).
+- **Each soul's harness and model again**, with what chose them (#289), and
+  a session card says where a model set on this computer came from (#293).
+- **Readiness shows `launch-changed`** for a home whose launch preference
+  moved, and the Desktop's readers accept any team id the kernel accepts
+  (#292).
+- **One Automations item** with Schedules and Triggers subtabs (#267).
+- **Untrusted workspace automations** need attention: the row reads "Not
+  trusted here" and shows the kernel's line to add, and Setup shows each
+  trust warning with its remedy (#301).
+- **The spawn dialog says the kernel's missing-harness fix once** (#302).
+- The Desktop accepts OATS CLIs `>=0.25.8 <0.31.0`.

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

@@ -0,0 +1,123 @@
+# OATS 0.30.1
+
+## Fixes
+
+- **Desktop: an instance-less soul no longer takes the whole roster down.**
+  `oats status --json` reports an agent row's `key` as `null` when no instance
+  records a workspace soul, as the roster contract documents. That happens for a
+  soul directory with no instances: after a spawn preview of a soul that has
+  never been spawned, or after its last instance is retired. The 0.30.0 Desktop
+  accepted only a string there, so one such row rejected the whole observation
+  with `E_CLI_PROTOCOL` ("The installed OATS CLI returned an invalid deployment
+  observation"). The Desktop now accepts `null` and still refuses any other
+  type.
+- **Knowledge readiness answers, fast.** With oats.okf 4.0.5, `oats readiness`
+  answers the knowledge check from okf's cache in the knowledge `stateDir`, well
+  inside the kernel's 30 s cap, instead of cloning every base and timing out as
+  `unknown` (measured: 7 s against 35 s and `unknown` before). A base that is
+  not cached yet, out of date or unreachable is reported as a named warning or
+  problem, never `unknown`. A spawn with harvest off fills the cache, spending at
+  most 20 s per base, and still refuses a soul that names a node its base does
+  not have.
+- **Desktop: a stored workspace selection the server no longer serves** (a
+  deleted deployment) locked the Desktop out: every roster refresh refused the
+  server's reply as "belongs to a different workspace", and the switcher
+  already showed the served workspace as active. A selection that is not
+  among the served workspaces is now treated like an empty one: both rosters
+  adopt the served workspace and the stored selection is replaced. A
+  selection the server does serve, answered with another workspace, is still
+  refused.
+- **Desktop: terminal tabs are back to native geometry.** 13px system
+  monospace, xterm's default line height, and 32px side gutters with no
+  vertical inset, as before Redesign v3. The block cursor is one cell tall
+  again. A font size you chose yourself is kept.
+- **Desktop: the spawn dialog could stay on "Reading defaults…" forever.**
+  A routine roster refresh restarted the spawn preview while it was still
+  being read, so on a machine where the preview takes several seconds it
+  never finished. The dialog now re-reads only when a fact the preview
+  depends on changes.
+
+## Packages
+
+- **oats.okf 4.0.5** (was 4.0.4 in 0.30.0): the knowledge readiness fix above.
+- **oats.engineering 1.3.0** (was 1.1.0 in 0.30.0).
+  - 1.2.0: the packaged `code-reviewer` launches on Codex with `gpt-6-astra` by default, a different model family from the developers it reviews. A machine without the `codex` binary gets `E_HARNESS_UNAVAILABLE` when it spawns `code-reviewer`, until it installs Codex or overrides the preference (`oats-local.yaml` `souls.launch`, or `--harness`/`--model` at spawn).
+  - 1.3.0: review happens on local branches, before the PR. The developer runs its adversarial loop with the `code-reviewer` on its local branch and hands the reviewed branch to its expert. The expert reviews that branch, and only when it accepts is a PR opened. A returned branch's delta goes back through the same reviewer first.
+
+## Changed
+
+- **Desktop: calmer selection, focus and search fields.** A selected segment
+  (Group by, List/Graph and similar) now uses the brand tint instead of
+  white-on-grey. Clicking a button, tab or row no longer draws a focus ring.
+  Keyboard focus stays visible as the tint plus a thin accent edge, not a
+  2px ring. Search and filter fields have a single border that turns accent
+  on focus, with no inner ring.
+  Sidebar instance rows are more compact, with a gap between highlighted rows,
+  and an instance's pull request number sits before its branch name instead of
+  on its own line.
+- **The official workspace lists each package capability once.** The `oats`
+  repository kept byte mirrors of the official packages' capabilities
+  (`oats.okf`, `oats.aweb`, `oats.jira`, …) under `capabilities/`, so `oats
+  capabilities` in the official workspace also listed each of them as a member
+  capability of `github.com/awebai/oats`, beside its package. The mirrors now
+  live in `mirrors/`, which member discovery does not read, and the npm
+  package no longer carries them (nothing read them at runtime: capabilities
+  resolve from Git at the locked commit). No operator action.
+- **Desktop: clearer Workspace views, and Spawn goes straight to the soul.**
+  Soul cards label their facts ("Team oats", "No instances" instead of a
+  bare "none"), group by repo by default, and keep a compact Spawn on the
+  instances line. Capabilities are compact one-line row cards with a
+  kind-coloured tile, their source and who uses them; a row opens the
+  capability page with the full description. Teams show one card per team,
+  split into shared and this-computer sections. Spawn on a soul card or the
+  soul page opens the spawn dialog for that soul, with a "What will be
+  created" preview (core capabilities and capabilities with their sources);
+  "Change soul" returns to the picker.
+- **Two Desktop souls.** The `oats-desktop-designer` soul is removed.
+  `oats-desktop-expert` now owns Desktop's UX and design direction as well as
+  its product rationale, and `oats-desktop-developer` builds all of
+  `packages/desktop`, including renderer views, styles, themes and copy.
+  Running designer instances keep working until they are retired; `oats
+  status` reports their soul as no longer present.
+- **The legacy Desktop soul trees are removed.** `agents/oats-desktop-engineer`
+  and `agents/ux-designer` were no longer offered souls. The
+  `oats-desktop-expert` knowledge node carries their durable rationale.
+- **The remaining legacy soul trees are removed.** `agents/cli-dev`,
+  `dev-coordinator`, `docs-expert`, `integrations-expert`, `lead`,
+  `oats-coordinator` and `oats-expert` were pre-v2 soul bundles, not offered
+  souls; the offered souls live in `souls/` and the packages. Their bundled
+  knowledge gate (`npm run validate:okf`) goes with them: the souls' knowledge
+  lives in the central knowledge base, which validates itself.
+- **Desktop: a calmer instance panel.** The summary bar under the terminal
+  (harness, tmux target, team marks, Details, Focus mode) is gone, and the
+  terminal gets its height. A panel toggle at the end of the tab bar shows or
+  hides the instance panel (⌥⌘B, Ctrl+Alt+B on Linux and Windows; also in the
+  command palette). Focus mode stays in the palette; in focus mode the panel
+  toggle and the sidebar's edge button stay visible and leave it. The Instance
+  tab drops Built from and Details. When the kernel reports drift, its header
+  shows an "older build" chip whose tooltip says what changed and that
+  re-spawning picks up the new state. Where it works is one card: the work mode
+  in plain words, then repo, branch and home. Messaging is a compact list of
+  teams, with an icon refresh and the identity address on its own line. The Git
+  & GitHub tab is now the Developer tab; it shows branch, changes and pull
+  request cards; the branch line says how far it is from main and, when it has
+  an upstream, how many commits are unpushed. An instance without Git by design
+  (directory or workspace mode) gets a calm "No Git for this instance" note
+  instead of a red error; a worktree that has gone missing still reports its
+  error.
+- **The official workspace's souls declare launch preferences.** Its experts,
+  developers and setup admin prefer Claude Code with Opus 5.5 (`launch:` in
+  each `soul.yaml`); each machine can override them in `oats-local.yaml`
+  `souls.launch`, and spawn flags win over both.
+
+## Still known in 0.30.1
+
+The 0.30.0 notes said the first two below would be fixed in 0.30.1. They are
+not in this release, and are planned for 0.30.2.
+
+- With no teams configured, a spawn is refused by the provider
+  (`E_SPAWN_FAILED`, relaying "no teams configured: run `oats aweb setup`"),
+  not by the kernel's `E_TEAM_UNCONFIGURED`.
+- A capability operator command run from a deployment needs `--soul <soul>`.
+- On a team you control (BYOT), retire cannot revoke membership; the retire
+  prints the owner's `aw id team remove-member` command, as in 0.30.0.