@awebai/oats 0.27.2 → 0.29.0

package/lib/packages.mjs

@@ -28,7 +28,8 @@
  *         version:      "<version string, no leading v>",
  *         commit:       "<full 40-hex OID>",
  *         integrity:    "sha256-<hex>",          // contentDigest of the package tree at <path>
- *         capabilities: ["<cap name>", …]         // sorted
+ *         capabilities: ["<cap name>", …],        // sorted
+ *         souls: [{ name, path, digest }]         // package souls (0.28.0), sorted by name; omitted when none
  *       }
  *     }
  *   }
@@ -57,6 +58,11 @@ export const DEFAULT_PACKAGE_PATH = "oats-package";
 
 const OID_RE = /^[0-9a-f]{40}$/;
 const DIGEST_RE = /^sha256-[0-9a-f]{64}$/;
+/** A soul name (docs/soul.schema.json#/$defs/slug): a package soul's name is its directory's. */
+const SOUL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** The one symlink a soul source may carry: its CLAUDE.md → AGENTS.md alias (at the soul's root).
+ *  Sync and spawn fetch a package soul with this same predicate, so their digests agree. */
+export const SOUL_ALIAS_SYMLINK = (p) => p === "CLAUDE.md";
 const CONTRACT_DOC = "docs/design/2026-09-23-workspace-module-contracts.md";
 
 /** `oatsError` with details attached as BOTH `e.provenance` (today's field) and
@@ -143,6 +149,14 @@ export function validateLock(lock, { file } = {}) {
     if (typeof entry.commit !== "string" || !OID_RE.test(entry.commit)) throw bad("commit", "must be a full 40-hex OID");
     if (typeof entry.integrity !== "string" || !DIGEST_RE.test(entry.integrity)) throw bad("integrity", "must be sha256-<hex>");
     if (!Array.isArray(entry.capabilities) || entry.capabilities.some((c) => typeof c !== "string" || !c)) throw bad("capabilities", "must be an array of capability names");
+    if (entry.souls !== undefined) {
+      if (!Array.isArray(entry.souls)) throw bad("souls", "must be an array of { name, path, digest }");
+      for (const [i, soul] of entry.souls.entries()) {
+        if (!plainObject(soul) || typeof soul.name !== "string" || !SOUL_NAME_RE.test(soul.name)) throw bad(`souls/${i}/name`, "must be a soul name");
+        if (typeof soul.path !== "string" || !soul.path || soul.path.split("/").some((p) => p === ".." || p === "") || soul.path.startsWith("/")) throw bad(`souls/${i}/path`, "must be a relative path inside the package");
+        if (typeof soul.digest !== "string" || !DIGEST_RE.test(soul.digest)) throw bad(`souls/${i}/digest`, "must be sha256-<hex>");
+      }
+    }
   }
   return lock;
 }
@@ -168,6 +182,7 @@ export function canonicalLock(lock) {
     packages[id] = {
       source: e.source, ...(typeof e.url === "string" && e.url ? { url: e.url } : {}), path: e.path, version: e.version, commit: e.commit, integrity: e.integrity,
       capabilities: [...e.capabilities].sort(),
+      ...(Array.isArray(e.souls) && e.souls.length ? { souls: [...e.souls].sort((a, b) => byCodepoint(a.name, b.name)).map((x) => ({ name: x.name, path: x.path, digest: x.digest })) } : {}),
     };
   }
   return { lockfileVersion: LOCK_VERSION, packages };
@@ -319,7 +334,63 @@ export async function readPackageManifests(remote, remoteRef, commit, path, deta
     capabilities.push({ name: capManifest.capability, dir, manifest: capManifest });
   }
   capabilities.sort((a, b) => byCodepoint(a.name, b.name));
-  return { manifest, capabilities };
+  // Package souls (0.28.0): ordinary soul directories, versioned and locked with the package. A soul's
+  // name is its directory's (as for a member's souls/<name>); soul.yaml is validated where it is
+  // discovered, AGENTS.md is required where it is locked (packageSoulDigests).
+  const souls = [];
+  if (manifest.souls !== undefined) {
+    if (!Array.isArray(manifest.souls)) throw oatsError("E_PACKAGE_MANIFEST", `package manifest at ${manifestPath}: "souls" must be a list of soul directories`, { ...details, path: manifestPath });
+    const seenSouls = new Map();
+    for (const rel of manifest.souls) {
+      assertRelPath(`${manifestPath} souls[]`, rel, { ...details, path: manifestPath });
+      const soulPath = posix.normalize(rel).replace(/\/+$/, "");
+      const name = posix.basename(soulPath);
+      if (!SOUL_NAME_RE.test(name)) throw oatsError("E_PACKAGE_MANIFEST", `${manifestPath} souls[]: ${JSON.stringify(rel)} — a soul's directory is its name, which must match ${SOUL_NAME_RE}`, { ...details, path: manifestPath, soul: rel });
+      if (seenSouls.has(name)) throw oatsError("E_PACKAGE_MANIFEST", `package ${manifest.package} declares soul ${JSON.stringify(name)} twice (${seenSouls.get(name)} and ${soulPath})`, { ...details, path: manifestPath, duplicate: name, other: seenSouls.get(name) });
+      seenSouls.set(name, soulPath);
+      souls.push({ name, path: soulPath, dir: pjoin(path, soulPath) });
+    }
+    souls.sort((a, b) => byCodepoint(a.name, b.name));
+  }
+  return { manifest, capabilities, souls };
+}
+
+/** Fetch each package soul at `commit` and return its lock record `{ name, path, digest }` — the digest
+ *  is what `fetchRemoteTree` reports with SOUL_ALIAS_SYMLINK, the same fetch a spawn makes and verifies.
+ *  A soul without soul.yaml or AGENTS.md is E_PACKAGE_MANIFEST. */
+export async function packageSoulDigests(remote, remoteRef, commit, souls, details = {}) {
+  if (!souls.length) return [];
+  if (typeof remote.fetchRemoteTree !== "function") throw oatsError("E_PACKAGE_INTEGRITY", "remote must provide fetchRemoteTree() to compute a package soul's digest", { path: "/remote" });
+  const scratch = mkdtempSync(join(tmpdir(), "oats-pkg-soul-"));
+  try {
+    const out = [];
+    for (const soul of souls) {
+      const dest = join(scratch, soul.name);
+      let digest;
+      try { ({ digest } = await remote.fetchRemoteTree(remoteRef, commit, soul.dir, dest, { allowSymlinks: SOUL_ALIAS_SYMLINK })); }
+      catch (e) {
+        if (e?.code === "E_REMOTE_PATH_MISSING") throw oatsError("E_PACKAGE_MANIFEST", `package soul ${soul.path} is missing at ${String(commit).slice(0, 12)}`, { ...details, soul: soul.name, path: soul.dir });
+        throw e;
+      }
+      // A fake remote reports a digest without copying: only a real copy can be checked for its files.
+      if (existsSync(dest)) {
+        for (const file of ["soul.yaml", "AGENTS.md"]) {
+          if (!existsSync(join(dest, file))) throw oatsError("E_PACKAGE_MANIFEST", `package soul ${soul.path} lacks ${file} at ${String(commit).slice(0, 12)} — a soul directory carries soul.yaml and AGENTS.md`, { ...details, soul: soul.name, path: soul.dir, missing: file });
+        }
+      }
+      out.push({ name: soul.name, path: soul.path, digest: assertDigest(`package soul ${soul.path} digest`, digest, details) });
+    }
+    return out;
+  } finally { rmSync(scratch, { recursive: true, force: true }); }
+}
+
+/** The repo ref a lock entry is read from without a catalog: its recorded url, else the key of a
+ *  `git:<key>@<ref>` source. → string | null (a catalog entry written without a url). */
+export function lockedPackageRef(entry) {
+  if (typeof entry?.url === "string" && entry.url) return entry.url;
+  const m = /^git:(.+)@([^@]+)$/.exec(String(entry?.source ?? ""));
+  if (!m) return null;
+  return m[1].startsWith("local/") ? m[1].slice("local/".length) : `git:${m[1]}`;
 }
 
 /** Content digest of the package tree at `path`: the digest `fetchRemoteTree` reports for a
@@ -345,6 +416,23 @@ function assertDigest(what, value, details) {
 }
 
 /** Bind `remoteOptions` (cacheDir, exec, …) into every call of a contract-§1 remote. */
+/** A remote whose reads at a commit are shared for one command (feature desktop-facts): the souls and
+ *  capabilities listings resolve many souls over the same package manifests and skill listings, and a read at
+ *  an immutable commit gives the same answer every time. A failed read is not kept (it is retried). */
+export function memoizedRemote(remote) {
+  const memo = { ...remote };
+  for (const name of ["readRemoteFile", "listRemoteTree"]) {
+    if (typeof remote[name] !== "function") continue;
+    const cache = new Map();
+    memo[name] = (...args) => {
+      const key = JSON.stringify(args);
+      if (!cache.has(key)) cache.set(key, Promise.resolve(remote[name](...args)).catch((e) => { cache.delete(key); throw e; }));
+      return cache.get(key);
+    };
+  }
+  return memo;
+}
+
 export function bindRemote(remote, remoteOptions) {
   if (!remoteOptions || Object.keys(remoteOptions).length === 0) return remote;
   const bound = { ...remote };
@@ -419,23 +507,36 @@ export async function resolvePackages(workspace, { catalog = {}, lock = emptyLoc
       // The lock's capability list must still be what the package declares at that commit —
       // spawn refuses a mismatch (E_PACKAGE_INTEGRITY why:capabilities), so sync must too, or
       // a bad list would pass every sync and fail every spawn.
-      const { capabilities } = await readPackageManifests(remote, req.remoteRef, obs.commit, old.path, details);
+      const { capabilities, souls: soulDirs } = await readPackageManifests(remote, req.remoteRef, obs.commit, old.path, details);
       const listed = capabilities.map((c) => c.name).sort(), locked = [...old.capabilities].sort();
       if (listed.length !== locked.length || listed.some((c, i) => c !== locked[i])) {
         throw oatsError("E_PACKAGE_INTEGRITY",
           `packages.${id} ${version} @ ${obs.commit}: the lock lists capabilities [${locked.join(", ")}] but the package declares [${listed.join(", ")}] — the lock was edited; remove this entry from oats-lock.json and run \`oats sync\` again`,
           { ...details, version, why: "capabilities", listed, locked });
       }
-      const { approved: _dropped, ...kept } = clone(old); // a pre-0.26 approval record is dropped on write
-      nextPackages[id] = kept;
+      // The lock's souls must be what the package ships at that commit: the same names, paths and
+      // digests. A lock written before 0.28.0 carries no `souls` — it is filled in, not refused.
+      const souls = await packageSoulDigests(remote, req.remoteRef, obs.commit, soulDirs, details);
+      if (old.souls !== undefined) {
+        const show = (list) => list.map((x) => `${x.name}@${x.path}:${x.digest.slice(7, 19)}`).sort().join(", ");
+        if (show(old.souls) !== show(souls)) {
+          throw oatsError("E_PACKAGE_INTEGRITY",
+            `packages.${id} ${version} @ ${obs.commit}: the lock's souls [${show(old.souls)}] do not match what the package ships [${show(souls)}] — the lock was edited; remove this entry from oats-lock.json and run \`oats sync\` again`,
+            { ...details, version, why: "souls", listed: souls, locked: old.souls });
+        }
+      }
+      const { approved: _dropped, souls: _souls, ...kept } = clone(old); // a pre-0.26 approval record is dropped on write
+      nextPackages[id] = { ...kept, ...(souls.length ? { souls } : {}) };
       continue;
     }
 
-    const { capabilities } = await readPackageManifests(remote, req.remoteRef, obs.commit, req.path, details);
+    const { capabilities, souls: soulDirs } = await readPackageManifests(remote, req.remoteRef, obs.commit, req.path, details);
     const integrity = assertDigest(`packages.${id} integrity`, await packageIntegrity(remote, req.remoteRef, obs.commit, req.path), details);
+    const souls = await packageSoulDigests(remote, req.remoteRef, obs.commit, soulDirs, details);
     nextPackages[id] = {
       source, url: obs.url, path: req.path, version, commit: obs.commit, integrity,
       capabilities: capabilities.map((c) => c.name).sort(),
+      ...(souls.length ? { souls } : {}),
     };
     changes.push({ id, from: old ? old.version : null, to: version, commit: obs.commit });
   }

package/lib/remote.mjs

@@ -475,7 +475,7 @@ function assertNoCollisions(entries, ref, commit, prefix) {
 async function lsTree(repo, spec, { flags = [], path, ref, commit } = {}) {
   try {
     const args = ["ls-tree", "-l", "-z", ...flags, spec];
-    if (path !== undefined) args.push("--", path);
+    if (path !== undefined) args.push("--", ...[].concat(path));
     const out = await repo.local(args, { maxBuffer: 64 * 1024 * 1024 });
     return parseLsTree(out.stdout);
   } catch (error) {
@@ -514,6 +514,26 @@ export async function readRemoteFile(refText, commitArg, path, options = {}) {
   return { bytes: out.stdout, size: out.stdout.length };
 }
 
+/** The Git tree object ids of `dirs` at `commit`, in one listing (feature desktop-facts: a member capability's
+ *  fingerprint — content-addressed, so the same bytes give the same id; NOT the sha256 content digest a
+ *  materialized module records). → Map dir → oid, null for a dir that is not a directory there. */
+export async function remoteTreeOids(refText, commitArg, dirs, options = {}) {
+  const ref = parseRepoRef(refText, options);
+  requireCommit(commitArg);
+  const rels = dirs.map((dir) => normalizeTreePath(dir, { allowRoot: false }));
+  const { repo, commit } = await ensureCommit(ref, commitArg, options);
+  const entries = rels.length ? (await lsTree(repo, commit, { path: rels, ref, commit })) ?? [] : [];
+  return new Map(dirs.map((dir, i) => [dir, entries.find((e) => e.path === rels[i] && e.type === "tree")?.oid ?? null]));
+}
+
+/** A browsable URL of a repo at a commit (feature desktop-facts): the file's page with `path`, else the tree.
+ *  Only GitHub keys have one; any other host or a local repo → null. */
+export function browseUrl(key, commit, path = null) {
+  if (typeof key !== "string" || !/^github\.com\/[^/]+\/[^/]+$/.test(key) || typeof commit !== "string" || !commit) return null;
+  const clean = typeof path === "string" && path ? path.split("/").filter(Boolean).map(encodeURIComponent).join("/") : null;
+  return clean ? `https://${key}/blob/${commit}/${clean}` : `https://${key}/tree/${commit}`;
+}
+
 /**
  * → [{ path, type: "blob"|"tree", size? }] relative to <dir>, depth-bounded (depth 1 = direct children).
  * Missing dir → []. Symlinks are reported as type "symlink" so callers can skip them.

package/lib/resolve.mjs

@@ -368,12 +368,16 @@ export function teamsOf(workspace, labels) {
  * Two labels that give one capability different entries (`off` vs a location, or two locations) →
  * E_TEAM_CONFLICT { capability, labels: [a, b] }; identical entries are not a conflict, and a capability
  * the soul names itself is not one either (the soul's entry wins over both).
+ * `offs` (optional, feature desktop-facts): receives what the soul turned off — { name, reason: "off",
+ * overrides } for each capability its own `off` removed from a lower layer, and { name, reason: "slot-none",
+ * slot, overrides: "workspace" } for a slot default its `<slot>: none` dropped (`overrides`: fromOfVia vocabulary).
  */
-export function composeCapabilities(workspace, soulDefinition, { team = null, labels = team === null ? [] : [team] } = {}) {
+export function composeCapabilities(workspace, soulDefinition, { team = null, labels = team === null ? [] : [team], offs = null } = {}) {
   const map = new Map();
   const apply = (entries, via, path) => {
     for (const [name, value] of Object.entries(entries || {})) {
       const choice = choiceOf(value, `${path}/${name}`, via);
+      if (choice === "off" && via === "soul" && offs && map.has(name)) offs.push({ name, reason: "off", overrides: fromOfVia(map.get(name).via) });
       if (choice === "off") map.delete(name);
       else map.set(name, { name, from: choice.from, via });
     }
@@ -381,6 +385,7 @@ export function composeCapabilities(workspace, soulDefinition, { team = null, la
   const defaults = isObject(workspace?.defaults) ? workspace.defaults : {};
   for (const slot of SLOTS) {
     const d = defaults[slot];
+    if (soulDefinition?.[slot] === "none" && offs && isObject(d)) for (const name of Object.keys(d)) offs.push({ name, reason: "slot-none", slot, overrides: "workspace" });
     if (soulDefinition?.[slot] === "none" || d === "none" || !isObject(d)) continue;
     const names = Object.keys(d);
     if (names.length > 1) throw fail("E_WORKSPACE_SCHEMA", `defaults.${slot} names ${names.length} capabilities; a slot default names at most one`, { path: `/defaults/${slot}`, names });
@@ -472,6 +477,15 @@ function lookupPackage(lock, name, via, soul, declared) {
   return providing;
 }
 
+/** `from: here` in a package soul: the capability must be one its OWN locked package provides. */
+function ownPackageEntry(lock, name, via, soul, id) {
+  const where = { capability: name, from: "here", soul: soul.name, via, package: id };
+  const entry = isObject(lock?.packages) ? lock.packages[id] : null;
+  if (!isObject(entry)) throw fail("E_PACKAGE_MISSING", `${name}: from: here in package soul ${id}/${soul.name} needs ${id} in the lock — run \`oats sync\``, { ...where, reason: "no-lock" });
+  if (!entry.capabilities.includes(name)) throw fail("E_CAPABILITY_MISSING", `${name}: from: here in package soul ${id}/${soul.name}, but package ${id} v${entry.version} provides [${entry.capabilities.join(", ")}]`, { ...where, version: entry.version, listed: [...entry.capabilities] });
+  return { id, entry };
+}
+
 /** The repo ref a locked package is read from: the lock's recorded url, else the catalog's url for catalog ids, else the key for git refs. */
 export function packageRef(id, entry, catalog, remote) {
   const cat = isObject(catalog) ? (isObject(catalog.packages) && !("url" in catalog.packages) ? catalog.packages : catalog) : {};
@@ -538,6 +552,28 @@ async function enumerateSkills({ remote, ref, commit, dir, manifest, listing, mo
   return skills;
 }
 
+/** What a capability provides, by name (feature desktop-facts): its skills (enumerated exactly as a spawn
+ *  would), commands and hooks. `skills` is null when its declared skills cannot be listed (a spawn of it
+ *  would refuse; the listing does not). */
+export async function capabilityProvides({ ref, commit, dir, manifest, remote: injected, remoteOptions }) {
+  const remote = remoteOf({ remote: injected, remoteOptions });
+  const keys = (o) => (isObject(o) ? Object.keys(o).sort(byCodepoint) : []);
+  let skills;
+  try {
+    const missing = (raw, why, text) => fail("E_CAPABILITY_MISSING", text, { skill: raw, why });
+    skills = (await enumerateSkills({ remote, ref, commit, dir, manifest, moduleName: manifest.capability, missing })).map((x) => x.name).sort(byCodepoint);
+  } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) skills = null; else throw e; }
+  return { skills, commands: keys(manifest.commands), hooks: keys(manifest.hooks) };
+}
+
+/** The capability manifests of a locked package, read at its locked commit (feature desktop-facts). */
+export async function lockedPackageCapabilities(id, entry, { catalog = null, remote: injected, remoteOptions } = {}) {
+  const remote = remoteOf({ remote: injected, remoteOptions });
+  const ref = packageRef(id, entry, catalog, remote);
+  const { capabilities } = await readPackageManifests(remote, ref, entry.commit, entry.path, { id, version: entry.version, commit: entry.commit });
+  return { ref, capabilities };
+}
+
 /* ───────────────────────────── resolveSoul ────────────────────────────── */
 
 /**
@@ -568,9 +604,13 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
   const soul = { name: soulEntry.name, repoKey: soulEntry.repoKey, commit: soulEntry.commit ?? null, team, path: soulEntry.path ?? null };
 
   // Standalone: the soul's own repo only, workspace defaults unknown (decision 10).
+  // What the soul turned off (feature desktop-facts): its own `off` over a lower layer, and a `<slot>: none`
+  // that dropped a workspace default below. Provenance, like slotsFrom.
+  const offs = [];
   const declared = discovery?.standalone === true
-    ? composeCapabilities(null, { ...definition, capabilities: soulEntry.capabilities ?? definition.capabilities }, { labels })
-    : composeCapabilities(workspace, definition, { labels });
+    ? composeCapabilities(null, { ...definition, capabilities: soulEntry.capabilities ?? definition.capabilities }, { labels, offs })
+    : composeCapabilities(workspace, definition, { labels, offs });
+  const turnedOff = offs;
 
   const modules = [];
   const skills = [];
@@ -582,8 +622,12 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
   const emptied = new Set(SLOTS.filter((slot) => definition[slot] === "none"));
   for (const { name, from, via } of declared) {
     let module;
-    if (from === "package") {
-      const { id, entry } = lookupPackage(lock, name, via, soul, discovery?.standalone === true ? null : (isObject(workspace?.packages) ? workspace.packages : {}));
+    const ownPackage = from === "here" && typeof soulEntry.package === "string";
+    if (from === "package" || ownPackage) {
+      // `from: here` in a package soul is its own package, at the locked commit (§2.2).
+      const { id, entry } = ownPackage
+        ? ownPackageEntry(lock, name, via, soul, soulEntry.package)
+        : lookupPackage(lock, name, via, soul, discovery?.standalone === true ? null : (isObject(workspace?.packages) ? workspace.packages : {}));
       const ref = packageRef(id, entry, catalog, remote);
       const details = { capability: name, id, version: entry.version, commit: entry.commit, path: entry.path };
       const { capabilities } = await readPackageManifests(remote, ref, entry.commit, entry.path, details);
@@ -595,7 +639,7 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
       const cap = capabilities.find((c) => c.name === name);
       if (!cap) throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides it, but ${entry.path}/oats-package.json at ${short(entry.commit)} does not`, { ...details, listed: capabilities.map((c) => c.name) });
       const layer = layerOf(cap.manifest);
-      if (layer && emptied.has(layer) && via !== "soul") continue;
+      if (layer && emptied.has(layer) && via !== "soul") { turnedOff.push({ name, reason: "slot-none", slot: layer, overrides: fromOfVia(via) }); continue; }
       module = {
         name, from: { kind: "package", package: id, version: entry.version, commit: entry.commit, integrity: entry.integrity, repoKey: remote.parseRepoRef(ref).key },
         manifest: clone(cap.manifest), layer, private: cap.manifest.private === true, dir: cap.dir,
@@ -605,7 +649,7 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
     } else {
       const { row, cap } = lookupMember(discovery, soul, name, from, via, lock);
       const layer = layerOf(cap.manifest);
-      if (layer && emptied.has(layer) && via !== "soul") continue;
+      if (layer && emptied.has(layer) && via !== "soul") { turnedOff.push({ name, reason: "slot-none", slot: layer, overrides: fromOfVia(via) }); continue; }
       const ref = memberRef(discovery, remote, cap.repoKey);
       module = {
         name, from: { kind: "member", repoKey: cap.repoKey, commit: cap.commit ?? row.commit },
@@ -724,6 +768,16 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
     throw fail("E_CAPABILITY_INCOMPATIBLE", `${m.name} requires oats ${c.range}; this kernel is ${kernel} — ${remedy}`, { capability: m.name, range: c.range, kernel, from: m.from });
   }
 
+  // Capability-defined agents (`agents:` in a manifest) were removed in 0.29.0: an agent ships as a
+  // soul. A module still declaring them is refused before anything is composed from it.
+  for (const m of modules) {
+    if (m.manifest?.agents === undefined) continue;
+    const agents = Array.isArray(m.manifest.agents) ? m.manifest.agents.filter((a) => typeof a === "string") : [];
+    const how = "ship each agent as a soul — a package soul (`souls/<name>/` beside the package's capabilities, spawned as `oats spawn <package>/<name>`) or a member soul (`souls/<name>/` in a member) — and drop `agents:` from the manifest";
+    const remedy = m.from.kind === "package" ? `pin a release of ${m.from.package} without \`agents:\`, or ${how}` : `in ${m.from.repoKey}: ${how}`;
+    throw fail("E_CAPABILITY_AGENTS_REMOVED", `${m.name} declares \`agents:\` (${agents.join(", ") || "…"}); capability-defined agents were removed in OATS 0.29.0 — ${remedy}`, { capability: m.name, agents, from: m.from });
+  }
+
   // Compatibility floors (soul.compatibility) are constraints on PACKAGE versions.
   for (const [cap, range] of Object.entries(isObject(definition.compatibility) ? definition.compatibility : {})) {
     const m = modules.find((x) => x.name === cap);
@@ -755,9 +809,12 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
   // decision 3) is live messaging state, not composition: it stays out of both fingerprints too, so a
   // single-label soul's revision is what it was.
   // `slotsFrom` (where each filled slot's capability came from) is provenance, like payloadOrigins: outside
-  // both fingerprints, so the same capability reached another way is not a composition change.
+  // both fingerprints, so the same capability reached another way is not a composition change. So are
+  // `capabilitiesFrom` (the same per composed capability) and `turnedOff` (feature desktop-facts).
   const teams = teamsOf(discovery?.standalone === true ? null : workspace, labels);
-  return deepFreeze({ ...decl, payloads, payloadOrigins: origins, teams, slotsFrom, declRevision, payloadRevision, revision });
+  const capabilitiesFrom = Object.fromEntries(modules.map((m) => [m.name, fromOfVia(viaOf.get(m.name))]));
+  turnedOff.sort((a, b) => byCodepoint(a.name, b.name));
+  return deepFreeze({ ...decl, payloads, payloadOrigins: origins, teams, slotsFrom, capabilitiesFrom, turnedOff, declRevision, payloadRevision, revision });
 }
 
 /** Where a composed capability came from, as the Desktop names it (`layers.<layer>.from`): the soul's own
@@ -783,6 +840,11 @@ function assertSoulDiscovered(discovery, soulEntry) {
   const { name, repoKey } = soulEntry;
   const where = { soul: name, repoKey };
   const sameSoul = (s) => isObject(s) && s.name === name && s.repoKey === repoKey && (s.commit ?? null) === (soulEntry.commit ?? null);
+  if (typeof soulEntry.package === "string") {
+    // A package soul: the discovery listed it from the lock, at this package's locked commit.
+    if ((discovery?.packageSouls || []).some((s) => sameSoul(s) && s.package === soulEntry.package)) return;
+    throw fail("E_PACKAGE_MISSING", `soul ${soulEntry.package}/${name}: the discovery does not list it at ${short(soulEntry.commit)} — the soul entry is stale; run \`oats sync\` and discover again`, { ...where, package: soulEntry.package, reason: "stale" });
+  }
   if ((discovery?.external || []).some((e) => sameSoul(e?.soul))) return;
   const row = memberRow(discovery, repoKey);
   if (!row) throw fail("E_NOT_A_MEMBER", `soul ${name}: ${repoKey} is not a member of the workspace${discovery?.key ? ` ${discovery.key}` : ""} (nor an external soul) — a soul is spawned from a confirmed member or an external entry`, { ...where, reason: "not-listed" });