@awebai/oats 0.27.2 → 0.29.0

package/lib/instance-resolution.mjs

@@ -16,19 +16,19 @@
  *
  *  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, realpathSync, readlinkSync, copyFileSync, chmodSync } from "node:fs";
-import { join, resolve as resolvePath, dirname, basename, relative, isAbsolute, sep } from "node:path";
+import { existsSync, readFileSync, readdirSync, lstatSync, realpathSync } from "node:fs";
+import { join, resolve as resolvePath, dirname, relative, isAbsolute, sep } from "node:path";
 import { oatsError } from "./errors.mjs";
 import { loadLocal, discoverWorkspace, discoverRepo, standaloneRepo, observeWorkspace, observeSoulLabels } from "./workspace.mjs";
-import { resolveSoul, packageRef, memberRef, manifestDefaultsPayload, mergePayload, payloadOrigins, revisionOf, teamsOf, kernelCompatibility, RESOLUTION_API, SLOTS } from "./resolve.mjs";
-import { declaredSettings, settingValueProblems } from "./capability-contract.mjs";
+import { resolveSoul, teamsOf, kernelCompatibility } from "./resolve.mjs";
+import { declaredSettings } from "./capability-contract.mjs";
 import { materialize, MODULES_DIR, SKILLS_DIR } from "./materialize.mjs";
 import { fetchRemoteTree } from "./remote.mjs";
 import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync, symlinkSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { readLock, LOCK_FILE, readPackageManifests } from "./packages.mjs";
+import { readLock, LOCK_FILE, SOUL_ALIAS_SYMLINK } from "./packages.mjs";
 import * as defaultRemote from "./remote.mjs";
 import { parseRepoRef } from "./remote.mjs";
 
@@ -77,30 +77,58 @@ export function parseProviderFlags(pairs) {
   return JSON.parse(JSON.stringify(out));
 }
 
-/** Find the soul named `name` in a discovery: confirmed members first (by
- *  `repo/name` or bare name when unique), then external souls. */
+/** The qualified name of a discovered soul: `<package>/<soul>` for a package soul,
+ *  `<member name>/<soul>` for a member's, `<source repo name>/<soul>` for an external one. */
+export function qualifiedSoulName(entry) {
+  if (typeof entry?.package === "string") return `${entry.package}/${entry.name}`;
+  return `${memberNameOf(entry?.repoKey ?? "")}/${entry?.name}`;
+}
+
+/** Find the soul named `name` in a discovery: confirmed members, external souls and package
+ *  souls. A bare name must be unique across all three (else E_SOUL_AMBIGUOUS naming each
+ *  qualified form); `<repo>/<soul>` names a member (its key, a key suffix or its member name)
+ *  or an external source, `<package>/<soul>` a package soul. */
 export function findSoulEntry(discovery, name) {
   const [repoPart, soulPart] = name.includes("/") && !name.startsWith("/") ? [name.slice(0, name.lastIndexOf("/")), name.slice(name.lastIndexOf("/") + 1)] : [null, name];
   const hits = [];
   // A standalone view's one row is the repo's own (unconfirmed by definition — the
   // workspace could not be read); resolveSoul admits exactly that case.
   const standaloneOwn = discovery.standalone === true ? discovery.key : null;
+  const memberMatches = (key) => !repoPart || key === repoPart || key.endsWith(repoPart) || memberNameOf(key) === repoPart;
   for (const m of discovery.members || []) {
     if (!m.confirmed && m.key !== standaloneOwn) continue;
     for (const s of m.souls || []) {
-      if (s.name !== soulPart) continue;
-      if (repoPart && !m.key.endsWith(repoPart) && m.key !== repoPart) continue;
+      if (s.name !== soulPart || !memberMatches(m.key)) continue;
       hits.push({ ...s, repoKey: m.key, memberCommit: m.commit, external: false });
     }
   }
   for (const x of discovery.external || []) {
     if (x.soul?.name === soulPart && (!repoPart || (x.source && String(x.source).includes(repoPart)))) hits.push({ ...x.soul, repoKey: x.soul.repoKey ?? parseRepoRef(x.source.replace(/@.*$/, "")).key, commit: x.commit, external: true });
   }
-  if (hits.length === 0) throw err("E_SOUL_UNKNOWN", `no soul ${JSON.stringify(name)} among the confirmed members or external souls of this workspace`, { name, members: (discovery.members || []).filter((m) => m.confirmed).map((m) => m.key) });
-  if (hits.length > 1) throw err("E_SOUL_AMBIGUOUS", `soul ${JSON.stringify(name)} exists in ${hits.length} repos; name it as <repo>/${soulPart}`, { name, repos: hits.map((h) => h.repoKey) });
+  for (const s of discovery.packageSouls || []) {
+    if (s.name === soulPart && (!repoPart || repoPart === s.package)) hits.push({ ...s, external: false });
+  }
+  if (hits.length === 0) throw err("E_SOUL_UNKNOWN", `no soul ${JSON.stringify(name)} among the confirmed members, external souls or package souls of this workspace`, { name, members: (discovery.members || []).filter((m) => m.confirmed).map((m) => m.key), packages: [...new Set((discovery.packageSouls || []).map((s) => s.package))].sort() });
+  if (hits.length > 1) {
+    const qualified = hits.map(qualifiedSoulName);
+    throw err("E_SOUL_AMBIGUOUS", `soul ${JSON.stringify(name)} is ${hits.length} souls (${qualified.join(", ")}); name one of them`, { name, repos: hits.map((h) => h.repoKey), qualified });
+  }
+  if (Array.isArray(hits[0].collides)) throw err("E_SOUL_AMBIGUOUS", `package souls ${hits[0].collides.join(" and ")} would share the agent directory agents/${hits[0].agentName}/ — keep one of the packages in the workspace's packages:`, { name, agentDir: hits[0].agentName, qualified: hits[0].collides });
   return hits[0];
 }
 
