@awebai/oats 0.37.0 → 0.38.0

package/docs/packages.md

@@ -51,7 +51,7 @@ packages:
 - **Bare version** (`v4.1.1`, `4.1.1`, `1.0.0-rc.1`): the id is looked up in
   the official catalog — `package-catalog.json` in the `oats` repo, or the file
   named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
-  convention (`v4.1.1` or `oats-framework/v1.4.3`) and the payload path. An id
+  convention (`v4.1.1` or `oats-framework/v1.5.0`) and the payload path. An id
   the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
   a package outside the catalog"). The catalog is the reviewed official list
   ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,9 +74,9 @@ members:
   - git:github.com/acme/agents
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.4.3
+  oats.framework: v1.5.0
   oats.okf: v4.1.1
-  oats.aweb: v1.18.1
+  oats.aweb: v1.19.0
 teams:
   platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
 defaults:
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
 ## `oats package add | remove`
 
 ```bash
-oats package add oats.aweb v1.18.1                         # a catalog version
+oats package add oats.aweb v1.19.0                         # a catalog version
 oats package add acme.tools git:github.com/acme/tools@v0.4.0
 oats package remove acme.tools
 ```
@@ -247,8 +247,9 @@ oats-package/
   souls; otherwise `E_SOUL_AMBIGUOUS` names each qualified form
   (`details.qualified`). A member soul's qualified form is `<member name>/<soul>`.
 - **Resolved** like any soul: the workspace defaults apply, `off` and
-  `<slot>: none` work, its teams here are keyed `<package>/<soul>` in
-  `oats-local.yaml` `souls.teams`, and `from: here` means **this package** at the locked commit
+  `<slot>: none` work, its teams are keyed `<package>/<soul>` (or `<package>/*`)
+  in the workspace's `souls:` (unlisted, it joins its default only), and
+  `from: here` means **this package** at the locked commit
   (a capability it does not provide is `E_CAPABILITY_MISSING`).
 - **Spawned** at the locked commit: the soul is fetched into the per-commit
   soul cache and its digest must equal the lock's (`E_PACKAGE_INTEGRITY
@@ -332,11 +333,11 @@ A soul that names one of the package's capabilities with
   "policy": "docs/official-catalog.md",
   "packages": {
     "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.1.1", "path": "oats-package" },
