@awebai/oats 0.25.4 → 0.25.6

package/docs/integrations.md

@@ -85,10 +85,11 @@ can spawn. `owns`/`reads` are responsibility/context, not ACLs. See
 [knowledge](knowledge.md) for the **prepared** version scope, provisioning and
 commands, and [migration](knowledge-migration.md) before updating v1.
 
-**`oats.aweb`** fills `messaging`: mints an instance identity at spawn,
-removes it at retire, contributes the aweb messaging and team skills, wires
-the channel plugin so sessions are woken by mail, and exposes
-`oats aweb roster` and `oats aweb setup`. Requires the `aw` CLI.
+**`oats.aweb`** fills `messaging`: mints an instance identity at spawn (local
+mode) or grants an instance an expiring session as a resident global identity
+(global mode), removes or revokes it at retire, contributes the aweb messaging
+and team skills, wires the channel plugin so sessions are woken by mail, and
+exposes `oats aweb roster` and `oats aweb setup`. Requires the `aw` CLI.
 
 **`oats.jira`** fills `tasks`: the `jira-tasks` protocol and an advisory
 spawn hook. Requires `acli`; settings commonly include `site` and `project`.
@@ -135,6 +136,26 @@ remove it on `retire`; supply the roster; teach send, reply, chat, and "read
 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 (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.
@@ -197,12 +218,57 @@ warning naming the fresh-purpose remedy. On an older `aw` the pre-1.36.1
 report stands (`aliasReusable: false`, warning naming aweb-abim), because
 that CLI cannot revoke the certificate.
 
-## oats.aweb settings (1.10.0)
+## oats.aweb settings (1.12.0)
 
 Set in `oats-local.yaml` under `settings.oats.aweb.<key>` (host-owned), in the
 soul's `messaging:` payload (true of every instance), or per spawn with
-`oats spawn … --provider oats.aweb <key>=<value>`.
-
+`oats spawn … --provider oats.aweb <key>=<value>`. The effective payload is
+merged in order: workspace messaging, `byTeam[team]`, soul messaging,
+`oats-local.yaml` `settings.oats.aweb`, then per-spawn `--provider` values.
+`residents` is host-file-only: put custody paths only in `oats-local.yaml`,
+never in a committed workspace or soul file (current kernels document this rule
+but do not yet enforce provenance in the hook payload).
+
+- `team: <team id>`. The payload team wins over `OATS_TEAM_ID`/
+  `OATS_TEAM_NAME`; if both are set and differ, the hook warns and uses the
+  payload. Workspace v2 spawns can have an empty `OATS_TEAM_ID`, so set this in
+  the payload for global grants.
+- `identity.mode: local | global` (default `local`). Any other value is fatal.
+  Local mode is the historical behavior: a spawned team identity is minted for
+  the instance, or `identity.source` uses the existing retained-seat flow below.
+  Its spawn meta includes `identity: { mode: "local", alias, team, address:
+  null, resident: null }` beside the existing top-level `alias`, `team`, and
+  `delivery` keys.
+- `identity.mode: global` makes the instance act as a resident global identity
+  through an aweb session grant; it never mints a new global identity and never
+  copies root keys into the instance home. `identity.resident` is required and
+  resolves through `residents.<name>` to an absolute custody directory whose
+  `.aw/identity.yaml` already exists. Missing or unresolved residents fail with
+  the `oats-local.yaml settings.oats.aweb.residents.<name>` key to set. Optional
+  `identity.scopes` defaults to exactly `[mail.read, mail.send, chat.read,
+  chat.send]`; optional `identity.ttl` defaults to `8h` (aw accepts `60s` to
+  `720h`). Spawn runs `aw id grant mint --scope <comma-list> --ttl <ttl>
+  --label oats:<instance> --out <home>/.aweb-identity --json` from the custody
+  directory with `AWEB_IDENTITY_HOME` removed from the child environment: in aw
+  1.36.1, grant commands are not identity-home-aware and intentionally refuse
+  both `--identity-home` and external `AWEB_IDENTITY_HOME`, so cwd selects the
+  custody identity. The hook parses the whole JSON document because aw `--json`
+  output is indented across lines, with a fallback to the first brace-prefixed
+  block when progress lines precede it; it then verifies the minted grant's
+  `team_id` and returns
+  `env.AWEB_IDENTITY_HOME=<home>/.aweb-identity`. If the minted team differs,
+  the hook revokes the grant and keeps nothing. As of aw 1.36.1, receiving,
+  wake registration and `aw whoami` work through a grant, but sending mail or
+  chat through a grant is rejected by the server with 422 (`from_did must match
+  the authenticated sender`) because the aw client signs with the grant-key DID
+  where the server expects the resident's. Retire revokes
+  `meta.identity.grant.id` through the custody directory; with no grant id it
+  reports `nothing-to-revoke`. A failed revoke exits nonzero and reports the TTL
+  expiry.
+- `residents: { <name>: /abs/custody/dir }` is the host-owned map for global
+  mode. Each custody directory's `.aw` holds the resident identity root keys and
+  team certificate. Do not put this map in committed source; the hook cannot
+  distinguish payload provenance.
 - `delivery: channel | session` (default `channel`). `session` hands
   notification delivery to the host wake broker: `AWEB_DELIVERY=session` in
   the launch environment (declared by the manifest), no Claude channel flag,

package/docs/rebuild-to-v2.md

@@ -48,8 +48,9 @@ capabilities plus `oats.core`), so a public soul stays usable.
 Two teams that need two different messaging identities (an open-source team
 and a hosted-operations team, say) stay in ONE workspace: `team:` is a label,
 and the provider payload is addressed by label under `messaging.byTeam` (§2).
