@awebai/oats 0.25.1 → 0.25.2

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/"] });
@@ -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") {
@@ -6569,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, 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 +6899,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

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

package/lib/materialize.mjs

@@ -571,6 +571,35 @@ export function driftOf(instanceJson, discovery, { lock } = {}) {
   return rows;
 }
 
+/**
+ * soulDriftOf(instanceJson, discovery)
+ * → { name, repoKey, commit, current: { commit } | null, status: "current"|"moved"|"missing", reason? } | null
+ *
+ * Decision 17 for the SOUL SOURCE: a workspace spawn records `instance.json.workspace.soul =
+ * { repoKey, commit, team }` (the member and commit the soul was fetched from). The member row
+ * for `repoKey` in `discovery.members` is the current state: a different commit → "moved", the
+ * soul gone from the member → "missing" (reason "soul-absent"), no usable row → "missing"
+ * (reason "unconfirmed" / the row's reason). A standalone view's own member row is unconfirmed
+ * by construction (reason "cannot-read") yet carries the repo's current commit — it is compared,
+ * not reported missing. Returns null for a home without a recorded workspace soul (classic).
+ */
+export function soulDriftOf(instanceJson, discovery) {
+  const soul = plainObject(instanceJson?.workspace) && plainObject(instanceJson.workspace.soul) ? instanceJson.workspace.soul : null;
+  if (!soul || typeof soul.repoKey !== "string") return null;
+  const name = typeof instanceJson.agent === "string" ? instanceJson.agent : (typeof instanceJson.soul === "string" ? instanceJson.soul : null);
+  const commit = typeof soul.commit === "string" ? soul.commit : null;
+  const members = Array.isArray(discovery?.members) ? discovery.members : [];
+  const member = members.find((m) => m && m.key === soul.repoKey) || null;
+  const standaloneOwn = discovery?.standalone === true && member && member.key === discovery.key && typeof member.commit === "string";
+  const base = { name, repoKey: soul.repoKey, commit, team: soul.team ?? null };
+  if (!member || (!member.confirmed && !standaloneOwn) || typeof member.commit !== "string") {
+    return { ...base, current: null, status: "missing", reason: member ? (member.reason || "unconfirmed") : "unconfirmed" };
+  }
+  const present = name === null || (Array.isArray(member.souls) && member.souls.some((s) => s && s.name === name));
+  if (!present) return { ...base, current: { commit: member.commit }, status: "missing", reason: "soul-absent" };
+  return { ...base, current: { commit: member.commit }, status: member.commit === commit ? "current" : "moved" };
+}
+
 /** Read the modules recorded in an instance home (→ {} when absent). */
 export function recordedModules(home) {
   const file = join(resolve(home), "instance.json");

package/package.json

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