-    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.4.3", "path": "oats-package" }
+    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.5.0", "path": "oats-package" }
   }
 }
 ```
 
-`ref` carries the tag convention: a workspace's `oats.framework: v1.4.3`
-resolves to tag `oats-framework/v1.4.3`. Resolving through the catalog never
+`ref` carries the tag convention: a workspace's `oats.framework: v1.5.0`
+resolves to tag `oats-framework/v1.5.0`. Resolving through the catalog never
 advances a lock by itself: `oats sync` does, and says so.

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

@@ -0,0 +1,128 @@
+# OATS 0.38.0
+
+## Changed (breaking)
+
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.39.0`**, so it runs against
+  this release's kernel. Install the CLI and the Desktop 0.38.0 together: the
+  Desktop 0.37.x refuses a 0.38 CLI.
+
+- **Team model 3: the teams a soul may join, and its default, are committed
+  in the workspace** (awebai/oats#484; feature `team-model-3` replaces
+  `team-model-2`). An instance in two teams is a bridge between them, so which
+  teams an organisation's instances may be in is now its decision, committed
+  in `oats-workspace.yaml` and closed by default. This prevents accidental
+  joins and makes the intended team set reviewable in git; it does not stop a
+  deliberate relay by someone holding credentials for two teams (see
+  docs/design/2026-10-02-team-model-3.md).
+  - `oats-workspace.yaml` `defaultTeam`, `localTeams` and `souls:` (accepted
+    since 0.36.1) now apply. `souls:` keys are `"*"`, `<member|package>/*` and
+    `<member|package>/<soul>`; the most specific key gives a soul's teams
+    outright (lists never merge), and the most specific key that sets one
+    gives its default: `a/*: {default: security}` and `a/x: {teams: [docs]}`
+    give `a/x` the default `security` and the teams `[docs]` only. `teams:
+    any` is every shared team. A soul no key matches has its default only,
+    package souls included.
+  - A soul's default team is its `souls:` default; else the deployment's
+    `oats-local.yaml` `defaultTeam`, only when the workspace says
+    `localTeams: true`; else the workspace's `defaultTeam`; else none.
+    `defaultTeam.from` and `OATS_DEFAULT_TEAM_FROM` are `soul`, `deployment`
+    or `workspace`; `soul` now means the workspace's `souls:` default (it was
+    the local `souls.default`).
+  - A soul may join its default, its `souls:` teams and, with
+    `localTeams: true`, every local team. Every team row carries `via`
+    (`default`, `workspace`, `local`), in reports, `OATS_TEAMS` and
+    `instance.json`.
+  - `oats-local.yaml` `souls.teams` and `souls.default` are refused
+    (`E_WORKSPACE_SCHEMA`, reason `removed-key`). The refusal names each key
+    and prints the `souls:` to commit instead (`details.replacement`); `oats
+    doctor` answers with it.
+  - `oats-local.yaml` `teams` and `defaultTeam` are refused unless the
+    workspace says `localTeams: true` (`E_WORKSPACE_SCHEMA`, reason
+    `local-teams-closed`, naming both fixes). Spawn, preview and inspect
+    refuse; `oats teams`, readiness and `oats doctor` (offline, from the cached
+    workspace file) report it as a failure. The standalone view allows them.
+  - `oats teams add` and `oats teams default` are refused where local teams
+    are closed; `oats teams remove` still works there. `oats soul teams` is
+    read only: `--add`, `--remove`, `--default` and `--clear-default` are
+    `E_BAD_ARGS`, naming `souls:` in `oats-workspace.yaml`.
+  - `oats teams --json` is `teamsApi: 2` (`localTeams`, a `DefaultTeam`, the
+    workspace's `souls:`) and now discovers the workspace's souls; `oats soul
+    teams --json` is `soulTeamsApi: 2` (`key` is the qualified soul key,
+    `match` and `defaultMatch` name the `souls:` keys that applied).
+  - New readiness items: local-teams-closed (failure) and `team-soul-unknown`
+    (a warning for a `souls:` key that names no soul of the workspace).
+    `team-model-3-migration` is retired, and the kernel no longer reports
+    `E_TEAM_NOT_ELIGIBLE` (a soul's default is always eligible).
+  - Shapes: docs/desktop-cli-api.md, under Teams.
+- **The Desktop follows team model 3.** With a 0.38 CLI (feature `team-model-3`) the Workspace ›
+  Teams page shows the workspace's `souls:` read only, and offers Add and Make default for local teams
+  only where the workspace says `localTeams: true`; where it doesn't, a local team still in
+  `oats-local.yaml` keeps Remove under the kernel's local-teams-closed message. A soul's *Teams here* is
+  read only: it says where the soul's default and teams come from and that they change as `souls:` in
+  `oats-workspace.yaml` (a PR to the workspace file). The Desktop never sends the removed `oats soul
+  teams` edit flags, and a 0.37 or older CLI keeps the team model v2 views.
+- **oats.aweb 1.19.0** (catalog and workspace pin, and the bundled mirror),
+  for team model 3. A default team that comes from the workspace's
+  `defaultTeam` is reported as `from: "workspace"` in `oats aweb teams --json`
+  and the recorded meta (1.18 reported it as `deployment`). `oats aweb setup
+  --create` asks the kernel whether the workspace allows local teams before it
+  creates anything; where it does not, it creates the team and its per-team
+  root, records no local team, and prints the `teams:` entry (and
+  `defaultTeam:`) to commit in `oats-workspace.yaml`, or the `localTeams: true`
+  alternative. `--username` and setup's other advice say the same where local
+  teams are closed, and an unmapped default's remedy names `defaultTeam:` in
+  the workspace file. Joining stays limited to the eligible `OATS_TEAMS` rows.
+
+- **oats.framework 1.5.0** (oats.core 2.3.0, oats.setup 2.3.0; catalog and
+  workspace pin `oats-framework/v1.5.0`): the skills
+  describe team model 3. `oats-teams`, `oats-workspace-config`,
+  `oats-setup-model`, `oats-onboarding` and the setup inject say a soul's teams
+  and default are committed in `souls:` of `oats-workspace.yaml`, local teams
+  only with `localTeams: true`; `oats-operate` and `oats-souls` say where an
+  instance's teams come from.
+
+## Upgrade
+
+Before upgrading a deployment, its workspace must say what its
+`oats-local.yaml` said. 0.36.1 and 0.37.x already accept the workspace keys,
+and their `team-model-3-migration` warnings list what each deployment has to
+move.
+
+1. **In the workspace file** (a PR, once everyone who reads it runs 0.36.1 or
+   later):
+   - commit `souls:` entries for what the deployments' `souls.teams` and
+     `souls.default` said. A v2 soul's teams were its default, `"*"`'s teams
+     and its own, and patterns never merge, so a soul's own entry lists
+     `"*"`'s teams too. Qualify bare soul names with their member's name
+     (`<member>/<soul>`, as `souls.disabled` names it). Running 0.38.0 against
+     an unmigrated `oats-local.yaml` prints this snippet for you;
+   - commit `defaultTeam: <label>` when the deployments' default is a shared
+     team;
+   - for local (personal) teams and a local default, choose: (a) keep them
+     personal, with `localTeams: true`; or (b) commit them in `teams:` (and the
+     default as `defaultTeam:`).
+2. **In each `oats-local.yaml`**, when the deployment moves to 0.38.0: remove
+   `souls.teams` and `souls.default`, and, under (b), the local `teams` and
+   `defaultTeam` (`oats teams remove` works while local teams are closed).
+3. **Check:** `oats teams` lists no problems, and `oats spawn <soul>
+   --preview` shows each soul's `defaultTeam` and `teams` as intended. Running
+   instances keep their spawn-time default; readiness reports
+   `default-team-changed` where it moved, and a respawn follows it.
+
+What each kind of deployment changes:
+
+- **A workspace whose people keep personal teams or a personal default** (for
+  example awebai/oats): `localTeams: true`, plus `souls:` for the souls'
+  shared teams (e.g. `"*": { teams: [oats] }`); drop `souls.teams` locally.
+- **A workspace whose default team is a committed shared team**: commit
+  `defaultTeam: <label>` and the `souls:` entries; drop the local
+  `defaultTeam` (and any `souls.*` team keys).
+- **A standalone deployment**: nothing changes for local teams and the local
+  default; drop `souls.teams` and `souls.default` (a standalone view has no
+  `souls:` patterns: every soul may join every local team).
+
+Consumers: the Desktop's team views read `teamsApi: 1` / `soulTeamsApi: 1` and
+edit through `oats soul teams --add`; they follow in their own change. Another
+messaging provider receives `OATS_DEFAULT_TEAM_FROM=workspace` and `via` on
+the `OATS_TEAMS` rows; one that records local teams with `oats teams add` needs
+the workspace to allow them (oats.aweb 1.19.0 does both, above).

package/docs/souls-and-instances.md

@@ -164,8 +164,8 @@ composed skills and instructions, a spawn records:
     "key": "github.com/acme/agents", "commit": "3f2a9c1e…", "resolution": "20ec8ec527311d71d0973086",
     "soul": { "repoKey": "github.com/acme/agents", "commit": "3f2a9c1e…" }
   },
-  "teams": [{ "label": "ana-acme", "team": "ana-acme:ana.aweb.ai", "default": true, "from": "local" },
-            { "label": "engineering", "team": "engineering:acme.aweb.ai", "default": false, "from": "shared" }],
+  "teams": [{ "label": "ana-acme", "team": "ana-acme:ana.aweb.ai", "default": true, "from": "local", "via": ["default", "local"] },
+            { "label": "engineering", "team": "engineering:acme.aweb.ai", "default": false, "from": "shared", "via": ["workspace"] }],
   "defaultTeam": { "label": "ana-acme", "team": "ana-acme:ana.aweb.ai", "from": "deployment" }
 }
 ```
@@ -183,7 +183,8 @@ composed skills and instructions, a spawn records:
   compares `workspace.soul` with the member's current commit too: `soul: <name>
   from <member> @ <c7>  [member moved since …]` (`--json`: `instances[].soul`).
 - `teams` / `defaultTeam`: the soul's teams at spawn, exactly as the providers
-  received them (mapped teams only) and its default: evidence, never rewritten.
+  received them (mapped teams only, each with `via`: why the soul may join it)
+  and its default: evidence, never rewritten.
   A running home's hooks and messaging commands read the teams live
   ([capabilities.md](capabilities.md#teams-in-the-provider-environment)).
 

package/docs/workspaces.md

@@ -35,7 +35,7 @@ workspace commit. Schemas: [`oats-workspace.schema.json`](oats-workspace.schema.
 [`oats-membership.schema.json`](oats-membership.schema.json),
 [`soul.schema.json`](soul.schema.json), [`oats-local.schema.json`](oats-local.schema.json);
 the lock's format is in [packages](packages.md#lock-v3). The JSON schemas encode
-shapes; domain rules (declared teams, duplicate members, canonical `from:` keys,
+shapes; domain rules (labels that are shared teams, duplicate members, canonical `from:` keys,
 the two `packages:` value forms) live in the kernel's `validateWorkspace` /
 `validateSoul`, which are the authority.
 
@@ -54,13 +54,16 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
   - git:github.com/acme/tools              # a member that ALSO publishes a package (see below)
 
 packages:                                  # the ONLY versioned things
-  oats.framework: v1.4.3                   # bare version → resolves through the official catalog
+  oats.framework: v1.5.0                   # bare version → resolves through the official catalog
   oats.okf: v4.1.1
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 
 teams:                                     # SHARED teams: the same provider team for everyone
   engineering: { description: Platform and release automation, team: "engineering:acme.aweb.ai" }
   reviewers:   { description: Code review }   # declared, not created yet (no `team` id): readiness team-unmapped
+defaultTeam: engineering                   # the workspace's default team; see Teams below
+souls:                                     # which teams each soul may join besides its default
+  platform/*: { teams: [reviewers] }
 
 defaults:
   capabilities:
@@ -146,7 +149,8 @@ its content digest.
 ### `oats-local.yaml`: the only per-machine file
 
 Which workspace this machine realizes, where member clones live, host-owned
-provider settings, this deployment's local teams and team membership, host
+provider settings, this deployment's local teams and default (where the
+workspace allows them), host
 facts for automations, and launch configurations. The full reference is
 [configuration.md](configuration.md).
 
@@ -308,89 +312,130 @@ Harnesses start normally, with their own skill discovery intact
 
 ## Teams
 
-A team is a messaging-provider team (for oats.aweb, an
-aweb team id `<team>:<namespace>`) under a **label**. Two files declare them:
-
-- **Shared teams**: the committed `oats-workspace.yaml` `teams.<label> =
-  { description?, team? }`: the same provider team for everyone, edited by a PR.
-  A shared team without `team` is declared but not created yet (readiness
-  `team-unmapped`): its owner creates it with the messaging provider, then
-  commits the id.
-- **Local teams**: the deployment's `oats-local.yaml` `teams.<label> = { team,
-  description? }`: a team only this deployment uses (a personal team). A label in
-  both files is `team-label-collision` (a warning); the **shared** definition
-  wins, and the fix is renaming the local label.
-
-`oats-local.yaml` also says which teams each soul belongs to **here**:
-
-- `defaultTeam: <label>`: the team every instance of this deployment lives in
-  (its default-team identity);
-- `souls.teams`: `"*"` for every soul, and a soul's own entry (its bare name, or
-  `<package>/<soul>` for a package soul) adds to it;
-- `souls.default`: a per-soul override of `defaultTeam`; it must be one of that
-  soul's teams (`E_TEAM_NOT_ELIGIBLE`).
-
-A soul's default is `souls.default[soul] ?? defaultTeam`; its teams are that
-default ∪ `souls.teams["*"]` ∪ `souls.teams[soul]`. A label no file declares is
-`E_TEAM_UNKNOWN` (a spawn, preview or `inspect --soul` of that soul is
-refused). At spawn an instance joins its **default** only; the others are
+A team is a messaging-provider team (for oats.aweb, an aweb team id
+`<team>:<namespace>`) under a **label**. An instance that sits in two teams is
+a bridge between them: one process reads both inboxes and could relay anything
+from one to the other. So which teams an organisation's instances may be in is
+the organisation's decision, committed in its workspace file and closed by
+default; a deployment's `oats-local.yaml` adds a team only where the workspace
+allows it. Souls stay team-free in their own repositories: an organisation
+says how souls behave in its teams in its `oats-workspace.yaml`, and someone
+running the same souls standalone sees none of it.
+
+**What this protects against, and what it does not.** The workspace's team
+rules prevent **accidental** joins in a cooperative installation, and they make
+the organisation's intended team set visible and reviewable in its git. That is
+all they claim. They do not stop an operator from bridging teams on purpose:
+whoever holds credentials for two teams can read under one identity and relay
+under the other, or copy content outside the messaging layer, and distinct keys
+do not prove distinct processes. The messaging provider's admission (for aweb,
+the team controller key signs memberships; hosted invites are mediated by the
+service) controls who holds credentials for a team, not what a process does
+with what it reads. A deployment's authority comes from the credentials it
+holds, not from its path or its name, and a team certificate carries no soul,
+workspace or home-team claim (such metadata would be self-asserted, not a
+control).
+
+### Where teams are declared
+
+```yaml
+# oats-workspace.yaml (committed, edited by PR)
+teams:                                   # SHARED teams: the same provider team for everyone
+  engineering: { team: "engineering:acme.aweb.ai" }
+  security:    { team: "security:acme.aweb.ai" }
+  docs:        { description: Docs rota }       # declared, not created yet: team-unmapped
+defaultTeam: engineering                 # the workspace's fallback default team (a shared label)
+localTeams: false                        # may deployments declare their own teams? (absent: false)
+souls:                                   # per soul pattern: its default team and the other teams it may join
+  "*": { teams: [] }                     # unlisted souls: default only (also what no entry means)
+  security-souls/*: { default: security, teams: [engineering] }
+  security-souls/incident-responder: { default: security, teams: [engineering, docs] }
+  oats.engineering/*: { teams: any }     # any: every shared team of this file
+```
+
+- **Shared teams** (`teams.<label> = { description?, team? }`): a shared team
+  without `team` is declared but not created yet (readiness `team-unmapped`):
+  its owner creates it with the messaging provider, then commits the id.
+- **`souls:` keys are patterns**: `<member>/<soul>` or `<package>/<soul>`,
+  `<member>/*` or `<package>/*`, and `"*"`, with the member and package names
+  `souls.disabled` uses (a member's name is its repository's). A bare soul name
+  is refused. A key that is neither a pattern nor a soul the workspace offers
+  is the warning `team-soul-unknown` (a typo guard).
+- **The most specific key wins outright** for a soul's teams, and lists never
+  merge: the soul's own key, then `<member|package>/*`, then `"*"`. The
+  default comes from the most specific key that sets one. So
+  `a/*: {default: security}` and `a/x: {teams: [docs]}` give `a/x` the default
+  `security` and the teams `[docs]` only.
+- **A soul no key matches** (and no `"*"`) has its default only. That applies
+  to member and package souls alike: a workspace opens a package explicitly.
+- **Every label** (`defaultTeam`, each `default`, each of `teams`) must be a
+  shared team of the same file; anything else is `E_WORKSPACE_SCHEMA` when the
+  file is read, never at a spawn on someone else's machine.
+- **Local teams** (`oats-local.yaml` `teams.<label> = { team, description? }`)
+  and a local `defaultTeam` are allowed only when the workspace says
+  `localTeams: true`. Otherwise every spawn, preview and inspect is refused with
+  `E_WORKSPACE_SCHEMA` (reason `local-teams-closed`), naming both fixes: add
+  `localTeams: true` to the workspace file, or commit the teams and the
+  default there and remove them locally. A label in both files is
+  `team-label-collision` (a warning): the **shared** definition wins, and the
+  fix is renaming the local label.
+- **The standalone view** (an explicit `standalone:`, or a fallback when the
+  workspace cannot be read) has no workspace rules: local teams and the local
+  `defaultTeam` apply there.
+- `soul.yaml` and `oats-membership.yaml` say nothing about teams.
+  `oats-local.yaml` `souls.teams` and `souls.default` were removed in 0.38.0:
+  they are refused, and the refusal prints the `souls:` to commit instead.
+
+### A soul's default team and its teams
+
+The default, in order:
+
+1. the soul's `default` from `souls:` (the most specific matching key that
+   sets one);
+2. else the deployment's `oats-local.yaml` `defaultTeam`, only when
+   `localTeams: true`;
+3. else the workspace's `defaultTeam`;
+4. else none (`E_TEAM_UNCONFIGURED` when a messaging layer is active).
+
+`defaultTeam.from` says which: `soul`, `deployment` or `workspace`.
+
+The teams a soul may join: its default, plus the `teams` of its most specific
+matching `souls:` key, plus, with `localTeams: true`, every local team the
+deployment declares. Each row says why (`via`: `default`, `workspace`,
+`local`). At spawn an instance joins its **default** only; the others are
 eligible: offered, and joined on request through the provider (`join=` at
-spawn, or its own verbs later). Nothing committed besides the shared `teams:`
-says anything about teams, and capabilities compose from the workspace defaults
-and the soul only, the same for everyone. **A label never gates, restricts,
-changes trust or partitions the knowledge store.**
+spawn, or its own verbs later), which refuses a team that is not eligible.
+A local default no file declares is `E_TEAM_UNKNOWN`. Capabilities compose
+from the workspace defaults and the soul only, the same for everyone. **A
+label never gates, restricts, changes trust or partitions the knowledge
+store.**
+
+### The verbs
 
-The verbs edit `oats-local.yaml` in place; they never call a provider:
+They never call a provider. `oats teams add` and `oats teams default` edit
+`oats-local.yaml` in place, where the workspace allows local teams; `oats teams
+remove` runs anywhere (removing local teams is how a deployment moves them into
+the workspace). A soul's teams are edited by a PR to `oats-workspace.yaml`:
+`oats soul teams` only reads them.
 
 ```
-oats teams [--json]                                  # this deployment's teams, ids, the default, problems
-oats teams add <label> --team <id> [--description d] # declare a local team (the first one becomes the default)
-oats teams remove <label>                            # refused while referenced (E_TEAM_IN_USE) or shared (E_TEAM_SHARED)
-oats teams default <label>
-oats soul teams <soul>|'*' [--add a,b] [--remove a,b] [--default <label> | --clear-default] [--json]
+oats teams [--json]                                  # the teams, ids, the default, localTeams, the workspace's souls:, problems
+oats teams add <label> --team <id> [--description d] # declare a local team (the first one becomes the local default)
+oats teams remove <label>                            # refused while it is the local default (E_TEAM_IN_USE) or shared (E_TEAM_SHARED)
+oats teams default <label>                           # the local default
+oats soul teams <soul>|'*' [--json]                  # a soul's default and teams here, and which souls: key gave them
 ```
 
-The messaging provider's own setup creates provider teams and records them with
-`oats teams add` (see the provider's documentation). The spawn preview, `inspect` and `oats souls` report a soul's
+The messaging provider's own setup creates provider teams (see the provider's
+documentation). The spawn preview, `inspect` and `oats souls` report a soul's
 `teams` and `defaultTeam`; readiness reports the team problems in
 `checks.configured` (`E_TEAM_UNCONFIGURED` when a messaging layer is active and
 there is no default; `team-unmapped`, blocking when it is the default;
-`default-team-changed` for a running instance). The provider receives them in
-its environment — see [capabilities.md](capabilities.md#teams-in-the-provider-environment).
-Exact shapes: [desktop-cli-api.md](desktop-cli-api.md#team-model-v2-feature-team-model-2-oats-0300-replaces-feature-teams).
-
-### Preparing for team model 3 (0.36.x)
-
-OATS 0.38.0 commits a soul's teams in the workspace (team model 3,
-awebai/oats#484): the teams an organisation's instances may join become its
-own decision, visible and reviewable in its git, so a deployment's
-`oats-local.yaml` no longer adds one by accident. 0.36.x and 0.37.x prepare for it, so
-every workspace and deployment can migrate first:
-
-- **`oats-workspace.yaml` accepts the new keys** and validates them, but
-  **does not apply them**: a soul's teams and default are still resolved as
-  above, from `oats-local.yaml`.
-
-  ```yaml
-  defaultTeam: engineering          # the workspace's fallback default team
-  localTeams: true                  # deployments may declare their own teams (absent: false)
-  souls:                            # per pattern: "*", <member|package>/*, <member|package>/<soul>
-    "*": { teams: [] }              # default only ({} says the same)
-    security-souls/*: { default: security, teams: [engineering] }
-    oats.engineering/*: { teams: any }   # every shared team
-  ```
-
-  `<member|package>` is the name `souls.disabled` uses. Every label (`defaultTeam`,
-  a `souls:` `default`, each of its `teams`) must be a shared team in `teams:` of
-  the same file; anything else is `E_WORKSPACE_SCHEMA` when the file is read. A
-  key naming a member or package the workspace does not have is not an error.
-- **The readiness warning `team-model-3-migration`** (never blocking) names
-  what 0.38.0 will refuse: `souls.teams` / `souls.default` in `oats-local.yaml`
-  (they move to `souls:`), and local `teams` / `defaultTeam` while the workspace
-  does not say `localTeams: true` (fix: add `localTeams: true`, or commit the
-  teams and `defaultTeam` in the workspace file). `oats teams`, readiness (and
-  so the Desktop) and `oats doctor` show it. The migration steps are in the
-  [0.36.1 release notes](release-notes/v0.36.1.md).
+local-teams-closed; `team-soul-unknown`; `default-team-changed` for a running
+instance). The provider receives them in its environment — see
+[capabilities.md](capabilities.md#teams-in-the-provider-environment). Exact
+shapes: [desktop-cli-api.md](desktop-cli-api.md#team-model-3-feature-team-model-3-oats-0370-replaces-feature-team-model-2).
+Why it is shaped this way: [team model 3](design/2026-10-02-team-model-3.md).
 
 ## Provider payloads have three homes
 

package/lib/instance-inspect.mjs

@@ -18,7 +18,7 @@ import { capabilityManifests, sessionDefaults, homeLaunchLayers, instanceSoulDir
 import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance } from "./instance-resolution.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
 import { kernelCompatibility } from "./resolve.mjs";
-import { recordedTeams, reportRows, soulKeyOf, soulTeams, teamModel, teamProblems } from "./teams.mjs";
+import { discoveredTeamKeys, isRemovedTeamKeys, isTeamRefusal, recordedTeams, reportRows, soulKeyOf, teamKeyOf, soulTeams, teamModel, teamProblems } from "./teams.mjs";
 import { launchLayers, launchReport } from "./launch-preference.mjs";
 import { loadLocal } from "./workspace.mjs";
 import { ensureModuleTree } from "./operator-dispatch.mjs";
@@ -35,10 +35,10 @@ const obj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
 
 /** A resolution refusal that is a readiness FACT (the soul cannot resolve as the
- *  lock stands), not a failure to answer: reported as a failing `installed` item. */
-export const RESOLUTION_FACTS = new Set(["E_PACKAGE_MISSING", "E_PACKAGE_INTEGRITY", "E_CAPABILITY_MISSING", "E_LOCK_SCHEMA", "E_REQUIREMENT_INACTIVE", "E_TEAM_UNKNOWN", "E_TEAM_NOT_ELIGIBLE"]);
-/** A resolution refusal that readiness reports as a team item (checks.configured), not an install failure. */
-const TEAM_FACTS = new Set(["E_TEAM_UNKNOWN", "E_TEAM_NOT_ELIGIBLE"]);
+ *  lock stands), not a failure to answer: reported as a failing `installed` item —
+ *  or, for a refusal of the soul's teams (isTeamRefusal), as a team item in `configured`. */
+const RESOLUTION_FACTS = new Set(["E_PACKAGE_MISSING", "E_PACKAGE_INTEGRITY", "E_CAPABILITY_MISSING", "E_LOCK_SCHEMA", "E_REQUIREMENT_INACTIVE"]);
+const isResolutionFact = (e) => RESOLUTION_FACTS.has(e?.code) || isTeamRefusal(e);
 
 /** Is `name` an executable on PATH? (manifest `requires`, no shell). */
 function onPath(name) {
@@ -89,6 +89,9 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
   const modules = obj(meta.modules) ? meta.modules : {};
   const agentsRoot = dirname(dirname(dirname(realHome)));
   const deployment = dirname(agentsRoot);
+  // The deployment's removed team keys (team model 3) refuse every reader of its oats-local.yaml, before
+  // anything below falls back past an unreadable local file (live teams, launch, session defaults).
+  try { loadLocal(deployment); } catch (e) { if (isRemovedTeamKeys(e)) throw e; }
   const ws = obj(meta.workspace) ? meta.workspace : {};
   const soulDir = instanceSoulDir(realHome, meta) ?? null;
   const { definition, problems } = readSoulYaml(soulDir);
@@ -111,13 +114,13 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
     if (external === null && (discovery.members || []).some((m) => m.key === ws.soul?.repoKey)) external = false;
   }
   const slots = Object.fromEntries(LAYERS.map((l) => [l, Object.keys(modules).find((n) => manifests[n]?.layer === l) ?? null]));
