@awebai/oats 0.28.0 → 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, SOUL_ALIAS_SYMLINK } from "./packages.mjs";
+import { readLock, LOCK_FILE, SOUL_ALIAS_SYMLINK } from "./packages.mjs";
 import * as defaultRemote from "./remote.mjs";
 import { parseRepoRef } from "./remote.mjs";
 
@@ -143,7 +143,7 @@ export function disabledEntry(local, soulEntry) {
 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");
@@ -380,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). */
@@ -417,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 } = {}) {
@@ -495,115 +513,9 @@ export async function discoverOrStandalone(local, { lock, deployment, remoteOpti
 /** 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, { lock, 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.
@@ -622,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
@@ -681,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, { deployment, 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;
 }

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

package/lib/packages.mjs

@@ -416,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 };

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 });
@@ -547,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 ────────────────────────────── */
 
 /**
@@ -577,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 = [];
@@ -608,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,
@@ -618,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 },
@@ -737,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);
@@ -768,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