@awebai/oats 0.25.0 → 0.25.1

package/lib/core.mjs

@@ -6131,7 +6131,13 @@ function* spawnBody(root, agent, o = {}) {
   if (!["tmux", "herdr"].includes(backend)) throw new Error(`unknown session backend "${backend}" (tmux|herdr)`);
   if (o.herdrSocket !== undefined && (typeof o.herdrSocket !== "string" || !o.herdrSocket)) throw oatsError("E_BAD_ARGS", "herdrSocket must be a socket path");
   const launch = o.launch !== false;
-  const repoAbs = resolveExecutionContext(root, work === "directory" ? (o.repo !== undefined ? o.repo : agent.repo) : (o.repo || agent.repo), work);
+  // Workspace model (`o.prepared`) + work: workspace: ./work is the deployment
+  // boundary — the directory holding oats-local.yaml (`prepared.deployment`), which
+  // is a plain directory with member clones beside it, not a Git checkout. It is
+  // the execution/config context too; no Git identity is required or recorded.
+  const preparedDeployment = o.prepared && work === "workspace" && typeof o.prepared.deployment === "string" && o.prepared.deployment ? resolve(o.prepared.deployment) : undefined;
+  if (preparedDeployment !== undefined && !(existsSync(preparedDeployment) && statSync(preparedDeployment).isDirectory())) throw oatsError("E_BAD_ARGS", `workspace mode: the deployment directory ${preparedDeployment} (where oats-local.yaml lives) is not a directory`);
+  const repoAbs = preparedDeployment ?? resolveExecutionContext(root, work === "directory" ? (o.repo !== undefined ? o.repo : agent.repo) : (o.repo || agent.repo), work);
   if (!repoAbs) throw new Error(`agent "${agent.name}" has no repo configured — pass one`);
   // Launch selection: a named configuration (explicit, or the soul's
   // launch-config default), or none; the runtime and model follow from it.
@@ -6564,7 +6570,7 @@ function* spawnBody(root, agent, o = {}) {
     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}` }))) : [];
     return deliver({
-      ...(o.prepared ? { modules: o.prepared.preview ?? null, team: o.prepared.soulEntry?.team ?? null, resolution: o.prepared.resolution.revision, workspace: o.prepared.discovery?.key ?? null, standalone: o.prepared.discovery?.standalone === true } : {}),
+      ...(o.prepared ? { modules: o.prepared.preview ?? null, team: o.prepared.soulEntry?.team ?? null, resolution: o.prepared.resolution.revision, declRevision: o.prepared.resolution.declRevision ?? null, payloadRevision: o.prepared.resolution.payloadRevision ?? null, workspace: o.prepared.discovery?.key ?? null, standalone: o.prepared.discovery?.standalone === true } : {}),
       spawnPreviewApi: 2, preview: true, agent: agent.name, kind: agent.kind || "persistent", instance, home, repo: repoAbs, work,
       subject: o.subject ?? { soul: agent.name, agentsRoot: root, context: null },
       decision, preflight,
@@ -6684,7 +6690,29 @@ function* spawnBody(root, agent, o = {}) {
   initializeNativeHistory(home);
 
   // Body: the soul is linked for reference, while instructions are a generated instance-local view.
-  symlinkSync(soulDir, join(home, "soul"));
+  // The home's soul link. A workspace soul (o.prepared) lives in the per-commit cache
+  // agents/<name>/souls/<commit12>/ and agents/<name>/soul is only the kernel-owned
+  // "current" POINTER (a symlink swapped by every ensureWorkspaceSoul, including a
+  // preview's). The home links ITS commit's directory by realpath — never the pointer —
+  // so a later fetch can move "current" without changing anything under a running
+  // instance (decision 7); the OKF hook's owner pin (realpath of <home>/soul) stays valid.
+  let homeSoulTarget = soulDir;
+  if (o.prepared?.soulEntry?.commit) {
+    const perCommit = join(agent._dir, "souls", String(o.prepared.soulEntry.commit).slice(0, 12));
+    if (existsSync(join(perCommit, "soul.yaml"))) homeSoulTarget = realpathSync(perCommit);
+  }
+  if (homeSoulTarget === soulDir) {
+    // Not prepared (or the cache entry is absent): still never link a swappable pointer —
+    // when agents/<name>/soul is the kernel's pointer into souls/, link what it shows now.
+    try {
+      if (lstatSync(soulDir).isSymbolicLink()) {
+        const real = realpathSync(soulDir), soulsReal = realpathSync(join(dirname(soulDir), "souls"));
+        const rel = relative(soulsReal, real);
+        if (rel && !rel.startsWith("..") && !isAbsolute(rel) && !rel.includes(sep)) homeSoulTarget = real;
+      }
+    } catch { /* absent souls/ or unreadable link: link the classic soul dir */ }
+  }
+  symlinkSync(homeSoulTarget, join(home, "soul"));
   if (!o.prepared) { writeFileSync(join(home, "AGENTS.md"), composition.text); symlinkSync("AGENTS.md", join(home, "CLAUDE.md")); }
   else if (!existsSync(join(home, "CLAUDE.md"))) symlinkSync("AGENTS.md", join(home, "CLAUDE.md"));
 
@@ -6839,13 +6867,22 @@ function* spawnBody(root, agent, o = {}) {
     symlinkSync(resolve(o.workDir), join(home, "work"));
     branch = shTry(`git -C ${shq(o.workDir)} rev-parse --abbrev-ref HEAD`);
   } else if (work === "workspace") {
-    // Cross-repo coordinator: ./work is the TEAM SCOPE (deployment boundary), not
-    // a repo — member repos are read-context; repo edits are routed, not made.
-    // Requires a declared boundary: config team: scope, else the workspace scope.
+    // Cross-repo coordinator: ./work is the deployment boundary, not a repo — member
+    // repos are read-context; repo edits are routed, not made.
+    //   workspace model (o.prepared): the directory holding oats-local.yaml
+    //   (prepared.deployment — the taught <name>-workspace/, member clones beside it);
+    //   classic: config team: scope, else the workspace-scope oats-config.yaml.
     const resolvedCfgEarly = composition.resolved;
-    const wsRoot = resolvedCfgEarly.team?.scope
+    const wsRoot = preparedDeployment
+      || resolvedCfgEarly.team?.scope
       || resolvedCfgEarly.chain?.find((c) => c._level !== homedir())?._level;
-    if (!wsRoot) { rmSync(home, { recursive: true, force: true }); throw new Error(`workspace mode needs a declared boundary — add a "team:" block (or a workspace-scope oats-config.yaml) so ./work has a root`); }
+    if (!wsRoot) {
+      rmSync(home, { recursive: true, force: true });
+      const remedy = o.prepared
+        ? `add oats-local.yaml (workspace: <ref> or standalone: <ref>) to the deployment directory so ./work has a root`
+        : `add a "team:" block (or a workspace-scope oats-config.yaml) so ./work has a root`;
+      throw new Error(`workspace mode needs a declared boundary — ${remedy}`);
+    }
     symlinkSync(resolve(wsRoot), join(home, "work"));
     branch = undefined; // no repo identity: the workspace is not a git tree
   } else {

package/lib/instance-resolution.mjs

@@ -16,8 +16,8 @@
  *
  *  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";
@@ -98,29 +98,104 @@ 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;
 }
 
 /** The async half of a spawn: everything that touches the network. Returns a

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`,