-  // The home's soul key (souls.teams / souls.default): its name, or <package>/<soul> for a package soul.
-  const teamKey = ws.soul?.package && typeof ws.soul.qualifiedName === "string" ? ws.soul.qualifiedName : meta.agent;
+  // The home's soul key in the workspace's souls: (teamKeyOf): <package>/<soul>, or <member>/<soul>.
+  const teamKey = ws.soul?.package ? teamKeyOf({ ...ws.soul, package: ws.soul.package.id }) : teamKeyOf({ name: meta.agent, repoKey: ws.soul?.repoKey ?? "" });
   let live, model = null;
   if (discovery) {
     model = teamModel(discovery.standalone === true ? null : discovery.workspace, local, { workspaceKey: discovery.key ?? null });
     try { const t = soulTeams(model, teamKey); live = { teams: reportRows(t.teams), defaultTeam: t.defaultTeam, source: "live" }; }
-    catch (e) { if (!String(e?.code).startsWith("E_TEAM_")) throw e; live = { ...recordedTeams(meta), source: "recorded" }; }
+    catch (e) { if (!isTeamRefusal(e)) throw e; live = { ...recordedTeams(meta), source: "recorded" }; }
   } else if (readLive) live = await liveTeams(realHome, meta, { remoteOptions });
   else live = { ...recordedTeams(meta), source: "recorded" };
   // Feature launch-preference: the recorded launch (frozen), and what --reselect-launch would choose now —
