@awebai/oats 0.36.0 → 0.37.0

package/bin/oats.mjs

@@ -36,7 +36,7 @@ import {
   writeFileAtomic, LOCK_FILE, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
   classifyPackageValue, parsePackageRequest } from "../lib/packages.mjs";
 import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, workspaceWarnings, memberRowByKey } from "../lib/workspace.mjs";
-import { recordedTeams, reportRows, soulKeyOf, soulTeams, teamModel } from "../lib/teams.mjs";
+import { migrationProblems, recordedTeams, reportRows, soulKeyOf, soulTeams, teamModel } from "../lib/teams.mjs";
 import { launchLayers } from "../lib/launch-preference.mjs";
 import { parseConfigData } from "../lib/config-data.mjs";
 import * as remoteModule from "../lib/remote.mjs";
@@ -221,6 +221,19 @@ async function doctorComposition(ctx, soulName, ws, bail) {
   } finally { for (const c of cleanups) { try { c(); } catch { /* best effort: temporary copies only */ } } }
 }
 
+/** team-model-3-migration in doctor (0.36.x), OFFLINE like the rest of doctor: oats-local.yaml, and for its
+ *  local teams the workspace file this machine's parsed cache holds (cachedWorkspace: no git process, no
+ *  network). Without that file, whether local teams need `localTeams: true` is said to be unchecked
+ *  (information), never guessed. The standalone view has no workspace rules. → { problems, information } */
+function doctorTeamMigration(local) {
+  const standalone = typeof local.standalone === "string" && local.standalone !== "";
+  const file = standalone ? null : cachedWorkspace(local.workspace)?.file ?? null;
+  const model = teamModel(file, local);
+  const unchecked = !standalone && file === null && model.migration.teamKeys.length > 0;
+  return { problems: migrationProblems(model),
+    information: unchecked ? ["team-model-3-migration: whether oats-local.yaml teams/defaultTeam need localTeams: true couldn't be checked: this deployment hasn't observed its workspace yet; run oats sync"] : [] };
+}
+
 /** Workspace-model v2 doctor data, OFFLINE: the deployment declaration found
  * walking up from ctx (oats-local.yaml) and the lock v3 beside it. Doctor never
  * goes to the network for this view (only `--soul`, which resolves the soul like a
@@ -230,7 +243,7 @@ function doctorLockData(ctx) {
   let lockDir = ctx;
   try {
     const found = loadLocal(ctx);
-    out.local = { path: found.path, workspace: found.local.workspace };
+    out.local = { path: found.path, workspace: found.local.workspace, value: found.local };
     lockDir = dirname(found.path);
   } catch (e) {
     // An unreadable oats-local.yaml, or a 0.25 oats-config.yaml inside the deployment
@@ -584,12 +597,13 @@ function legacyLayoutProblems(root) {
 async function doctorWorkspaceJson(ctx, soulName, ws) {
   const composition = await doctorComposition(ctx, soulName, ws, (code, msg, details) => jsonFail(code, msg, details));
   const agentsRoot = join(dirname(ws.local.path), "agents");
-  const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot)].filter(Boolean);
+  const migration = doctorTeamMigration(ws.local.value);
+  const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot), ...migration.problems].filter(Boolean);
   return {
     schemaVersion: 1, workspaceApi: 2, context: ctx,
     workspace: { file: ws.local.path, ref: ws.local.workspace },
     workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
-    information: operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : [],
+    information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...migration.information],
     composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
     ...(problems.length ? { problems } : {}),
   };
@@ -624,7 +638,10 @@ async function doctor(dir) {
   const composition = await doctorComposition(ctx, soulName, ws, (code, msg) => die(`${msg} [${code}]`));
   printDoctorWorkspace(ws);
   const agentsRoot = join(dirname(ws.local.path), "agents");
+  const migration = doctorTeamMigration(ws.local.value);
   for (const p of [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot)].filter(Boolean)) console.log(`\n! ${p.code}: ${p.message}`);
+  for (const p of migration.problems) console.log(`\n! ${p.code}: ${p.message} — ${p.fix}`);
+  for (const line of migration.information) console.log(`\nINFO: ${line}`);
   if (soulName) {
     const information = operationalKnowledgeNote(composition, soulName);
     if (information) console.log(`\nINFO: ${information}`);

package/docs/capabilities.md

@@ -341,7 +341,9 @@ Hooks receive:
 A spawn hook also gets `OATS_TASK`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`,
 `OATS_HARNESS`, `OATS_KIND` and, for a spawn a trigger started,
 `OATS_TRIGGER_EVENT_FILE`. A launch hook also gets `OATS_HARNESS` and
-`OATS_PREVIOUS_HARNESS`.
+`OATS_PREVIOUS_HARNESS`, and `OATS_LAUNCH_PREVIEW=1` when it runs for a
+preview (only a preview-aware hook does, below); on a real run
+`OATS_LAUNCH_PREVIEW` is not set.
 
 `OATS_SETTINGS_ORIGINS` says where each leaf of
 `OATS_SETTINGS` came from: a JSON object from a JSON pointer to `{ kind, at }`,
@@ -350,7 +352,8 @@ A spawn hook also gets `OATS_TASK`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`,
 `{"/harvest":{"kind":"soul","at":"soul.yaml#/knowledge"}}`. A provider tells a
 soul-set value from a host-set one there, and never reads `soul.yaml` for it;
 a home with none recorded gives `{}`. A final JSON line may return `meta`,
-`brief`, `warning`, or harness-specific `launch` arguments. A **spawn or
+`brief`, `warning`, or harness-specific `launch` arguments; a preview-aware
+launch hook's preview answer may add `volatileEnv` (below). A **spawn or
 launch hook** may also return an `env` object for the launched process;
 returning `env` from a retire hook is an explicit contract error.
 
@@ -364,6 +367,54 @@ start (a renewed session grant, for example) leaves the CURRENT one on record. A
 launch hook that answers without `meta` keeps its previous entry; a start whose
 preparation fails changes nothing.
 
+A launch hook may do idempotent provider registration on a real start (an
+aweb home registering with the host wake broker, for example). How the
+kernel runs it depends on whether its capability declares **preview
+awareness**: `"launchPreview": true` at the top level of its manifest. The
+kernel reads the declaration from the home's own module copy, so a home keeps
+the behaviour of the module it was spawned with.
+
+**A preview-aware hook** must change nothing under `OATS_LAUNCH_PREVIEW=1`,
+and must return the same contribution (`launch` arguments and `env`) as for
+a real start. It runs twice per start:
+
+1. **As a preview, under `OATS_LAUNCH_PREVIEW=1`.** The start's preflight uses
+   this contribution: trust, environment ownership, the harness-package
+   probe and the rendered command. `oats launch-config preview` (which
+   Desktop's start dialog uses) runs only this pass.
+2. **For real, without the flag.** This pass runs only once preflight has
+   passed, including the check that the home is not already running
+   (`E_SESSION_RUNNING`), and before a restart stops the running harness.
+
+The real run's `meta` and warnings are what the start records. If its
+contribution differs from its preview contribution, the start is refused
+with `E_LAUNCH_PREPARATION` and nothing is stopped or started.
+
+Some values only a real run can know, such as a credential minted at start.
+A preview answer may list those names in `volatileEnv` (for example
+`"volatileEnv": ["AWEB_IDENTITY_HOME"]`, beside `env`). For those names:
+
+- The start takes the values from the real run, records them, and renders
+  the launch command again with them.
+- The comparison leaves those values out. Everything else must still be
+  identical.
+
+Each name must be one the same hook returned in `env`. Preflight sees only
+the preview's value, so a volatile name must not affect how the harness
+resolves its packages. The kernel refuses (`E_LAUNCH_PREPARATION`) a volatile
+`CLAUDE_CONFIG_DIR`, `CODEX_HOME` or `PI_CODING_AGENT_DIR`. It reads
+`volatileEnv` only from a preview answer and never records it.
+
+**A hook that does not declare preview awareness** runs once per start, for
+real, during preflight, before the checks that use its contribution. A
+refused start may therefore already have run it. `oats launch-config preview`
+never runs it. The preview shows that capability's recorded contribution, and
+its `capabilities` check says the hook was not run.
+
+`launchPreview` is a top-level key so that a kernel older than 0.37 ignores
+it and runs the hook once, as it always did. A key inside the hook's
+declaration would make such a kernel refuse the whole package.
+
 Hook environment values are strings, at most 8192 UTF-8 bytes, with no NUL or
 newlines. Names use the portable environment grammar and must belong to an
 unambiguous vendor namespace. Only a dotted capability ID participates: its

package/docs/capability-manifest.schema.json

@@ -61,6 +61,10 @@
       "type": "boolean",
       "description": "Workspace discovery: true makes this member capability repo-owned — listed (private: true) but usable only by souls of its own repository (E_CAPABILITY_PRIVATE elsewhere)."
     },
+    "launchPreview": {
+      "type": "boolean",
+      "description": "true declares the launch hook preview-aware: it changes nothing under OATS_LAUNCH_PREVIEW=1 and returns the same contribution (apart from its preview answer's volatileEnv values), so a start runs it as a preview during preflight and for real after it, and a launch preview runs it. Without it the hook runs once per start, for real, during preflight, and never for a launch preview. Top-level so that older kernels ignore it."
+    },
     "layer": {
       "enum": [
         "knowledge",

package/docs/configuration.md

@@ -81,6 +81,12 @@ refused (`E_WORKSPACE_SCHEMA`).
 How teams are resolved, and what a messaging provider does with them, is in
 [workspaces.md](workspaces.md#teams).
 
+OATS 0.38.0 (team model 3) removes `souls.teams` and `souls.default` (they move
+to `souls:` in `oats-workspace.yaml`) and allows `teams` and `defaultTeam` here
+only when the workspace file says `localTeams: true`. 0.36.x and 0.37.x still apply all
+four keys and warn about them (`team-model-3-migration`): see
+[Preparing for team model 3](workspaces.md#preparing-for-team-model-3-036x).
+
 ## Launch configurations
 
 An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`
@@ -236,7 +242,12 @@ recipe is resolved again against the home's recorded context and every check
 runs first. With `--reselect-launch`, the launch preferences decide again
 (the home's recorded soul and this deployment's `souls.launch`). A capability that contributed harness-specific arguments must
 declare a `launch` hook to follow a harness change; otherwise the start is
-refused (`E_LAUNCH_PREPARATION`). A launch hook's warnings do not stop
+refused (`E_LAUNCH_PREPARATION`). The checks use the preview run
+(`OATS_LAUNCH_PREVIEW=1`) of the launch hooks whose capabilities declare
+`launchPreview`. Those hooks run for real only after every check has passed,
+so a start refused by preflight has run none of them for real. Other launch
+hooks run once, for real, during the checks (see
+[capabilities.md](capabilities.md)). A launch hook's warnings do not stop
 the start: `session start|restart` print them (and answer them as
 `warnings` under `--json`), as spawn does, and each is kept as a
 `launch-warning` instance event (`oats instance events`).

package/docs/desktop-cli-api.md

@@ -725,7 +725,7 @@ Read-only (it writes no lock):
              "souls":["rm"],"capabilities":["nw-house-style"],"publishes":null,"url":"https://github.com/nw/agents/tree/66566512…",
              "membershipFile":{"path":"oats-membership.yaml","url":"https://github.com/nw/agents/blob/66566512…/oats-membership.yaml"}}],
  "packages":[{"id":"oats.okf","version":"3.0.0","source":"catalog:oats.okf","commit":"ab897841…","integrity":"sha256-bada35…",
-              "capabilities":["oats.okf"],"souls":[],"latest":{"version":"4.1.0","ref":"v4.1.0"}}],
+              "capabilities":["oats.okf"],"souls":[],"latest":{"version":"4.1.1","ref":"v4.1.1"}}],
  "declaredPackages":["oats.framework","oats.okf"],"unsynced":["oats.framework"],"stale":[],
  "external":[{"source":"git:github.com/oss/experts@3c606e09…","soul":"security-reviewer"}],
  "problems":[],"warnings":[],
@@ -784,8 +784,8 @@ packages' capabilities and souls, sorted by name, then origin. Both carry
     "defaultTeam":{"label":"mine","team":"mine:ana.aweb.ai","from":"deployment"},
     "private":false,"path":"souls/writer","work":"directory","description":"Drafts campaigns.","harness":"pi","model":null,"harnessFrom":"kernel-default",
     "file":{"path":"souls/writer/soul.yaml","url":null},"spawnable":true,"problem":null},
-   {"name":"knowledge-maintainer","qualifiedName":"oats.okf/knowledge-maintainer","origin":"package oats.okf v4.1.0","kind":"package","package":"oats.okf",
-    "version":"4.1.0","repoKey":"github.com/awebai/oats-okf","commit":"e331a996…","teams":null,"defaultTeam":null,"private":false,
+   {"name":"knowledge-maintainer","qualifiedName":"oats.okf/knowledge-maintainer","origin":"package oats.okf v4.1.1","kind":"package","package":"oats.okf",
+    "version":"4.1.1","repoKey":"github.com/awebai/oats-okf","commit":"e1d604f7…","teams":null,"defaultTeam":null,"private":false,
     "path":"oats-package/souls/knowledge-maintainer","work":"directory","description":"Reviews harvested knowledge.","harness":"pi","model":null,
     "harnessFrom":"kernel-default","file":{"path":"oats-package/souls/knowledge-maintainer/soul.yaml","url":null},
     "spawnable":false,"problem":{"code":"E_TEAM_UNKNOWN","message":"team \"reviewers\" is not declared (oats-local.yaml#/souls/teams/…)"}}],
@@ -874,8 +874,8 @@ nothing reads a working clone.
 **The show:**
 
 ```json
-{"capabilityShowApi":1,"name":"oats.okf","kind":"package","repoKey":"github.com/awebai/oats-okf","package":"oats.okf","version":"4.1.0",
- "commit":"e331a996…","path":"oats-package/capabilities/oats-okf",
+{"capabilityShowApi":1,"name":"oats.okf","kind":"package","repoKey":"github.com/awebai/oats-okf","package":"oats.okf","version":"4.1.1",
+ "commit":"e1d604f7…","path":"oats-package/capabilities/oats-okf",
  "inject":{"path":"injects/okf.md","bytes":2422,"text":"## Knowledge: OKF\n\nYou have two kinds of knowledge. …","binary":false,"truncated":false},
  "skills":[{"name":"okf-consultation","path":"skills/okf-consultation","description":"Consulting your soul's knowledge with the `oats okf` CLI: …",
             "files":[{"path":"skills/okf-consultation/SKILL.md","bytes":6947},{"path":"skills/okf-consultation/references/consult.md","bytes":4465}],
@@ -901,7 +901,7 @@ nothing reads a working clone.
 **The `--file` answer:**
 
 ```json
-{"capabilityShowApi":1,"name":"oats.okf","kind":"package","commit":"e331a996…",
+{"capabilityShowApi":1,"name":"oats.okf","kind":"package","commit":"e1d604f7…",
  "file":{"path":"skills/okf-instance-knowledge/SKILL.md","bytes":4787,"text":"---\nname: okf-instance-knowledge\n…","binary":false,"truncated":false}}
 ```
 
@@ -1229,9 +1229,38 @@ for a failure and `false` for a warning, plus the problem's own keys.
 | `default-team-changed` | warning | `recorded`, `current` | `--home` with live teams: the default changed since the spawn |
 | `E_TEAM_UNKNOWN` | failure | `label`, `at` | a reference to an undeclared label |
 | `E_TEAM_NOT_ELIGIBLE` | failure | `soul`, `label`, `at` | `souls.default` outside the soul's teams |
+| `team-model-3-migration` | warning | `condition`, `keys` | 0.36.x and 0.37.x: what OATS 0.38.0 (team model 3) refuses, one item per condition (below) |
 
-The last two are also spawn, preview and inspect refusals, with the same
-details.
+The `E_TEAM_UNKNOWN` and `E_TEAM_NOT_ELIGIBLE` codes are also spawn, preview and
+inspect refusals, with the same details.
+
+`team-model-3-migration` is a deployment fact, so every soul's readiness
+carries it, and `oats teams` lists it once. Its `condition`:
+
+- `local-soul-teams`: `oats-local.yaml` has `souls.teams` and/or
+  `souls.default` (`keys`: `["souls.teams", "souls.default"]` as found). They
+  move to `souls:` in `oats-workspace.yaml`.
+- `local-teams-closed`: `oats-local.yaml` declares `teams` and/or
+  `defaultTeam` (`keys`: `["teams", "defaultTeam"]` as found) and the
+  workspace file does not say `localTeams: true`. The `fix` names both
+  remedies: add `localTeams: true` to the workspace file, or commit the teams
+  and `defaultTeam` there and remove them locally. Never raised in the
+  standalone view, which has no workspace rules.
+
+```json
+{"code":"team-model-3-migration","severity":"warning","condition":"local-teams-closed","keys":["teams","defaultTeam"],
+ "message":"oats-local.yaml declares teams, defaultTeam, but oats-workspace.yaml does not say localTeams: true: OATS 0.38.0 refuses local teams and a local defaultTeam unless the workspace allows them",
+ "fix":"either (a) add `localTeams: true` to oats-workspace.yaml, or (b) commit the teams and defaultTeam in oats-workspace.yaml, then remove them from oats-local.yaml"}
+```
+
+As a readiness item it is `{subject: "teams", status: "fail", required: false,
+producer: "team model", code, reason: <message>, remedy: <fix>, condition,
+keys}`. `oats doctor --json` lists the same problems under `problems[]`. Doctor
+stays offline: for `local-teams-closed` it reads only the workspace file this
+machine's parsed cache holds; when there is none, it adds no problem and says
+so in `information[]`: `"team-model-3-migration: whether oats-local.yaml
+teams/defaultTeam need localTeams: true couldn't be checked: this deployment
+hasn't observed its workspace yet; run oats sync"`.
 
 <a id="soul-launch-preferences-feature-launch-preference-oats-0300"></a>
 ## Launch preferences

package/docs/desktop.md

@@ -104,6 +104,39 @@ opened, or your home directory when there is none (never ~/Downloads);
 
 Launch flags for scripted use: `--dir <workspace>` and `OATS_DESKTOP_PORT`.
 
+### One window per workspace
+
+Each workspace has at most one window, titled with the workspace's name (a
+workspace on a server: `name — server`).
+
+- **Switching.** Choosing a workspace in the switcher shows it in the current
+  window. If that workspace already has a window, that window comes to the
+  front instead and the current one doesn't change.
+- **Open in new window.** Each workspace in the switcher has an **Open in new
+  window** button beside it. From the keyboard: Right Arrow on the workspace,
+  then Enter, or ⌘Enter on macOS / Ctrl+Enter on Linux and Windows. A
+  workspace that already has a window is brought to the front.
+- **New Window.** On macOS, **File → New Window** (⌘⇧N); everywhere,
+  **Window: new window** in the command palette. The new window has no
+  workspace yet: it opens the switcher, and shows "Choose a workspace" until
+  you pick one. It reads nothing until then.
+- **Moving between windows.** On macOS, ⌘\` cycles the app's windows, and the
+  **Window** menu lists them.
+- **Restore.** Quitting and relaunching brings every window back with its
+  size and place (moved onto a visible display if its own is gone). A window
+  whose workspace isn't served at launch doesn't come back, but it is
+  remembered until you close it while its workspace is served. With nothing
+  to restore, one window opens on the last workspace you used.
+- **Launching again.** Running the app again (`open -a "OATS Desktop" --args
+  --dir <deployment>`, or from inside a deployment) adds that deployment if
+  needed and brings its window to the front, opening one if it has none. Any
+  other launch brings the most recently used window to the front.
+- **Closing.** Closing a window leaves the other windows, and their
+  terminals, running. Closing the last window quits the app.
+- Tabs belong to their window: a workspace's terminals and tabs stay in the
+  window they were opened in, and switching that window back to the
+  workspace brings them back.
+
 ## One workspace, several machines
 
 The switcher lists each workspace once, however many deployments it has: the

package/docs/integrations.md

@@ -40,8 +40,8 @@ arrives from.
 ```yaml
 # oats-workspace.yaml: one default per slot, for every soul
 packages:
-  oats.okf: v4.1.0
-  oats.aweb: v1.17.7
+  oats.okf: v4.1.1
+  oats.aweb: v1.18.1
   oats.linear: v1.0.1
   oats.jira: v1.0.1
 defaults:

package/docs/knowledge.md

@@ -26,7 +26,7 @@ The workspace pins the package and fills the slot for every soul by default:
 ```yaml
 # oats-workspace.yaml (excerpt)
 packages:
-  oats.okf: v4.1.0
+  oats.okf: v4.1.1
 defaults:
   knowledge: { oats.okf: { from: package } }
 stores:

package/docs/oats-workspace.schema.json

@@ -27,6 +27,20 @@
       "additionalProperties": { "$ref": "#/$defs/team" },
       "description": "SHARED teams: <label>: { description?, team? }. `team` is the messaging provider's team id, the same for everyone; without it the team is declared but not yet created (readiness team-unmapped). Local teams, the default and which teams each soul belongs to live in the deployment's oats-local.yaml (`oats teams`, `oats soul teams`). A label never gates, restricts or partitions anything."
     },
+    "defaultTeam": {
+      "$ref": "#/$defs/label",
+      "description": "Team model 3 (0.38.0): the workspace's fallback default team, a label of teams: in this file. 0.36.x and 0.37.x accept and validate it without applying it."
+    },
+    "localTeams": {
+      "type": "boolean",
+      "description": "Team model 3 (0.38.0): whether deployments may declare their own teams and defaultTeam in oats-local.yaml. Absent: false. 0.36.x and 0.37.x accept it without applying it."
+    },
+    "souls": {
+      "type": "object",
+      "propertyNames": { "type": "string", "pattern": "^(?:\\*|[a-z0-9][a-z0-9._-]*/(?:\\*|[a-z0-9]+(?:-[a-z0-9]+)*))$" },
+      "additionalProperties": { "$ref": "#/$defs/soulTeams" },
+      "description": "Team model 3 (0.38.0): per soul pattern (\"*\", <member|package>/* or <member|package>/<soul>; the most specific key wins outright), the soul's default team and the other teams it may join. Every label is a label of teams: in this file. 0.36.x and 0.37.x accept and validate it without applying it."
+    },
     "defaults": { "$ref": "#/$defs/defaults" },
     "stores": {
       "type": "object",
@@ -111,6 +125,20 @@
         "team": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,255}$", "description": "The messaging provider's team id (for oats.aweb, <team>:<namespace>). Absent: declared, not yet created. The kernel's safety rule: never '-'-led, no whitespace or control characters, at most 256 characters; the provider validates its own shape." }
       }
     },
