@awebai/oats 0.29.4 → 0.30.0

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`.