@@ -147,7 +150,7 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
   let prepared = null, resolutionError = null;
   try { prepared = await prepareInstance(contextDir, soul, { remoteOptions }); }
   catch (e) {
-    if (!RESOLUTION_FACTS.has(e?.code)) throw e;
+    if (!isResolutionFact(e)) throw e;
     resolutionError = { code: e.code, message: e.message, details: e.details ?? null };
   }
   const found = loadLocal(contextDir);
@@ -160,11 +163,11 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
   }
   const res = prepared?.resolution;
   // A refused resolution still names the soul's teams when they resolve (a package refusal, …); a
-  // refusal of the teams themselves (E_TEAM_UNKNOWN / E_TEAM_NOT_ELIGIBLE) names none.
+  // refusal of the teams themselves (isTeamRefusal) names none.
   const model = teamModel(discovery?.standalone === true ? null : discovery?.workspace ?? null, prepared?.local ?? found.local, { workspaceKey: discovery?.key ?? null });
-  const teamKey = soulKeyOf(soulEntry);
+  const teamKey = teamKeyOf(soulEntry);
   let teams = res?.teams ?? null, defaultTeam = res ? res.defaultTeam ?? null : null;
-  if (!res) { try { const t = soulTeams(model, teamKey); teams = reportRows(t.teams); defaultTeam = t.defaultTeam; } catch (e) { if (!String(e?.code).startsWith("E_TEAM_")) throw e; } }
+  if (!res) { try { const t = soulTeams(model, teamKey); teams = reportRows(t.teams); defaultTeam = t.defaultTeam; } catch (e) { if (!isTeamRefusal(e)) throw e; } }
   // The soul being asked about is materialised as a spawn would (ensureWorkspaceSoul: idempotent per
   // commit, never touching a directory an instance links), so its checks always get OATS_SOUL; only a
   // spawn wrote the per-commit copy before, and a provider asked about a soul not yet spawned at this