+    "soulTeams": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "default": { "$ref": "#/$defs/label", "description": "The soul's default team: a label of teams: in this file." },
+        "teams": {
+          "anyOf": [
+            { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/label" } },
+            { "const": "any" }
+          ],
+          "description": "The other teams the soul may join: labels of teams: in this file, or \"any\" for every one. [] (or no teams) is default only."
+        }
+      }
+    },
     "defaults": {
       "type": "object",
       "additionalProperties": false,

package/docs/official-catalog.md

@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
 
 | package | release | capabilities | package souls |
 |---|---|---|---|
-| `oats.framework` | `oats-framework/v1.4.1` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
-| `oats.okf` | `v4.1.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
-| `oats.aweb` | `v1.17.7` | `oats.aweb` (messaging) | |
+| `oats.framework` | `oats-framework/v1.4.3` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
+| `oats.okf` | `v4.1.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
+| `oats.aweb` | `v1.18.1` | `oats.aweb` (messaging) | |
 | `oats.engineering` | `v1.5.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
 | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
 | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
@@ -27,7 +27,7 @@ no lock and adds nothing to an existing workspace.
 ## Find and use packages
 
 - A workspace pins an official package by **bare version** in its
-  `packages:` map (`oats.okf: v4.1.0`); `oats sync` resolves it through the
+  `packages:` map (`oats.okf: v4.1.1`); `oats sync` resolves it through the
   catalog to an exact commit, fetches it, verifies its integrity and locks it.
   A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
   not join a team or adopt the publisher's workspace. See

package/docs/packages.md

@@ -44,14 +44,14 @@ whole organisation:
 
 ```yaml
 packages:
-  oats.okf: v4.1.0                                    # bare version → the official catalog
+  oats.okf: v4.1.1                                    # bare version → the official catalog
   acme.tools: git:github.com/acme/tools@v0.4.0        # direct ref: git:<repo>@<tag or full OID>
 ```
 
-- **Bare version** (`v4.1.0`, `4.1.0`, `1.0.0-rc.1`): the id is looked up in
+- **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.0` or `oats-framework/v1.4.1`) and the payload path. An id
+  convention (`v4.1.1` or `oats-framework/v1.4.3`) 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.1
-  oats.okf: v4.1.0
-  oats.aweb: v1.17.7
+  oats.framework: v1.4.3
+  oats.okf: v4.1.1
+  oats.aweb: v1.18.1
 teams:
   platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
 defaults:
