@awebai/oats 0.25.0 → 0.25.2

package/docs/souls-and-instances.md

@@ -25,10 +25,12 @@ A soul is durable and committed. It is the part you review, improve, and keep.
   AGENTS.md            # canonical operating doc
   CLAUDE.md → AGENTS.md
   skills/              # skills specific to this expert
+  okf.json             # if the soul uses oats.okf: { version: 1, owner, owns: ["<base>/<node>"], reads: […] } — the provider's, not the kernel's
 ```
 
-(A deployment's own `agents/<name>/soul/` has the same shape; a member soul is
-fetched there at its discovered commit before its first spawn.)
+(A deployment's `agents/<name>/souls/<commit12>/` has the same shape; a member
+soul is fetched there at its discovered commit before its first spawn, and
+`agents/<name>/soul` points at the current commit.)
 
 ### `soul.yaml` v2
 
@@ -47,8 +49,8 @@ capabilities:                             # WHERE each capability comes from —
   acme-house-style: off                   # removes a workspace/team default
 
 knowledge:                                # provider payloads — opaque to the kernel, consumed by the slot's capability
-  owns: release-manager
-  reads: [platform-engineer]
+  harvest-runtime: claude                 #   (oats.okf 2.1.3 reads only its binding's settings keys here; what the soul
+                                          #    owns/reads is in this directory's okf.json — see "Soul anatomy")
 messaging:
   channels: [acme-eng]
 tasks: none                               # `none` empties the slot (drops the workspace default)
@@ -63,7 +65,7 @@ compatibility:                            # optional floors on PACKAGE versions
 | `team` | A label declared in the workspace's `teams:`; may add `defaults.byTeam` capabilities. Never gates or restricts. |
 | `private` | `true` keeps the soul out of workspace discovery; its own repo can still spawn it. |
 | `capabilities` | `<cap>: { from: here \| <repo key> \| package }` or `<cap>: off`. Composed over `defaults.<slot>` ⊕ `defaults.capabilities` ⊕ `defaults.byTeam[team]`; the soul wins. |
-| `knowledge` / `messaging` / `tasks` | The slot's provider payload (true of every instance of the soul), or `none`. Merged with `oats-local.yaml` `settings.<cap>` and `spawn --provider <cap>`; the provider's `binding` contract validates the result. |
+| `knowledge` / `messaging` / `tasks` | The slot's provider payload (true of every instance of the soul), or `none`. Merged with `oats-local.yaml` `settings.<cap>` and `spawn --provider <cap>`; the provider's `binding` contract validates the result — and refuses keys it does not declare. For `oats.okf` 2.1.3 the admitted keys are its settings (`bindings-file`, `state-dir`, `harvest-runtime`, `harvest-model`); the soul's `owns`/`reads` live in `souls/<name>/okf.json`, which OKF reads from the soul directory. |
 | `compatibility` | `<cap>: <semver range>` checked against the locked package version (`E_COMPATIBILITY`). |
 
 Schema: [`soul.schema.json`](soul.schema.json). Not in v2: `kind`, `type`,
@@ -82,7 +84,9 @@ souls — is ordinary capability content: **`oats.core`** (package
 `defaults.capabilities: { oats.core: { from: package } }`; a soul may say
 `oats.core: off`. **`oats.setup`** (same package) carries the whole-architecture
 knowledge an onboarding expert needs. Neither is kernel magic; the kernel still
-composes its own instance-boundary and work-mode briefings.
+composes its own instance-boundary and work-mode briefings — and, when
+`oats.core` resolves as a module, leaves the "You run on OATS" briefing to the
+module's inject (one block, not two; 0.25.2).
 
 ## Instance anatomy
 
@@ -134,7 +138,7 @@ skills and instructions), a workspace spawn records:
     }
   },
   "providers": {
-    "oats.okf": { "owns": "release-manager", "reads": ["platform-engineer"], "state-dir": "/Users/ana/.oats/okf" },
+    "oats.okf": { "bindings-file": "/Users/ana/.oats/okf-bindings.json", "state-dir": "/Users/ana/.oats/okf", "harvest-runtime": "claude" },
     "acme-release-tooling": {}
   },
   "workspace": {
@@ -149,9 +153,13 @@ skills and instructions), a workspace spawn records:
   shows `moved` / `missing` per module (drift is shown, not prevented).
 - `providers.<cap>` — the merged provider payload the capability was bound with
   (soul ⊕ machine settings ⊕ `--provider`), so a later inspection can tell
-  which instance holds a retained seat or a one-off state root.
+  which instance holds a retained seat or a one-off state root. `spawn
+  --preview` shows the same map before anything exists, as `settings.<cap>`,
+  beside `providers` (the `--provider` flags as given).
 - `workspace` — the workspace commit observed at spawn, the soul's repo/commit/
-  team, and the **resolution revision** the spawn decision bound.
+  team, and the **resolution revision** the spawn decision bound. `oats status`
+  compares `workspace.soul` with the member's current commit too: `soul: <name>
+  from <member> @ <c7>  [member moved since …]` (`--json`: `instances[].soul`).
 
 A running instance never changes under itself: a member moving or a package
 bump affects only new spawns.
@@ -176,14 +184,16 @@ instructions and pins model/provider settings; it excludes nothing.
 ```bash
 oats spawn release-manager --purpose cut-3.2 --task "…"            # a soul of a confirmed member
 oats spawn release-manager --preview --json                        # decide everything, create nothing
