@awebai/oats 0.25.1 → 0.25.3

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.
@@ -183,7 +191,9 @@ 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
@@ -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,7 +359,7 @@ 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=/abs/path/to/retained/.aw` |
 
@@ -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,9 @@ 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

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/"] });
@@ -631,7 +640,7 @@ const LAUNCH_CONFIG_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Environment the kernel sets for every launch (identity, home, roots) and
  *  its reference aliases: a configuration may not name them. */
-export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "OATS_AGENT", "OATS_SOUL", "OATS_ROOT", "OATS_CONTEXT", "OATS_WORKSPACE", "OATS_EVENT", "OATS_SETTINGS", "OATS_CLI_BIN", "PI_AGENT_INSTANCE", "PI_AGENT_HOME", "PI_AGENTS_ROOT"]);
+export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "OATS_AGENT", "OATS_SOUL", "OATS_SOUL_ID", "OATS_ROOT", "OATS_CONTEXT", "OATS_WORKSPACE", "OATS_EVENT", "OATS_SETTINGS", "OATS_CLI_BIN", "PI_AGENT_INSTANCE", "PI_AGENT_HOME", "PI_AGENTS_ROOT"]);
 export const LAUNCH_REF_PREFIX = "OATS_LAUNCH_REF_";
 const reservedLaunchEnv = (n) => RESERVED_LAUNCH_ENV.has(n) || n.startsWith(LAUNCH_REF_PREFIX);
 export function validateLaunchConfig(name, entry, where) {
@@ -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") {
@@ -4785,7 +4806,31 @@ function validateHookEnvironment(capabilityID, value, owners, declarations) {
   return accepted;
 }
 
-export function runLifecycleHooks(event, { home, instance, agentName, soulDir, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {}, assertRoots }) {
+/**
+ * A soul's STABLE identity for capability hooks (OATS_SOUL_ID): what a provider
+ * may key durable state on. Workspace soul: `<repo key>#<soul name>` — it does not
+ * change when the member commits (the per-commit soul directory does) or when the
+ * copy moves. Classic soul: the realpath of agents/<name>/soul, i.e. today's value,
+ * so 0.24 deployments are unchanged. Order: an explicit `soulId` (a prepared spawn),
+ * the home's recorded `instance.json.workspace.soul` (retire/launch of a workspace
+ * home), else the path.
+ */
+export function stableSoulId({ soulId, home, soulDir, agentName } = {}) {
+  if (typeof soulId === "string" && soulId) return soulId;
+  if (home) {
+    try {
+      const meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8"));
+      const s = meta?.workspace?.soul;
+      if (typeof s?.id === "string" && s.id) return s.id;
+      if (typeof s?.repoKey === "string" && s.repoKey) return `${s.repoKey}#${meta.agent ?? agentName ?? ""}`;
+    } catch { /* not a workspace home */ }
+  }
+  if (soulDir) { try { return realpathSync(soulDir); } catch { return soulDir; } }
+  return "";
+}
+export const workspaceSoulId = (repoKey, name) => `${repoKey}#${name}`;
+
+export function runLifecycleHooks(event, { home, instance, agentName, soulDir, soulId, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {}, assertRoots }) {
   const results = { meta: {}, briefs: [], warnings: [], order: [], launch: {}, env: {}, failures: [], contributions: [] };
   const envOwners = new Map();
   const envDeclarations = new Map((resolved.capabilities || []).map((cap) => [cap.id, { names: new Set(cap.environment || []), namespaces: [...(cap.environmentNamespaces || [])] }]));
@@ -4813,7 +4858,7 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, c
           // the package STORE root — do not conflate them.
           OATS_EVENT: event, OATS_INSTANCE: instance, OATS_INSTANCE_HOME: home, OATS_HOME: home, OATS_AGENT: agentName,
           OATS_CAPABILITY: cap.id, OATS_LAYER: cap.layer || "", OATS_ROOT: rootDir || "",
-          OATS_SOUL: soulDir || "", OATS_CONTEXT: contextDir, OATS_WORKSPACE: workspaceDir || "", OATS_LEVEL: cap.level || "",
+          OATS_SOUL: soulDir || "", OATS_SOUL_ID: stableSoulId({ soulId, home, soulDir, agentName }), OATS_CONTEXT: contextDir, OATS_WORKSPACE: workspaceDir || "", OATS_LEVEL: cap.level || "",
           OATS_TEAM_NAME: resolved.team?.name || "", OATS_TEAM_ID: resolved.team?.id || "", OATS_TEAM_SCOPE: resolved.team?.scope || "",
           ...extraEnv,
           // Hooks also run through direct core callers (not only bin/oats).
@@ -6569,8 +6614,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, declRevision: o.prepared.resolution.declRevision ?? null, payloadRevision: o.prepared.resolution.payloadRevision ?? null, 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,
@@ -6870,7 +6923,7 @@ function* spawnBody(root, agent, o = {}) {
     // 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 taught <name>-workspace/, member clones beside it);
+    //   (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 = preparedDeployment
@@ -6909,8 +6962,12 @@ function* spawnBody(root, agent, o = {}) {
   // Capability lifecycle hooks (spawn) — the knowledge integration scaffolds instance
   // memory (STATE.md/log.md/notes/ are OKF conventions, not kernel ones); the
   // messaging integration mints the comms identity. Kernel stays memory-agnostic.
+  const preparedSoulId = o.prepared ? workspaceSoulId(o.prepared.soulEntry.repoKey, o.prepared.soulEntry.name) : undefined;
+  // Hooks read the soul the HOME links (the per-commit directory for a workspace
+  // soul), never the swappable agents/<name>/soul pointer: a provider that pins a
+  // path must pin this instance's content, and OATS_SOUL_ID is what it keys on.
   const hookRes = runLifecycleHooks("spawn", {
-    home, instance, agentName: agent.name, soulDir, contextDir: repoAbs,
+    home, instance, agentName: agent.name, soulDir: homeSoulTarget, soulId: preparedSoulId, contextDir: repoAbs,
     workspaceDir: workspaceOf(root), rootDir: root, resolved: resolvedCfg,
     extraEnv: { OATS_TASK: task, OATS_REPO: repoAbs, OATS_BRANCH: branch || "", OATS_WORK: work, OATS_RUNTIME: runtime, OATS_KIND: agent.kind || "persistent" },
   });
@@ -7014,7 +7071,7 @@ function* spawnBody(root, agent, o = {}) {
     catch (e) { return retainDirectory(e); }
     try {
       const comp = runLifecycleHooks("retire", {
-        home, instance, agentName: agent.name, soulDir, contextDir: repoAbs,
+        home, instance, agentName: agent.name, soulDir: homeSoulTarget, soulId: preparedSoulId, contextDir: repoAbs,
         workspaceDir: workspaceOf(root), rootDir: root, resolved: resolvedCfg,
         priorMeta: hookRes.meta || {},
       });
@@ -7213,7 +7270,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     // digests) in instance.json before this metadata is assembled — carry them.
     if (o.prepared) {
       try { const prior = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); if (prior.modules) meta.modules = prior.modules; if (prior.providers) meta.providers = prior.providers; } catch { /* materialize wrote it; absent means nothing to carry */ }
-      meta.workspace = { key: o.prepared.discovery?.key ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, team: o.prepared.soulEntry.team ?? null } };
+      meta.workspace = { key: o.prepared.discovery?.key ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { id: workspaceSoulId(o.prepared.soulEntry.repoKey, o.prepared.soulEntry.name), repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, team: o.prepared.soulEntry.team ?? null } };
     }
     const spawnWarnings = warnings;
 
@@ -9337,9 +9394,12 @@ export function retireInstance(root, name, o = {}) {
     const resolved = meta.capabilityRuntime
       ? { capabilities: meta.capabilityRuntime }
       : resolveOatsConfig(meta.repo, found.agent.name);
+    // The soul this HOME links (a workspace home links its per-commit directory;
+    // agents/<name>/soul may since point elsewhere) — the same value spawn's hook saw.
+    const homeSoulLink = (() => { try { return realpathSync(join(found.home, "soul")); } catch { return null; } })();
     hookResults = runLifecycleHooks("retire", {
       home: found.home, instance: name, agentName: found.agent.name,
-      soulDir: found.agent._soulDir || join(found.agent._dir, "soul"),
+      soulDir: homeSoulLink || found.agent._soulDir || join(found.agent._dir, "soul"),
       contextDir: meta.repo, workspaceDir: workspaceOf(root), rootDir: root, resolved, priorMeta: meta.capabilityMeta || {},
     });
   }

package/lib/instance-resolution.mjs

@@ -23,7 +23,8 @@ import { loadLocal, discoverWorkspace, discoverRepo, standaloneRepo } from "./wo
 import { resolveSoul, packageRef } from "./resolve.mjs";
 import { materialize, MODULES_DIR, SKILLS_DIR } from "./materialize.mjs";
 import { fetchRemoteTree } from "./remote.mjs";
-import { mkdirSync, renameSync, rmSync, writeFileSync, symlinkSync } from "node:fs";
+import { mkdirSync, renameSync, rmSync, writeFileSync, symlinkSync, statSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { readLock, LOCK_FILE, readPackageManifests } from "./packages.mjs";
 import * as defaultRemote from "./remote.mjs";
@@ -198,6 +199,135 @@ export async function ensureWorkspaceSoul(prepared, agentsRoot) {
   return target;
 }
 
+// ---------------------------------------------------------------------------
+// Member clones — where a workspace soul's `work: worktree|checkout` target lives
+// ---------------------------------------------------------------------------
+
+/** The taught member name of a repo key: the last path segment without `.git`
+ *  (`github.com/northwind/platform` → `platform`). The same rule `oats onboard`
+ *  and `oats sync` print (memberLabel). */
+export function memberNameOf(key) {
+  return String(key).split("/").filter(Boolean).pop()?.replace(/\.git$/i, "") || String(key);
+}
+
+/** The convention path of a member's clone: `<deployment>/<member name>` — except a
+ *  member called `agents`, which is cloned as `agents-repo/` because `<deployment>/agents/`
+ *  is the instance root (design doc §4; matches onboard's cloneDirOf). */
+export function conventionCloneDir(deployment, key) {
+  const name = memberNameOf(key);
+  return join(deployment, name === "agents" ? "agents-repo" : name);
+}
+
+/** Normalise a key an operator may have WRITTEN in `clones:` — the canonical key
+ *  (`github.com/org/repo`), or any ref form parseRepoRef understands (`git:…`,
+ *  `https://…`, `git@host:…`, `/abs/bare.git`) — to the canonical key. A key that
+ *  parses no way is returned as written (it can then only match literally). */
+function canonicalCloneKey(written) {
+  const s = String(written).trim();
+  if (s.startsWith("local/")) return s; // a local key is already canonical
+  for (const candidate of [s, `git:${s}`]) {
+    try { return parseRepoRef(candidate).key; } catch { /* next form */ }
+  }
+  return s;
+}
+
+/** The remote urls a clone carries (any remote, not only origin), parsed to their
+ *  repo keys. Not a git repo → null. */
+function cloneRemoteKeys(path) {
+  const git = (argv) => spawnSync("git", ["-C", path, ...argv], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10_000, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
+  const inside = git(["rev-parse", "--git-dir"]);
+  if (inside.status !== 0) return null;
+  const cfg = git(["config", "--get-regexp", "^remote\\..*\\.url$"]);
+  const keys = [];
+  if (cfg.status === 0) {
+    for (const line of cfg.stdout.split("\n")) {
+      const url = line.replace(/^\S+\s+/, "").trim();
+      if (!url) continue;
+      try { keys.push(parseRepoRef(url).key); } catch { keys.push(`?/${url}`); }
+    }
+  }
+  return keys;
+}
+
+/** Two repo keys name the same repository. Hosted keys compare literally; `local/<abs>`
+ *  keys compare by realpath when the path exists (macOS tmpdir → /private/var…). */
+function sameRepoKey(a, b) {
+  if (a === b) return true;
+  if (!a.startsWith("local/") || !b.startsWith("local/")) return false;
+  const real = (k) => { try { return realpathSync(k.slice("local/".length)); } catch { return k.slice("local/".length); } };
+  return real(a) === real(b);
+}
+
+/** Verify `path` is the clone of `key`: it exists, is a directory, is a Git repo, and
+ *  one of its remotes parses to `key`. Anything else → E_CLONE_MISMATCH { path, expected,
+ *  found } — the operator pointed the kernel at the wrong place; it never works there. */
+export function verifyMemberClone(path, key, { via } = {}) {
+  const mismatch = (found, why) => err("E_CLONE_MISMATCH", `${via ? `${via}: ` : ""}${path} is not a clone of ${key}${why ? ` (${why})` : ""}${found && found.length ? ` — its remotes point at ${found.join(", ")}` : ""}`, { path, expected: key, found, via: via ?? null });
+  let st; try { st = statSync(path); } catch { throw mismatch(null, "the path does not exist"); }
+  if (!st.isDirectory()) throw mismatch(null, "not a directory");
+  const found = cloneRemoteKeys(path);
+  if (found === null) throw mismatch(null, "not a Git repository");
+  if (!found.some((k) => sameRepoKey(k, key))) throw mismatch(found, found.length ? "no remote names it" : "it has no remotes");
+  return path;
+}
+
+/**
+ * Where the work target of a PREPARED spawn lives — the member clone of the soul's
+ * repo on this machine (design doc §4; decision 9: the work target is the only thing
+ * that needs a clone). In order:
+ *   1. `explicit` (`--repo`) — the operator's word; relative to the deployment; not
+ *      verified against the member (an explicit --repo may deliberately point elsewhere);
+ *   2. `oats-local.yaml` `clones: { <repo key>: <path> }` — the key as written is
+ *      normalised through parseRepoRef so `git:…`, `https://…`, `git@…` spellings match;
+ *   3. `<deployment>/<member name>` (`agents` → `agents-repo`);
+ *   4. null — nothing on this machine.
+ * A path found by (2) or (3) is VERIFIED: a directory, a Git repo, one remote parsing to
+ * the member's key → else E_CLONE_MISMATCH. A `clones:` entry whose path is absent is a
+ * mismatch too (the operator named it; "missing" would hide the typo).
+ * Returns an absolute path or null.
+ */
+export function resolveMemberClone(prepared, { explicit } = {}) {
+  const deployment = resolvePath(prepared?.deployment ?? process.cwd());
+  if (typeof explicit === "string" && explicit.trim()) return isAbsolute(explicit) ? resolvePath(explicit) : resolvePath(deployment, explicit);
+  const key = prepared?.soulEntry?.repoKey;
+  if (typeof key !== "string" || !key) return null;
+  const clones = prepared?.local?.clones;
+  if (clones && typeof clones === "object") {
+    for (const [written, value] of Object.entries(clones)) {
+      if (!sameRepoKey(canonicalCloneKey(written), key)) continue;
+      if (typeof value !== "string" || !value.trim()) throw err("E_CLONE_MISMATCH", `oats-local.yaml clones: ${written} must be a path`, { path: value, expected: key, found: null, via: "oats-local.yaml clones:" });
+      const path = isAbsolute(value) ? resolvePath(value) : resolvePath(deployment, value);
+      return verifyMemberClone(path, key, { via: `oats-local.yaml clones: ${written}` });
+    }
+  }
+  const convention = conventionCloneDir(deployment, key);
+  if (!existsSync(convention)) return null;
+  return verifyMemberClone(convention, key, { via: "convention path" });
+}
+
+/** The clone url of the soul's member as the workspace names it (for remedies). */
+function memberUrlOf(prepared, key) {
+  for (const ref of prepared?.discovery?.workspace?.members || []) {
+    try { const p = parseRepoRef(ref); if (sameRepoKey(p.key, key)) return p.url; } catch { /* validated already */ }
+  }
+  if (prepared?.discovery?.standalone === true && prepared.discovery.key === key) return prepared.discovery.url ?? null;
+  return key.startsWith("local/") ? key.slice("local/".length) : `https://${key}.git`;
+}
+
+/** resolveMemberClone, or E_CLONE_MISSING naming BOTH ways to provide the clone
+ *  (the convention path and a `clones:` entry) plus `--repo` for a one-off. */
+export function requireMemberClone(prepared, { explicit } = {}) {
+  const found = resolveMemberClone(prepared, { explicit });
+  if (found) return found;
+  const key = prepared?.soulEntry?.repoKey ?? "<repo>";
+  const deployment = resolvePath(prepared?.deployment ?? process.cwd());
+  const convention = conventionCloneDir(deployment, key);
+  const url = memberUrlOf(prepared, key);
+  const soul = prepared?.soulEntry?.name ?? "<soul>";
+  const work = prepared?.soulEntry?.definition?.work ?? "worktree";
+  throw err("E_CLONE_MISSING", `soul ${soul} works in a ${work} of ${key}, and this machine has no clone of it — either \`git clone ${url} ${convention}\` (the convention: <deployment>/<member name>) or point oats-local.yaml at an existing clone: \`clones: { ${key}: <abs path> }\`; for a one-off pass --repo <path>`, { soul, repoKey: key, work, deployment, convention, url, remedies: { clone: `git clone ${url} ${convention}`, local: { clones: { [key]: "<abs path>" } }, flag: "--repo <path>" } });
+}
+
 /** The async half of a spawn: everything that touches the network. Returns a
  *  PREPARED object that `spawnInstance` consumes synchronously. */
 export async function prepareInstance(contextDir, soulName, { spawn = {}, remoteOptions, remote, local: localOverride, discovery: discoveryOverride } = {}) {
@@ -208,7 +338,7 @@ export async function prepareInstance(contextDir, soulName, { spawn = {}, remote
   const discovery = discoveryOverride ?? await discoverOrStandalone(local, { remoteOptions, remote });
   const soulEntry = findSoulEntry(discovery, soulName);
   const resolution = await resolveSoul(discovery, soulEntry, { local, lock, spawn, remoteOptions, remote });
-  return { local, deployment, lock, discovery, soulEntry, resolution, remoteOptions };
+  return { local, deployment, lock, discovery, soulEntry, resolution, remoteOptions, spawn };
 }
 
 /** E_REMOTE_UNREADABLE reasons (lib/remote.mjs classifyRemoteFailure) that mean "the