@@ -105,7 +105,7 @@ decision recorded in the lock.
 $ oats sync
 workspace  acme  (github.com/acme/agents @ 3f2a9c1e)
 members    agents ✓↔ (@ 3f2a9c1e)   platform ✓↔ (@ 77c0a1b2)   billing ✗ (no-backlink)
-packages   acme.tools 0.4.0 ✓ (@ 47f4b816)   oats.okf 4.1.0 ✓ (@ e331a996)
+packages   acme.tools 0.4.0 ✓ (@ 47f4b816)   oats.okf 4.1.1 ✓ (@ e1d604f7)
 changed    acme.tools  — → 0.4.0 (@ 47f4b816)
 souls      9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
 teams      platform (shared) · this deployment's: oats teams
@@ -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.17.7                         # a catalog version
+oats package add oats.aweb v1.18.1                         # a catalog version
 oats package add acme.tools git:github.com/acme/tools@v0.4.0
 oats package remove acme.tools
 ```
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
       "source": "catalog:oats.okf",
       "url": "https://github.com/awebai/oats-okf.git",
       "path": "oats-package",
-      "version": "4.1.0",
-      "commit": "e331a9969d10aabddaa5824991f1846c7dedb388",
+      "version": "4.1.1",
+      "commit": "e1d604f70c5e4cdc39602095f139383e61f69323",
       "integrity": "sha256-…",
       "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
     },
@@ -331,12 +331,12 @@ 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.0", "path": "oats-package" },
-    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.4.1", "path": "oats-package" }
+    "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" }
   }
 }
 ```
 