-oats spawn release-manager --provider oats.aweb identity.source=retained:release-seat   # instance-level payload
+oats spawn release-manager --provider oats.aweb identity.source=/abs/path/to/retained/.aw   # instance-level payload
 ```
 
 From a deployment (where `oats-local.yaml` is), a spawn: reads the local file →
 discovers the workspace over its remotes and confirms membership → finds the
 soul among the confirmed members (or `external:`; an ambiguous bare name is
 `E_SOUL_AMBIGUOUS` — say `<repo>/<soul>`) → fetches the soul's source into
-`<agents-root>/<soul>/soul/` at its commit → resolves every capability by
+`<agents-root>/<soul>/souls/<commit12>/` at its commit (the home links that
+directory; `<agents-root>/<soul>/soul` points at the current one) → resolves
+every capability by
 `from:` (member = latest, package = locked + approved) → creates the home →
 **materializes each module whole** into `.oats/modules/` and copies its skills
 into `.agents/skills/` (a transaction: any failure leaves nothing behind) →
@@ -194,8 +204,10 @@ unchanged. This is a normal agent process with its own home and tools, not a
 subagent call.
 
 `--preview` reports `modules[]` (`from`, `layer`, `changedSince` the newest
-previous instance of the soul), `team`, the `resolution` revision and the
-decision it would bind; the apply refuses with `E_DECISION_STALE` if a member
+previous instance of the soul), `team`, the `resolution` revision, the decision
+it would bind, `providers` (the `--provider` map exactly as given) and
+`settings.<cap>` (the merged payload each provider's binding will receive);
+the apply refuses with `E_DECISION_STALE` if a member
 moved in between. `--provider <cap> key=value` (repeatable; dotted keys nest)
 must name a capability the soul resolves (`E_CAPABILITY_MISSING` otherwise) and
 needs a workspace deployment. The full DTOs are in
@@ -208,7 +220,7 @@ Examples of spawn hooks:
   registers a durable source plus its per-source schedule definition. Missing
   knowledge is an error, not permission to bootstrap an empty substitute.
 - `oats.aweb` mints a messaging identity — or, with
-  `--provider oats.aweb identity.source=retained:<seat>`, re-takes a retained
+  `--provider oats.aweb identity.source=/abs/path/of/the/.aw/to/retain`, re-takes a retained
   one for exactly this instance.
 
 ### Work
@@ -324,7 +336,10 @@ directory is for, not a place to settle in.
 ### `worktree` — isolated branch
 
 `work/` is a git worktree on the instance's own branch, by default
-`agents/<instance>`.
+`agents/<instance>`. The worktree is created from the member's **clone**, found
+as `--repo`, then `oats-local.yaml` `clones:`, then `<deployment>/<member name>`
+(`E_CLONE_MISSING` / `E_CLONE_MISMATCH` otherwise — see
+[configuration.md](configuration.md)).
 
 Use this for agents that will edit code or docs independently.
 
@@ -341,7 +356,8 @@ inside each fresh worktree. Failures warn but do not block spawn.
 
 ### `checkout` — shared current branch
 
-`work/` is a symlink to the repo checkout itself.
+`work/` is a symlink to the repo checkout itself (the member clone, found as for
+`worktree`).
 
 Use this for maintainers, coordinators, auditors, or agents working on the
 repo's current state.
@@ -382,8 +398,10 @@ exchanged for a symlink. Recovery does not replace the worker's delivery protoco
 
 ### `workspace` — cross-repo coordinator
 
-`work/` is a symlink to the **whole deployment** (the `<name>-workspace/`
-directory holding `oats-local.yaml` and the member clones) — not a repo. Every
+`work/` is a symlink to the **whole deployment** — the directory holding
+`oats-local.yaml`, with `agents/` and the member clones that sit beside it —
+not a repo (0.25.1; a member cloned elsewhere is reached through
+`oats-local.yaml` `clones:`). Every
 member repo is read-context; the instance's product is coordination:
 routing, analysis, task-writing, messaging, spawning specialists.
 

package/docs/workspaces.md

@@ -122,9 +122,8 @@ capabilities:
   acme-deploy: { from: package }           # provided by acme.tools, pinned in packages:
   acme-house-style: off                    # removes a workspace default
 
-knowledge:                                 # provider payload, opaque to the kernel
-  owns: release-manager
-  reads: [platform-engineer]
+knowledge:                                 # provider payload, opaque to the kernel — the slot capability's BINDING keys
+  harvest-runtime: claude                  # (oats.okf 2.1.3: what this soul owns/reads is in souls/<name>/okf.json, not here — see below)
 messaging:
   channels: [acme-eng]
 tasks: none                                # empties the slot
@@ -133,7 +132,15 @@ compatibility:                             # optional FLOORS on package versions
   oats.okf: ">=2.1"
 ```
 