-Read §8b before relying on it: the kernel merges `byTeam`, but oats.aweb 1.11.2
-does not yet read the `team` it delivers.
+Read §8b before relying on it: oats.aweb 1.12.0 mints into the `team` the
+payload names, but the `.aw` root it mints FROM is still found by search and
+must hold that team's membership (1.11.2 ignored `team` altogether).
 
 ## 2. Write `oats-workspace.yaml` v2 in the host repo
 
@@ -76,8 +77,8 @@ members:
   - git:github.com/acme/platform
 packages:
   oats.framework: v1.1.3
-  oats.okf: v2.1.3
-  oats.aweb: v1.11.2
+  oats.okf: v2.1.4
+  oats.aweb: v1.12.0
 teams:
   global: { description: Org-wide }
   engineering: { description: Platform }
@@ -136,7 +137,7 @@ they enumerate `souls/*/soul.yaml`. A soul left under `agents/` is invisible to
 | 0.24 | v2 |
 |---|---|
 | `schemaVersion: 1` | `schemaVersion: 2` |
-| `requires.knowledge: { capability: oats.okf, source: git:…@v2.1.3#oats-package }` | `capabilities: { oats.okf: { from: package } }` — or nothing, if the workspace default already says so |
+| `requires.knowledge: { capability: oats.okf, source: git:…@v2.1.4#oats-package }` | `capabilities: { oats.okf: { from: package } }` — or nothing, if the workspace default already says so |
 | `requires.capabilities.<cap>: { source: git:… }` | `<cap>: { from: package }` (published) or `<cap>: { from: here }` / `{ from: <repo key> }` (a member capability) |
 | `source: repo:…` / `path:` | `{ from: here }` |
 | `defaults.capabilities` | fold into `capabilities:`; use `off` to remove a workspace default |
@@ -217,8 +218,8 @@ messaging identity per team (§1), a soul that loses its label silently lands
 outside every team-addressed payload; nothing refuses it. Label the membership
 when a whole repo belongs to one team, and the soul when it does not.
 