+/** The agents-root directory of a discovered soul: a package soul's is `<package>--<soul>`
+ *  (packageSoulAgentName), every other soul's is its name. */
+export function agentDirOf(entry) { return typeof entry?.agentName === "string" ? entry.agentName : entry?.name; }
+
+/** `oats-local.yaml` `souls.disabled` (not run on this machine): an entry names a soul by its
+ *  bare name (every soul of that name) or its qualified name. → the matching entry or null. */
+export function disabledEntry(local, soulEntry) {
+  const list = Array.isArray(local?.souls?.disabled) ? local.souls.disabled : [];
+  const qualified = qualifiedSoulName(soulEntry);
+  return list.find((d) => d === soulEntry.name || d === qualified) ?? null;
+}
+
 /**
  * A home's LIVE eligible teams (teams contract 2026-09-25, decision 6). Teams are messaging
  * state, not frozen composition: the soul's labels are read from its repository NOW and each
@@ -115,8 +143,10 @@ export function findSoulEntry(discovery, name) {
 export async function liveTeams(home, meta, { remoteOptions, remote } = {}) {
   const recorded = (reason, error) => ({ teams: Array.isArray(meta?.teams) ? meta.teams : null, source: "recorded", reason, ...(error ? { error } : {}) });
   const soul = meta?.workspace?.soul;
-  // A capability agent's soul is its providing module's: no team labels, nothing to re-read.
+  // A home without a workspace soul record (a pre-0.29 capability agent's) has nothing to re-read.
   if (!soul || typeof soul.repoKey !== "string" || typeof meta.agent !== "string") return recorded("no-workspace-soul");
+  // A package soul's labels are pinned with the package: the spawn-time record is its answer.
+  if (soul.package && typeof soul.package === "object") return recorded("package-soul");
   const deployment = dirname(dirname(dirname(dirname(resolvePath(home)))));
   try {
     const found = loadLocal(deployment);
@@ -162,9 +192,13 @@ function swapSoulPointer(soulDir, target) {
 /** Fetch a prepared soul's source tree (soul.yaml + AGENTS.md, CLAUDE.md → AGENTS.md) into `dest`. */
 async function fetchSoulSource(prepared, dest) {
   const e = prepared.soulEntry;
-  const ref = e.repoKey.startsWith("local/") ? e.repoKey.slice("local/".length) : `git:${e.repoKey}`;
+  const ref = typeof e.ref === "string" ? e.ref : e.repoKey.startsWith("local/") ? e.repoKey.slice("local/".length) : `git:${e.repoKey}`;
   // A soul's CLAUDE.md → AGENTS.md alias is the one symlink a soul source may carry.
-  await fetchRemoteTree(ref, e.commit, e.path, dest, { ...(prepared.remoteOptions || {}), allowSymlinks: (p) => p === "CLAUDE.md" });
+  const { digest } = await fetchRemoteTree(ref, e.commit, e.path, dest, { ...(prepared.remoteOptions || {}), allowSymlinks: SOUL_ALIAS_SYMLINK });
+  // A package soul is what the lock recorded at sync: the same bytes at the locked commit.
+  if (typeof e.package === "string" && digest !== e.digest) {
+    throw err("E_PACKAGE_INTEGRITY", `package soul ${e.qualifiedName} v${e.version} @ ${String(e.commit).slice(0, 12)}: content digest ${digest} does not match the locked ${e.digest} — run \`oats sync\` (a lock that was edited: remove the entry and sync again)`, { package: e.package, soul: e.name, version: e.version, commit: e.commit, why: "soul-digest", locked: e.digest, observed: digest });
+  }
   if (!existsSync(join(dest, "soul.yaml")) || !existsSync(join(dest, "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(dest, "CLAUDE.md"))) symlinkSync("AGENTS.md", join(dest, "CLAUDE.md"));
 }
@@ -176,7 +210,7 @@ async function fetchSoulSource(prepared, dest) {
  *  that temporary copy; `fetched` says whether the preview had to fetch. */
 export async function previewWorkspaceSoul(prepared, agentsRoot) {
   const e = prepared.soulEntry;
-  const commitDir = join(agentsRoot, e.name, SOULS_DIR, commit12(e.commit));
+  const commitDir = join(agentsRoot, agentDirOf(e), SOULS_DIR, commit12(e.commit));
   if (existsSync(join(commitDir, "soul.yaml")) && existsSync(join(commitDir, "AGENTS.md"))) return { soulDir: realpathSync(commitDir), fetched: false, cleanup: () => {} };
   const tmp = realpathSync(mkdtempSync(join(tmpdir(), "oats-preview-soul-")));
   const cleanup = () => rmSync(tmp, { recursive: true, force: true });
@@ -202,7 +236,7 @@ export async function previewWorkspaceSoul(prepared, agentsRoot) {
  *  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 agentDir = join(agentsRoot, agentDirOf(e)); const soulDir = join(agentDir, "soul");
   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; } };
@@ -248,7 +282,8 @@ export async function ensureWorkspaceSoul(prepared, agentsRoot) {
   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");
+    const pkg = typeof e.package === "string" ? { package: e.package, version: e.version } : {};
+    writeFileSync(stamp, JSON.stringify({ repoKey: e.repoKey, commit: e.commit, path: e.path, ...pkg, fetchedAt: new Date().toISOString() }, null, 2) + "\n");
   }
   return target;
 }
@@ -345,18 +380,25 @@ export function resolveMemberClone(prepared, { explicit } = {}) {
   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;
+  return memberCloneOf(deployment, prepared?.local, key).path;
+}
+
+/** Steps 2–4 of resolveMemberClone for one member, naming the rule that found it (feature desktop-facts):
+ *  → { path, rule: "clones" | "convention" } | { path: null, rule: null }; a named or conventional path that
+ *  is not the member's clone is E_CLONE_MISMATCH, as for a spawn. */
+export function memberCloneOf(deployment, local, key) {
+  const clones = 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}` });
+      return { path: verifyMemberClone(path, key, { via: `oats-local.yaml clones: ${written}` }), rule: "clones" };
     }
   }
   const convention = conventionCloneDir(deployment, key);
-  if (!existsSync(convention)) return null;
-  return verifyMemberClone(convention, key, { via: "convention path" });
+  if (!existsSync(convention)) return { path: null, rule: null };
+  return { path: verifyMemberClone(convention, key, { via: "convention path" }), rule: "convention" };
 }
 
 /** The clone url of the soul's member as the workspace names it (for remedies). */
@@ -382,6 +424,17 @@ export function requireMemberClone(prepared, { explicit } = {}) {
   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>" } });
 }
 
+/** Would a spawn of this discovered soul be refused before it touches this machine (feature desktop-facts)?
+ *  The same checks prepareInstance makes — souls.disabled, then the soul's resolution (team conflicts, slot
+ *  conflicts, missing or private capabilities, compatibility …) — without spawning anything.
+ *  → { spawnable: true, problem: null } | { spawnable: false, problem: { code, message } } */
+export async function soulSpawnability(local, discovery, lock, soulEntry, { remoteOptions, remote } = {}) {
+  const disabled = disabledEntry(local, soulEntry);
+  if (disabled !== null) return { spawnable: false, problem: { code: "E_SOUL_DISABLED", message: `disabled on this machine (oats-local.yaml souls.disabled: ${disabled})` } };
+  try { await resolveSoul(discovery, soulEntry, { local, lock, spawn: {}, remoteOptions, remote }); return { spawnable: true, problem: null }; }
+  catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return { spawnable: false, problem: { code: e.code, message: e.message } }; throw e; }
+}
+
 /** The async half of a spawn: everything that touches the network. Returns a
  *  PREPARED object that `spawnInstance` consumes synchronously. */
 export async function prepareInstance(contextDir, soulName, { spawn = {}, remoteOptions, remote, local: localOverride, discovery: discoveryOverride } = {}) {
@@ -389,8 +442,10 @@ export async function prepareInstance(contextDir, soulName, { spawn = {}, remote
   const local = found.local;
   const deployment = found.path ? dirname(found.path) : resolvePath(contextDir);
   const lock = existsSync(join(deployment, LOCK_FILE)) ? readLock(deployment) : null;
-  const discovery = discoveryOverride ?? await discoverOrStandalone(local, { remoteOptions, remote });
+  const discovery = discoveryOverride ?? await discoverOrStandalone(local, { lock, remoteOptions, remote });
   const soulEntry = findSoulEntry(discovery, soulName);
+  const disabled = disabledEntry(local, soulEntry);
+  if (disabled !== null) throw err("E_SOUL_DISABLED", `soul ${qualifiedSoulName(soulEntry)} is disabled on this machine (oats-local.yaml souls.disabled: ${disabled}) — remove it from that list to spawn it here`, { name: soulEntry.name, qualifiedName: qualifiedSoulName(soulEntry), entry: disabled });
   const resolution = await resolveSoul(discovery, soulEntry, { local, lock, spawn, remoteOptions, remote });
   return { local, deployment, lock, discovery, soulEntry, resolution, remoteOptions, spawn };
 }
@@ -402,6 +457,11 @@ export async function prepareInstance(contextDir, soulName, { spawn = {}, remote
 const ACCESS_REASONS = new Set(["auth", "not-found"]);
 const isAccessFailure = (e) => e?.code === "E_REMOTE_UNREADABLE" && ACCESS_REASONS.has(e?.details?.reason ?? e?.provenance?.reason);
 
+/** The deployment's lock, or null when it has none (an unreadable lock is E_LOCK_SCHEMA). */
+export function deploymentLock(deployment) {
+  return existsSync(join(deployment, LOCK_FILE)) ? readLock(deployment) : null;
+}
+
 /** Decision 10: a standalone view is a MEMBER whose workspace cannot be read — the
  *  repo must declare that workspace (oats-membership.yaml). A lone repo with no
  *  backlink is not a member of anything and never becomes a capability source. */
@@ -424,21 +484,23 @@ function requireMembership(repo, ref) {
  *                        readable in this access context (auth / not-found).
  * A transient failure reading the host (network, timeout) is rethrown as-is.
  */
-export async function discoverOrStandalone(local, { remoteOptions, remote } = {}) {
+export async function discoverOrStandalone(local, { lock, deployment, remoteOptions, remote } = {}) {
   const ro = { remoteOptions, remote };
+  // Package souls are listed from the deployment's lock (the `lock` given, else `<deployment>/oats-lock.json`).
+  if (lock === undefined) lock = typeof deployment === "string" ? deploymentLock(deployment) : null;
   if (typeof local.standalone === "string" && local.standalone) {
     const repo = await discoverRepo(local.standalone, ro);
     requireMembership(repo, local.standalone);
     return { ...standaloneRepo(local.standalone, repo.commit, repo, { remote }), standaloneReason: "explicit" };
   }
-  try { return await discoverWorkspace(local.workspace, { local, ...ro }); }
+  try { return await discoverWorkspace(local.workspace, { local, lock, ...ro }); }
   catch (e) {
     if (e?.code !== "E_WORKSPACE_SCHEMA" || e?.details?.notAHost !== true) throw e;
     // The ref is a repository without oats-workspace.yaml: is it a member whose
     // workspace we cannot read? Then the standalone view is what the operator gets.
     const repo = await discoverRepo(local.workspace, ro);
     if (!repo.membership) throw e;
-    try { return await discoverWorkspace(repo.membership.workspace, { local, ...ro }); }
+    try { return await discoverWorkspace(repo.membership.workspace, { local, lock, ...ro }); }
     catch (inner) {
       // Only an ACCESS failure on the host means "standalone"; anything else
       // (network, timeout, a broken workspace file) is the caller's to see.
@@ -451,115 +513,9 @@ export async function discoverOrStandalone(local, { remoteOptions, remote } = {}
 /** Materialize a prepared resolution into `home`. Called by spawnInstance after
  *  the home directory exists and before the harness is launched. */
 export async function materializePrepared(prepared, home) {
-  const localModules = prepared.localModules || null;
-  // A capability agent's module copied from its anchor's verified copy (prepareCapabilityAgent):
-  // materialize still checks the copy's digest against the one the anchor recorded.
-  const fetch = localModules ? async (ref, commit, dir, dest, options) => {
-    const src = localModules[basename(dest)];
-    if (!src) return defaultRemote.fetchRemoteTree(ref, commit, dir, dest, options);
-    copyLocalModule(src, dest);
-    return { digest: defaultRemote.contentDigest(dest, { allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK }) };
-  } : undefined;
-  return materialize(prepared.resolution, home, { lock: prepared.lock, remoteOptions: prepared.remoteOptions, soulAgentsMd: prepared.soulAgentsMd, soulDir: prepared.soulDir, ...(fetch ? { fetch } : {}) });
-}
-/** Copy a materialized module tree (regular files, directories, the CLAUDE.md alias) — nothing else. */
-function copyLocalModule(src, dest, rel = "") {
-  mkdirSync(dest, { recursive: true });
-  for (const name of readdirSync(src).sort()) {
-    const from = join(src, name), to = join(dest, name), at = rel ? `${rel}/${name}` : name, st = lstatSync(from);
-    if (st.isSymbolicLink()) {
-      if (!defaultRemote.OATS_ALIAS_SYMLINK(at) || readlinkSync(from) !== "AGENTS.md") throw err("E_REMOTE_TREE_UNSAFE", `${from} is a symlink`, { path: from, why: "symlink" });
-      symlinkSync("AGENTS.md", to);
-    } else if (st.isDirectory()) copyLocalModule(from, to, at);
-    else if (st.isFile()) { copyFileSync(from, to); chmodSync(to, (st.mode & 0o111) ? 0o755 : 0o644); }
-    else throw err("E_REMOTE_TREE_UNSAFE", `${from} is not a regular file`, { path: from, why: "device" });
-  }
+  return materialize(prepared.resolution, home, { lock: prepared.lock, remoteOptions: prepared.remoteOptions, soulAgentsMd: prepared.soulAgentsMd, soulDir: prepared.soulDir });
 }
 
-/**
- * The prepared resolution of a CAPABILITY AGENT (a capability's `agents:` soul, e.g.
- * OKF's memory-harvest worker) — lead decision c3 Q1. It composes its providing
- * capability's module and NOTHING else: no workspace defaults, no knowledge,
- * messaging or tasks module, so no provider hook of any slot runs for it, and the
- * providing module's own hooks do not run either (a manifest has no way to declare
- * them for an agent). A knowledge-layer provider's inject is left out: a service
- * agent carries no memory protocol.
- *
- * The module comes from `agent._manifestSource` — the instance home whose module
- * copy declared the agent (the --parent/--relative-to anchor first): its recorded
- * `modules[<cap>]` (copied from that home's verified copy, pinned to the recorded
- * digest) and its recorded `providers[<cap>]` payload. Without such a home (the
- * source instance is gone), `pkg` — the deployment lock's package entry that
- * declares the agent (resolvePackageCapabilityAgent) — supplies the module, and the
- * payload is the manifest defaults ⊕ the workspace's messaging payload (for a
- * messaging-layer provider) ⊕ oats-local.yaml `settings.<cap>`.
- */
-export async function prepareCapabilityAgent(contextDir, agent, { discovery, pkg = null, remoteOptions, catalog = null, remote = defaultRemote } = {}) {
-  const found = loadLocal(contextDir);
-  const local = found.local;
-  const deployment = dirname(found.path);
-  const lock = existsSync(join(deployment, LOCK_FILE)) ? readLock(deployment) : null;
-  const view = discovery ?? await discoverOrStandalone(local, { remoteOptions });
-  const cap = agent.capability;
-  let module, payload, origins, localModules = null;
-  const anchor = pkg ? null : agent._manifestSource;
-  if (anchor) {
-    let meta;
-    try { meta = JSON.parse(readFileSync(join(anchor, "instance.json"), "utf8")); } catch { meta = null; }
-    const recorded = meta?.modules?.[cap];
-    const moduleDir = join(anchor, MODULES_DIR, cap);
-    if (!recorded?.from || typeof recorded.digest !== "string" || !existsSync(join(moduleDir, "oats.json"))) {
-      throw err("E_CAPABILITY_BROKEN", `capability agent ${agent.name}: ${anchor} does not record a verified copy of ${cap} (instance.json modules.${cap} with a digest, and ${join(MODULES_DIR, cap)}); respawn that instance`, { capability: cap, anchor });
-    }
-    const manifest = JSON.parse(readFileSync(join(moduleDir, "oats.json"), "utf8"));
-    module = { name: cap, from: { ...recorded.from }, manifest, layer: SLOTS.includes(manifest.layer) ? manifest.layer : null, private: manifest.private === true, digest: recorded.digest };
-    payload = meta.providers?.[cap] && typeof meta.providers[cap] === "object" ? JSON.parse(JSON.stringify(meta.providers[cap])) : {};
-    origins = Object.fromEntries(Object.keys(payload).map((k) => [`/${k.replace(/~/g, "~0").replace(/\//g, "~1")}`, { kind: "anchor", at: `${join(anchor, "instance.json")}#/providers/${cap}` }]));
-    localModules = { [cap]: moduleDir };
-  } else if (pkg) {
-    const manifest = pkg.manifest;
-    if (pkg.kind === "member") {
-      module = { name: cap, from: { kind: "member", repoKey: pkg.repoKey, commit: pkg.commit }, manifest, layer: SLOTS.includes(manifest.layer) ? manifest.layer : null, private: false, dir: pkg.capDir };
-    } else {
-      const entry = lock?.packages?.[pkg.package];
-      if (!entry) throw err("E_PACKAGE_MISSING", `capability agent ${agent.name}: package ${pkg.package} is not in ${LOCK_FILE}`, { capability: cap, package: pkg.package });
-      const ref = packageRef(pkg.package, entry, catalog, remote);
-      module = {
-        name: cap, from: { kind: "package", package: pkg.package, version: entry.version, commit: entry.commit, integrity: entry.integrity, repoKey: remote.parseRepoRef(ref).key },
-        manifest, layer: SLOTS.includes(manifest.layer) ? manifest.layer : null, private: manifest.private === true, dir: pkg.capDir,
-      };
-    }
-    const layers = [{ payload: manifestDefaultsPayload(manifest), origin: { kind: "manifest-default", at: "oats.json#/settings" } }];
-    if (module.layer === "messaging" && view?.workspace?.messaging && typeof view.workspace.messaging === "object") {
-      const { byTeam, ...base } = view.workspace.messaging;
-      layers.push({ payload: base, origin: { kind: "workspace", at: "oats-workspace.yaml#/messaging" } });
-    }
-    const host = local.settings?.[cap];
-    if (host && typeof host === "object") layers.push({ payload: host, origin: { kind: "host", at: `oats-local.yaml#/settings/${cap}` } });
-    payload = mergePayload(...layers.map((l) => l.payload));
-    origins = payloadOrigins(layers);
-  } else {
-    throw new TypeError("prepareCapabilityAgent: the agent names no source home, and no package entry was given");
-  }
-  // The capability's own kernel range, as resolveSoul checks every soul's modules.
-  const compat = kernelCompatibility({ ...module.manifest, capability: cap });
-  if (!compat.ok) throw err("E_CAPABILITY_INCOMPATIBLE", `capability agent ${agent.name}: ${cap} requires oats ${compat.range}; this kernel is ${compat.kernel}`, { capability: cap, range: compat.range, kernel: compat.kernel, from: module.from });
-  for (const { key, value, values } of settingValueProblems(module.manifest, payload)) {
-    throw err("E_WORKSPACE_SCHEMA", `${cap}: setting ${JSON.stringify(key)} is ${JSON.stringify(value)}, not one of ${values.map((v) => JSON.stringify(v)).join(", ")}`, { capability: cap, key, value, values, reason: "setting-value" });
-  }
-  const slots = { knowledge: null, messaging: null, tasks: null };
-  if (module.layer) slots[module.layer] = cap;
-  if (module.layer === "knowledge") module.inject = false;
-  const injects = module.inject !== false && typeof module.manifest.inject === "string" && module.manifest.inject ? [{ module: cap, path: module.manifest.inject }] : [];
-  const repoKey = module.from.repoKey ?? `package:${module.from.package}`;
-  const soulEntry = { name: agent.name, repoKey, commit: module.from.commit, team: null, path: null, capability: cap };
-  const soul = { name: agent.name, repoKey, commit: module.from.commit, team: null, path: null };
-  const decl = { resolutionApi: RESOLUTION_API, soul, modules: [module], slots, skills: [], injects };
-  const payloads = { [cap]: payload };
-  const declRevision = revisionOf(decl), payloadRevision = revisionOf(payloads);
-  const resolution = { ...decl, payloads, payloadOrigins: { [cap]: origins }, teams: [], declRevision, payloadRevision, revision: revisionOf({ declRevision, payloadRevision }) };
-  return { local, deployment, lock: anchor ? null : lock, discovery: view, soulEntry, resolution, remoteOptions, spawn: { providers: {} }, capabilityAgent: true, ...(localModules ? { localModules } : {}) };
-}
 
 /** Turn a Resolution's modules (already materialized under `home`) into the
  *  capability rows the kernel's hooks/environment/requirements code consumes.
@@ -578,7 +534,8 @@ export function toCapabilityRows(resolution, home) {
       level: home, origin: m.from.kind === "package" ? `package:${m.from.package}@${m.from.version}` : `member:${m.from.repoKey}@${m.from.commit}`,
       provenance: [m.from.kind === "package" ? `package ${m.from.package} v${m.from.version}` : `member ${m.from.repoKey} @ ${String(m.from.commit).slice(0, 12)}`],
       settings: { ...(resolution.payloads?.[m.name] && typeof resolution.payloads[m.name] === "object" ? resolution.payloads[m.name] : {}) },
-      skills, inject: m.inject !== false && inject && existsSync(inject) ? inject : undefined,
+      settingsOrigins: { ...(resolution.payloadOrigins?.[m.name] && typeof resolution.payloadOrigins[m.name] === "object" ? resolution.payloadOrigins[m.name] : {}) },
+      skills, inject: inject && existsSync(inject) ? inject : undefined,
       skillsDeclared: manifest.skills || [], injectDeclared: manifest.inject,
       // Member capabilities are trusted by membership (decision 2); package
       // capabilities by their declaration in the workspace's packages: (human
@@ -637,67 +594,3 @@ export const INSTANCE_SKILLS_DIR = SKILLS_DIR;
 export const INSTANCE_MODULES_DIR = MODULES_DIR;
 
 
-/**
- * Workspace model: a capability-defined agent (a package capability's `agents:`
- * soul — OKF's memory-harvest worker, say) resolves from the deployment's LOCK,
- * not from any instance: every locked package's capability manifests are read
- * over the remote; the first `agents/<name>` match has its capability tree fetched
- * into the deployment's module store `<deployment>/.oats/modules/<cap>@<commit>/`
- * (a per-commit cache shared by every such spawn) so the classic capability-agent
- * machinery can read it exactly as it reads a materialized instance module.
- * → { capability, dir, commit, package, version, manifest, rel } | undefined.
- */
-export async function resolvePackageCapabilityAgent(contextDir, name, { remoteOptions, catalog = null, discovery = undefined } = {}) {
-  if (typeof name !== "string" || !name) return undefined;
-  const found = loadLocal(contextDir);
-  const deployment = found.path ? dirname(found.path) : resolvePath(contextDir);
-  const remote = defaultRemote;
-  const view = discovery === undefined ? await discoverOrStandalone(found.local, { remoteOptions }) : discovery;
-  // A confirmed member's own (non-private) capability first: membership is its trust
-  // decision, exactly as for a soul's `from: <member>` module.
-  for (const row of view?.members || []) {
-    if (!row?.confirmed && view?.standalone !== true) continue;
-    for (const cap of row.capabilities || []) {
-      if (cap.private) continue;
-      const agents = Array.isArray(cap.manifest?.agents) ? cap.manifest.agents : [];
-      const rel = agents.find((a) => typeof a === "string" && basename(a) === name);
-      if (!rel) continue;
-      const commit = cap.commit ?? row.commit;
-      const store = join(deployment, MODULES_DIR);
-      const dir = join(store, `${cap.name}@${String(commit).slice(0, 12)}`);
-      if (!existsSync(join(dir, "oats.json"))) {
-        mkdirSync(store, { recursive: true });
-        await fetchRemoteTree(memberRef(view, remote, cap.repoKey), commit, cap.path, dir, { ...(remoteOptions || {}), allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK });
-      }
-      return { kind: "member", capability: cap.name, dir, capDir: cap.path, commit, repoKey: cap.repoKey, manifest: cap.manifest, rel };
-    }
-  }
-  if (!existsSync(join(deployment, LOCK_FILE))) return undefined;
-  const lock = readLock(deployment);
-  // Declaring a package in packages: is the trust decision: a workspace view
-  // admits only locked packages the workspace still declares (a stale lock entry
-  // is never a capability-agent source). A standalone view's lock holds only what
-  // a standalone sync wrote.
-  const declared = view?.standalone === true ? null : (view?.workspace?.packages && typeof view.workspace.packages === "object" ? view.workspace.packages : {});
-  for (const [id, entry] of Object.entries(lock.packages || {})) {
-    if (!entry || typeof entry !== "object") continue;
-    if (declared && !Object.hasOwn(declared, id)) continue;
-    let ref;
-    try { ref = packageRef(id, entry, catalog, remote); } catch { continue; }
-    let read;
-    try { read = await readPackageManifests(remote, ref, entry.commit, entry.path, { package: id }); } catch { continue; }
-    for (const cap of read.capabilities) {
-      const agents = Array.isArray(cap.manifest.agents) ? cap.manifest.agents : [];
-      const rel = agents.find((a) => typeof a === "string" && basename(a) === name);
-      if (!rel) continue;
-      const store = join(deployment, MODULES_DIR);
-      const dir = join(store, `${cap.name}@${String(entry.commit).slice(0, 12)}`);
-      if (!existsSync(join(dir, "oats.json"))) {
-        mkdirSync(store, { recursive: true });
-        await fetchRemoteTree(ref, entry.commit, cap.dir, dir, { ...(remoteOptions || {}), allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK });
-      }
-      return { kind: "package", capability: cap.name, dir, capDir: cap.dir, commit: entry.commit, package: id, version: entry.version, manifest: cap.manifest, rel };
-    }
-  }
-  return undefined;
-}

package/lib/materialize.mjs

@@ -240,11 +240,8 @@ function moduleSkills(resolution, module, moduleDir) {
   return rows;
 }
 
-/** The inject files a module contributes → [relative path]. resolution.injects rows first, else manifest.inject;
- * none for a module row marked `inject: false` (a capability agent's knowledge-layer provider carries no
- * memory protocol: lib/instance-resolution.mjs#prepareCapabilityAgent). */
+/** The inject files a module contributes → [relative path]. resolution.injects rows first, else manifest.inject. */
 function moduleInjects(resolution, module, moduleDir) {
-  if (module.inject === false) return [];
   const declared = (resolution.injects || []).filter((i) => i && i.module === module.name);
   const rels = declared.length
     ? declared.map((i) => modulePath(i.path, module.name, "inject"))
@@ -566,9 +563,10 @@ export function driftOf(instanceJson, discovery, { lock } = {}) {
       rows.push({ module: name, from: clone(from), recorded, current: null, status: "missing", reason: member ? (member.reason || "unconfirmed") : "unconfirmed" });
       continue;
     }
-    const present = Array.isArray(member.capabilities) && member.capabilities.some((c) => c && c.name === name);
-    if (!present) { rows.push({ module: name, from: clone(from), recorded, current: { commit: member.commit }, status: "missing", reason: "capability-absent" }); continue; }
-    rows.push({ module: name, from: clone(from), recorded, current: { commit: member.commit }, status: member.commit === commit ? "current" : "moved" });
+    const cap = Array.isArray(member.capabilities) ? member.capabilities.find((c) => c && c.name === name) : null;
+    if (!cap) { rows.push({ module: name, from: clone(from), recorded, current: { commit: member.commit }, status: "missing", reason: "capability-absent" }); continue; }
+    // `version` (feature desktop-facts): the member capability's manifest version now, beside the commit.
+    rows.push({ module: name, from: clone(from), recorded, current: { commit: member.commit, version: typeof cap.manifest?.version === "string" ? cap.manifest.version : null }, status: member.commit === commit ? "current" : "moved" });
   }
   return rows;
 }
@@ -584,12 +582,25 @@ export function driftOf(instanceJson, discovery, { lock } = {}) {
  * (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).
+ * A PACKAGE soul (`workspace.soul.package`) is compared with the discovery's package souls: the
+ * pin moved → "moved"; the package no longer locked/declared → "missing" ("package-absent"); the
+ * soul no longer shipped by the package → "missing" ("soul-absent").
  */
 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;
+  if (plainObject(soul.package) && typeof soul.package.id === "string") {
+    // A package soul: "moved" means the package pin moved (another version/commit is locked now).
+    const pkg = { package: soul.package.id, version: soul.package.version ?? null };
+    const soulName = typeof soul.name === "string" ? soul.name : name;
+    const base = { name: soulName, repoKey: soul.repoKey, commit, team: soul.team ?? null, ...pkg };
+    const listed = Array.isArray(discovery?.packageSouls) ? discovery.packageSouls.filter((s) => s && s.package === soul.package.id) : [];
+    const now = listed.find((s) => s.name === soulName) || null;
+    if (!now) return { ...base, current: null, status: "missing", reason: listed.length ? "soul-absent" : "package-absent" };
+    return { ...base, current: { commit: now.commit, version: now.version }, status: now.commit === commit ? "current" : "moved" };
+  }
   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";

package/lib/operator-dispatch.mjs

@@ -6,8 +6,7 @@
  *  `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
+ *  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