-Beside it: `AGENTS.md` (canonical), `CLAUDE.md → AGENTS.md`, `skills/`. Every
+Beside it: `AGENTS.md` (canonical), `CLAUDE.md → AGENTS.md`, `skills/`, and
+whatever the slot providers read from the soul directory — for `oats.okf`
+2.1.3 that is **`okf.json`** (`{ version: 1, owner, owns: ["<base>/<node>"],
+reads: […] }`, written by `oats okf init|migrate`), the soul's knowledge
+declaration; it travels with the soul into the per-commit soul cache. The
+`knowledge:` payload on `soul.yaml` reaches OKF as `OATS_SETTINGS` and may
+carry only the binding's settings keys (`bindings-file`, `state-dir`,
+`harvest-runtime`, `harvest-model`); `owns`/`reads`/`root` there are refused by
+the provider, not read (a soul payload grammar is an OKF follow-up). Every
 `souls/*/soul.yaml` in a member is discoverable; one that wants to stay
 internal says `private: true` (spawnable only from its own repo). A soul's
 `name` must equal its directory name; the first of two souls declaring one
@@ -257,8 +264,11 @@ integrity on the next `oats sync` and asks again.
 
 `oats sync` confirms membership, resolves every `packages:` entry to a commit +
 content digest, asks (on a terminal) for any missing per-version executable
-approval, writes `oats-lock.json` (lockfileVersion 3) and reports what changed.
-`oats package add <id> <version|git:…@…>` / `oats package remove <id>` edit
+approval — or takes it from repeatable `--approve <id>@<version>` flags for
+unattended runs (each approves exactly the entry the resolution contains; the
+digest is always computed, never typed; Ctrl+D at the prompt is a decline,
+exit `2`) — writes `oats-lock.json` (lockfileVersion 3), creates `agents/` if
+absent and reports what changed. `oats package add <id> <version|git:…@…>` / `oats package remove <id>` edit
 `packages:` in the workspace file when it is tracked by the current checkout,
 else print the line to add — the workspace file is shared through Git. Details:
 [packages.md](packages.md).
