@awebai/oats 0.36.1 → 0.38.0

package/docs/workspaces.md

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

package/lib/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.