@@ -181,7 +184,7 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
   // Feature launch-preference: what a spawn with no flags would launch here.
   let launchConfigs = {};
   try { launchConfigs = launchConfigsAt(deployment); } catch { launchConfigs = {}; }
-  const launch = launchReportFor({ layers: prepared?.launch ?? launchLayers({ definition: soulEntry.definition, entry: soulEntry, key: teamKey, local: found.local }), launchConfigs, contextDir: deployment });
+  const launch = launchReportFor({ layers: prepared?.launch ?? launchLayers({ definition: soulEntry.definition, entry: soulEntry, key: soulKeyOf(soulEntry), local: found.local }), launchConfigs, contextDir: deployment });
   return {
     kind: "soul", home: null, meta: null, deployment, agentsRoot: join(deployment, "agents"), teams, defaultTeam, teamsSource: "live", teamModel: model, teamKey, launch, session: newSessionDefaults(deployment),
     subject: { kind: "soul", soul: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null },
@@ -281,7 +284,7 @@ export function inspectDocument(t, { kernel }) {
  *  `required: false`. A home also compares its spawn-time default with the live one. */
 function teamItems(t) {
   if (!t.teamModel) return [];
-  const problems = teamProblems(t.teamModel, { key: t.teamKey, messaging: !!t.slots?.messaging });
+  const problems = teamProblems(t.teamModel, { key: t.teamKey, messaging: !!t.slots?.messaging, soulKeys: t.discovery ? discoveredTeamKeys(t.discovery) : null });
   const same = (a, b) => (a?.label ?? null) === (b?.label ?? null) && (a?.team ?? null) === (b?.team ?? null);
   if (t.home && t.teamsSource === "live" && t.meta?.defaultTeam !== undefined && !same(t.recordedDefaultTeam, t.defaultTeam)) {
     problems.push({ code: "default-team-changed", severity: "warning", recorded: t.recordedDefaultTeam, current: t.defaultTeam,
@@ -408,7 +411,7 @@ export const PROVIDER_CHECK_BUDGET_MS = 60_000;
 export async function readinessDocument(t, { selector = null, remoteOptions, catalog = null, budgetMs = PROVIDER_CHECK_BUDGET_MS } = {}) {
   const installed = [], configured = [], member = [], providers = [];
   const cap = (id) => ({ capability: { id } });
-  if (t.resolutionError && !TEAM_FACTS.has(t.resolutionError.code)) {
+  if (t.resolutionError && !isTeamRefusal(t.resolutionError)) {
     installed.push(item(t.soul.name, "fail", { producer: "workspace resolution", code: t.resolutionError.code, reason: t.resolutionError.message, evidence: t.resolutionError.details, remedy: "oats sync (the lock must provide every package capability the soul resolves)" }));
   }
   if (t.soul.copyError) {

package/lib/instance-resolution.mjs

@@ -21,7 +21,7 @@ import { join, resolve as resolvePath, dirname, relative, isAbsolute, sep } from
 import { oatsError } from "./errors.mjs";
 import { loadLocal, discoverWorkspace, discoverRepo, standaloneRepo, observeWorkspace } from "./workspace.mjs";
 import { resolveSoul, kernelCompatibility } from "./resolve.mjs";
-import { BY_TEAM_REMOVED, recordedTeams, reportRows, soulKeyOf, soulTeams, teamModel } from "./teams.mjs";
+import { BY_TEAM_REMOVED, isRemovedTeamKeys, isTeamRefusal, memberNameOf, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "./teams.mjs";
 import { launchLayers } from "./launch-preference.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
 import { materialize, moduleSkills, MODULES_DIR, SKILLS_DIR } from "./materialize.mjs";
@@ -159,6 +159,8 @@ export function disabledEntry(local, soulEntry) {
  * host; a standalone deployment has local teams only and reads none.
  * → { teams, defaultTeam, source: "live" } — or, when that cannot answer (the host is unreachable, the
  *   deployment or its teams are unreadable), the spawn-time record: { teams, defaultTeam, source: "recorded", reason }.
+ *   An oats-local.yaml still carrying the removed team keys (isRemovedTeamKeys) is thrown, never answered
+ *   from the record: the deployment must migrate before its homes act on teams again.
  * `source` travels as OATS_TEAMS_SOURCE: a provider leaves a joined team only on a `live` answer.
  */
 export async function liveTeams(home, meta, { remoteOptions, remote } = {}) {
@@ -166,7 +168,7 @@ export async function liveTeams(home, meta, { remoteOptions, remote } = {}) {
   const soul = meta?.workspace?.soul;
   // A home without a workspace soul record has nothing to resolve.
   if (!soul || typeof meta.agent !== "string") return recorded("no-workspace-soul");
-  const key = soul.package && typeof soul.qualifiedName === "string" ? soul.qualifiedName : meta.agent;
+  const key = soul.package ? teamKeyOf({ ...soul, package: soul.package.id }) : teamKeyOf({ name: meta.agent, repoKey: soul.repoKey ?? "" });
   const deployment = dirname(dirname(dirname(dirname(resolvePath(home)))));
   try {
     const found = loadLocal(deployment);
@@ -175,7 +177,10 @@ export async function liveTeams(home, meta, { remoteOptions, remote } = {}) {
     const wsObs = standalone ? null : await observeWorkspace(found.local.workspace, { remoteOptions, remote });
     const t = soulTeams(teamModel(wsObs?.workspace ?? null, found.local, { workspaceKey: wsObs?.key ?? null }), key);
     return { teams: reportRows(t.teams), defaultTeam: t.defaultTeam, source: "live" };
-  } catch (e) { return recorded(String(e?.code).startsWith("E_TEAM_") ? "invalid-teams" : "unreadable", { code: e?.code || "E_REMOTE_UNREADABLE", message: e?.message ?? String(e) }); }
+  } catch (e) {
+    if (isRemovedTeamKeys(e)) throw e;
+    return recorded(isTeamRefusal(e) ? "invalid-teams" : "unreadable", { code: e?.code || "E_REMOTE_UNREADABLE", message: e?.message ?? String(e) });
+  }
 }
 
 /** The per-commit soul cache under an agent directory: `<agentDir>/souls/<commit12>/`.
@@ -314,9 +319,7 @@ export async function ensureWorkspaceSoul(prepared, agentsRoot) {
 /** The taught member name of a repo key: the last path segment without `.git`
  *  (`github.com/northwind/platform` → `platform`). The same rule `oats onboard`
  *  and `oats sync` print (memberLabel). */
-export function memberNameOf(key) {
-  return String(key).split("/").filter(Boolean).pop()?.replace(/\.git$/i, "") || String(key);
-}
+export { memberNameOf };
 
 /** The convention path of a member's clone: `<deployment>/<member name>` — except a
  *  member called `agents`, which is cloned as `agents-repo/` because `<deployment>/agents/`