@@ -298,6 +308,7 @@ Nothing is symlinked, nothing is shared between instances.
 ```
 <agents-root>/<soul>/instances/<instance>/
 ├── AGENTS.md                          # composed: soul AGENTS.md + kernel/work-mode blocks + each module's inject
+│                                      #   (with oats.core resolved, the module's "You run on OATS" block is the only one — the kernel's legacy copy is suppressed)
 ├── CLAUDE.md → AGENTS.md
 ├── .agents/skills/<capability>/<skill>/SKILL.md    # full copies; where pi/codex look
 ├── .claude/skills → ../.agents/skills
@@ -317,10 +328,14 @@ bumped affects only new spawns. Details and DTOs:
 [souls-and-instances.md](souls-and-instances.md), [desktop-cli-api.md](desktop-cli-api.md).
 
 **Drift is shown, not prevented.** `oats status` compares each instance's
-recorded modules with the workspace's current picture: `current`, `moved`
-(member or package now at another commit) or `missing` (capability no longer
-present, member unconfirmed, package no longer locked). `oats spawn --preview`
-lists `changedSince` the newest previous instance of the same soul.
+recorded modules — and its recorded **soul source** (`instance.json.workspace.soul`)
+— with the workspace's current picture: `current`, `moved` (member or package
+now at another commit) or `missing` (capability no longer present, member
+unconfirmed, package no longer locked). The text form is `soul: <name> from
+<member> @ <c7>  [member moved since …]` above the module rows; `--json`
+carries `instances[].soul`. `oats spawn --preview` lists `changedSince` the
+newest previous instance of the same soul, plus `providers` (the `--provider`
+map as given) and `settings.<cap>` (the merged payload each provider receives).
 
 **Harnesses start normally.** OATS is a skill contributor, not a skill sandbox:
 cwd = the instance home, the harness's own skill discovery intact
@@ -344,9 +359,9 @@ store** — it organises and can supply defaults. The messaging provider's paylo
 
 | What it is | Where | Example |
 |---|---|---|
-| True of every instance of the soul | `soul.yaml` → `knowledge:` / `messaging:` / `tasks:` | `knowledge: { owns: release-manager }` |
+| True of every instance of the soul | `soul.yaml` → `knowledge:` / `messaging:` / `tasks:` | `messaging: { channels: [acme-eng] }`; `knowledge: { harvest-runtime: claude }` |
 | A fact about this machine | `oats-local.yaml` → `settings.<cap>.<key>` (absolute paths are refused in the workspace file) | `settings.oats.okf.state-dir: /Users/ana/.oats/okf` |
-| A fact about **this spawn** | `oats spawn … --provider <cap> key=value` (repeatable; dotted keys nest) → `instance.json.providers.<cap>` | `--provider oats.aweb identity.source=retained:release-seat` |
+| A fact about **this spawn** | `oats spawn … --provider <cap> key=value` (repeatable; dotted keys nest) → `instance.json.providers.<cap>` | `--provider oats.aweb identity.source=/abs/path/to/retained/.aw` |
 
 The merged payload is `workspace.messaging` (messaging slot only; its base
 keys ⊕ `byTeam[<soul's team>]`, with `byTeam` itself stripped) ⊕ soul slot
@@ -365,14 +380,26 @@ messaging:
 
 A soul with `team: cloud` hands its messaging provider `{ team: aweb:example.cloud, … }`;
 a label under `byTeam` that is not declared in `teams:` is `E_WORKSPACE_SCHEMA`.
-A store (`stores: { <name>: <repo ref> }`) names a repository; where the base
-lives inside it is the knowledge provider's own binding key (`root` for OKF),
-given in the payload — a repo ref never carries a `#path`.
+**`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).
+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`,
+`oats-local.yaml settings.oats.okf.bindings-file`), not a soul payload key; a
+repo ref never carries a `#path`.
 
 `--provider` for a capability the soul does not resolve is `E_CAPABILITY_MISSING`;
 `__proto__`/`constructor`/`prototype` as a key at any depth is refused.
 