-`ref` carries the tag convention: a workspace's `oats.framework: v1.4.1`
-resolves to tag `oats-framework/v1.4.1`. Resolving through the catalog never
+`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
 advances a lock by itself: `oats sync` does, and says so.

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

@@ -0,0 +1,103 @@
+# OATS 0.36.1
+
+## Changed
+
+- **oats.okf 4.1.1** (catalog and workspace pin, and the bundled mirrors):
+  three fixes to harvest completion and `harvest --once`.
+  - `oats okf complete` on an amended PR that is still open
+    (awebai/oats-okf#36). After the knowledge-maintainer pushed an amendment
+    on top of the delivered commit, `complete --run <id>` failed with `E_PR:
+    publication branch has unexpected commit; never force push`. The run is
+    now reported `delivered` when the known PR is open at the branch's tip
+    and Git shows that tip descends from the delivered commit; the answer
+    names the amended head. A tip that does not contain the delivered commit
+    is still refused with `E_PR`, and nothing is ever force-pushed. Ancestry
+    is read from the commit objects alone, so a checkout's grafts or
+    commit-graph file cannot fake it.
+  - `harvest --once`: one-shots of a seat no longer race
+    (awebai/oats-okf#39). The overlap checks and the install run under one
+    seat lock, so of two overlapping one-shots started together one installs
+    and the other gets `E_ONCE_OVERLAP`.
+  - `harvest --once`: a note edited between runs no longer strands a
+    draining one-shot (awebai/oats-okf#40). A rerun with the same manifest
+    continues from custody without reading the listed notes. Another
+    manifest listing a note a one-shot already holds is refused with
+    `E_ONCE_OVERLAP`, naming that one-shot, instead of a `sha256 mismatch`.
+- **Preparing for team model 3** (awebai/oats#485). OATS 0.37.0 commits the
+  teams an organisation's souls may join, and their default team, in the
+  workspace file, closed by default (awebai/oats#484), so the organisation's
+  intended team set is visible and reviewable in its git and a deployment's
+  `oats-local.yaml` no longer adds a team by accident. 0.36.1 lets every workspace and
+  deployment migrate before 0.37.0 refuses the old shape:
+  - `oats-workspace.yaml` accepts `defaultTeam`, `localTeams` and `souls:`,
+    and validates them: every label they name must be a shared team in
+    `teams:` of the same file (`E_WORKSPACE_SCHEMA` otherwise, when the file
+    is read). 0.36.1 does **not** apply them: a soul's teams and default are
+    still resolved from `oats-local.yaml`. Earlier releases refuse these keys,
+    so add them only once everyone who reads the workspace runs 0.36.1 or
+    later.
+  - A new readiness warning, `team-model-3-migration` (never blocking), names
+    what 0.37.0 will refuse. `oats teams`, `oats readiness` (and so the
+    Desktop's readiness view) and `oats doctor` show it. Its `condition` is
+    `local-soul-teams` when `oats-local.yaml` has `souls.teams` or
+    `souls.default`, and `local-teams-closed` when `oats-local.yaml` declares
+    `teams` or `defaultTeam` and the workspace file does not say
+    `localTeams: true` (never in the standalone view). `oats doctor` stays
+    offline: it checks `local-teams-closed` against the workspace file this
+    machine last observed, and says so when there is none yet (`oats sync`
+    fixes that). The shapes are in docs/desktop-cli-api.md, under Team
+    readiness items.
+- **oats.framework 1.4.2** (oats.setup 2.2.1; catalog and workspace pin
+  `oats-framework/v1.4.2`) ships the oats.setup skill changes made since
+  1.4.1, which deployments had not received:
+  - `oats-onboarding`: declare how this machine starts a harness once, as
+    that harness's default launch configuration (0.32.0, awebai/oats#368);
+    `oats spawn --preview` names the launch configuration that applies.
+  - `oats-workspace-config`: a soul's launch preference versus a host launch
+    configuration, `E_LAUNCH_CONFIG_INVALID` and `E_CLAUDE_CONFIG_REMOVED`
+    (awebai/oats#368), and the team model 3 workspace keys `defaultTeam`,
+    `localTeams` and `souls:` (awebai/oats#495).
+  - `oats-teams`: preparing for team model 3, and what each
+    `team-model-3-migration` condition asks for (awebai/oats#495).
+  - `oats-package-pins`: the example pins `oats.okf: v4.1.1`
+    (awebai/oats#494).
+
+## What 0.37.0 will change
+
+- **`souls:` in `oats-workspace.yaml` decides which teams a soul may join**
+  besides its default: the most specific key wins (`<member|package>/<soul>`,
+  then `<member|package>/*`, then `"*"`); `teams` is a list of shared labels
+  or `any`. A soul no key matches joins its default only. This applies to
+  package souls too: a workspace opens a package explicitly.
+- **A soul's default team**, in order: its `souls:` `default`; else the
+  deployment's `defaultTeam`, only when the workspace says
+  `localTeams: true`; else the workspace's `defaultTeam`.
+- **`oats-local.yaml` `souls.teams` and `souls.default` are refused**
+  (`E_WORKSPACE_SCHEMA`, reason `removed-key`), and so are `oats soul teams
+  --add/--remove/--default/--clear-default`.
+- **Local `teams` and `defaultTeam` are refused unless the workspace says
+  `localTeams: true`**, and so are `oats teams add/remove/default`. The
+  standalone view still allows them.
+
+## Upgrade
+
+Nothing is required for 0.36.1 itself. To be ready for 0.37.0
+(`oats teams` lists each deployment's `team-model-3-migration` warnings):
+
+1. **Now**, once everyone who reads the workspace runs 0.36.1 or later,
+   commit in `oats-workspace.yaml` the choices each deployment makes locally:
+   - a `souls:` entry for what `souls.teams` says (`"*": { teams: [...] }`
+     for every soul, `<member|package>/<soul>: { teams: [...] }` for one;
+     local keys are bare soul names, workspace keys are qualified by the
+     member or package, as in `souls.disabled`), with a `default:` for what
+     `souls.default` says;
+   - for local teams and a local `defaultTeam`, choose one: (a) keep them
+     personal, and add `localTeams: true`, which clears `local-teams-closed`
+     at once; or (b) commit the teams in `teams:` and the default as
+     `defaultTeam:`.
+2. **When the deployment moves to 0.37.0**, remove from its `oats-local.yaml`
+   `souls.teams`, `souls.default` and, under (b), the local `teams` and
+   `defaultTeam`. Not before: 0.36.1 does not apply the workspace keys, so
+   those local keys are still what decides a soul's teams and default until
+   then, and their warnings stay until they go. 0.37.0 refuses them, naming
+   the replacement.

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

@@ -0,0 +1,111 @@
+# OATS 0.37.0
+
+## Added
+
+- **The Desktop opens one window per workspace** (awebai/oats#481). Each
+  workspace has at most one window, titled with its name (a workspace on a
+  server: `name — server`). Choosing a workspace in the switcher shows it in the
+  current window, or brings its own window to the front when it has one.
+  Each workspace in the switcher has an **Open in new window** button
+  (keyboard: Right Arrow then Enter, or ⌘Enter / Ctrl+Enter). On macOS,
+  **File → New Window** (⌘⇧N) opens a window with no workspace that asks you
+  to choose one, and ⌘\` cycles the windows; on Linux and Windows the command
+  palette has **Window: new window**, with no default chord. Quitting and
+  relaunching brings every window back with its size and place; a window
+  whose workspace isn't served at launch stays remembered until you close it
+  while it is served. Launching the app again with `--dir <deployment>`
+  brings that deployment's window to the front, adding the deployment if
+  needed. An unfocused window re-reads its instance list at the server's
+  blurred cadence (30 s). A window's requests always carry its own
+  workspace: one the server doesn't serve is refused with
+  `E_WORKSPACE_NOT_SERVED`, never answered with another workspace's data.
+  Window positions are kept in `windows.json` in the app's data folder.
+
+## Changed
+
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.38.0`**, so it runs against
+  this release's kernel. Install the CLI and the Desktop 0.37.0 together: the
+  Desktop 0.36.x refuses a 0.37 CLI.
+
+- **Team model 3 is OATS 0.38.0, not 0.37.0.** 0.37.0 keeps 0.36.1's
+  behaviour: the new `oats-workspace.yaml` keys are validated but not applied,
+  and the `team-model-3-migration` warning, which now names 0.38.0, says what
+  0.38.0 will refuse. The migration steps in the 0.36.1 notes apply unchanged.
+
+- **oats.framework 1.4.3** (oats.setup 2.2.2, catalog and workspace pin
+  `oats-framework/v1.4.3`): the `oats-teams` and
+  `oats-workspace-config` skills say team model 3 is 0.38.0, and that 0.36.x
+  and 0.37.x keep applying the local team keys. Remove them only when the
+  deployment moves to 0.38.0.
+
+- **oats.aweb 1.18.1** (catalog and workspace pin, and the bundled mirror):
+  how mail reaches a session now depends on the runtime. Under the default
+  `delivery: channel`, Claude Code takes mail and chat through its
+  `aweb-channel` plugin and pi through the `@awebai/pi` extension, and
+  neither goes through the host wake broker. Codex keeps the wake broker. A
+  Codex home under `channel` is now registered with it at every start, where
+  before it got no wake at all. Every start of a home re-decides the path for
+  that start's runtime and leaves the home on exactly one path. A start that
+  cannot register or deregister the home is refused. Existing instances keep
+  the delivery they were spawned with until they are respawned.
+  `delivery: session` still sends every runtime through the broker.
+
+  oats.aweb 1.18.1 declares `launchPreview` (see Fixed below). A launch
+  preview, including Desktop's start dialog, and a start refused by
+  preflight change no broker registration: the hook calls `aw` only in the
+  real run, after preflight has passed.
+
+## Fixed
+
+- **Launch hooks no longer have side effects under a preview, or before a
+  start's preflight has passed** (awebai/oats#500). A launch hook may register
+  a home with its provider; oats.aweb's registers it with the host wake
+  broker. But `oats launch-config preview`, which Desktop's start dialog
+  calls for running homes, ran every hook for real. A start refused by
+  preflight, including a start of a home that was already running, had also
+  run them. Previewing a running Claude home with another harness could
+  therefore change how that live session is woken.
+
+  A capability now declares that its launch hook is preview-aware, with
+  `"launchPreview": true` at the top level of its manifest. The kernel reads
+  the declaration from the home's own module copy. A preview-aware hook
+  runs twice per start:
+  - **As a preview,** with `OATS_LAUNCH_PREVIEW=1` in the hook environment
+    (a new, additive hook environment variable). This run's contribution
+    drives the preflight and the rendered command.
+  - **For real, without the flag,** only once every check has passed, and
+    before a restart stops the running harness.
+
+  A preview runs only the first pass. A preview-aware hook must change
+  nothing under the flag. It must also return the same contribution either
+  way, apart from the values of the env names its preview answer lists in
+  `volatileEnv` (below). If the real run's contribution differs otherwise,
+  the start is refused with `E_LAUNCH_PREPARATION` and nothing is stopped or
+  started.
+
+  A hook that doesn't declare `launchPreview` runs as it did in 0.36: once
+  per start, for real, during preflight. `oats launch-config preview` never
+  runs it; the preview shows its recorded contribution and says so. The
+  kernel never passes on an `OATS_LAUNCH_PREVIEW` inherited from the
+  environment.
+
+  **Provider authors:** declare `launchPreview` once your launch hook
+  honours `OATS_LAUNCH_PREVIEW`, and expect it to run twice per start
+  (docs/capabilities.md). oats.aweb 1.18.1 does. A kernel before 0.37
+  ignores the key and runs the hook once, as before.
+- **Existing homes whose launch hook renews a credential at every start
+  start again** (awebai/oats#504). The first version of the two-pass rule
+  above ran every launch hook twice. A hook from before the preview flag
+  then really ran under the preview too, and a hook that answers new values
+  at every call failed the comparison. That covers oats.aweb homes with
+  `identity.mode: global` and `renew: launch`, which mint a grant at each
+  start: their starts were refused with `E_LAUNCH_PREPARATION`. Two passes
+  are now opt-in, through `launchPreview`.
+
+  A preview-aware hook can also name, in its preview answer, env whose
+  values only the real run can know, such as `"volatileEnv":
+  ["AWEB_IDENTITY_HOME"]`. The start takes those values from the real run
+  and leaves them out of the comparison. Each must be a name the same hook
+  returned. A harness configuration selector (`CLAUDE_CONFIG_DIR`,
+  `CODEX_HOME`, `PI_CODING_AGENT_DIR`) is refused as volatile, because the
+  package probe reads it before the real run.

package/docs/souls-and-instances.md

@@ -152,8 +152,8 @@ composed skills and instructions, a spawn records:
       "commit": "3f2a9c1e…", "digest": "sha256-…", "materializedAt": "2026-09-24T10:12:44.118Z"
     },
     "oats.okf": {
-      "from": { "kind": "package", "package": "oats.okf", "version": "4.1.0", "commit": "e331a996…", "integrity": "sha256-…", "repoKey": "github.com/awebai/oats-okf" },
-      "commit": "e331a996…", "digest": "sha256-…", "materializedAt": "2026-09-24T10:12:44.201Z"
+      "from": { "kind": "package", "package": "oats.okf", "version": "4.1.1", "commit": "e1d604f7…", "integrity": "sha256-…", "repoKey": "github.com/awebai/oats-okf" },
+      "commit": "e1d604f7…", "digest": "sha256-…", "materializedAt": "2026-09-24T10:12:44.201Z"
     }
   },
   "providers": {

package/docs/workspaces.md

@@ -54,8 +54,8 @@ 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.1                   # bare version → resolves through the official catalog
-  oats.okf: v4.1.0
+  oats.framework: v1.4.3                   # 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
@@ -359,6 +359,39 @@ there is no default; `team-unmapped`, blocking when it is the default;
 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).
+
 ## Provider payloads have three homes
 
 | What it is | Where | Example |

package/lib/core.mjs

@@ -1574,8 +1574,12 @@ export function teamEnv(resolved) {
     OATS_WORKSPACE_NAME: typeof ws.name === "string" ? ws.name : "", OATS_WORKSPACE_KEY: typeof ws.key === "string" ? ws.key : "",
   };
 }
+function withoutAmbientLaunchPreview(env) {
+  const { OATS_LAUNCH_PREVIEW: _ambient, ...rest } = env;
+  return rest;
+}
 export function runLifecycleHooks(event, { home, instance, agentName, soulDir, soulId, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {}, assertRoots }) {
-  const results = { meta: {}, briefs: [], warnings: [], order: [], launch: {}, env: {}, failures: [], contributions: [] };
+  const results = { meta: {}, briefs: [], warnings: [], order: [], launch: {}, env: {}, failures: [], contributions: [], volatileEnv: {} };
   // OATS_SOUL is set for EVERY hook: a caller that does not name the soul (launch,
   // retire) gets the directory the home's spawn recorded.
   if (!soulDir && home) soulDir = instanceSoulDir(home);
@@ -1596,7 +1600,9 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, s
       const stdout = execSync(cmd, {
         cwd: home, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000,
         env: {
-          ...process.env,
+          // OATS_LAUNCH_PREVIEW is the kernel's to give (prepareLaunchHooks), never
+          // inherited: a real start's hook must not read an ambient one as a preview.
+          ...withoutAmbientLaunchPreview(process.env),
           // OATS_INSTANCE_HOME is the runtime-neutral contract name for the
           // instance home (absolute). OATS_HOME predates it and stays as a
           // compatibility alias: shipped capability hooks read it
@@ -1624,6 +1630,8 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, s
       let o = {};
       try { o = JSON.parse(lastLine); } catch { /* non-JSON hook output is fine */ }
       if (o.meta) results.meta[cap.id] = o.meta;