-**Per-soul memory-harvest opt-out:** not available in OKF 2.1.3 — an OKF 2.1.4
-item. Neither `okf.json` (`version`, `owner`, `owns`, `reads`) nor the settings
+**Per-soul memory-harvest opt-out:** not available in OKF 2.1.3 or 2.1.4 — a
+later OKF item. Neither `okf.json` (`version`, `owner`, `owns`, `reads`) nor the settings
 payload (`bindings-file`, `state-dir`, `harvest-runtime`, `harvest-model`) has a
 key that keeps a soul registered for reads while excluding it from harvest. A
 soul that must not be harvested today says `knowledge: none` (no OKF at all for
@@ -327,7 +328,7 @@ Member capabilities need no approval: membership is the trust.
 **Non-interactive approval (CI, scripted rebuilds):**
 
 ```bash
-oats sync --approve oats.okf@v2.1.3 --approve oats.aweb@v1.11.2
+oats sync --approve oats.okf@v2.1.4 --approve oats.aweb@v1.12.0
 ```
 
 `--approve <id>@<version>` is repeatable and approves **exactly** the entry the
@@ -405,11 +406,11 @@ machine-level setting would give the seat to EVERY instance of every messaging
 soul on that machine, and a seat can be held once. The Desktop's
 confirmed apply carries the same map.
 
-## 8b. Where the team `.aw` lives now (oats.aweb 1.11.2), and what `byTeam` does today
+## 8b. Where the team `.aw` lives now, and what `byTeam` does today
 
 A freshly minted identity (every spawn without `identity.source`) needs an
 **initialised aweb root**: a directory holding `.aw` with a team membership to
-mint into. oats.aweb 1.11.2's spawn hook looks for `.aw` among these, first hit
+mint into. oats.aweb's spawn hook (1.11.2 and 1.12.0 alike) looks for `.aw` among these, first hit
 wins: the declared team scope (`OATS_TEAM_SCOPE`, from the removed
 `oats-config.yaml` `team:` block — **empty under v2**), the instance home, the
 git repo containing the home, the resolution context (the soul's work repo) and

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

@@ -0,0 +1,42 @@
+# OATS 0.25.5
+
+Patch release: one lifecycle-contract defect fixed; two provider releases
+pinned in the official catalog.
+
+## Fixed
+
+- **Launch-hook `meta` was collected and discarded.** A capability's `launch`
+  hook may return `meta` like the spawn hook does, but the start/restart path
+  consumed only its `launch` arguments and `env`, so `instance.json.capabilityMeta`
+  kept the spawn-time value forever. A provider that re-issues a credential at
+  every start (e.g. a renewed messaging session grant) would have left the
+  ORIGINAL id on record, and retire — which reads that record as `OATS_META` —
+  would have revoked the wrong one while the live one ran to its TTL. After a
+  successful start the kernel now merges each capability's launch `meta` over
+  its entry; a hook answering without `meta` keeps its prior entry; a failed
+  launch preparation changes nothing. Regression test in
+  `test/session-restart.test.mjs`; contract paragraph in `docs/capabilities.md`.
+
+No new flags, fields or hook events. `oats version --json` unchanged apart from
+the version.
+
+## Catalog
+
+- **oats.okf → v2.1.4** (mirror in `capabilities/oats-okf` synced, published
+  tag `2af47ad3`): sparse staging to `base.root` from a single-branch partial
+  clone with streamed object reads (large repositories and large files outside
+  the knowledge base no longer matter), `git-timeout` binding key (600 s for
+  remote operations), migration record hygiene + `oats okf migrate --forget`,
+  owners keyed by `OATS_SOUL_ID` with a one-time rewrite of same-name path pins
+  (closes the `E_OWNER`-after-member-commit regression; needs kernel ≥ 0.25.3),
+  and retire removes a drained source's `okf-<id>` scheduler job.
+- **oats.aweb → v1.12.0** (byte-identical to `capabilities/oats-aweb`):
+  resident identity session grants — `identity.mode: local | global`, `team`
+  read from the payload (so `messaging.byTeam.<label>.team` is now the per-label
+  identity), host-only `residents` map, and the messaging-layer meta key
+  `identity` on every spawn. Known limitation: sending mail/chat through a
+  grant is rejected by the aweb server as of aw 1.36.1 (client bug; receive,
+  wake and whoami work). Guide truths in `docs/workspaces.md` and
+  `docs/rebuild-to-v2.md` updated from "1.11.2 ignores `team`" to what 1.12.0
+  does.
+

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/workspace-adoption.md

@@ -29,7 +29,7 @@ two roles never collapse: `oats-okf`, `oats-aweb`, `oats-jira`, `oats-linear`,
 their `oats-package/` is consumed only as a package: `from: package`, pinned
 in the workspace's `packages:`, locked and approved per version. The framework's
 own souls therefore say `oats.okf: { from: package }` even though `oats-okf` is
-a member. A bare version in `packages:` (`oats.okf: v2.1.3`) resolves through
+a member. A bare version in `packages:` (`oats.okf: v2.1.4`) resolves through
 the catalog; a package outside it is written `git:<repo>@<ref>`.
 
 ## Join it on your machine

package/docs/workspaces.md

@@ -61,7 +61,7 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
 
 packages:                                  # the ONLY versioned things
   oats.framework: v1.1.3                   # bare version → resolves through the official catalog
-  oats.okf: v2.1.3
+  oats.okf: v2.1.4
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 
 teams:                                     # labels, declared once so they cannot drift
@@ -383,13 +383,16 @@ a label under `byTeam` that is not declared in `teams:` is `E_WORKSPACE_SCHEMA`.
 **`byTeam` is kernel-merged; whether a provider honours what arrives is the
 provider's.** `spawn --preview` shows the merged `settings.<cap>` so the
 delivery is verifiable, and `instance.json.providers.<cap>` records it — but
-oats.aweb **1.11.2 does not read `team` from its payload** (it resolves the
-team from the removed `oats-config.yaml` `team:` block, else the active team at
-the `.aw` root it finds), so for 1.11.2 `byTeam` is a recorded intent, not a
-per-label identity; the per-repo `.aw` placement in
-[rebuild-to-v2.md §8b](rebuild-to-v2.md#8b-where-the-team-aw-lives-now-oatsaweb-1112-and-what-byteam-does-today)
-is the working alternative. An oats.aweb release that reads `team` from the
-payload closes the gap without a workspace edit (release notes will name it).
+**oats.aweb 1.12.0 reads `team` from its payload** and mints into exactly that
+team (`--team-id`), warning when the payload disagrees with an `OATS_TEAM_*`
+value — so `byTeam.<label>.team` IS the per-label identity. What the payload
+does not change is **where the `.aw` root is found**: the hook still searches
+the bounded candidates in
+[rebuild-to-v2.md §8b](rebuild-to-v2.md#8b-where-the-team-aw-lives-now-and-what-byteam-does-today)
+and that root must hold a membership of the named team (the deployment's `.aw`
+joined to every team its labels name is the simple layout). On oats.aweb
+1.11.2 `team` was ignored (the root's active team won), so `byTeam` there is
+a recorded intent only.
 A store (`stores: { <name>: <repo ref> }`) names a repository; where a
 knowledge base lives inside it is the knowledge provider's own concern — for
 OKF 2.1.3 that is the **bindings file** (`bases.<alias>.repository` + `root`,

package/lib/core.mjs

@@ -6097,7 +6097,7 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
   const inst = instance || meta?.instance || basename(home);
   const command = renderLaunchRecipe(recipe, { home, instance: inst });
   const selectionSource = frozen ? (config?.frozen || (!config && !selection.launchConfig && !selection.runtime) ? "frozen" : "config") : "config";
-  return { recipe, command, runtime, model: model || undefined, modelSource, yolo, config, executable, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen };
+  return { recipe, command, runtime, model: model || undefined, modelSource, yolo, config, executable, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, ...(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
@@ -6603,7 +6603,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 +7363,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 +7420,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 } : {}) };
 
       });
   };
@@ -8296,6 +8323,7 @@ export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, c
   // prepares the target runtime under its CAPTURED settings.
   const ctx = contextDir || meta.repo;
   const withLaunchHook = [];
+  let hookMeta;
   for (const p of capturedProviders(meta, frozen)) {
     const manifest = ctx ? capabilityManifest(p.id, ctx) : undefined;
     if (!manifest) throw oatsError("E_LAUNCH_PREPARATION", `${p.id} was part of this home's launch at spawn but is no longer installed in the scope; reinstall it (oats install) or respawn the instance; nothing was stopped`);
@@ -8328,6 +8356,12 @@ export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, c
       refreshed.push(c.capability);
     }
     Object.assign(env, res.env || {});
+    // 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 unprepared = contributions.filter((c) => c.capability !== null && !refreshed.includes(c.capability) && c.launch && c.launch[frozen.runtime] !== undefined && c.launch[runtime] === undefined).map((c) => c.capability);
   const legacyArgs = contributions.filter((c) => c.capability === null && c.launch && Object.keys(c.launch).length);
@@ -8335,7 +8369,7 @@ export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, c
   if (unprepared.length) throw oatsError("E_LAUNCH_PREPARATION", `${unprepared.join(", ")} contributed ${frozen.runtime} launch arguments at spawn and none for ${runtime}; 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) { if (c.capability === null && refreshed.length) continue; for (const [rt, args] of Object.entries(c.launch || {})) if (args) launch[rt] = `${launch[rt] ? `${launch[rt]} ` : ""}${args}`; }
-  return { launch, env, contributions: contributions.filter((c) => !(c.capability === null && refreshed.length)), refreshed };
+  return { launch, env, contributions: contributions.filter((c) => !(c.capability === null && refreshed.length)), refreshed, ...(hookMeta ? { meta: hookMeta } : {}) };
 }
 
 /** Start a stopped instance again in its existing home: no new home, no
@@ -8639,7 +8673,7 @@ export function startInstanceSession(home, o = {}) {
   // The independent receipt first (retire and session consult it), then the
   // mutable metadata; both tmp+rename. A failure between them is what the
   // pending receipt exists for.
-  const record = (meta, { id, backend, target, model, command, startedAt, reused, launch, runtime: newRuntime, yolo: newYolo, stop, nativeRecordId }, clearPending = true) => {
+  const record = (meta, { id, backend, target, model, command, startedAt, reused, launch, runtime: newRuntime, yolo: newYolo, stop, nativeRecordId, hookMeta }, clearPending = true) => {
     checkRoots();
     const baselinePath = retirementBaselinePath(realHome);
     let baseline;
@@ -8654,7 +8688,10 @@ export function startInstanceSession(home, o = {}) {
     const restarts = (Array.isArray(meta.restarts) ? meta.restarts : []).slice(recorded ? -20 : -19);
     if (!recorded) restarts.push({ startedAt, model: model ?? null, reused });
     const next = { ...meta, model, command, launched: true, startId: id, restarts, restartCount: (meta.restartCount || 0) + (recorded ? 0 : 1),
-      ...(launch ? { launch } : {}), ...(newRuntime ? { runtime: newRuntime } : {}), ...(newYolo !== undefined ? { yolo: newYolo } : {}) };
+      ...(launch ? { launch } : {}), ...(newRuntime ? { runtime: newRuntime } : {}), ...(newYolo !== undefined ? { yolo: newYolo } : {}),
+      // Launch-hook meta lands per capability over the spawn's record; a hook
+      // that answered without meta keeps its previous entry (retire reads it).
+      ...(hookMeta ? { capabilityMeta: { ...(meta.capabilityMeta || {}), ...hookMeta } } : {}) };
     if (backend === "herdr") { next.sessionTarget = target; delete next.tmux; }
     else { next.tmux = { session: target.session, window: target.window, socket: resolve(target.socket) }; delete next.sessionTarget; }
     if (capturedStart) atomicWriteFileSync(metaPath, canonicalJson(next), { assertRoots: checkRoots });
@@ -8753,7 +8790,7 @@ export function startInstanceSession(home, o = {}) {
       const resolvedCfg = resolveOatsConfig(context, meta.agent);
       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 || { runtime: meta.runtime, model: meta.model, yolo: meta.yolo }, selection: { launchConfig: o.launchConfig, runtime: o.runtime, model: o.model, yolo: o.yolo }, resolvedCfg, env: o.env || process.env, assertRoots: checkRoots });
-      launchPlan = { recipe: plan.recipe, command: plan.command, runtime: plan.runtime, model: plan.model, yolo: plan.yolo };
+      launchPlan = { recipe: plan.recipe, command: plan.command, runtime: plan.runtime, model: plan.model, yolo: plan.yolo, ...(plan.hookMeta ? { hookMeta: plan.hookMeta } : {}) };
       command = launchPlan.command; model = launchPlan.model;
     } else if (o.model !== undefined && o.model !== null && String(o.model).trim() !== "") {
       const resolved = resolveModelPreference(String(o.model), runtime);
@@ -8770,6 +8807,7 @@ export function startInstanceSession(home, o = {}) {
     const paneEnvExports = paneEnv.map((r) => `export ${r.name}=${shq(r.value)}; `).join("");
     checkRoots(); // launch hooks/preparation have run; no backend has been observed
     const planExtra = launchPlan ? { launch: launchPlan.recipe, runtime: launchPlan.runtime, yolo: launchPlan.yolo,
+      ...(launchPlan.hookMeta ? { hookMeta: launchPlan.hookMeta } : {}),
       ...(capturedStart ? { capturedIntent: capturedStart.intent } : {}) } : {};
     let target = receipt.target;
     let state = { present: false, state: "not-launched" };

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-catalog.json

@@ -3,12 +3,12 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v2.1.3",
+      "ref": "v2.1.4",
       "path": "oats-package"
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.11.2",
+      "ref": "v1.12.0",
       "path": "oats-package"
     },
     "oats.jira": {

package/package.json

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