-## Discovery over remotes and the `<name>-workspace/` convention
+## Discovery over remotes and the deployment directory
 
 Discovery and resolution work against **Git remotes, never local clones**. The
 kernel fetches `oats-workspace.yaml`, each member's `oats-membership.yaml`,
@@ -382,25 +409,35 @@ BatchMode: nothing ever prompts). Neither the repo that defines a capability nor
 the repo that hosts the workspace needs to be cloned.
 
 **The only thing that needs a clone is a soul's work target** (`work:
-worktree | checkout`). Spawning a soul whose repo is not yet cloned is a guided
-clone-then-spawn, a job for the onboarding skill, not the kernel.
-
-The taught default is one folder named after the workspace:
+worktree | checkout`). The kernel finds it, first hit wins: (1) `oats spawn
+… --repo <abs path>`; (2) `oats-local.yaml` `clones: { <repo key>: <abs
+path> }` (keys are canonical repo keys — any ref spelling is normalised through
+`parseRepoRef`); (3) the convention `<deployment>/<member name>` (the last
+segment of the repo key; a member named `agents` is looked for at
+`<deployment>/agents-repo`, since `agents/` is the instance root). None →
+`E_CLONE_MISSING` naming the three remedies; a directory whose `origin` is a
+different repo → `E_CLONE_MISMATCH`. Spawning a soul whose repo is not yet
+cloned is a guided clone-then-spawn, a job for the onboarding skill, not the
+kernel.
+
+The deployment directory is **yours to choose** (decision 9) — an existing folder that already holds your member clones is the usual case; `oats onboard <dir>` adds what the kernel needs and nothing else:
 
 ```
-~/acme-workspace/                 ← "<name>-workspace"
+~/acme/                           ← the directory you chose
 ├── oats-local.yaml               ← which workspace this machine realizes + host paths + disabled souls
 ├── oats-lock.json                ← exact commit + integrity + per-version approval per package
 ├── agents/                       ← instance homes (each self-contained) + fetched soul sources
-├── platform/                     ← clone of github.com/acme/platform (only if someone works IN it)
+├── platform/                     ← clone of github.com/acme/platform (only if someone works IN it; may live elsewhere — see clones:)
 └── tools/
 ```
 
 The kernel never depends on this shape: `oats-local.yaml` is found by walking
-up from the current directory (`E_LOCAL_MISSING` otherwise); clones are found
-through `clones:` or the convention. A soul that lives in a member repo is
-fetched into `<agents-root>/<soul>/soul/` at its discovered commit before its
-first spawn (idempotent per commit); its instances then materialize as above.
+up from the current directory (`E_LOCAL_MISSING` otherwise); `agents/` is
+created by `oats sync` when absent; clones are found through `--repo`,
+`clones:` or the convention, in that order. A soul that lives in a member repo
+is fetched into `<agents-root>/<soul>/souls/<commit12>/` at its discovered
+commit before its first spawn (idempotent per commit; `<agents-root>/<soul>/soul`
+points at the current one); its instances then materialize as above.
 
 ## The standalone case
 