+      // A launch hook's answer as given; prepareLaunchHooks validates it.
+      if (event === "launch" && o.volatileEnv !== undefined) results.volatileEnv[cap.id] = o.volatileEnv;
       if (o.brief) results.briefs.push(`- ${o.brief}`);
       if (o.warning) results.warnings.push(o.warning);
       if (o.launch && typeof o.launch === "object") for (const [rt, args] of Object.entries(o.launch)) results.launch[rt] = `${results.launch[rt] ? `${results.launch[rt]} ` : ""}${args}`;
@@ -2468,7 +2476,10 @@ function requirementsWithArgsMessage(harness, providers, config) {
 /** ONE planner for what a start would run, used by preview and by starts of
  *  existing homes alike: the recorded recipe (or, under a selection, the
  *  current scoped configuration) resolved, preflighted, rendered. `preview`
- *  collects every failed check into `preflight` instead of throwing. A home
+ *  collects every failed check into `preflight` instead of throwing. Launch
+ *  hooks of capabilities declaring `launchPreview` run here only as a preview
+ *  (OATS_LAUNCH_PREVIEW=1); the others run here for real when a start plans,
+ *  and not at all for a preview. A home
  *  that records no launch recipe (an earlier kernel spawned it) is not planned:
  *  E_LAUNCH_LEGACY, re-spawn it from the deployment. */
 export function planLaunch({ home, instance, meta, contextDir, agentLike, selection = {}, launchConfigs, resolvedCfg, env = process.env, preview = false, assertRoots, reselect = null }) {
@@ -2514,14 +2525,17 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
     // Recorded contributions, refreshed by capabilities that declare a
     // launch hook; a harness change needs the new harness's arguments from
     // every capability that gave harness-specific ones; recorded arguments
-    // of a capability the scope no longer trusts are not reused.
+    // of a capability the scope no longer trusts are not reused. Hooks that
+    // declare launchPreview run here under OATS_LAUNCH_PREVIEW=1, for a start
+    // too (it runs them for real once its preflight passed); the others run
+    // here for real on a start, and not at all for a preview.
     try {
-      hooks = prepareLaunchHooks({ frozen, harness, resolvedCfg, home, meta, contextDir, assertRoots });
+      hooks = prepareLaunchHooks({ frozen, harness, resolvedCfg, home, meta, contextDir, assertRoots, pass: preview ? "preview" : "plan" });
       const current = new Map((resolvedCfg?.capabilities || []).map((c) => [c.id, c]));
       const untrusted = hooks.contributions.filter((c) => c.capability && current.has(c.capability) && !current.get(c.capability).trust?.trusted).map((c) => c.capability);
       const inactive = hooks.contributions.filter((c) => c.capability && !current.has(c.capability)).map((c) => c.capability);
       if (untrusted.length) fail("capabilities", "E_LAUNCH_PREPARATION", `${untrusted.join(", ")} contributed to this launch at spawn but is no longer trusted in the scope; respawn the instance; nothing was stopped`);
-      else problems.push({ check: "capabilities", ok: true, detail: `${harness !== frozen.harness ? "prepared for the new harness" : "recorded contributions reused"}${hooks.refreshed?.length ? `; refreshed by launch hooks: ${hooks.refreshed.join(", ")}` : ""}${inactive.length ? `; no longer active in the scope, recorded contribution kept: ${inactive.join(", ")}` : ""}` });
+      else problems.push({ check: "capabilities", ok: true, detail: `${harness !== frozen.harness ? "prepared for the new harness" : "recorded contributions reused"}${hooks.refreshed?.length ? `; refreshed by launch hooks: ${hooks.refreshed.join(", ")}` : ""}${hooks.notRun?.length ? `; recorded contribution shown, launch hook not run for a preview (not preview-aware): ${hooks.notRun.join(", ")}` : ""}${inactive.length ? `; no longer active in the scope, recorded contribution kept: ${inactive.join(", ")}` : ""}` });
     } catch (e) {
       if (e.code !== "E_LAUNCH_PREPARATION") throw e;
       fail("capabilities", e.code, e.message);
@@ -2574,7 +2588,7 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
   const { trustHome } = launchFolderTrust({ harness, home, meta, yolo: recipe.yolo, env });
   const command = renderLaunchRecipe(recipe, { home, instance: inst, trustHome });
   const selectionSource = frozen ? (config?.frozen || (!config && !selection.launchConfig && !selection.harness) ? "frozen" : "config") : "config";
-  return { recipe, command, trustHome, harness, model: model || undefined, modelSource, yolo, config, executable, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, launchChoice, warnings: hooks.warnings || [], ...(hooks.meta ? { hookMeta: hooks.meta } : {}) };
+  return { recipe, command, trustHome, harness, model: model || undefined, modelSource, yolo, config, executable, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, launchChoice, warnings: hooks.warnings || [], previewedHooks: hooks.previewed || [], volatileEnv: hooks.volatileEnv || [], ...(hooks.meta ? { hookMeta: hooks.meta } : {}) };
 }
 /** The environment a planned launch runs under: the host's base, the
  *  capabilities' validated env, the configuration's literals and its
@@ -4863,10 +4877,24 @@ export function capturedProviders(meta, frozen) {
 }
 /** Capability contributions for a start of an existing home: the recorded
  *  ones, refreshed by any capability that declares a `launch` hook (asked
- *  for the target harness; side-effect-free by contract; spawn hooks are
- *  never re-run). A harness change needs the new harness's launch arguments
- *  from every capability that contributed harness-specific ones. */
-export function prepareLaunchHooks({ frozen, harness, resolvedCfg, home, meta, contextDir, extraEnv = {}, assertRoots }) {
+ *  for the target harness; spawn hooks are never re-run). A harness change
+ *  needs the new harness's launch arguments from every capability that
+ *  contributed harness-specific ones.
+ *  The hook contract: a launch hook may do idempotent provider registration
+ *  on a real start. A capability whose manifest (the home's module copy)
+ *  declares `launchPreview: true` promises that its hook changes nothing
+ *  under OATS_LAUNCH_PREVIEW=1 and returns the same contribution (launch
+ *  arguments and env) either way, except for the env names its preview
+ *  answer lists in `volatileEnv`, whose values only the real run knows.
+ *  `pass` says which hooks run, and how:
+ *  - "preview" (a launch preview): declaring hooks under the flag; the others
+ *    do not run, and their recorded contributions stand (`notRun`);
+ *  - "plan" (a start's preflight): declaring hooks under the flag, the others
+ *    once, for real;
+ *  - "real" (a start after its preflight passed): declaring hooks for real,
+ *    over `frozen.hooks` = the planned contributions; startInstanceSession
+ *    refuses a contribution that differs from the preview's. */
+export function prepareLaunchHooks({ frozen, harness, resolvedCfg, home, meta, contextDir, extraEnv = {}, assertRoots, pass = "plan" }) {
   const contributions = (frozen.hooks?.contributions || []).map((c) => ({ ...c }));
   const env = { ...(frozen.hooks?.env || {}) };
   const refreshed = [];
@@ -4889,20 +4917,44 @@ export function prepareLaunchHooks({ frozen, harness, resolvedCfg, home, meta, c
     const hooks = manifestHookCommands(manifest);
     if (hooks.launch) withLaunchHook.push({ id: p.id, capability: p.id, manifest, layer: p.contribution?.layer ?? p.binding?.layer ?? manifest.layer ?? null, level: p.contribution?.level ?? p.binding?.level ?? null, settings: p.settings, settingsOrigins: p.settingsOrigins, hooks, trust, environment: [...(manifest.environment || [])], environmentNamespaces: [...(manifest.environmentNamespaces || [])], missingRequires: [] });
   }
-  if (withLaunchHook.length) {
-    const res = runLifecycleHooks("launch", { assertRoots, home, instance: meta.instance, agentName: meta.agent, soulDir: instanceSoulDir(home, meta), contextDir: ctx, rootDir: dirname(dirname(dirname(home))), resolved: { ...(resolvedCfg || {}), capabilities: withLaunchHook }, priorMeta: meta.capabilityMeta || {}, extraEnv: { OATS_HARNESS: harness, OATS_PREVIOUS_HARNESS: frozen.harness || "", OATS_RUNTIME: harness, OATS_PREVIOUS_RUNTIME: frozen.harness || "", ...extraEnv } });
-    const failed = (res.failures || []).map((f) => `${f.capability}: ${f.message}`);
+  const aware = withLaunchHook.filter((c) => c.manifest.launchPreview === true);
+  const unaware = withLaunchHook.filter((c) => c.manifest.launchPreview !== true);
+  const runs = (pass === "real" ? [[aware, false]] : pass === "preview" ? [[aware, true]] : [[unaware, false], [aware, true]]).filter(([caps]) => caps.length);
+  const notRun = pass === "preview" ? unaware.map((c) => c.id) : [];
+  const previewed = runs.filter(([, asPreview]) => asPreview).flatMap(([caps]) => caps.map((c) => c.id));
+  const volatileEnv = [];
+  if (runs.length) {
+    const results = runs.map(([caps, asPreview]) => ({ asPreview, res: runLifecycleHooks("launch", { assertRoots, home, instance: meta.instance, agentName: meta.agent, soulDir: instanceSoulDir(home, meta), contextDir: ctx, rootDir: dirname(dirname(dirname(home))), resolved: { ...(resolvedCfg || {}), capabilities: caps }, priorMeta: meta.capabilityMeta || {}, extraEnv: { OATS_HARNESS: harness, OATS_PREVIOUS_HARNESS: frozen.harness || "", OATS_RUNTIME: harness, OATS_PREVIOUS_RUNTIME: frozen.harness || "", ...(asPreview ? { OATS_LAUNCH_PREVIEW: "1" } : {}), ...extraEnv } }) }));
+    const failed = results.flatMap(({ res }) => res.failures || []).map((f) => `${f.capability}: ${f.message}`);
     if (failed.length) throw oatsError("E_LAUNCH_PREPARATION", `a capability could not prepare the ${harness} launch:\n  ${failed.join("\n  ")}`);
+    const fresh = results.flatMap(({ res }) => res.contributions || []);
     // Ownership holds across retained AND refreshed contributions, as the
     // spawn runner holds it across providers: a refreshed provider may
-    // replace its own previous keys, never a key another provider retains.
-    const refreshedIds = new Set((res.contributions || []).map((c) => c.capability));
+    // replace its own previous keys, never a key another provider retains,
+    // nor one another provider's hook set in this pass.
+    const refreshedIds = new Set(fresh.map((c) => c.capability));
     const retainedOwner = new Map();
     for (const c of contributions) if (c.capability && !refreshedIds.has(c.capability)) for (const name of c.env || []) retainedOwner.set(name, c.capability);
-    for (const c of res.contributions || []) for (const name of c.env || []) {
+    const freshOwner = new Map();
+    for (const c of fresh) for (const name of c.env || []) {
       if (retainedOwner.has(name)) throw oatsError("E_LAUNCH_PREPARATION", `${c.capability}'s launch hook set ${name}, which ${retainedOwner.get(name)} contributed at spawn and retains; one provider owns an environment name; nothing was stopped`);
+      if (freshOwner.has(name) && freshOwner.get(name) !== c.capability) throw oatsError("E_LAUNCH_PREPARATION", `${c.capability}'s launch hook set ${name}, which ${freshOwner.get(name)}'s launch hook also set; one provider owns an environment name; nothing was stopped`);
+      freshOwner.set(name, c.capability);
+    }
+    // A preview answer may name env whose values only the real run knows
+    // (a credential minted at start). Each is a name the same hook returned,
+    // and never a harness's configuration selector: the package probe reads
+    // that under the preview's value before the real run.
+    for (const { asPreview, res } of results) if (asPreview) for (const [id, names] of Object.entries(res.volatileEnv || {})) {
+      if (!Array.isArray(names) || names.some((n) => typeof n !== "string")) throw oatsError("E_LAUNCH_PREPARATION", `${id}'s launch hook answered volatileEnv that is not an array of environment names; nothing was stopped`);
+      const returned = (res.contributions || []).find((c) => c.capability === id)?.env || [];
+      for (const name of names) {
+        if (!returned.includes(name)) throw oatsError("E_LAUNCH_PREPARATION", `${id}'s launch hook declared ${name} volatile but did not return it in env; nothing was stopped`);
+        if (HARNESS_CONFIG_SELECTORS.has(name)) throw oatsError("E_LAUNCH_PREPARATION", `${id}'s launch hook declared ${name} volatile, but ${name} selects a harness's configuration, which the start's package probe reads before the real run; a volatile value must not affect harness package resolution; nothing was stopped`);
+        volatileEnv.push(name);
+      }
     }
-    for (const c of res.contributions || []) {
+    for (const c of fresh) {
       const idx = contributions.findIndex((x) => x.capability === c.capability);
       // The provider's previous contribution goes whole, its env names
       // included, before its new (validated) one is merged: an empty answer
@@ -4912,23 +4964,32 @@ export function prepareLaunchHooks({ frozen, harness, resolvedCfg, home, meta, c
       if (idx >= 0) contributions[idx] = row; else contributions.push(row);
       refreshed.push(c.capability);
     }
-    Object.assign(env, res.env || {});
+    for (const { res } of results) Object.assign(env, res.env || {});
+    // What the caller records comes from real runs only; a launch preview
+    // answers its own runs' warnings.
+    const recorded = results.filter(({ asPreview }) => asPreview === (pass === "preview")).map(({ res }) => res);
     // A launch hook's `meta` is part of its documented return (the same shape
     // spawn persists as capabilityMeta). It was collected and then dropped
     // here, so a provider that re-issues a credential at every start — a
     // renewed session grant, for instance — left the ORIGINAL id on record and
     // retire undid the wrong one. Carry it to the caller; the start records it.
-    hookMeta = res.meta && Object.keys(res.meta).length ? res.meta : undefined;
+    const metaOf = Object.assign({}, ...recorded.map((res) => res.meta || {}));
+    hookMeta = Object.keys(metaOf).length ? metaOf : undefined;
     // The hooks' advisory warnings go to the start's answer and events, as
     // spawn's do; they were dropped here before 0.30.
-    warnings = [...(res.warnings || [])];
+    warnings = recorded.flatMap((res) => res.warnings || []);
   }
-  const unprepared = contributions.filter((c) => !refreshed.includes(c.capability) && c.launch && c.launch[frozen.harness] !== undefined && c.launch[harness] === undefined).map((c) => c.capability);
+  // A hook not run for a preview keeps its recorded contribution: whether it
+  // has arguments for the target harness is its own run's answer, at start.
+  const unprepared = contributions.filter((c) => !refreshed.includes(c.capability) && !notRun.includes(c.capability) && c.launch && c.launch[frozen.harness] !== undefined && c.launch[harness] === undefined).map((c) => c.capability);
   if (unprepared.length) throw oatsError("E_LAUNCH_PREPARATION", `${unprepared.join(", ")} contributed ${frozen.harness} launch arguments at spawn and none for ${harness}; change that capability's setting (for example its delivery mode), or the provider must declare a launch hook; nothing was stopped`);
   const launch = {};
   for (const c of contributions) { for (const [rt, args] of Object.entries(c.launch || {})) if (args) launch[rt] = `${launch[rt] ? `${launch[rt]} ` : ""}${args}`; }
-  return { launch, env, contributions, refreshed, warnings, ...(hookMeta ? { meta: hookMeta } : {}) };
+  return { launch, env, contributions, refreshed, notRun, previewed, volatileEnv, warnings, ...(hookMeta ? { meta: hookMeta } : {}) };
 }
+/** Environment that selects which configuration (account, packages) a
+ *  harness reads, under which the package probe inspects its packages. */
+const HARNESS_CONFIG_SELECTORS = new Set(["CLAUDE_CONFIG_DIR", "CODEX_HOME", "PI_CODING_AGENT_DIR"]);
 
 
 export function restartInstanceSession(home, o = {}) { return startInstanceSession(home, { ...o, restart: true }); }
@@ -5093,7 +5154,7 @@ export function startInstanceSession(home, o = {}) {
     const reselect = o.reselectLaunch === true ? homeLaunchLayers(realHome, meta) : null;
     const selected = reselect !== null || o.launchConfig !== undefined || o.harness !== undefined || o.yolo !== undefined;
     const hasRecipe = meta.launch && typeof meta.launch === "object";
-    let launchPlan = null, explicitModelFrom = null, warnings = [];
+    let launchPlan = null, launchHooksPass = null, hookMeta, explicitModelFrom = null, warnings = [];
     if (selected || hasRecipe) {
       // Every start of a home with a recipe (ordinary, model-only, or under a
       // selection) goes through the one planner: recipe shape, the recorded
@@ -5106,11 +5167,15 @@ export function startInstanceSession(home, o = {}) {
       const resolvedCfg = resolvedFromHome(realHome, meta, { teams: o.teams, defaultTeam: o.defaultTeam, teamsSource: o.teamsSource });
       let agent; try { agent = findAgent(dirname(dirname(dirname(realHome))), meta.agent); } catch { agent = undefined; }
       const plan = planLaunch({ home: realHome, instance: meta.instance, meta, contextDir: context, agentLike: agent || { harness: meta.harness, model: meta.model, yolo: meta.yolo }, selection: { launchConfig: o.launchConfig, harness: o.harness, model: o.model, yolo: o.yolo }, reselect, resolvedCfg, env: o.env || process.env, assertRoots: checkRoots });
-      launchPlan = { recipe: plan.recipe, command: plan.command, harness: plan.harness, model: plan.model, yolo: plan.yolo, modelFrom: modelFromOf(plan.modelSource, { at: "start", prior: meta.modelFrom ?? null }), ...(plan.hookMeta ? { hookMeta: plan.hookMeta } : {}),
+      launchPlan = { recipe: plan.recipe, command: plan.command, harness: plan.harness, model: plan.model, yolo: plan.yolo, modelFrom: modelFromOf(plan.modelSource, { at: "start", prior: meta.modelFrom ?? null }),
         ...(plan.launchChoice ? { launchFrom: plan.launchChoice.from, launchAt: plan.launchChoice.at, launchDeclared: plan.launchChoice.declared } : {}) };
+      // The plan ran preview-aware launch hooks as a preview: their real run, over the planned
+      // contributions, waits for the rest of preflight.
+      if (plan.previewedHooks.length) launchHooksPass = { frozen: { ...plan.frozen, hooks: plan.recipe.hooks }, harness: plan.harness, resolvedCfg, contextDir: context, previewed: plan.recipe.hooks, volatileEnv: plan.volatileEnv, trustHome: plan.trustHome };
       command = launchPlan.command; model = launchPlan.model;
-      // The launch hooks have run: their warnings are events now, whatever
-      // the start does next, and the answer carries them.
+      // The other launch hooks ran for real in the plan: their warnings are
+      // events now, whatever the start does next, and the answer carries them.
+      hookMeta = plan.hookMeta;
       warnings = plan.warnings;
       for (const message of warnings) appendEvent(realHome, { kind: "launch-warning", data: { message } });
     } else if (o.model !== undefined && o.model !== null && String(o.model).trim() !== "") {
@@ -5127,10 +5192,7 @@ export function startInstanceSession(home, o = {}) {
     if (recipeForEnv) { const missing = missingLaunchEnvRefs(recipeForEnv.env, o.env || process.env); if (missing.length) throw oatsError("E_LAUNCH_ENV_MISSING", `this home's launch references ${missing.join(", ")}, not set on this host; nothing was started`); }
     const paneEnv = recipeForEnv ? launchEnvRefs(recipeForEnv, o.env || process.env) : [];
     const paneEnvFlags = paneEnv.flatMap((r) => ["-e", `${r.name}=${r.value}`]);
-    checkRoots(); // launch hooks/preparation have run; no backend has been observed
-    const planExtra = launchPlan ? { launch: launchPlan.recipe, harness: launchPlan.harness, yolo: launchPlan.yolo, ...(launchPlan.modelFrom ? { modelFrom: launchPlan.modelFrom } : {}),
-      ...(launchPlan.launchFrom ? { launchFrom: launchPlan.launchFrom, launchAt: launchPlan.launchAt, launchDeclared: launchPlan.launchDeclared } : {}),
-      ...(launchPlan.hookMeta ? { hookMeta: launchPlan.hookMeta } : {}) } : (explicitModelFrom ? { modelFrom: explicitModelFrom } : {});
+    checkRoots(); // preparation has run; no backend has been observed
     let target = receipt.target;
     let state = { present: false, state: "not-launched" };
     let serverGone = false;
@@ -5141,9 +5203,38 @@ export function startInstanceSession(home, o = {}) {
         else throw oatsError("E_SESSION_UNKNOWN", `cannot establish whether ${meta.instance} is running, so nothing was started: ${String(e.stderr ?? e.message ?? "").trim() || e.message}`);
       }
     }
+    if (state.present && state.state !== "shell" && !o.restart) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is running (${state.state}); nothing was started`);
+    // Every preflight has passed: the preview-aware launch hooks run for real
+    // (they may register the home with their provider), before a restart's
+    // stop, and must contribute exactly what they contributed as a preview,
+    // which is what the command was rendered and preflighted from, except the
+    // values of the env their preview declared volatile: those come from this
+    // run, and the command is rendered again with them.
+    if (launchHooksPass) {
+      const { previewed, volatileEnv, trustHome, ...pass } = launchHooksPass;
+      const real = prepareLaunchHooks({ ...pass, home: realHome, meta, assertRoots: checkRoots, pass: "real" });
+      const canon = (v) => canonicalJson(JSON.parse(JSON.stringify(v ?? null)));
+      const stable = (h) => Object.fromEntries(Object.entries(h.env).filter(([n]) => !volatileEnv.includes(n)));
+      if (canon({ launch: real.launch, env: stable(real), contributions: real.contributions }) !== canon({ launch: previewed.launch, env: stable(previewed), contributions: previewed.contributions })) {
+        // A provider's row names its env; the values are in the merged env.
+        const rowOf = (h, id) => { const row = h.contributions.find((c) => c.capability === id); return canon({ row, values: (row?.env || []).map((n) => volatileEnv.includes(n) ? null : h.env[n]) }); };
+        const differing = [...new Set([...real.contributions, ...previewed.contributions].map((c) => c.capability))].filter((id) => rowOf(real, id) !== rowOf(previewed, id));
+        throw oatsError("E_LAUNCH_PREPARATION", `the launch hook of ${differing.join(", ") || "a capability"} returned a contribution that differs from its preview contribution (a launch hook returns the same contribution under OATS_LAUNCH_PREVIEW, apart from the values of its volatileEnv); nothing was stopped or started`);
+      }
+      launchPlan.recipe = { ...launchPlan.recipe, hooks: { launch: real.launch, env: real.env, contributions: real.contributions } };
+      command = launchPlan.command = renderLaunchRecipe(launchPlan.recipe, { home: realHome, instance: meta.instance, trustHome });
+      if (real.meta) hookMeta = { ...(hookMeta || {}), ...real.meta };
+      // The real run's warnings are events now, whatever the start does next,
+      // and the answer carries them.
+      warnings = [...warnings, ...real.warnings];
+      for (const message of real.warnings) appendEvent(realHome, { kind: "launch-warning", data: { message } });
+      checkRoots();
+    }
+    const planExtra = launchPlan ? { launch: launchPlan.recipe, harness: launchPlan.harness, yolo: launchPlan.yolo, ...(launchPlan.modelFrom ? { modelFrom: launchPlan.modelFrom } : {}),
+      ...(launchPlan.launchFrom ? { launchFrom: launchPlan.launchFrom, launchAt: launchPlan.launchAt, launchDeclared: launchPlan.launchDeclared } : {}),
+      ...(hookMeta ? { hookMeta } : {}) } : (explicitModelFrom ? { modelFrom: explicitModelFrom } : {});
     let stopReceipt = null;
     if (state.present && state.state !== "shell") {
-      if (!o.restart) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is running (${state.state}); nothing was started`);
       // Restart: every preflight above passed, so ask the running harness to
       // end and wait, bounded. A harness still there afterwards is reported
       // as running; nothing is escalated and nothing is launched.

package/lib/schedule.mjs

@@ -516,7 +516,7 @@ export function childEnv() {
   for (const key of [...RESERVED_LAUNCH_ENV,
     "OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
     "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
-    "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_RETIRE_INTENT",
+    "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT",
     "OATS_TEAM_NAME", "OATS_TEAM_SCOPE", "OATS_TEAM_ID", "OATS_TEAM_LABEL", "OATS_TEAM_LABELS", "OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_TEAMS", "OATS_TEAMS_SOURCE", "OATS_TRIGGER_EVENT_FILE",
   ]) delete env[key];
   return env;

package/lib/teams.mjs

@@ -17,6 +17,10 @@
  * Rows (docs/desktop-cli-api.md, Team model v2): TeamRow { label, team, default, from: shared|local },
  * the default first, then by label. Reports carry unmapped rows (team null); OATS_TEAMS and
  * instance.json carry mapped rows only. DefaultTeam { label, team, from: deployment|soul } | null.
+ *
+ * Team model 3 (0.38.0, awebai/oats#484) moves these choices into the committed workspace file. 0.36.x and
+ * 0.37.x validate its keys (lib/workspace.mjs) without applying them, and warn about what 0.38.0 will refuse
+ * (migrationProblems: team-model-3-migration).
  */
 import { oatsError } from "./errors.mjs";
 
@@ -53,11 +57,19 @@ export function teamModel(workspace, local, { workspaceKey = null } = {}) {
     localTeams.set(label, { label, team: str(def?.team), description: str(def?.description), from: "local", at: `${LOCAL_FILE}#/teams/${pointerKey(label)}` });
   }
   const souls = isObject(local?.souls) ? local.souls : {};
+  const has = (v, k) => isObject(v) && Object.hasOwn(v, k);
   return {
     shared, local: localTeams,
     labels: new Map([...localTeams, ...shared]), // the committed definition wins a collision
     defaultTeam: str(local?.defaultTeam),
     souls: { teams: isObject(souls.teams) ? souls.teams : {}, default: isObject(souls.default) ? souls.default : {} },
+    // Team model 3 (0.38.0) moves these keys; 0.36.x and 0.37.x only warn (migrationProblems). `localTeams` is
+    // the workspace's answer, null without a workspace file (the standalone view has no workspace rules).
+    migration: {
+      soulKeys: ["teams", "default"].filter((k) => has(local?.souls, k)).map((k) => `souls.${k}`),
+      teamKeys: ["teams", "defaultTeam"].filter((k) => has(local, k)),
+      localTeams: isObject(workspace) ? workspace.localTeams === true : null,
+    },
   };
 }
 
@@ -130,6 +142,27 @@ const unconfiguredProblem = () => ({ code: "E_TEAM_UNCONFIGURED", severity: "fai
 const refusalProblem = (e) => ({ code: e.code, ...e.details, severity: "failure", message: e.message,
   fix: e.code === "E_TEAM_UNKNOWN" ? "declare the team (`oats teams add`), or remove the reference" : "add the label to the soul's teams (`oats soul teams … --add`), or clear its default (`--clear-default`)" });
 
+/** The fields of a team-model-3-migration problem other than code/severity/message/fix, as every
+ *  surface (oats teams, readiness, doctor) carries them. */
+export const MIGRATION_CODE = "team-model-3-migration";
+/**
+ * The team-model-3-migration warnings (0.36.x and 0.37.x; 0.38.0 refuses what they name): `local-soul-teams` when
+ * oats-local.yaml has souls.teams / souls.default, `local-teams-closed` when it declares teams /
+ * defaultTeam and the workspace file does not say `localTeams: true` (never without a workspace file).
+ */
+export function migrationProblems(model) {
+  const m = model.migration, problems = [];
+  if (m.soulKeys.length) problems.push({ code: MIGRATION_CODE, severity: "warning", condition: "local-soul-teams", keys: [...m.soulKeys],
+    message: `oats-local.yaml ${m.soulKeys.join(", ")}: OATS 0.38.0 refuses ${m.soulKeys.length > 1 ? "these keys" : "this key"}; which teams a soul may join, and its default, move to souls: in oats-workspace.yaml`,
+    fix: `commit the same choices as souls: entries in oats-workspace.yaml ("*" or <member|package>/<soul>: { default, teams }), then remove ${m.soulKeys.join(" and ")} from oats-local.yaml` });
+  if (m.teamKeys.length && m.localTeams === false) problems.push(localTeamsClosedProblem(m.teamKeys));
+  return problems;
+}
+/** `local-teams-closed` for the oats-local.yaml `keys` found (doctor builds it from its offline read). */
+export const localTeamsClosedProblem = (keys) => ({ code: MIGRATION_CODE, severity: "warning", condition: "local-teams-closed", keys: [...keys],
+  message: `oats-local.yaml declares ${keys.join(", ")}, but oats-workspace.yaml does not say localTeams: true: OATS 0.38.0 refuses local teams and a local defaultTeam unless the workspace allows them`,
+  fix: "either (a) add `localTeams: true` to oats-workspace.yaml, or (b) commit the teams and defaultTeam in oats-workspace.yaml, then remove them from oats-local.yaml" });
+
 /**
  * Readiness problems. Without `key`: the deployment's (`oats teams`): collisions, unmapped shared
  * teams (a failure when it is `defaultTeam`), every unknown reference, every ineligible
@@ -141,11 +174,11 @@ export function teamProblems(model, { key = null, messaging = false } = {}) {
   if (key !== null) {
     let t;
     try { t = soulTeams(model, key); }
-    catch (e) { if (e.code === "E_TEAM_UNKNOWN" || e.code === "E_TEAM_NOT_ELIGIBLE") return [refusalProblem(e)]; throw e; }
+    catch (e) { if (e.code === "E_TEAM_UNKNOWN" || e.code === "E_TEAM_NOT_ELIGIBLE") return [refusalProblem(e), ...migrationProblems(model)]; throw e; }
     for (const r of t.teams) if (model.shared.has(r.label) && model.local.has(r.label)) problems.push(collisionProblem(r.label, model.shared.get(r.label), model.local.get(r.label)));
     for (const r of t.teams) if (r.team === null) problems.push(unmappedProblem(model.labels.get(r.label), r.default));
     if (messaging && t.defaultTeam === null) problems.push(unconfiguredProblem());
-    return problems;
+    return [...problems, ...migrationProblems(model)];
   }
   const labels = [...model.labels.keys()].sort(byCodepoint);
   for (const label of labels) if (model.shared.has(label) && model.local.has(label)) problems.push(collisionProblem(label, model.shared.get(label), model.local.get(label)));
@@ -159,7 +192,7 @@ export function teamProblems(model, { key = null, messaging = false } = {}) {
     try { soulTeams(model, k); } catch (e) { if (e.code === "E_TEAM_NOT_ELIGIBLE" && e.details.soul === k) problems.push(refusalProblem(e)); else if (e.code !== "E_TEAM_UNKNOWN") throw e; }
   }
   if (messaging && model.defaultTeam === null) problems.push(unconfiguredProblem());
-  return problems;
+  return [...problems, ...migrationProblems(model)];
 }
 
 /**

package/lib/workspace.mjs

@@ -243,8 +243,22 @@ export function validateWorkspace(value, { remote = defaultRemote } = {}) {
     const d = value.defaults;
     for (const slot of ["knowledge", "messaging", "tasks", "capabilities"]) fromProblems(remote, d[slot], `/defaults/${slot}`, problems, { here: false });
   }
+  sharedLabelProblems(value, problems);
   return withRemovedKeys(problems, value, REMOVED_KEYS.workspace);
 }
+/** Team model 3: every label `defaultTeam` and `souls:` name is a shared team of this same file, so an
+ *  unknown label is refused when the file is read, never at a spawn on someone else's machine. */
+function sharedLabelProblems(value, problems) {
+  const shared = new Set(isObject(value.teams) ? Object.keys(value.teams) : []);
+  const known = (label, path) => { if (typeof label === "string" && !shared.has(label)) problems.push({ path, message: `${show(label)} is not a shared team: declare it in teams: of this file` }); };
+  known(value.defaultTeam, "/defaultTeam");
+  if (isObject(value.souls)) for (const [key, entry] of Object.entries(value.souls)) {
+    if (!isObject(entry)) continue;
+    const at = `/souls/${pointerKey(key)}`;
+    known(entry.default, `${at}/default`);
+    if (Array.isArray(entry.teams)) entry.teams.forEach((label, i) => known(label, `${at}/teams/${i}`));
+  }
+}
 export function validateMembership(value) { return withRemovedKeys(validateAgainst(schemaFor("membership"), value), value, REMOVED_KEYS.membership); }
 
 /** Keys 0.30 removed (team model v2): each is a schema problem naming its replacement, in place of

package/package-catalog.json

@@ -3,12 +3,12 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v4.1.0",
+      "ref": "v4.1.1",
       "path": "oats-package"
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.17.7",
+      "ref": "v1.18.1",
       "path": "oats-package"
     },
     "oats.jira": {
@@ -33,7 +33,7 @@
     },
     "oats.framework": {
       "url": "https://github.com/awebai/oats.git",
-      "ref": "oats-framework/v1.4.1",
+      "ref": "oats-framework/v1.4.3",
       "path": "oats-package"
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",

package/skills/oats-getting-started/SKILL.md

@@ -60,8 +60,8 @@ members:
   - git:github.com/acme/agents          # the host is a member too
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.4.1                # bare versions resolve through the official catalog
-  oats.okf: v4.1.0
+  oats.framework: v1.4.3                # bare versions resolve through the official catalog
+  oats.okf: v4.1.1
 defaults:
   capabilities: { oats.core: { from: package } }
   knowledge: { oats.okf: { from: package } }