@awebai/oats 0.36.1 → 0.37.0

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,10 +81,10 @@ 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.37.0 (team model 3) removes `souls.teams` and `souls.default` (they move
+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 still applies all
-four keys and warns about them (`team-model-3-migration`): see
+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
@@ -242,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

@@ -1229,7 +1229,7 @@ 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: what OATS 0.37.0 (team model 3) refuses, one item per condition (below) |
+| `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 `E_TEAM_UNKNOWN` and `E_TEAM_NOT_ELIGIBLE` codes are also spawn, preview and
 inspect refusals, with the same details.
@@ -1249,7 +1249,7 @@ carries it, and `oats teams` lists it once. Its `condition`:
 
 ```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.37.0 refuses local teams and a local defaultTeam unless the workspace allows them",
+ "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"}
 ```
 

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

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

package/docs/oats-workspace.schema.json

@@ -29,17 +29,17 @@
     },
     "defaultTeam": {
       "$ref": "#/$defs/label",
-      "description": "Team model 3 (0.37.0): the workspace's fallback default team, a label of teams: in this file. 0.36.x accepts and validates it without applying it."
+      "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.37.0): whether deployments may declare their own teams and defaultTeam in oats-local.yaml. Absent: false. 0.36.x accepts it without applying it."
+      "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.37.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 accepts and validates it without applying it."
+      "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": {

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.2` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
+| `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.17.7` | `oats.aweb` (messaging) | |
+| `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) | |

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.2`) 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.2
+  oats.framework: v1.4.3
   oats.okf: v4.1.1
-  oats.aweb: v1.17.7
+  oats.aweb: v1.18.1
 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.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
 ```
@@ -332,11 +332,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.2", "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.2`
-resolves to tag `oats-framework/v1.4.2`. 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.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/workspaces.md

@@ -54,7 +54,7 @@ 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.2                   # bare version → resolves through the official catalog
+  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
 
@@ -361,10 +361,10 @@ Exact shapes: [desktop-cli-api.md](desktop-cli-api.md#team-model-v2-feature-team
 
 ### Preparing for team model 3 (0.36.x)
 
-OATS 0.37.0 commits a soul's teams in the workspace (team model 3,
+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 prepares for it, so
+`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
@@ -385,7 +385,7 @@ every workspace and deployment can migrate first:
   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.37.0 will refuse: `souls.teams` / `souls.default` in `oats-local.yaml`
+  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

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

@@ -18,8 +18,8 @@
  * 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.37.0, awebai/oats#484) moves these choices into the committed workspace file. 0.36.x
- * validates its keys (lib/workspace.mjs) without applying them, and warns about what 0.37.0 will refuse
+ * 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";
@@ -63,7 +63,7 @@ export function teamModel(workspace, local, { workspaceKey = null } = {}) {
     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.37.0) moves these keys; 0.36.x only warns (migrationProblems). `localTeams` is
+    // 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}`),
@@ -146,21 +146,21 @@ const refusalProblem = (e) => ({ code: e.code, ...e.details, severity: "failure"
  *  surface (oats teams, readiness, doctor) carries them. */
 export const MIGRATION_CODE = "team-model-3-migration";
 /**
- * The team-model-3-migration warnings (0.36.x; 0.37.0 refuses what they name): `local-soul-teams` when
+ * 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.37.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`,
+    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.37.0 refuses local teams and a local defaultTeam unless the workspace allows them`,
+  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" });
 
 /**

package/package-catalog.json

@@ -8,7 +8,7 @@
     },
     "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.2",
+      "ref": "oats-framework/v1.4.3",
       "path": "oats-package"
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.36.1",
+  "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,7 +60,7 @@ members:
   - git:github.com/acme/agents          # the host is a member too
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.4.2                # bare versions resolve through the official catalog
+  oats.framework: v1.4.3                # bare versions resolve through the official catalog
   oats.okf: v4.1.1
 defaults:
   capabilities: { oats.core: { from: package } }