@@ -419,7 +456,16 @@ approved like any package (a soul may say `oats.core: off`); and the
 operator's `oats-local.yaml` may name the repo directly (`workspace: <member
 ref>` — the kernel notices it is a member whose workspace it cannot read and
 falls back to the standalone view — or `standalone: <repo ref>` to ask for
-that view explicitly).
+that view explicitly). `oats onboard` lists the host among the clones to make
+like any member (the host is a member; its souls may need a work clone); under
+an explicit `standalone:` header its next steps say so and name that one repo.
+
+**Executables from public members.** Membership is the trust (decision 2): a
+member capability's hooks and command scripts run on every operator's machine at
+spawn, gated by nothing but the handshake. In a mixed public/private
+organisation keep **souls only** in public members and let executable
+capabilities come from packages (approved per version in the lock) or from
+private members.
 
 **Hosting the workspace file when some members are private.** Everyone who
 can read the workspace file sees the member list. So: a public member never

package/lib/core.mjs

@@ -594,6 +594,15 @@ export function ensureRoot(cwd) {
   const root = findRoot(cwd);
   if (!root) {
     const from = resolve(cwd ?? process.cwd());
+    // Workspace model: an oats-local.yaml above `from` IS a deployment whose instance
+    // root (<deployment>/agents/) was never created — name that remedy, not a v1 verb.
+    let localDeployment = null;
+    for (let d = from; ; d = dirname(d)) { if (existsSync(join(d, "oats-local.yaml"))) { localDeployment = d; break; } if (dirname(d) === d) break; }
+    if (localDeployment) {
+      throw oatsError("E_NO_DEPLOYMENT",
+        `no instance root walking up from ${from}: ${join(localDeployment, "oats-local.yaml")} names this deployment but ${join(localDeployment, "agents")} does not exist — mkdir ${join(localDeployment, "agents")} (or run \`oats sync --dir ${localDeployment}\`, which creates it)`,
+        { from, looked: ["agents/", "local-agents/"], deployment: localDeployment, local: join(localDeployment, "oats-local.yaml"), remedy: `mkdir ${join(localDeployment, "agents")} (or run oats sync)` });
+    }
     throw oatsError("E_NO_DEPLOYMENT",
       `no deployment found walking up from ${from}: no agents/ or local-agents/ directory — create one (mkdir agents, or \`oats create <name> --local\`), run from the deployment (where oats-local.yaml lives), or set PI_AGENTS_ROOT`,
       { from, looked: ["agents/", "local-agents/"] });
@@ -4287,10 +4296,22 @@ export function composeInstanceAgentsMd(soulDir, contextDir, soulName, workMode,
     resolved.layers = Object.fromEntries(Object.entries(prepared.resolution.slots || {}).map(([slot, mod]) => [slot, mod ? { capability: mod } : null]));
   }
   const wanted = [];
