@awebai/oats 0.25.0 → 0.25.2

package/lib/instance-resolution.mjs

@@ -16,14 +16,15 @@
  *
  *  Nothing here reads `oats-config.yaml`, an installed-capability directory or a
  *  per-soul `source:` — those do not exist in this model. */
-import { existsSync, readFileSync, readdirSync, lstatSync } from "node:fs";
-import { join, resolve as resolvePath, dirname, basename } from "node:path";
+import { existsSync, readFileSync, readdirSync, lstatSync, realpathSync } from "node:fs";
+import { join, resolve as resolvePath, dirname, basename, relative, isAbsolute, sep } from "node:path";
 import { oatsError } from "./errors.mjs";
 import { loadLocal, discoverWorkspace, discoverRepo, standaloneRepo } from "./workspace.mjs";
 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";
@@ -98,29 +99,233 @@ export function findSoulEntry(discovery, name) {
   return hits[0];
 }
 
-/** Materialize a workspace soul's SOURCE (soul.yaml, AGENTS.md, skills/…) into
- *  `<agentsRoot>/<name>/soul/` so the classic spawn skeleton (which reads the
- *  soul from a directory) can proceed. Idempotent per (repo, commit): a soul dir
- *  already at that commit is reused; a different commit replaces it atomically
- *  (instances keep their own copies, so this is safe). Returns the soul dir. */
+/** The per-commit soul cache under an agent directory: `<agentDir>/souls/<commit12>/`.
+ *  Each entry is IMMUTABLE once written (fetched to staging, renamed in) and is never
+ *  removed by the kernel — a running instance's `<home>/soul` links straight at its
+ *  own commit's directory (realpath), so nothing can change under it. */
+export const SOULS_DIR = "souls";
+export const SOUL_SOURCE_STAMP = ".oats-soul-source.json";
+const commit12 = (c) => String(c || "").slice(0, 12) || "unknown";
+/** The kernel-owned "current" pointer `<agentDir>/soul` is a symlink whose target
+ *  sits inside `<agentDir>/souls/`. Returns that target's realpath, or null when the
+ *  path is absent, a real directory (0.25.0 layout) or a symlink elsewhere. */
+export function soulPointerTarget(soulDir) {
+  let st; try { st = lstatSync(soulDir); } catch { return null; }
+  if (!st.isSymbolicLink()) return null;
+  let real; try { real = realpathSync(soulDir); } catch { return null; }
+  let soulsReal; try { soulsReal = realpathSync(join(dirname(soulDir), SOULS_DIR)); } catch { return null; }
+  const rel = relative(soulsReal, real);
+  if (!rel || rel.startsWith("..") || isAbsolute(rel) || rel.includes(sep)) return null;
+  return real;
+}
+/** Atomically point `<agentDir>/soul` at `target`: symlink to a temp name, rename over.
+ *  The previous target directory is untouched (an instance may link it). */
+function swapSoulPointer(soulDir, target) {
+  const tmp = `${soulDir}.pointer-${process.pid}-${randomBytes(4).toString("hex")}`;
+  try {
+    symlinkSync(target, tmp);
+    renameSync(tmp, soulDir); // rename over an existing symlink replaces it; over a directory it fails (caller migrates first)
+  } catch (x) { try { rmSync(tmp, { force: true }); } catch { /* nothing */ } throw x; }
+}
+
+/** Materialize a workspace soul's SOURCE (soul.yaml, AGENTS.md, skills/…) into the
+ *  per-commit cache `<agentsRoot>/<name>/souls/<commit12>/` and point the classic
+ *  `<agentsRoot>/<name>/soul` at it (a SYMLINK, swapped atomically), so the classic
+ *  spawn skeleton, findAgent, doctor … keep reading "current" from the usual place
+ *  while every spawned home links its OWN commit's directory (decision 7: an
+ *  instance never changes under itself — a preview or a later spawn may fetch a new
+ *  commit and move the pointer, but no directory an instance links is ever touched).
+ *
+ *  Idempotent per (repo, commit): an existing complete entry is reused (never
+ *  refetched, never rewritten); an entry that lost its soul.yaml is moved aside and
+ *  refetched. `.oats-soul-source.json` stamps what the pointer currently shows.
+ *  Migration: a 0.25.0 `soul/` that is a REAL directory is moved to
+ *  `souls/<commit from the stamp | unknown>/` before the pointer replaces it.
+ *  Returns the PER-COMMIT directory (what a home should link). */
 export async function ensureWorkspaceSoul(prepared, agentsRoot) {
   const e = prepared.soulEntry;
   const agentDir = join(agentsRoot, e.name); const soulDir = join(agentDir, "soul");
-  const stamp = join(agentDir, ".oats-soul-source.json");
-  try { const cur = JSON.parse(readFileSync(stamp, "utf8")); if (cur.repoKey === e.repoKey && cur.commit === e.commit && existsSync(join(soulDir, "soul.yaml"))) return soulDir; } catch { /* absent or stale */ }
-  const ref = e.repoKey.startsWith("local/") ? e.repoKey.slice("local/".length) : `git:${e.repoKey}`;
-  const staging = join(agentDir, `.soul-staging-${process.pid}-${randomBytes(4).toString("hex")}`);
-  mkdirSync(agentDir, { recursive: true });
-  try {
-    // A soul's CLAUDE.md → AGENTS.md alias is the one symlink a soul source may carry.
-    await fetchRemoteTree(ref, e.commit, e.path, staging, { ...(prepared.remoteOptions || {}), allowSymlinks: (p) => p === "CLAUDE.md" });
-    if (!existsSync(join(staging, "soul.yaml")) || !existsSync(join(staging, "AGENTS.md"))) throw err("E_SOUL_INCOMPLETE", `soul ${e.name} at ${e.repoKey}@${String(e.commit).slice(0, 12)} lacks soul.yaml or AGENTS.md`, { repoKey: e.repoKey, commit: e.commit, path: e.path });
-    if (!existsSync(join(staging, "CLAUDE.md"))) symlinkSync("AGENTS.md", join(staging, "CLAUDE.md"));
-    if (existsSync(soulDir)) { const old = `${soulDir}.previous-${Date.now()}`; renameSync(soulDir, old); try { rmSync(old, { recursive: true, force: true }); } catch { /* leave it */ } }
-    renameSync(staging, soulDir);
+  const soulsDir = join(agentDir, SOULS_DIR);
+  const stamp = join(agentDir, SOUL_SOURCE_STAMP);
+  const readStamp = () => { try { return JSON.parse(readFileSync(stamp, "utf8")); } catch { return null; } };
+  const commitDir = join(soulsDir, commit12(e.commit));
+  mkdirSync(soulsDir, { recursive: true });
+
+  // --- migration: a 0.25.0 real `soul/` directory becomes souls/<commit|unknown>/ ---
+  let st; try { st = lstatSync(soulDir); } catch { st = null; }
+  if (st && !st.isSymbolicLink() && st.isDirectory()) {
+    const cur = readStamp();
+    const legacyCommit = cur && cur.repoKey === e.repoKey && typeof cur.commit === "string" && cur.commit ? commit12(cur.commit) : "unknown";
+    let dest = join(soulsDir, legacyCommit);
+    if (existsSync(dest)) dest = join(soulsDir, `${legacyCommit}.migrated-${process.pid}-${randomBytes(4).toString("hex")}`);
+    renameSync(soulDir, dest);
+    swapSoulPointer(soulDir, dest);
+  } else if (st && !st.isSymbolicLink()) {
+    // a regular file where the pointer belongs: not ours to keep
+    rmSync(soulDir, { force: true });
+  }
+
+  // --- the per-commit entry: reuse when complete, else fetch (staging → rename in) ---
+  let complete = existsSync(join(commitDir, "soul.yaml")) && existsSync(join(commitDir, "AGENTS.md"));
+  if (existsSync(commitDir) && !complete) {
+    // A damaged entry (someone removed soul.yaml): move it aside — an instance may
+    // still link it, so it is never deleted — and fetch a fresh copy under the canonical name.
+    renameSync(commitDir, `${commitDir}.damaged-${process.pid}-${randomBytes(4).toString("hex")}`);
+  }
+  if (!complete) {
+    const ref = e.repoKey.startsWith("local/") ? e.repoKey.slice("local/".length) : `git:${e.repoKey}`;
+    const staging = join(soulsDir, `.soul-staging-${process.pid}-${randomBytes(4).toString("hex")}`);
+    try {
+      // A soul's CLAUDE.md → AGENTS.md alias is the one symlink a soul source may carry.
+      await fetchRemoteTree(ref, e.commit, e.path, staging, { ...(prepared.remoteOptions || {}), allowSymlinks: (p) => p === "CLAUDE.md" });
+      if (!existsSync(join(staging, "soul.yaml")) || !existsSync(join(staging, "AGENTS.md"))) throw err("E_SOUL_INCOMPLETE", `soul ${e.name} at ${e.repoKey}@${String(e.commit).slice(0, 12)} lacks soul.yaml or AGENTS.md`, { repoKey: e.repoKey, commit: e.commit, path: e.path });
+      if (!existsSync(join(staging, "CLAUDE.md"))) symlinkSync("AGENTS.md", join(staging, "CLAUDE.md"));
+      try { renameSync(staging, commitDir); }
+      catch (x) {
+        // Lost a race with a concurrent fetch of the same commit: theirs is the same bytes.
+        if (!(existsSync(join(commitDir, "soul.yaml")) && existsSync(join(commitDir, "AGENTS.md")))) throw x;
+        rmSync(staging, { recursive: true, force: true });
+      }
+    } catch (x) { try { rmSync(staging, { recursive: true, force: true }); } catch { /* nothing */ } throw x; }
+  }
+
+  // --- the "current" pointer + its stamp ---
+  const target = realpathSync(commitDir);
+  if (soulPointerTarget(soulDir) !== target) swapSoulPointer(soulDir, target);
+  const cur = readStamp();
+  if (!cur || cur.repoKey !== e.repoKey || cur.commit !== e.commit || cur.path !== e.path) {
     writeFileSync(stamp, JSON.stringify({ repoKey: e.repoKey, commit: e.commit, path: e.path, fetchedAt: new Date().toISOString() }, null, 2) + "\n");
-    return soulDir;
-  } catch (x) { try { rmSync(staging, { recursive: true, force: true }); } catch { /* nothing */ } throw x; }
+  }
+  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
@@ -133,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/lib/operator-dispatch.mjs

@@ -0,0 +1,117 @@
+/** Operator-level capability commands — `oats <ns> <cmd>` run from a DEPLOYMENT
+ *  directory (one holding `oats-local.yaml`), not from an instance home.
+ *
+ *  Contract (docs/design/2026-09-23-workspace-module-contracts.md, "Post-0.25.0
+ *  clarifications"): resolve exactly as `oats spawn --soul <name>` would —
+ *  `prepareInstance(dir, soul)` → the soul's Resolution — find the module whose
+ *  manifest `command` is the namespace, fetch that capability into the
+ *  deployment's per-commit module store `<deployment>/.oats/modules/<cap>@<commit12>/`
+ *  (the same store capability-defined agents use; see
+ *  lib/instance-resolution.mjs#resolvePackageCapabilityAgent) and dispatch to that
+ *  copy with the soul's merged payload as `OATS_SETTINGS`.
+ *
+ *  Never "the newest instance's copy" (an instance is not an authority for the
+ *  deployment) and never an unlocked cache read: trust is exactly spawn's —
+ *  members by membership, packages by the lock's approval (`prepareInstance`
+ *  already refuses E_PACKAGE_UNAPPROVED). A module in the Resolution IS active.
+ *
+ *  `--soul` is required: without a soul there is no Resolution to answer from
+ *  (E_BAD_ARGS naming --soul). Nothing here reads oats-config.yaml. */
+import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { randomBytes } from "node:crypto";
+import { oatsError } from "./errors.mjs";
+import { loadLocal } from "./workspace.mjs";
+import { packageRef, refForKey } from "./resolve.mjs";
+import { MODULES_DIR } from "./materialize.mjs";
+import * as defaultRemote from "./remote.mjs";
+import { prepareInstance } from "./instance-resolution.mjs";
+
+function err(code, message, details) { const e = oatsError(code, message, details); e.details = details; return e; }
+
+/** Is `dir` (or an ancestor) a v2 deployment? → the loadLocal result or null when
+ *  no oats-local.yaml is in reach (the caller then falls back to the classic chain).
+ *  Any OTHER failure (a malformed oats-local.yaml → E_WORKSPACE_SCHEMA) propagates. */
+export function deploymentOf(dir) {
+  try { return loadLocal(dir); }
+  catch (e) { if (e?.code === "E_LOCAL_MISSING") return null; throw e; }
+}
+
+/** The repo ref a module's tree is fetched from, spelled as lib/remote.mjs accepts it:
+ *  member → the member repoKey (`local/<abs>` → the abs path, else `git:<key>`);
+ *  package → packageRef over the lock entry (catalog url or git source). */
+export function moduleRef(module, lock, { catalog = null, remote = defaultRemote } = {}) {
+  const from = module?.from;
+  if (!from || typeof from !== "object") throw err("E_CAPABILITY_BROKEN", `module ${module?.name ?? "?"}: resolution carries no provenance`, { module: module?.name ?? null });
+  if (from.kind === "member") return refForKey(from.repoKey);
+  if (from.kind === "package") {
+    const entry = lock?.packages?.[from.package];
+    if (!entry || typeof entry !== "object") throw err("E_PACKAGE_MISSING", `module ${module.name}: package ${from.package} is not in the deployment's lock`, { module: module.name, id: from.package });
+    return packageRef(from.package, entry, catalog, remote);
+  }
+  throw err("E_CAPABILITY_BROKEN", `module ${module.name}: unknown provenance kind ${JSON.stringify(from.kind)}`, { module: module.name, kind: from.kind ?? null });
+}
+
+/** `<deployment>/.oats/modules/<cap>@<commit12>` — the per-commit store path of a module. */
+export function moduleStoreDir(deployment, module) {
+  return join(deployment, MODULES_DIR, `${module.name}@${String(module.from.commit).slice(0, 12)}`);
+}
+
+/** Ensure the module's capability tree is in the deployment store; returns its dir.
+ *  A tree already there (oats.json present) is reused — the commit is in the name,
+ *  so it cannot be stale. The fetch lands in a sibling staging dir and is renamed
+ *  into place, so a failed or interrupted fetch never leaves a half tree that a
+ *  later call would trust. */
+export async function ensureModuleTree(deployment, module, lock, { catalog = null, remote = defaultRemote, remoteOptions, fetch = defaultRemote.fetchRemoteTree } = {}) {
+  const store = join(deployment, MODULES_DIR);
+  const dir = moduleStoreDir(deployment, module);
+  if (existsSync(join(dir, "oats.json"))) return dir;
+  const ref = moduleRef(module, lock, { catalog, remote });
+  if (typeof module.dir !== "string" || !module.dir) throw err("E_CAPABILITY_BROKEN", `module ${module.name}: resolution records no capability directory`, { module: module.name });
+  mkdirSync(store, { recursive: true });
+  const staging = join(store, `.staging-${module.name}-${process.pid}-${randomBytes(4).toString("hex")}`);
+  try {
+    await fetch(ref, module.from.commit, module.dir, staging, { ...(remoteOptions || {}), allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK });
+    if (!existsSync(join(staging, "oats.json"))) throw err("E_CAPABILITY_BROKEN", `module ${module.name}: ${module.dir} at ${String(module.from.commit).slice(0, 12)} has no oats.json`, { module: module.name, dir: module.dir, commit: module.from.commit });
+    // A concurrent call may have won; its tree is the same commit — keep it.
+    if (existsSync(join(dir, "oats.json"))) { rmSync(staging, { recursive: true, force: true }); return dir; }
+    if (existsSync(dir)) rmSync(dir, { recursive: true, force: true }); // a half tree from an interrupted direct write
+    renameSync(staging, dir);
+    return dir;
+  } catch (x) { try { rmSync(staging, { recursive: true, force: true }); } catch { /* nothing */ } throw x; }
+}
+
+/**
+ * Resolve an operator-level command namespace from a deployment directory.
+ *
+ *   contextDir  — where the operator stands (oats-local.yaml is found walking up)
+ *   namespace   — the `<ns>` the operator typed (`okf`)
+ *   soulName    — the value of --soul; REQUIRED (undefined/true/"" → E_BAD_ARGS)
+ *
+ * → { deployment, soul: { name, repoKey, commit, team }, module, manifest, commands,
+ *     settings: <resolution.payloads[cap] or {}>, resolution, prepared,
+ *     ensureTree(): Promise<dir> }   — or null when no module of the soul's
+ *     resolution claims the namespace (the caller answers E_UNKNOWN_COMMAND).
+ * Two modules claiming one namespace → E_DUPLICATE_NAMESPACE. Everything
+ * prepareInstance can throw (E_SOUL_UNKNOWN, E_PACKAGE_UNAPPROVED,
+ * E_REMOTE_UNREADABLE, …) propagates untouched.
+ */
+export async function resolveOperatorDispatch(contextDir, namespace, soulName, { remoteOptions, remote, catalog = null, fetch, prepare = prepareInstance } = {}) {
+  if (typeof namespace !== "string" || !namespace) throw err("E_BAD_ARGS", "a command namespace is required");
+  if (typeof soulName !== "string" || !soulName.trim()) {
+    throw err("E_BAD_ARGS", `oats ${namespace}: outside an instance home a capability command resolves as a spawn would — pass --soul <name> (the soul whose resolution provides the "${namespace}" namespace)`, { namespace, flag: "--soul" });
+  }
+  const prepared = await prepare(resolvePath(contextDir), soulName, { remoteOptions, remote });
+  const { resolution, lock } = prepared;
+  const deployment = prepared.deployment ?? dirname(loadLocal(contextDir).path);
+  const claimants = (resolution.modules || []).filter((m) => m?.manifest && m.manifest.command === namespace && m.manifest.commands && typeof m.manifest.commands === "object");
+  if (!claimants.length) return null;
+  if (claimants.length > 1) throw err("E_DUPLICATE_NAMESPACE", `duplicate operational command namespace "${namespace}": ${claimants.map((m) => m.name).join(", ")}`, { namespace, modules: claimants.map((m) => m.name) });
+  const module = claimants[0];
+  const payload = resolution.payloads?.[module.name];
+  const settings = payload && typeof payload === "object" ? { ...payload } : {};
+  return {
+    deployment, soul: resolution.soul, module, manifest: module.manifest, commands: module.manifest.commands, settings, resolution, prepared,
+    ensureTree: () => ensureModuleTree(deployment, module, lock, { catalog, remote, remoteOptions: remoteOptions ?? prepared.remoteOptions, fetch }),
+  };
+}

package/lib/packages.mjs

@@ -43,6 +43,12 @@
  *   the executable target whose bytes are digested. Only command targets are
  *   digested — skills, injects and other files are covered by `integrity`.
  *
+ * `executablesDigestAt(remote, ref, commit, path, capabilities?)` is the ONE shared
+ * computation of that digest over a remote tree at a commit: `oats sync` approves
+ * what it returns, `resolveSoul` requires equality with `approved.executables` at
+ * spawn (E_PACKAGE_UNAPPROVED reason "digest-mismatch"). An edited lock — same
+ * id/version, different commit, copied approval — can therefore never materialize.
+ *
  * Deprecated shims: every name the 0.24 kernel still imports from this module
  * is exported below as a thin function throwing E_REMOVED so nothing breaks at
  * import time; callers are deleted in the next phase.
@@ -370,6 +376,61 @@ export async function readPackageTree(remote, remoteRef, commit, path, { depth =
   return { manifests };
 }
 
+/**
+ * The executables digest of a locked package AT A COMMIT, read over the remote — the ONE definition
+ * `oats sync` (approval) and `resolveSoul` (the gate at spawn) share, so what was approved is exactly what
+ * is checked. `remote` is a contract-§1 remote (default lib/remote.mjs; `remoteOptions` bound here).
+ *
+ *   executablesDigestAt(remote, ref, commit, path, capabilities?, { remoteOptions } = {})
+ *   → { digest: "sha256-…", executables: [{ capability, kind, name, target }], capabilities: [<names>] }  (frozen)
+ *
+ * `capabilities` (optional, the lock entry's list) is checked against what `<path>/oats-package.json`
+ * declares at `commit`: a mismatch is E_PACKAGE_INTEGRITY { why: "capabilities", listed, locked } — a lock
+ * whose capability list drifted from the tree it names is not describing that tree.
+ *
+ * Cached per process by (remote identity, repo key, commit, path): a commit is content-addressed, so the
+ * tree — and its digest — can never change under the same OID. The cache is keyed on the remote OBJECT
+ * (WeakMap): a test's fake remote gets its own cache and never sees another test's tree; the kernel's
+ * default remote keeps one cache for the process (sync → many spawns of the same lock).
+ */
+const digestCache = new WeakMap();
+export async function executablesDigestAt(remote, ref, commit, path, capabilities = null, { remoteOptions } = {}) {
+  if (!remote || typeof remote.readRemoteFile !== "function" || typeof remote.listRemoteTree !== "function") {
+    throw new TypeError("executablesDigestAt: remote must provide readRemoteFile()/listRemoteTree() (module contract §1)");
+  }
+  if (typeof commit !== "string" || !OID_RE.test(commit)) throw oatsError("E_PACKAGE_INTEGRITY", `executablesDigestAt: commit must be a full 40-hex OID, got ${JSON.stringify(commit)}`, { commit, path });
+  if (capabilities !== null && (!Array.isArray(capabilities) || capabilities.some((c) => typeof c !== "string"))) throw new TypeError("executablesDigestAt: capabilities must be an array of names or null");
+  const parse = typeof remote.parseRepoRef === "function" ? remote.parseRepoRef : defaultRemote.parseRepoRef;
+  let repoKey; try { repoKey = parse(ref).key; } catch { repoKey = String(ref); }
+  const cacheKey = `${repoKey}\0${commit}\0${path}`;
+  let perRemote = digestCache.get(remote);
+  if (!perRemote) { perRemote = new Map(); digestCache.set(remote, perRemote); }
+  let pending = perRemote.get(cacheKey);
+  if (!pending) {
+    pending = (async () => {
+      const tree = await readPackageTree(remote, ref, commit, path, { remoteOptions });
+      const digest = executablesDigest(tree);
+      const executables = [];
+      for (const m of [...tree.manifests].sort((a, b) => byCodepoint(String(a.name), String(b.name)))) {
+        for (const x of manifestExecutables(m.manifest)) executables.push({ capability: m.name, kind: x.kind, name: x.name, target: x.target });
+      }
+      return Object.freeze({ digest, executables: Object.freeze(executables.map((x) => Object.freeze(x))), capabilities: Object.freeze(tree.manifests.map((m) => m.name).sort(byCodepoint)) });
+    })();
+    perRemote.set(cacheKey, pending);
+    // A failed read is not cached: the next caller retries (a transient remote failure must not pin an error).
+    pending.catch(() => { if (perRemote.get(cacheKey) === pending) perRemote.delete(cacheKey); });
+  }
+  const result = await pending;
+  if (capabilities !== null) {
+    const locked = [...capabilities].sort(byCodepoint);
+    const listed = result.capabilities;
+    if (locked.length !== listed.length || locked.some((c, i) => c !== listed[i])) {
+      throw oatsError("E_PACKAGE_INTEGRITY", `the lock lists capabilities [${locked.join(", ")}] for ${path} at ${commit.slice(0, 12)}, but the package there declares [${listed.join(", ")}]`, { why: "capabilities", commit, path, listed: [...listed], locked });
+    }
+  }
+  return result;
+}
+
 // ---------- resolvePackages ----------
 
 function assertDigest(what, value, details) {
@@ -454,7 +515,7 @@ export async function resolvePackages(workspace, { catalog = {}, lock = emptyLoc
       }
       // A recorded approval must describe THESE executables, not merely any well-formed digest.
       if (old.approved) {
-        const executables = executablesDigest(await readPackageTree(remote, req.remoteRef, obs.commit, old.path));
+        const { digest: executables } = await executablesDigestAt(remote, req.remoteRef, obs.commit, old.path);
         if (executables !== old.approved.executables) {
           throw oatsError("E_PACKAGE_UNAPPROVED",
             `packages.${id} ${version}: the recorded approval ${old.approved.executables} does not match the package's executables ${executables} — approve again`,