@awebai/oats 0.25.5 → 0.25.7

package/bin/oats.mjs

@@ -31,7 +31,7 @@ import {
   packageIntegrity, capabilityArtifactIntegrity, verifyCapabilityInstallation, installedCapabilityDir,
   resolveOatsConfig, resolveWorkMode, composeInstanceAgentsMd, parseYamlNested, assertSafeConfigValue, stripInternalAnnotations, withConfigFile, teamAgentRoots,
   findTeamAgent, findTeamInstance, findCapabilityAgent, findInstanceHome, findInstanceHomes, listCapabilityAgents, workspaceOf, stopInstanceSession, recomposeInstanceInstructions,
-  ensureRoot, findRoot, findAgent, listAgents, listInstances, listAgentDefs, createAgent as coreCreateAgent,
+  ensureRoot, findRoot, findAgent, listAgents, listInstances, servedIdentityLine, servedIdentityOf, listAgentDefs, createAgent as coreCreateAgent,
   spawnInstance, spawnInstanceAsync, findModuleCapabilityAgent, capabilityAgentFromDir, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, upsertLocalAgent, defaultRepo, RELATIONS, validateLaunchConfig, resolveLaunchSelection, resolveLaunchExecutable, checkLaunchExecutable, missingLaunchEnvRefs, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_RUNTIMES, LAUNCH_RECIPE_VERSION, parseLaunchCommand, resolveYolo, planLaunch, redactLaunchCommand, restartInstanceSession,
 } from "../lib/core.mjs";
 import {
@@ -935,7 +935,9 @@ function computeInspect({ onFail } = {}) {
   const result = {
     operationsApi: 1, kernel: OATS_VERSION,
     scope: { context: ctx, requestedContext: requestedContext === ctx ? null : requestedContext, workspace: roots.length ? workspaceOf(roots[0]) : ctx, team: r.team || null, chain: chain.map((c) => ({ file: c._file, level: c._level, levelKind: levelOf(c._level) })), agentsRoots: roots },
-    selected: { soul: selectedSoul?.name || null, agentsRoot: selectedSoul?.agentsRoot || null, home: home || null, source: meta ? "snapshot" : "config" },
+    selected: { soul: selectedSoul?.name || null, agentsRoot: selectedSoul?.agentsRoot || null, home: home || null, source: meta ? "snapshot" : "config",
+      // Decision 27 (K2): the principal this home acts as, from its messaging provider's hook meta.
+      ...(meta ? { identity: servedIdentityOf(meta) } : {}) },
     souls, sources, layers, capabilities, knowledge, snapshot, currentConfig,
     problems: [...(lockError ? [lockError] : []), ...packagedDiagnostics.map((d) => ({ code: d.code, message: d.message, capability: d.capability })),
       ...(meta ? snapshotCaps.filter((c) => !mans[c.id]).map((c) => ({ code: "captured-capability-missing", message: `${c.id} was active when this home was composed but no manifest for it is acquired now`, capability: c.id })) : [])],
@@ -947,6 +949,7 @@ function printInspect(result) {
   const { ctx, selectedSoul, home } = result._print; delete result._print;
   const { souls, layers, capabilities } = result;
   console.log(`oats inspect — ${shortPath(ctx)}${selectedSoul ? ` soul ${selectedSoul.name}` : ""}${home ? ` home ${shortPath(home)}` : ""}`);
+  if (result.selected?.identity) console.log(`  identity: ${servedIdentityLine(result.selected.identity)}`);
   for (const s of souls) console.log(`  soul ${s.name} [${s.kind}${s.capability ? ` ${s.capability}` : ""}] runtime ${s.runtime}${s.model ? ` model ${s.model}` : ""} work ${s.work}${s.editable.fields.length ? "" : " (read-only)"}`);
   for (const l of LAYERS) console.log(`  layer ${l}: ${layers[l].id || (layers[l].disabled ? "disabled" : "none")}${layers[l].provenance ? `  (${layers[l].provenance})` : ""}`);
   for (const c of capabilities) console.log(`  ${c.id}@${c.version || "?"} ${c.health.status}${c.activation.enabled ? ` active:${c.activation.target}` : " inactive"}${c.operations.length ? `  ops: ${c.operations.map((o) => `${o.name}${o.available ? "" : "(unavailable)"}`).join(", ")}` : ""}`);
@@ -2343,6 +2346,7 @@ async function status() {
     for (const i of a.instances) {
       console.log(`      • ${i.instance}  ${i.retirePending ? "RETIRING" : i.running ? "RUNNING" : "idle"}  (branch ${i.branch || "?"}, ${i.work || "?"})`);
       const key = i.home ?? `${a.name}/${i.instance}`;
+      if (i.identity) console.log(`          identity: ${servedIdentityLine(i.identity)}`);
       const s = ws?.soul.get(key);
       if (s && (verbose || s.status !== "current")) console.log(`          ${soulDriftLine(s, a.name)}`);
       const rows = ws?.drift.get(key) || [];
@@ -3366,7 +3370,7 @@ function versionCmd() {
     // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
     // runs on resolve/materialize (contract §6); a feature the binary does not implement is
     // never listed.
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "session-recompose", "readiness-verify", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload"], workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 1, lifecycleApi: 1, readinessApi: 1, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 1, capturedDispatchApi: 1, capturedDispatchActions: ["inspect", "compose", "command", "operation", "spawn", "trust"] }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "session-recompose", "readiness-verify", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity"], workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 1, lifecycleApi: 1, readinessApi: 1, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 1, capturedDispatchApi: 1, capturedDispatchActions: ["inspect", "compose", "command", "operation", "spawn", "trust"] }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);

package/docs/capabilities.md

@@ -282,6 +282,14 @@ for this contract. Hyphenated vendors are also excluded because translating a
 hyphen to `_` would let `aweb-evil.*` collide with names already inside
 `aweb.*`'s `AWEB_*` namespace.
 
+A manifest's `settings.<key>` may carry `hostOnly: true` (decision 27). Such a
+key is a fact about the machine — a custody directory, a state root — and the
+resolver accepts it only from the deployment's own `oats-local.yaml`
+`settings.<capability>`; a committed workspace or soul file or a `--provider`
+flag carrying it is refused (`E_WORKSPACE_SCHEMA`, reason `host-only-key`).
+Declare it for any key whose value points at something a committed file must
+never be able to choose.
+
 A hook may return only names in its manifest's exact `environment` declaration.
 For package capabilities that declaration is part of the integrity-locked tree
 and of what the per-version approval showed; for member capabilities it is

package/docs/capability-manifest.schema.json

@@ -263,6 +263,10 @@
           },
           "description": {
             "type": "string"
+          },
+          "hostOnly": {
+            "type": "boolean",
+            "description": "When true, this key is a host fact (a custody path, a state directory): the resolver accepts it only from the deployment's oats-local.yaml settings.<capability> and refuses it in the workspace file, byTeam payloads, a soul's slot payload and --provider flags (E_WORKSPACE_SCHEMA reason host-only-key). Decision 27."
           }
         },
         "additionalProperties": false

package/docs/configuration.md

@@ -50,7 +50,12 @@ refused (`E_WORKSPACE_SCHEMA`).
 Every `oats` command that needs the workspace (`sync`, `workspace status`,
 `capabilities`, `souls`, `spawn`, `status` drift) walks **up** from the current
 directory (or `--dir`) to the nearest `oats-local.yaml`; its directory is the
-deployment. Not found → `E_LOCAL_MISSING`. Beside it:
+deployment. Not found → `E_LOCAL_MISSING`. The deployment is also a
+**configuration boundary**: nothing above the directory holding
+`oats-local.yaml` composes into it (a deployment created inside another
+scope — a scratch deployment under a repository, a fixture under an operator
+workspace — sees only its own files; `oats inspect` reports it, not the outer
+scope, as the workspace). Beside it:
 
 ```
 ~/acme-workspace/

package/docs/design/2026-09-20-redesign-program-board.md

@@ -2,7 +2,7 @@
 
 **Purpose:** the one accurate view of every work stream in the redesign, what is on main, what is in flight, who owns it, and what blocks it. Lead: `oats-expert` (redesign lead). Updated whenever anything merges, is returned, or reality changes. Older per-lane boards are superseded by this file.
 
-**Last update:** 2026-09-23 20:00Z · **0.25.0–0.25.4 PUBLISHED** (workspace model A–C; team-review fixes; operator-rebuild round; OATS_SOUL_ID; quarantine-retry fix) · **OKF 2.1.4 content complete on oats-okf main, tag pending human GO** · **oats.aweb 1.12.0 (PR #107) in rehearsal round 4; decision 27 (per-spawn identity) proposed to the human** · Phase D plan next · **Desktop engineer paused by the human** (10B-0 uncommitted foundation preserved; resume is the human's call; 0.24.14 to be cut from a maintenance branch off `e5cdaf95` when its PR lands) · parity pipeline ⏸.
+**Last update:** 2026-09-24 13:30Z · **0.25.0–0.25.6 PUBLISHED** (0.25.6 = decision 27 kernel half + Desktop 10B-0 terminal owner leases, native gate 23/23) (workspace model A–C; team-review fixes; operator-rebuild round; OATS_SOUL_ID; quarantine-retry fix; launch meta + catalog pins) · **OKF v2.1.4 + oats.aweb v1.12.0 TAGGED and pinned** · **decision 27 accepted; K1′/K1″/K2 kernel PR next** · **oats.aweb 1.13.0 (#110) queued** · **Desktop 10B-0 resumed** · Phase D plan next · **Desktop engineer paused by the human** (10B-0 uncommitted foundation preserved; resume is the human's call; 0.24.14 to be cut from a maintenance branch off `e5cdaf95` when its PR lands) · parity pipeline ⏸.
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 

package/docs/design/2026-09-23-workspace-module-contracts.md

@@ -565,6 +565,21 @@ is a member; a soul that lives in it may need a work clone). Under an explicit
 `oats-local.yaml` `standalone:` header the next steps say the view is standalone
 and list only that repo.
 
+### 0.25.6 — decision 27: served identity is a messaging-layer fact (K1′, K1″, K2)
+
+- **K1′** `decision.effective.providers` = the resolution's merged per-module payloads
+  (exactly what reaches `OATS_SETTINGS`), bound by the decision revision. No new flag.
+- **K1″** manifest `settings.<key>.hostOnly: true` → the resolver refuses that key in
+  the workspace base, `byTeam[*]`, the soul's slot and `--provider` layers with
+  `E_WORKSPACE_SCHEMA { reason: "host-only-key", path, key, capability }`; only
+  `oats-local.yaml settings.<cap>` may carry it. Generalises decision 23's reserved
+  `byTeam` into a capability-declared attribute. Schema: `docs/capability-manifest.schema.json`.
+- **K2** `oats status --json instances[].identity` and `oats inspect … selected.identity`
+  copy `capabilityMeta[<cap>].identity` (messaging-layer capability preferred; `provider`
+  added); text `identity: acts as <address> via grant, expires <t>` / `alias <a> on <team>`.
+  Layer contract shape in `docs/integrations.md`.
+- `features[]` gains `served-identity`.
+
 ### 0.25.5 — launch-hook `meta` is persisted
 
 `runLifecycleHooks("launch")` collected each capability's `meta` and the

package/docs/design/2026-09-24-desktop-phase-f-boundary.md

@@ -0,0 +1,180 @@
+# Desktop Phase F — the Desktop is built FOR workspace model v2
+
+**Status**: boundary for the Desktop engineer, issued 2026-09-24 by the lead under
+the human's direction: *"the desktop should not just adapt to the new version,
+it should be natively built for it."* Supersedes the Phase 3 parity plan's
+assumptions about what the Desktop reads; keeps its visual deliverable (the
+redesign frames, excl. 05/06).
+
+**Human's second directive, verbatim intent**: make ultra sure the Desktop is set
+up to work in the new setup — new versions, new CLI, new deployment shape.
+
+## 0. Why this is a rebuild of the model, not a patch
+
+The Desktop today is a 0.24 product that *tolerates* 0.25 kernels: its
+`ACCEPT_RANGE` admits `0.25.x`, so it launches, and the few CLI verbs it drives
+(`version`, `session *`, `spawn`, `retire`, `schedule`, `catalog`) still answer.
+But its **model of a deployment is 0.24's**, reimplemented in
+`packages/desktop/server/deployment.mjs`: it reads `oats-config.yaml`,
+`agents/<name>/soul`, `local-agents/`, and capability manifests from
+`.agents/capabilities/installed/`, and derives the roster itself. None of these
+is how a v2 deployment is shaped:
+
+| 0.24 (what the Desktop reads) | v2 (what a deployment IS) |
+|---|---|
+| `oats-config.yaml` at the repo root | `oats-local.yaml` at the deployment directory → `workspace:` URL |
+| souls at `agents/<name>/soul` | souls at `souls/<name>` **in member repos**, materialised per commit into `agents/<name>/souls/<commit>` |
+| capabilities installed into `.agents/capabilities/installed/` | packages resolved through `oats-workspace.yaml` + the official catalog, locked in `oats-lock.json`, **copied whole into each instance home** (`.oats/modules/<cap>`) |
+| `team:` block | `oats-membership.yaml` `team:` label per member; `messaging.byTeam.<label>` payloads |
+| `oats catalog` DTO | removed; the catalog is `package-catalog.json` resolved by `oats sync` |
+| roster derived by the Desktop | `oats status --json` is the roster (agents, instances, `modules[]` drift, `soul` source drift, `identity`) |
+
+A Desktop that keeps the left column and adds a few right-column fields is the
+"adapt" outcome the human rejected. Phase F replaces the left column.
+
+## 1. The principle: the kernel is the model; the Desktop renders and drives it
+
+- **Read model**: every fact the Desktop shows about a deployment comes from
+  the kernel's JSON surfaces — `oats status --json`, `oats inspect --json`,
+  `oats workspace status --json`, `oats spawn --preview --json`, `oats
+  readiness --json`, `oats version --json`, `oats sync --json`. The Desktop
+  does not parse `oats-config.yaml`, `oats-local.yaml`, `soul.yaml`,
+  manifests or lock files itself. Where a fact is missing from a kernel
+  surface, the fix is a kernel PR (lead's lane), not a Desktop-side parser.
+- **Write model**: every mutation is a kernel verb with `--json`: `sync`,
+  `sync --approve`, `spawn` (preview → `--expect-decision` apply), `retire`,
+  `session start|restart|recompose`, `schedule *`, `onboard`. The Desktop
+  never writes a deployment file.
+- **Version contract**: `oats version --json` `features[]` is the capability
+  probe. The Desktop's `ACCEPT_RANGE` moves to `>=0.25.6 <0.27.0` (the first
+  kernel with `served-identity`), and each feature the UI depends on is gated
+  on its `features[]` name, not on a version number.
+
+## 2. Deliverables (slices; each is one PR against main, each reviewed by the lead)
+
+**F1 — Deployment model on kernel JSON.** Replace
+`server/deployment.mjs`'s own readers with `oats status --json` (+ `oats
+workspace status --json` for the workspace header: name, key, members, packages,
+lock state, `approvalNeeded`). Roster rows carry `modules[]` drift, `soul`
+source (`repo: <member> @ <c7>`, "member moved since"), `identity`. Legacy
+`local-agents/`/`tmp-agents/` paths are dropped. Remove `server/catalog.mjs`'s
+`oats catalog` DTO validation (the verb no longer exists).
+
+**F2 — Workspace onboarding and sync.** A "Open deployment" flow that: detects a
+directory with `oats-local.yaml` (v2), or offers `oats onboard` for one without
+(the kernel asks for the deployment directory and the workspace URL — the
+Desktop collects both, never invents a folder name; decision 9). A "Sync"
+action runs `oats sync --json`; exit 2 with `approvalNeeded[]` renders an
+approval sheet showing each package's `executables` digest and applies with
+`oats sync --approve <id>@<version>` (the version string is what
+`approvalNeeded[].version` reports — for a git-pinned package, the full OID).
+Lock drift and `E_PACKAGE_INTEGRITY` are surfaced verbatim.
+
+**F3 — Spawn dialog on the v2 preview.** The preview already carries
+`modules`, `providers`, `settings.<cap>`, `team`, `resolution`, `decision`.
+Render: which modules the instance will get and from where (package vs member,
+commit); the merged `settings.<cap>` per provider (read-only); **Identity**
+select (local | global) with a Resident field for global, prefilled from
+`settings.<messaging cap>.identity`, forwarded as `--provider <cap>
+identity.mode=… identity.resident=…` (decision 27 — there is no kernel flag);
+`decision.effective.providers` is what the confirm binds. `cli-adapter.mjs`
+`SPAWN_ARG_RULES` gains one `provider` rule (capability id, dotted key, value
+grammar); no identity-named rules. Work mode select includes `workspace`.
+
+**F4 — Instance card and roster on v2 facts.** The served-identity line (`acts
+as <address> via grant, expires <t>` / `alias <a> on <team>`); module rows with
+"moved since" markers and a **re-spawn** action (preview → apply, then retire
+the old instance — module homes answer `E_UNSUPPORTED_MODE` to
+`session recompose` by design; an instance never changes under itself); the
+soul-source row; quarantine state from `rollbackIncomplete` with the retry
+action (`oats retire`) and `--force` behind a confirm.
+
+**F5 — Redesign frames** (the original Phase 3 deliverable, excl. 05/06),
+implemented on top of F1–F4 rather than on the 0.24 model.
+
+**F6 — Version and doctor surface.** `oats version --json` and `oats doctor
+--json` in an About/Health pane; `ACCEPT_RANGE` and the three pins move to
+`>=0.25.6`; a kernel below the floor is refused with the upgrade command shown.
+
+Order: F1 → F2 → F3 → F4 → F5 → F6, or F1 then F3/F4 in parallel if the engineer
+spawns children (its call; the lead reviews each PR).
+
+## 3. What the engineer must LEARN first (before F1)
+
+Read, in this order, in the checked-out main:
+1. `docs/workspaces.md` — the v2 model end to end (deployment vs workspace,
+   members, packages, payloads, `byTeam`, hosting).
+2. `docs/rebuild-to-v2.md` — how an operator builds a deployment (this is the
+   flow F2 wraps).
+3. `docs/desktop-cli-api.md` — every JSON surface, with examples; note
+   `features[]`, `decision.effective.providers`, `instances[].identity`.
+4. `docs/design/2026-09-23-workspace-module-contracts.md` §0.25.x — what
+   changed per release and why.
+5. `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md` and
+   `…/served-identity-is-a-messaging-layer-fact.md` — the decisions.
+6. `test/fixtures/northwind/build.mjs` — the two-team fixture workspace; run
+   `node --test test/spawn-workspace.test.mjs` once and read what a v2 spawn
+   produces on disk (`.oats/modules/`, `instance.json` `modules`/`providers`/
+   `workspace.soul.id`).
+
+Then build a scratch deployment by hand with the CLI (`oats onboard`, `oats
+sync`, `oats sync --approve`, `oats spawn --preview`, `oats spawn --no-launch`,
+`oats status`, `oats inspect`, `oats retire`) against the Northwind fixture
+remotes, and keep the transcript: F1's tests are written against exactly those
+JSON shapes.
+
+## 3b. Native rework, not a compatibility layer (human, 2026-09-24)
+
+The human's rule, verbatim intent: *"do a native rework — do not keep v1-specific
+things, and no v1 modules calling v2 modules."* Concretely:
+
+- **Remove, do not wrap.** A 0.24 reader (`server/deployment.mjs`'s
+  `oats-config.yaml`/`soul.yaml`/manifest parsing, `local-agents/`,
+  `.agents/capabilities/installed/`, the `oats catalog` DTO) is deleted in the
+  slice that replaces it — never kept behind a flag, a fallback branch, or an
+  "if the kernel is old" path. The Desktop supports one kernel line
+  (`ACCEPT_RANGE` from 0.25.6) and refuses older ones with the upgrade command.
+- **No adapters between generations.** No module whose job is to translate a
+  v1-shaped object into a v2-shaped one or vice versa (no `legacyRosterToV2()`,
+  no `toOldCard()`); the v2 kernel JSON is consumed where it is read and shaped
+  once for rendering. If a v1 module still needs a v2 fact, the v1 module is
+  the thing being replaced — replace it, do not feed it.
+- **Names and types follow v2.** Types, fields and UI labels use the kernel's
+  vocabulary (workspace, member, package, module, deployment, soul source,
+  served identity); 0.24 vocabulary (installed capability, config chain, team
+  block, agents root as identity) leaves the codebase with the code that used
+  it. `git grep` for the old terms is part of each slice's exit check.
+- **Tests follow the same rule.** Fixtures shaped like 0.24 deployments are
+  deleted with the readers; new fixtures are v2 deployments produced by the
+  kernel (Northwind or a hand-built scratch deployment), not hand-written
+  JSON imitating old shapes.
+- **One exception, stated per case.** Where a 0.24 concept has a genuine v2
+  successor with the same meaning and the Desktop code is already correct for
+  it (a terminal broker, a tmux target admission), it stays — the PR names it
+  as "unchanged, v2-agnostic", not as "kept for compatibility".
+
+Exit check for Phase F as a whole: no file under `packages/desktop/` reads a
+deployment file, names a 0.24 concept, or contains a code path that exists
+only for a kernel below the floor.
+
+## 4. Rules that do not change
+
+- `packages/desktop/**` only; kernel gaps go to the lead as a written ask
+  (they become kernel PRs; the engineer never adds a Desktop-side parser to
+  work around one).
+- No native tmux/PTY/Electron execution by the agent; the lead's native gate
+  at review time is the acceptance.
+- Every slice: focused tests + the intended mutants on the new code; the
+  Desktop suite green; one PR per slice against main; lead's pr-review.
+- The design frames are the visual authority; the kernel JSON is the data
+  authority; where a frame shows a 0.24 concept (an "installed capability"
+  list, a `team:` block), the frame is adapted to the v2 concept and the
+  adaptation noted in the PR.
+
+## 5. Acceptance for Phase F as a whole
+
+The lead builds a fresh v2 deployment from the Northwind fixture using ONLY the
+Desktop (open → onboard → sync → approve → spawn with a global identity →
+inspect → retire) on kernel 0.25.6+, and every fact shown matches `oats status
+--json` / `oats inspect --json` byte for byte. Nothing in
+`packages/desktop/server` reads a deployment file.

package/docs/design/2026-09-24-phase-d-plan.md

@@ -0,0 +1,164 @@
+# Phase D — the OATS project runs on the architecture it offers (plan)
+
+**Status**: plan, 2026-09-24, lead. Decisions 18–22 of the workspace model, the
+five-soul roster and its 2026-09-24 amendment, the human's sequencing
+("knowledge centralisation first"; "do not retire live souls until their
+instances retire"). Mailed to the human and the OSS coordinator before the
+first swarm. Method per standing instruction: write → swarm build →
+adversarial-review swarm → PR → main; releases under delegated authority.
+
+## Co-leads and lanes (human, 2026-09-24)
+
+The human made the two `oats-expert` instances — the redesign lead
+(`oats-expert-knowledge-reworks`) and the maintainer of the second deployment
+(`oats-expert-antares`) — **co-leads with equivalent authority**, who agree on
+pushes. Agreed by both on 2026-09-24:
+
+| Lane | Owner | Status |
+|---|---|---|
+| Desktop Phase F (engineer PRs, native gates) | lead | assigned |
+| Kernel (`lib/`, `bin/`; kernel gaps raised by anyone) | lead | assigned |
+| Releases 0.25.7 and D5 (catalog + 0.26.0) | lead | assigned |
+| oats.aweb 1.13.0 re-land end to end | Antares | assigned |
+| D1 operator node + integrations node | Antares | assigned (draft PR `d1/operator-node` handed over) |
+| aweb and okf package-expert seams | Antares | assigned |
+| D2, D3, D4, desktop + kernel bundle migrations (D1 remainder) | Antares | assigned (both humans agreed, 2026-09-24). D2's machine-bound onboard of the lead's deployment is run by the lead on Antares' word; kernel gaps come to the lead as asks. |
+
+**Push protocol.**
+- **Class A** — notify after, one line: stewardship, docs and knowledge inside
+  one's own lane or node; merging a PR the other co-lead approved in writing;
+  merging one's own lane's PR after the other co-lead's review; the bump PR of
+  an agreed release.
+- **Class B** — `PUSH INTENT: <what> @ <commit/PR>` → `ACK <message-id>` before
+  acting: tags, releases, npm publishes, catalog pins; framework-behaviour
+  changes (kernel semantics, OKF/memory contracts, workspace config semantics,
+  published skills); merges into the other's lane; reverts, force-anything,
+  branch or tag deletion. A blocking intent unanswered for about 45 minutes goes
+  to the human, never to action.
+- Every PR is reviewed by the co-lead who did not author it (a helper's PR is
+  reviewed by its own lead, inside that lead's lane). A disagreement not settled
+  in two mails goes to the human. Standing rules unchanged: PR CI is the full
+  gate; published tags never move; no destructive git on shared checkouts.
+- `main` on these repositories carries no branch or tag protection: the parity
+  gate and the cross-review are the only things between a merge and `main`.
+
+## Slices, in order
+
+### D1 — Knowledge centralisation (IN PROGRESS)
+
+Goal: every roster soul's knowledge lives in the central base
+`awebai/oats-knowledge` (OKF 2.1.4), one owned node each; the in-repo
+`agents/*/soul/knowledge` bundles stop receiving writes and are decommissioned
+when no live instance links them.
+
+Done: nodes `oats-operator-expert` and `integrations-expert` chartered
+(oats-knowledge PR #3); eight attributed seeds landed in
+`agents/oats-expert/soul/knowledge/inbox` (oats PR #121); the roster amendment
+accepted; the rule "no per-soul knowledge merges" in force.
+
+Work:
+1. **Copy-migrate by judgement** (the 2026-09-21 method: two-part test plus the
+   2026-09-24 recipe refinement; not copying): `agents/oats-expert/soul/knowledge`
+   (~130 files) → node `oats-expert`; `agents/oats-desktop-engineer/soul/knowledge`
+   (~120) → `oats-desktop-expert`; `agents/cli-dev/soul/knowledge` (~155) →
+   `oats-kernel-expert`; `agents/integrations-expert/soul/knowledge` (13) →
+   `integrations-expert`. Others (`dev-coordinator`, `docs-expert`, `ux-designer`,
+   `lead`, `oats-coordinator`) are assessed for the few universal concepts they
+   hold and otherwise not carried. One PR per node on oats-knowledge, reviewed
+   by the lead; the OSS coordinator reviews the operator and integrations PRs.
+2. **Seed the operator node** — attributed to `oats-expert-antares`:
+   MOVE (not copy) from the oats-expert bundle: `lessons/the-aweb-team-root-must-sit-where-the-spawn-hook-looks`,
+   `lessons/okf-state-directory-must-sit-outside-every-work-tree`,
+   `lessons/capability-trust-hash-covers-the-installation-record`,
+   `lessons/a-locally-minted-oats-identity-has-no-cross-team-first-contact-address`,
+   `lessons/stale-checkout-serves-stale-soul`,
+   `playbooks/rebuild-a-deployment-in-scratch-against-local-bare-remotes`;
+   generalise the R1–R10 rebuild findings and the published-combination
+   verifications from `stewardship/delivery-log` (the log keeps the record).
+   From the inbox: `check-the-record-before-redesigning-identity`,
+   `grant-custody-service-and-renewal-belong-on-the-custody-host` (operator
+   half), `the-wake-broker-accepts-a-grant-home`.
+3. **Seed the integrations node** — from the inbox:
+   `a-merged-provider-payload-cannot-enforce-host-only-keys`,
+   `aw-grant-commands-resolve-the-identity-from-cwd-only` (discipline half),
+   `oats-runtime-requirements-for-grant-backed-resident-operation`; from the
+   integrations-expert bundle: `fake-aw-must-model-real-refusals` and the rest
+   of this week's harvested lessons.
+4. **Route the remainder of the inbox**: aweb package expert (D3) gets
+   `aweb-grants-are-team-bound-to-the-custody-identitys-active-team`,
+   `a-grant-signed-send-must-name-the-subject-as-sender` and the aw halves;
+   kernel expert gets `path-keyed-owner-registry-breaks-under-per-commit-soul-copies`.
+5. **Rebind the souls** in `souls/<name>/`: the `knowledge:` grammar there is
+   still 0.24's (`capability` + `source: git:…@v2.1.2#oats-package`); v2 is
+   `capabilities: { oats.okf: { from: package } }` plus `okf.json`
+   (`{ version: 1, owner: <node owner uuid>, owns: ["oats/<node>"], reads: [...] }`)
+   and the store `oats` naming `awebai/oats-knowledge` / `knowledge` / `main`.
+   Add `souls/oats-operator-expert` (rename of `oats-setup-expert`, keeps the
+   `oats.setup` charter) and `souls/integrations-expert`.
+6. **Do NOT delete** `agents/<n>/soul/knowledge` or the legacy souls while a
+   live instance links them (human rule). Record which are live; decommission
+   as they retire; new spawns use `souls/<n>`.
+7. **Release playbook** (`oats-expert` node, stewardship area): landing order
+   for provider PRs (tag → pin on the branch → squash; a bundled provider never
+   lands ahead of its tag), the version literals to bump on a catalog bump,
+   the mirror checker, the bump-PR step. First entries: today's two lessons.
+
+### D2 — The OATS workspace as a v2 workspace (decisions 18, 19, 21)
+
+`oats-workspace.yaml` at the `oats` repo (name `oats`; members = the seven
+framework repos incl. `oats` itself; `packages:` = oats.framework / okf / aweb /
+jira / linear / authoring / dev pinned from the catalog; `defaults.capabilities`
+= `oats.core` from package + knowledge `oats.okf`); `oats-membership.yaml` ×7
+(each package repo is a member AND a package publisher — non-collapse:
+`packages:` resolves it as a package, membership only grants trust and a soul).
+`package-catalog.json` stays the official marketplace (decision 21); the `oats`
+repo keeps `oats-dev` as dev capabilities. A fresh deployment directory (asked
+for, never named by convention — decision 9) is the acceptance: `oats onboard`
+→ `sync` → `approve` → spawn every roster soul `--no-launch`.
+
+### D3 — Souls to `souls/<name>` and the six package-expert souls (decision 20)
+
+Each package repo carries `souls/<pkg>-expert` (okf-expert, aweb-expert,
+jira-expert, linear-expert, authoring-expert, dev-expert), the expert in that
+package, with a node in the central base from day one. **Seams named in the
+charters** (roster amendment): `aweb-expert` READS
+`aweb-protocol-expert` in base `aweb-oss-knowledge` (repo
+`github.com/awebai/aweb`, root `knowledge/`, branch `main`, OKF 2.1.x
+descriptor at `knowledge/okf-base.json`; owner `1913b77b-…`) through a
+read-only store reference; `okf-expert` names its seam to the knowledge-theory
+material in `oats-expert`. Whether the aweb bookshelf decisions the program
+rests on are published into that node is the aweb side's call (asked).
+
+### D4 — `oats.core` and `oats.setup` rewritten (decision 22, W9b)
+
+Not patched: written for the v2 world. `oats.core`: home layout, `oats status`
+with modules/soul/identity rows, spawn preview → apply, `sync --approve`, the
+two-directory boundary, what a module is. `oats.setup` (held by
+`oats-operator-expert`): onboarding that ASKS for the deployment directory and
+the workspace URL, the hosting rule (decision 26), the public-member executable
+rule, the rebuild guide as procedure with the operator node as rationale.
+Developer souls in `oats.dev` gain `promotesTo: <node>` (roster amendment);
+the harvester delivers to that node as a PR the owning expert reviews.
+
+### D5 — Catalog update and 0.26.0
+
+Catalog pins for the new package versions; **widen Desktop `ACCEPT_RANGE` and
+the three pins FIRST** (minor bump rule); release notes; tag; the fresh
+deployment from D2 rebuilt on the published artefacts by the OSS coordinator
+(outsider verification) before the program board marks Phase D done.
+
+## Adversarial review (per slice)
+
+Each slice's swarm is followed by a review swarm with the standing lenses
+(direction against the decisions; correctness by reproduction; security —
+trust at acquisition, hoisted paths, hook approval, host-only keys; docs as
+contract — every guide claim has a test), plus two Phase-D-specific ones: **the
+outsider** (can a reader who was not in the room set OATS up from `oats.setup`
+alone?) and **the seam** (does every cross-project read resolve to a real node
+with a real owner?).
+
+## Out of scope
+
+Desktop (Phase F, its own boundary); oats.aweb 1.13.0 re-land (held on the
+aweb release); legacy `~/OATS` deployment cutover (the operator's, on the
+published 0.26.0).

package/docs/desktop-cli-api.md

@@ -376,12 +376,32 @@ the pre-fix marker and is never accepted for dispatch.
   import; `--instructions-file`/`--def-file` refused with `E_BAD_ARGS`). Test:
   the deployment tree is byte-identical after a success, a refusal and an
   unknown-soul preview.
+  **Workspace deployments (0.25.1+) — one stated exception**: the first preview
+  of a workspace soul may populate the deployment's per-commit soul cache
+  (`agents/<soul>/souls/<commit>/`, the swappable `agents/<soul>/soul` pointer,
+  `soulFetched: true` in the result). That cache is derived, content-addressed
+  and idempotent — the same member commit yields the same bytes, a later
+  preview of the same commit writes nothing — and nothing else moves: no lock,
+  no event, no home, no instance. A Desktop treats a preview as
+  side-effect-free for everything it shows; it must not assume the deployment
+  directory's byte-identity across the FIRST preview of a soul or commit.
 - **Exact root**: `spawn <soul> --agents-root <abs>` binds the soul to that root
   (as inspect/readiness take it) — no team-soul / capability-agent / importable-
   def fallback; mismatch → `E_SOUL_UNKNOWN`. The preview echoes
   `subject {soul, agentsRoot|null, dir|null}` **as given, byte-exact**.
 - **Decision binding**: `decision {instance, home, branch, base{ref,oid},
-  revision}` (24-hex). Apply with `spawn … --expect-decision <revision>`: the
+  effective{…, providers}, resolution, revision}` (24-hex). From 0.25.6
+  (`features: served-identity`) `effective.providers` is the merged
+  per-module payload each provider will receive (`{ "<cap>": {…} }`, exactly
+  `settings.<cap>` of the preview) — so a confirmed apply binds every
+  provider fact (an identity choice, a delivery mode) **by value**; a Desktop
+  that changes a provider field re-previews. `instances[].identity` (status)
+  and `selected.identity` (inspect) carry the served principal a messaging
+  provider reported: `{ mode: "local"|"global", alias, team, address|null,
+  resident|null, grant?: { id, expiresAt, scopes }, provider }`; absent when
+  no provider emitted one. A Desktop offers the identity choice as
+  `--provider <cap> identity.mode=… identity.resident=…` — there is no
+  kernel flag for it. Apply with `spawn … --expect-decision <revision>`: the
   kernel recomputes name/home/branch/base under the same placement path and
   refuses **`E_DECISION_STALE`** with `details.decision` (the fresh one) on ANY
   drift — no auto-suffix, no silent re-base, nothing created. A GUI re-previews
@@ -774,9 +794,12 @@ written. Captured selectors are refused (`E_BAD_ARGS`).
 
 - `sync` is the `syncApi: 1` report of the first sync (members, packages,
   changes, `approvalNeeded`, `problems`); `lock` is the lock it wrote.
-- **Exit `2` with `ok: true`** when `sync.approvalNeeded` is non-empty (approval
-  is interactive-only; tell the operator to run `oats sync --dir <dir>` in a
-  terminal). Exit `0` otherwise.
+- **Exit `2` with `ok: true`** when `sync.approvalNeeded` is non-empty. Approve
+  non-interactively with `oats sync --dir <dir> --approve <id>@<version> …`
+  (0.25.2+; `<version>` is `approvalNeeded[].version` verbatim — a catalog
+  version, or the full commit OID for a git-pinned package); a Desktop renders
+  `approvalNeeded[].executables` (the digest of the executable set it is
+  approving) and `targets`, then runs that command. Exit `0` otherwise.
 - `hosting` states decision 26 (the kernel cannot see forge visibility, so it
   reports `hostIsMember` and the rule rather than judging).
 - `next.clone[]` is one row per **confirmed** member (`url` = what the
@@ -801,9 +824,10 @@ written. Captured selectors are refused (`E_BAD_ARGS`).
 
 Discovers, confirms membership, resolves `packages:` to commits, writes
 `oats-lock.json` (lockfileVersion 3), reports. **Exit `2` with `ok: true`** when
-the lock was written but approvals are pending (`approvalNeeded` non-empty);
-approval is interactive-only, so a Desktop must tell the operator to run
-`oats sync` in a terminal. Exit `0` otherwise.
+the lock was written but approvals are pending (`approvalNeeded` non-empty).
+Approve with repeatable `--approve <id>@<version>` (0.25.2+, non-interactive;
+`<version>` = `approvalNeeded[].version` verbatim); the interactive prompt is
+the TTY fallback, not the contract. Exit `0` otherwise.
 
 ```json
 {"syncApi":1,
@@ -1052,6 +1076,10 @@ refreshes the home in place:
   materialized modules is not supported yet; re-spawn"): its `AGENTS.md` was
   composed from the soul at a recorded member commit plus the materialized
   modules' injects, and the instance never changes under itself (decision 7).
+  **Desktop contract (Phase F, F4)**: for a module home, show the drift rows
+  and offer *re-spawn* (preview → apply of the same soul/purpose, then retire
+  the old instance); do not offer "recompose". A kernel recompose for module
+  homes is not planned — an instance never changes under itself.
   The refresh path for such a home is a new spawn (the soul is re-fetched at
   the member's current commit). `session-recompose` **stays advertised** in
   `features[]` because the verb still works for classic homes; gate the UI

package/docs/integrations.md

@@ -137,8 +137,25 @@ the event first" in the inject and skill; contribute launch arguments so the
 session is woken; enforce the soul type's `reach` on both sides; state
 whether the address outlives the instance; and keep task coordination out.
 Any messaging provider emits `identity: { mode, alias, team, address|null,
-resident|null, grant?: { id, expiresAt, scopes } }` in its spawn meta;
-`oats.aweb` is the reference implementation.
+resident|null, grant?: { id, expiresAt, scopes } }` in its spawn meta (and
+in its launch meta when it renews); `oats.aweb` is the reference
+implementation. **This is a messaging-layer contract, not an oats.aweb
+detail** (decision 27): from kernel 0.25.6 the kernel copies it through as
+the principal the instance *acts as* — `oats status --json
+instances[].identity`, the roster's `identity:` line, `oats inspect --home …
+selected.identity` — preferring the capability whose captured layer is
+`messaging`, adding `provider: <capability id>`, and never interpreting
+`grant`. The kernel offers no `--identity` flag: the choice travels as
+`--provider <cap> identity.mode=… identity.resident=…` and is bound by the
+spawn decision's `effective.providers`.
+
+A provider whose settings include a **host fact** — a custody directory, a
+state root — declares that key `hostOnly: true` in its manifest. The
+resolver then accepts it **only** from the deployment's `oats-local.yaml`
+`settings.<cap>` and refuses it in the workspace file, `byTeam` payloads, a
+soul's slot payload and `--provider` flags (`E_WORKSPACE_SCHEMA`, reason
+`host-only-key`, path and key named). The provider cannot enforce this
+itself: it receives one merged payload without provenance.
 
 **Tasks.** Teach claim, update, block, hand off, and complete; identify the
 instance to the tracker in a way that survives it; keep conversation out.

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

@@ -0,0 +1,37 @@
+# OATS 0.25.6
+
+Decision 27 — per-spawn identity choice (local | global) — lands its kernel half.
+No new CLI flags; three provider-neutral additions and one manifest attribute.
+
+## Added
+
+- **`decision.effective.providers`** — the spawn decision now binds the merged
+  per-module payloads the providers will receive (exactly the preview's
+  `settings.<cap>`), so a confirmed apply covers every provider fact by value.
+- **`hostOnly` settings keys** — a capability manifest may mark a settings key
+  `hostOnly: true`; the resolver accepts it only from the deployment's
+  `oats-local.yaml settings.<cap>` and refuses it in the workspace file, `byTeam`
+  payloads, a soul's slot payload and `--provider` flags (`E_WORKSPACE_SCHEMA`,
+  reason `host-only-key`). Closes the documented hole where a committed file
+  could point a messaging provider at a custody root.
+- **Served identity on the roster** — `oats status --json instances[].identity`,
+  the text roster's `identity:` line and `oats inspect --home … selected.identity`
+  carry the principal an instance acts as, copied from its messaging provider's
+  hook meta (`{ mode, alias, team, address, resident, grant?, provider }`).
+- `oats version --json` `features[]` gains `served-identity`.
+
+## Desktop (10B-0)
+
+- **Terminal owner leases** (PR #117) — the Desktop's terminal wire is now
+  `terminalApi: 2`: every terminal is a lease (256-bit token) held by the
+  admitted renderer *document*; a navigation, reload or renderer crash revokes
+  the document and cleans its viewers; the 20-terminal cap is reserved
+  synchronously so parallel opens cannot overshoot; writes are bounded and
+  one-way. Maintainer's native gate (real Electron, tmux, PTY) passed 23/23:
+  open/ready/write/close, quota, reload revocation, source isolation, no
+  residue after quit. See `packages/desktop/docs/terminal-owner-leases.md`.
+
+## For providers
+
+oats.aweb 1.13.0 (next) can declare `residents` `hostOnly`. Any messaging provider
+that emits `identity` in its spawn/launch meta appears on the roster.

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

@@ -0,0 +1,11 @@
+# OATS 0.25.7
+
+## Fixed
+
+- **A v2 deployment is a configuration boundary.** The ancestor walk that
+  composes legacy `oats-config.yaml` levels now stops at the directory holding
+  `oats-local.yaml`. A deployment created inside another scope (a scratch
+  deployment under an operator's workspace, a fixture under a repository) no
+  longer inherits the outer scope's files, and `oats inspect` no longer names
+  the outer checkout as its `scope.workspace` or lists the outer files in
+  `scope.chain`. Found by the Desktop engineer's Phase F study.

package/lib/core.mjs

@@ -781,6 +781,13 @@ export function configChain(startDir) {
   while (true) {
     const cfg = loadLevelConfig(d);
     if (cfg) chain.push(cfg);
+    // A v2 deployment root (the directory holding oats-local.yaml) is a
+    // configuration boundary: nothing above it composes into it. Without this
+    // stop, a deployment created under another scope (a scratch deployment
+    // inside an operator's workspace, a fixture under a repo) inherited the
+    // ancestors' oats-config.yaml and `oats inspect` reported the outer scope
+    // as its workspace (Desktop Phase F study, 2026-09-24).
+    if (existsSync(join(d, "oats-local.yaml"))) break;
     const parent = dirname(d);
     if (parent === d) break;
     d = parent;
@@ -6603,7 +6610,14 @@ function* spawnBody(root, agent, o = {}) {
     // Workspace model: the decision binds WHAT WILL BE MATERIALIZED — the
     // resolution revision (member commits, package commits, payloads). A member
     // that moved between preview and apply changes it → E_DECISION_STALE.
-    if (o.prepared) d.resolution = o.prepared.resolution.revision;
+    if (o.prepared) {
+      d.resolution = o.prepared.resolution.revision;
+      // Decision 27 (K1′): the decision also binds the merged per-module payloads the spawn will
+      // hand each provider (exactly what reaches OATS_SETTINGS) — so a confirmed apply covers every
+      // provider fact (an identity choice, a delivery mode) by value, not only through the
+      // resolution revision. Kernel-agnostic: whatever keys the payloads carry.
+      d.effective.providers = structuredClone(o.prepared.resolution.payloads ?? {});
+    }
     d.revision = createHash("sha256").update(canonicalJson(d)).digest("hex").slice(0, 24);
     return d;
   };
@@ -7356,6 +7370,25 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
   }
 }
 
+/** Decision 27 (K2): the principal an instance ACTS AS, as its messaging-layer provider reported
+ *  it — a documented layer contract `{ mode: "local"|"global", alias, team, address|null, resident|null,
+ *  grant?: { id, expiresAt, scopes } }` under `identity` in the provider's hook meta. The kernel copies it
+ *  through and never interprets `grant`. Preference: the capability whose captured layer is "messaging";
+ *  else any capability that emitted an `identity` object. Null when none did. */
+export function servedIdentityOf(meta) {
+  const cm = meta?.capabilityMeta;
+  if (!cm || typeof cm !== "object") return null;
+  const runtime = Array.isArray(meta.capabilityRuntime) ? meta.capabilityRuntime : [];
+  const messaging = runtime.filter((c) => c && c.layer === "messaging").map((c) => c.id);
+  const pick = (ids) => { for (const id of ids) { const v = cm[id]?.identity; if (v && typeof v === "object" && !Array.isArray(v)) return { ...v, provider: id }; } return null; };
+  return pick(messaging) ?? pick(Object.keys(cm));
+}
+/** One line for a roster/inspect: `acts as <address> via grant, expires <t>` or `alias <alias> on <team>`. */
+export function servedIdentityLine(identity) {
+  if (!identity) return null;
+  if (identity.mode === "global" && identity.grant) return `acts as ${identity.address || identity.alias || identity.resident || "?"} via grant${identity.grant.expiresAt ? `, expires ${identity.grant.expiresAt}` : ""}`;
+  return `alias ${identity.alias || "?"} on ${identity.team || "?"}`;
+}
 export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
   const windows = tmuxWindows(tmuxSession);
   const readInstancesOf = (agentDir) => {
@@ -7394,7 +7427,8 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
           try { const state = inspectHerdr({ ...meta.sessionTarget, binary: "herdr" }); liveness = { running: state.present, runtimeState: state.status }; }
           catch (error) { liveness = { running: null, runtimeState: "unreachable", runtimeError: error.message }; }
         }
-        return { ...meta, ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(retirePending ? { retirePending } : {}) };
+        const identity = servedIdentityOf(meta);
+        return { ...meta, ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(retirePending ? { retirePending } : {}) };
 
       });
   };

package/lib/resolve.mjs

@@ -121,6 +121,23 @@ function assertNoReservedKey(value, path) {
   }
 }
 
+/** Settings keys a manifest marks `hostOnly: true` (decision 27, K1″). */
+export function hostOnlyKeys(manifest) {
+  const out = new Set();
+  const decl = isObject(manifest?.settings) ? manifest.settings : {};
+  for (const [key, spec] of Object.entries(decl)) if (isObject(spec) && spec.hostOnly === true) out.add(key);
+  return out;
+}
+/** Refuse a hostOnly key in a committed or per-spawn payload layer: only oats-local.yaml `settings.<cap>` may carry it. */
+function assertNoHostOnlyKey(value, path, hostOnly, capability) {
+  if (!hostOnly.size || !isObject(value)) return;
+  for (const key of hostOnly) {
+    if (Object.hasOwn(value, key)) {
+      throw fail("E_WORKSPACE_SCHEMA", `${path}/${key}: ${show(key)} is a host-only setting of ${capability} (its manifest marks it hostOnly) — it may appear only in the deployment's oats-local.yaml under settings.${capability}, never in a committed workspace or soul file or a --provider flag (decision 27)`, { path: `${path}/${key}`, key, capability, reason: "host-only-key" });
+    }
+  }
+}
+
 /** Canonical JSON: object keys sorted (recursively), arrays in order, no whitespace. */
 export function canonicalJson(value) {
   if (value === undefined) return "null";
@@ -569,15 +586,21 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
   for (const slot of SLOTS) if (isObject(definition[slot])) assertNoReservedKey(definition[slot], `/${slot}`);
   for (const m of modules) {
     const layers = [];
+    // Decision 27 (K1″): a manifest may mark a settings key `hostOnly` — a host fact (a custody
+    // path, a state directory) that only the deployment's own oats-local.yaml may supply. Every
+    // committed or per-spawn layer is refused with that key present, BEFORE the merge, because the
+    // provider receives one merged payload without provenance and cannot enforce this itself.
+    const hostOnly = hostOnlyKeys(m.manifest);
+    const committed = (payload, path) => { assertNoHostOnlyKey(payload, path, hostOnly, m.name); layers.push(payload); };
     if (m.layer === "messaging" && isObject(workspace?.messaging)) {
       // Decision 23: base ⊕ byTeam[soul.team]; `byTeam` never reaches the provider (nor may a team's own payload nest one).
       const { byTeam, ...base } = workspace.messaging;
-      layers.push(base);
-      if (team !== null && isObject(byTeam) && isObject(byTeam[team])) { assertNoReservedKey(byTeam[team], `/messaging/byTeam/${team}`); layers.push(byTeam[team]); }
+      committed(base, "/messaging");
+      if (team !== null && isObject(byTeam) && isObject(byTeam[team])) { assertNoReservedKey(byTeam[team], `/messaging/byTeam/${team}`); committed(byTeam[team], `/messaging/byTeam/${team}`); }
     }
-    if (m.layer && isObject(definition[m.layer])) { assertNoReservedKey(definition[m.layer], `/${m.layer}`); layers.push(definition[m.layer]); }
-    if (Object.hasOwn(settings, m.name) && isObject(settings[m.name])) { assertNoReservedKey(settings[m.name], `/settings/${m.name}`); layers.push(settings[m.name]); }
-    if (Object.hasOwn(providers, m.name) && isObject(providers[m.name])) layers.push(providers[m.name]);
+    if (m.layer && isObject(definition[m.layer])) { assertNoReservedKey(definition[m.layer], `/${m.layer}`); committed(definition[m.layer], `/${m.layer}`); }
+    if (Object.hasOwn(settings, m.name) && isObject(settings[m.name])) { assertNoReservedKey(settings[m.name], `/settings/${m.name}`); layers.push(settings[m.name]); } // the host layer: hostOnly keys are legal here
+    if (Object.hasOwn(providers, m.name) && isObject(providers[m.name])) committed(providers[m.name], `/spawn/providers/${m.name}`);
     payloads[m.name] = mergePayload(...layers);
   }
 

package/package.json

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