-  const declaredOperations = declaredOperationalCapabilities(soulDir);
+  // Kernel "You run on OATS" block (R3, 0.25.2). Workspace model: the RESOLUTION
+  // decides — when it carries oats.core / oats.setup as a module, that module's
+  // inject and skills are the operational essentials and the kernel's legacy
+  // block (which names the bundled `oats` skill no such home has) is suppressed,
+  // whatever the soul's v1 `requires:` block says. A soul that resolves NO such
+  // module (`oats.core: off`) still gets the kernel block: the instance needs the
+  // essentials from somewhere. The classic path keeps reading `requires`.
+  const resolvedOperations = prepared
+    ? ["oats.core", "oats.setup"].filter((id) => (prepared.resolution?.modules || []).some((m) => m.name === id))
+    : null;
+  const declaredOperations = prepared ? resolvedOperations : declaredOperationalCapabilities(soulDir);
   const oatsCoreDeclared = declaredOperations.includes("oats.core");
   if (declaredOperations.length) resolved.kernelInjection = { inject: undefined,
-    provenance: `declared ${declaredOperations.join(", ")} ${declaredOperations.length === 1 ? "capability" : "capabilities"}` };
+    provenance: prepared
+      ? `declared ${declaredOperations.join(", ")} (workspace module)`
+      : `declared ${declaredOperations.join(", ")} ${declaredOperations.length === 1 ? "capability" : "capabilities"}` };
   const kernelInject = resolved.kernelInjection?.inject;
   if (kernelInject && existsSync(kernelInject)) wanted.push(["kernel:oats", kernelInject]);
   if (kind === "local") {
@@ -6131,7 +6152,13 @@ function* spawnBody(root, agent, o = {}) {
   if (!["tmux", "herdr"].includes(backend)) throw new Error(`unknown session backend "${backend}" (tmux|herdr)`);
   if (o.herdrSocket !== undefined && (typeof o.herdrSocket !== "string" || !o.herdrSocket)) throw oatsError("E_BAD_ARGS", "herdrSocket must be a socket path");
   const launch = o.launch !== false;
-  const repoAbs = resolveExecutionContext(root, work === "directory" ? (o.repo !== undefined ? o.repo : agent.repo) : (o.repo || agent.repo), work);
+  // Workspace model (`o.prepared`) + work: workspace: ./work is the deployment
+  // boundary — the directory holding oats-local.yaml (`prepared.deployment`), which
+  // is a plain directory with member clones beside it, not a Git checkout. It is
+  // the execution/config context too; no Git identity is required or recorded.
+  const preparedDeployment = o.prepared && work === "workspace" && typeof o.prepared.deployment === "string" && o.prepared.deployment ? resolve(o.prepared.deployment) : undefined;
+  if (preparedDeployment !== undefined && !(existsSync(preparedDeployment) && statSync(preparedDeployment).isDirectory())) throw oatsError("E_BAD_ARGS", `workspace mode: the deployment directory ${preparedDeployment} (where oats-local.yaml lives) is not a directory`);
+  const repoAbs = preparedDeployment ?? resolveExecutionContext(root, work === "directory" ? (o.repo !== undefined ? o.repo : agent.repo) : (o.repo || agent.repo), work);
   if (!repoAbs) throw new Error(`agent "${agent.name}" has no repo configured — pass one`);
   // Launch selection: a named configuration (explicit, or the soul's
   // launch-config default), or none; the runtime and model follow from it.
@@ -6563,8 +6590,16 @@ function* spawnBody(root, agent, o = {}) {
     // directory basename with a `module:<cap>` source — not the classic chain's view.
     const preparedCapabilities = o.prepared ? o.prepared.resolution.modules.map((m) => ({ name: m.name, origin: m.from.kind === "package" ? `package:${m.from.package}@${m.from.version}` : `member:${m.from.repoKey}@${m.from.commit}` })) : null;
     const preparedSkills = o.prepared ? o.prepared.resolution.modules.flatMap((m) => (m.manifest?.skills || []).filter((s) => typeof s === "string" && s).map((s) => ({ name: basename(s.replace(/\/+$/, "")), source: `module:${m.name}` }))) : [];
+    // R5 (0.25.2, decision 14): the preview shows the provider payloads the apply
+    // will record — `providers` is the --provider map exactly as parsed (what the
+    // operator typed; prepareInstance keeps it on prepared.spawn.providers) and
+    // `settings.<cap>` is the MERGED payload per module (soul ⊕ workspace byTeam ⊕
+    // local.settings ⊕ --provider), i.e. what the provider receives. Reserved and
+    // poison keys were refused by resolveSoul before this point (E_WORKSPACE_SCHEMA).
+    const preparedProviders = o.prepared ? structuredClone(o.prepared.spawn?.providers && typeof o.prepared.spawn.providers === "object" ? o.prepared.spawn.providers : {}) : null;
+    const preparedSettings = o.prepared ? Object.fromEntries(o.prepared.resolution.modules.map((m) => [m.name, structuredClone(o.prepared.resolution.payloads?.[m.name] && typeof o.prepared.resolution.payloads[m.name] === "object" ? o.prepared.resolution.payloads[m.name] : {})])) : null;
     return deliver({
-      ...(o.prepared ? { modules: o.prepared.preview ?? null, team: o.prepared.soulEntry?.team ?? null, resolution: o.prepared.resolution.revision, workspace: o.prepared.discovery?.key ?? null, standalone: o.prepared.discovery?.standalone === true } : {}),
+      ...(o.prepared ? { modules: o.prepared.preview ?? null, team: o.prepared.soulEntry?.team ?? null, resolution: o.prepared.resolution.revision, declRevision: o.prepared.resolution.declRevision ?? null, payloadRevision: o.prepared.resolution.payloadRevision ?? null, workspace: o.prepared.discovery?.key ?? null, standalone: o.prepared.discovery?.standalone === true, providers: preparedProviders, settings: preparedSettings } : {}),
       spawnPreviewApi: 2, preview: true, agent: agent.name, kind: agent.kind || "persistent", instance, home, repo: repoAbs, work,
       subject: o.subject ?? { soul: agent.name, agentsRoot: root, context: null },
       decision, preflight,
@@ -6684,7 +6719,29 @@ function* spawnBody(root, agent, o = {}) {
   initializeNativeHistory(home);
 
   // Body: the soul is linked for reference, while instructions are a generated instance-local view.
-  symlinkSync(soulDir, join(home, "soul"));
+  // The home's soul link. A workspace soul (o.prepared) lives in the per-commit cache
+  // agents/<name>/souls/<commit12>/ and agents/<name>/soul is only the kernel-owned
+  // "current" POINTER (a symlink swapped by every ensureWorkspaceSoul, including a
+  // preview's). The home links ITS commit's directory by realpath — never the pointer —
+  // so a later fetch can move "current" without changing anything under a running
+  // instance (decision 7); the OKF hook's owner pin (realpath of <home>/soul) stays valid.
+  let homeSoulTarget = soulDir;
+  if (o.prepared?.soulEntry?.commit) {
+    const perCommit = join(agent._dir, "souls", String(o.prepared.soulEntry.commit).slice(0, 12));
+    if (existsSync(join(perCommit, "soul.yaml"))) homeSoulTarget = realpathSync(perCommit);
+  }
+  if (homeSoulTarget === soulDir) {
+    // Not prepared (or the cache entry is absent): still never link a swappable pointer —
+    // when agents/<name>/soul is the kernel's pointer into souls/, link what it shows now.
+    try {
+      if (lstatSync(soulDir).isSymbolicLink()) {
+        const real = realpathSync(soulDir), soulsReal = realpathSync(join(dirname(soulDir), "souls"));
+        const rel = relative(soulsReal, real);
+        if (rel && !rel.startsWith("..") && !isAbsolute(rel) && !rel.includes(sep)) homeSoulTarget = real;
+      }
+    } catch { /* absent souls/ or unreadable link: link the classic soul dir */ }
+  }
+  symlinkSync(homeSoulTarget, join(home, "soul"));
   if (!o.prepared) { writeFileSync(join(home, "AGENTS.md"), composition.text); symlinkSync("AGENTS.md", join(home, "CLAUDE.md")); }
   else if (!existsSync(join(home, "CLAUDE.md"))) symlinkSync("AGENTS.md", join(home, "CLAUDE.md"));
 
@@ -6839,13 +6896,22 @@ function* spawnBody(root, agent, o = {}) {
     symlinkSync(resolve(o.workDir), join(home, "work"));
     branch = shTry(`git -C ${shq(o.workDir)} rev-parse --abbrev-ref HEAD`);
   } else if (work === "workspace") {
-    // Cross-repo coordinator: ./work is the TEAM SCOPE (deployment boundary), not
-    // a repo — member repos are read-context; repo edits are routed, not made.
-    // Requires a declared boundary: config team: scope, else the workspace scope.
+    // Cross-repo coordinator: ./work is the deployment boundary, not a repo — member
+    // repos are read-context; repo edits are routed, not made.
+    //   workspace model (o.prepared): the directory holding oats-local.yaml
+    //   (prepared.deployment — the directory holding oats-local.yaml, whatever it is named);
+    //   classic: config team: scope, else the workspace-scope oats-config.yaml.
     const resolvedCfgEarly = composition.resolved;
-    const wsRoot = resolvedCfgEarly.team?.scope
+    const wsRoot = preparedDeployment
+      || resolvedCfgEarly.team?.scope
       || resolvedCfgEarly.chain?.find((c) => c._level !== homedir())?._level;
-    if (!wsRoot) { rmSync(home, { recursive: true, force: true }); throw new Error(`workspace mode needs a declared boundary — add a "team:" block (or a workspace-scope oats-config.yaml) so ./work has a root`); }
+    if (!wsRoot) {
+      rmSync(home, { recursive: true, force: true });
+      const remedy = o.prepared
+        ? `add oats-local.yaml (workspace: <ref> or standalone: <ref>) to the deployment directory so ./work has a root`
+        : `add a "team:" block (or a workspace-scope oats-config.yaml) so ./work has a root`;
+      throw new Error(`workspace mode needs a declared boundary — ${remedy}`);
+    }
     symlinkSync(resolve(wsRoot), join(home, "work"));
     branch = undefined; // no repo identity: the workspace is not a git tree
   } else {