@awebai/oats 0.25.9 → 0.26.0

package/lib/instance-resolution.mjs

@@ -4,7 +4,7 @@
  *  A spawn is: read this machine's `oats-local.yaml` → discover the workspace over
  *  its Git remotes in the operator's access context → find the soul among the
  *  confirmed members (or external souls) → resolve every capability by `from:`
- *  (member = latest state, package = the locked, approved version) → materialize
+ *  (member = latest state, package = the locked version) → materialize
  *  each capability WHOLE into the new home (`.oats/modules/`, `.agents/skills/`) →
  *  compose AGENTS.md → launch the harness normally.
  *
@@ -16,14 +16,16 @@
  *
  *  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 } from "node:fs";
+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 { oatsError } from "./errors.mjs";
-import { loadLocal, discoverWorkspace, discoverRepo, standaloneRepo } from "./workspace.mjs";
-import { resolveSoul, packageRef } from "./resolve.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 { materialize, MODULES_DIR, SKILLS_DIR } from "./materialize.mjs";
 import { fetchRemoteTree } from "./remote.mjs";
-import { mkdirSync, renameSync, rmSync, writeFileSync, symlinkSync, statSync } from "node:fs";
+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";
@@ -99,10 +101,39 @@ export function findSoulEntry(discovery, name) {
   return hits[0];
 }
 
+/**
+ * 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
+ * label's payload from the workspace's current `messaging`. The home's modules and skills are
+ * untouched. No workspace discovery: exactly two repository reads — the workspace host at its
+ * current commit (observeWorkspace) and the soul's own repo (observeSoulLabels).
+ * → { teams, source: "live" } — or, when that cannot answer (the host or the soul's repo is
+ *   unreachable, the soul is no longer listed, a standalone deployment), the spawn-time record:
+ *   { teams: <record, or null when none>, source: "recorded", reason }.
+ * `source` travels as OATS_TEAMS_SOURCE: a provider leaves a joined team only on a `live` answer.
+ */
+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.
+  if (!soul || typeof soul.repoKey !== "string" || typeof meta.agent !== "string") return recorded("no-workspace-soul");
+  const deployment = dirname(dirname(dirname(dirname(resolvePath(home)))));
+  try {
+    const found = loadLocal(deployment);
+    if (!found.path || resolvePath(dirname(found.path)) !== resolvePath(deployment)) return recorded("no-deployment");
+    if (typeof found.local.standalone === "string" && found.local.standalone) return recorded("standalone");
+    const wsObs = await observeWorkspace(found.local.workspace, { remoteOptions, remote });
+    const labels = await observeSoulLabels(wsObs, { name: meta.agent, repoKey: soul.repoKey }, { remoteOptions, remote });
+    if (labels === null) return recorded("soul-not-listed");
+    return { teams: teamsOf(wsObs.workspace, labels), source: "live" };
+  } catch (e) { return recorded("unreadable", { code: e?.code || "E_REMOTE_UNREADABLE", message: e?.message ?? String(e) }); }
+}
+
 /** The per-commit soul cache under an agent directory: `<agentDir>/souls/<commit12>/`.
  *  Each entry is IMMUTABLE once written (fetched to staging, renamed in) and is never
- *  removed by the kernel — a running instance's `<home>/soul` links straight at its
- *  own commit's directory (realpath), so nothing can change under it. */
+ *  removed by the kernel — a running instance records its own commit's directory
+ *  (realpath, instance.json `soulDir`, handed to hooks as OATS_SOUL), so nothing can
+ *  change under it. */
 export const SOULS_DIR = "souls";
 export const SOUL_SOURCE_STAMP = ".oats-soul-source.json";
 const commit12 = (c) => String(c || "").slice(0, 12) || "unknown";
@@ -128,13 +159,40 @@ function swapSoulPointer(soulDir, target) {
   } catch (x) { try { rmSync(tmp, { force: true }); } catch { /* nothing */ } throw x; }
 }
 
+/** 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}`;
+  // 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" });
+  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"));
+}
+
+/** A preview's soul source. A preview writes NOTHING in the deployment (K6b), so it
+ *  never populates the per-commit cache or moves the `soul` pointer: it reads the
+ *  cache entry for the prepared commit when one is already complete, else fetches
+ *  the source into a temporary directory outside the deployment. `cleanup` removes
+ *  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));
+  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 });
+  try { await fetchSoulSource(prepared, join(tmp, "soul")); }
+  catch (x) { cleanup(); throw x; }
+  return { soulDir: join(tmp, "soul"), fetched: true, cleanup };
+}
+
 /** Materialize a workspace soul's SOURCE (soul.yaml, AGENTS.md, skills/…) into the
  *  per-commit cache `<agentsRoot>/<name>/souls/<commit12>/` and point the classic
  *  `<agentsRoot>/<name>/soul` at it (a SYMLINK, swapped atomically), so the classic
  *  spawn skeleton, findAgent, doctor … keep reading "current" from the usual place
  *  while every spawned home links its OWN commit's directory (decision 7: an
- *  instance never changes under itself — a preview or a later spawn may fetch a new
- *  commit and move the pointer, but no directory an instance links is ever touched).
+ *  instance never changes under itself — a later spawn may fetch a new commit and
+ *  move the pointer, but no directory an instance links is ever touched; a preview
+ *  never calls this, see previewWorkspaceSoul).
  *
  *  Idempotent per (repo, commit): an existing complete entry is reused (never
  *  refetched, never rewritten); an entry that lost its soul.yaml is moved aside and
@@ -173,13 +231,9 @@ export async function ensureWorkspaceSoul(prepared, agentsRoot) {
     renameSync(commitDir, `${commitDir}.damaged-${process.pid}-${randomBytes(4).toString("hex")}`);
   }
   if (!complete) {
-    const ref = e.repoKey.startsWith("local/") ? e.repoKey.slice("local/".length) : `git:${e.repoKey}`;
     const staging = join(soulsDir, `.soul-staging-${process.pid}-${randomBytes(4).toString("hex")}`);
     try {
-      // A soul's CLAUDE.md → AGENTS.md alias is the one symlink a soul source may carry.
-      await fetchRemoteTree(ref, e.commit, e.path, staging, { ...(prepared.remoteOptions || {}), allowSymlinks: (p) => p === "CLAUDE.md" });
-      if (!existsSync(join(staging, "soul.yaml")) || !existsSync(join(staging, "AGENTS.md"))) throw err("E_SOUL_INCOMPLETE", `soul ${e.name} at ${e.repoKey}@${String(e.commit).slice(0, 12)} lacks soul.yaml or AGENTS.md`, { repoKey: e.repoKey, commit: e.commit, path: e.path });
-      if (!existsSync(join(staging, "CLAUDE.md"))) symlinkSync("AGENTS.md", join(staging, "CLAUDE.md"));
+      await fetchSoulSource(prepared, staging);
       try { renameSync(staging, commitDir); }
       catch (x) {
         // Lost a race with a concurrent fetch of the same commit: theirs is the same bytes.
@@ -397,7 +451,114 @@ 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) {
-  return materialize(prepared.resolution, home, { lock: prepared.lock, remoteOptions: prepared.remoteOptions, soulAgentsMd: prepared.soulAgentsMd, soulDir: prepared.soulDir });
+  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" });
+  }
+}
+
+/**
+ * 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
@@ -417,14 +578,14 @@ 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: inject && existsSync(inject) ? inject : undefined,
+      skills, inject: m.inject !== false && inject && existsSync(inject) ? inject : undefined,
       skillsDeclared: manifest.skills || [], injectDeclared: manifest.inject,
       // Member capabilities are trusted by membership (decision 2); package
-      // capabilities were approved per version at sync (E_PACKAGE_UNAPPROVED
-      // otherwise, so reaching here means approved).
+      // capabilities by their declaration in the workspace's packages: (human
+      // decision 2026-09-24: declaring a package is the trust decision).
       hooks: hookCommandsOf(manifest, dir), requiredHooks: requiredHooksOf(manifest),
       environment: [...(manifest.environment || [])], environmentNamespaces: [...(manifest.environmentNamespaces || [])],
-      missingRequires: [], compatibility: { ok: true }, trust: { trusted: true, reason: m.from.kind === "package" ? "approved package version" : "workspace member" },
+      missingRequires: [], compatibility: kernelCompatibility({ ...manifest, capability: m.name }), trust: { trusted: true, reason: m.from.kind === "package" ? "declared workspace package" : "workspace member" },
       executable: !!manifest.commands && Object.keys(manifest.commands).length > 0,
       retirement: manifest.retirement,
       dir, from: m.from, _scope: 0,
@@ -466,7 +627,7 @@ export function modulesPreview(resolution, agentsRoot, soulName) {
   return resolution.modules.map((m) => {
     const prev = previous?.modules?.[m.name];
     const changedSince = !previous ? null : !prev ? { instance: previous.name, was: null } : (prev.commit !== m.from.commit ? { instance: previous.name, was: prev.commit } : false);
-    return { name: m.name, from: m.from, layer: m.manifest.layer ?? null, private: !!m.private, changedSince };
+    return { name: m.name, from: m.from, layer: m.manifest.layer ?? null, private: !!m.private, declares: declaredSettings(m.manifest), changedSince };
   });
 }
 
@@ -479,23 +640,48 @@ 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 approved package's capability manifests are read
+ * 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.
- * Unapproved packages are skipped (they could not have materialized anywhere).
  */
-export async function resolvePackageCapabilityAgent(contextDir, name, { remoteOptions, catalog = null } = {}) {
+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);
-  const remote = defaultRemote;
+  // 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" || !entry.approved || typeof entry.approved.executables !== "string") continue;
+    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;
@@ -510,7 +696,7 @@ export async function resolvePackageCapabilityAgent(contextDir, name, { remoteOp
         mkdirSync(store, { recursive: true });
         await fetchRemoteTree(ref, entry.commit, cap.dir, dir, { ...(remoteOptions || {}), allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK });
       }
-      return { capability: cap.name, dir, commit: entry.commit, package: id, version: entry.version, manifest: cap.manifest, rel };
+      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/instruction-composition.mjs

@@ -1,7 +1,5 @@
 /** Formatting shared by current preparation and retained instruction projection.
  * Selection/order is supplied by the caller; this module never discovers config. */
-import { readPortableBytes } from "./portable-files.mjs";
-import { oatsError } from "./errors.mjs";
 
 export function renderInstructionText(body, blocks) {
   let text = body.replace(/\n*$/, "\n");
@@ -11,21 +9,3 @@ export function renderInstructionText(body, blocks) {
   return text;
 }
 
-/** Input is the result of exact record verification, not a current config or
- * a mutable soul directory. All paths come from its verified resource inventory. */
-export function composeCapturedInstructions(verified) {
-  const composition = verified.record.dispatch.composition;
-  if (!composition) throw oatsError("resolution-incomplete", "captured instruction composition is absent");
-  const read = (key) => {
-    const file = verified.resources.get(key);
-    if (!file) throw oatsError("resolution-incomplete", "captured instruction resource is absent");
-    let content;
-    try { content = new TextDecoder("utf-8", { fatal: true }).decode(readPortableBytes(file)); }
-    catch (cause) { throw oatsError("invalid-resolution", "captured instructions are not readable UTF-8", { cause }); }
-    return { file, content };
-  };
-  const body = read(composition.body);
-  const blocks = composition.blocks.map(({ source, resource }) => ({ source, ...read(resource) }));
-  const skills = composition.skills.map(({ name, resource }) => ({ name, path: verified.resources.get(resource) }));
-  return { text: renderInstructionText(body.content, blocks), blocks, skills, omissions: composition.omissions };
-}

package/lib/materialize.mjs

@@ -1,7 +1,7 @@
 /** lib/materialize.mjs — copy whole, compose, record (workspace model v2, module contract §5).
  *
  * Supersedes the module/skill assembly in core.mjs spawn (`prepared` copies, symlinked
- * skill sets, ambient exclusion) and capability-artifacts.mjs.
+ * skill sets, ambient exclusion) and the captured path's artifact store.
  *
  * materialize(resolution, home, options)
  *   For every module of the resolution: fetch its capability directory whole into
@@ -240,8 +240,11 @@ function moduleSkills(resolution, module, moduleDir) {
   return rows;
 }
 
-/** The inject files a module contributes → [relative path]. resolution.injects rows first, else manifest.inject. */
+/** 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). */
 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"))
@@ -280,7 +283,6 @@ function soulBody(home, options) {
   if (typeof options.soulAgentsMd === "string") return { text: options.soulAgentsMd, file: null };
   const candidates = [];
   if (typeof options.soulDir === "string") candidates.push(join(resolve(options.soulDir), "AGENTS.md"));
-  candidates.push(join(home, "soul", "AGENTS.md"));
   for (const file of candidates) {
     try { if (statSync(file).isFile()) return { text: readFileSync(file, "utf8"), file }; } catch {}
   }
@@ -309,7 +311,7 @@ function ensureOatsDir(home) {
  *   remoteOptions     threaded into fetch (cacheDir, exec, …)
  *   lock              oats-lock.json v3 object: package repo/path/commit for from.kind === "package"
  *   catalog           { <id>: { url, ref, path } } for lock entries whose source is "catalog:<id>"
- *   soulAgentsMd      the soul's canonical AGENTS.md text (else read from options.soulDir or <home>/soul/AGENTS.md)
+ *   soulAgentsMd      the soul's canonical AGENTS.md text (else read from options.soulDir)
  *   blocks            pre-rendered blocks [{ source, file, content }] placed BEFORE the capability injects
  *                     (the kernel's own kernel:… and work-mode:… blocks, composed by core.mjs)
  *   now()             ISO timestamp source (tests)

package/lib/operator-dispatch.mjs

@@ -12,13 +12,13 @@
  *
  *  Never "the newest instance's copy" (an instance is not an authority for the
  *  deployment) and never an unlocked cache read: trust is exactly spawn's —
- *  members by membership, packages by the lock's approval (`prepareInstance`
- *  already refuses E_PACKAGE_UNAPPROVED). A module in the Resolution IS active.
+ *  members by membership, packages by their declaration in the workspace's
+ *  packages:. A module in the Resolution IS active.
  *
  *  `--soul` is required: without a soul there is no Resolution to answer from
  *  (E_BAD_ARGS naming --soul). Nothing here reads oats-config.yaml. */
-import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
-import { dirname, join, resolve as resolvePath } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve as resolvePath } from "node:path";
 import { randomBytes } from "node:crypto";
 import { oatsError } from "./errors.mjs";
 import { loadLocal } from "./workspace.mjs";
@@ -58,25 +58,45 @@ export function moduleStoreDir(deployment, module) {
 }
 
 /** Ensure the module's capability tree is in the deployment store; returns its dir.
- *  A tree already there (oats.json present) is reused — the commit is in the name,
- *  so it cannot be stale. The fetch lands in a sibling staging dir and is renamed
- *  into place, so a failed or interrupted fetch never leaves a half tree that a
- *  later call would trust. */
+ *  Nothing that differs from the locked commit is ever handed out to run:
+ *  - a fetch's content digest must match what the fetch read at the commit (and
+ *    the resolution's `module.digest` when it pins one), else E_PACKAGE_INTEGRITY;
+ *    the verified digest is recorded beside the tree (`.<cap>@<commit12>.digest`,
+ *    in the same operator-owned deployment as oats-lock.json);
+ *  - a tree already there is reused only while its content still digests to that
+ *    record (the commit in the name does not stop a local edit); a drifted tree,
+ *    or one with no record, is removed and fetched again.
+ *  The fetch lands in a sibling staging dir and is renamed into place, so a failed
+ *  or interrupted fetch never leaves a half tree that a later call would trust. */
 export async function ensureModuleTree(deployment, module, lock, { catalog = null, remote = defaultRemote, remoteOptions, fetch = defaultRemote.fetchRemoteTree } = {}) {
   const store = join(deployment, MODULES_DIR);
   const dir = moduleStoreDir(deployment, module);
-  if (existsSync(join(dir, "oats.json"))) return dir;
+  const record = join(store, `.${basename(dir)}.digest`);
+  const digestOf = (tree) => { try { return (remote.contentDigest ?? defaultRemote.contentDigest)(tree, { allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK }); } catch { return null; } };
+  const expected = () => { if (module.digest) return module.digest; try { return readFileSync(record, "utf8").trim() || null; } catch { return null; } };
+  const verified = (tree) => { const want = expected(); return !!want && digestOf(tree) === want; };
+  if (existsSync(join(dir, "oats.json"))) {
+    if (verified(dir)) return dir;
+    rmSync(dir, { recursive: true, force: true }); // drifted or unrecorded: re-materialize, never run it
+  }
   const ref = moduleRef(module, lock, { catalog, remote });
   if (typeof module.dir !== "string" || !module.dir) throw err("E_CAPABILITY_BROKEN", `module ${module.name}: resolution records no capability directory`, { module: module.name });
   mkdirSync(store, { recursive: true });
   const staging = join(store, `.staging-${module.name}-${process.pid}-${randomBytes(4).toString("hex")}`);
   try {
-    await fetch(ref, module.from.commit, module.dir, staging, { ...(remoteOptions || {}), allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK });
+    const fetched = await fetch(ref, module.from.commit, module.dir, staging, { ...(remoteOptions || {}), allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK });
     if (!existsSync(join(staging, "oats.json"))) throw err("E_CAPABILITY_BROKEN", `module ${module.name}: ${module.dir} at ${String(module.from.commit).slice(0, 12)} has no oats.json`, { module: module.name, dir: module.dir, commit: module.from.commit });
-    // A concurrent call may have won; its tree is the same commit — keep it.
-    if (existsSync(join(dir, "oats.json"))) { rmSync(staging, { recursive: true, force: true }); return dir; }
+    const digest = digestOf(staging);
+    const reported = fetched && typeof fetched.digest === "string" ? fetched.digest : null;
+    if (!digest || (reported && reported !== digest) || (module.digest && module.digest !== digest)) {
+      throw err("E_PACKAGE_INTEGRITY", `module ${module.name}: ${module.dir} at ${String(module.from.commit).slice(0, 12)} digests ${digest ?? "unreadably"}, not ${module.digest ?? reported}`,
+        { module: module.name, commit: module.from.commit, expected: module.digest ?? reported, actual: digest, why: "module-store" });
+    }
+    // A concurrent call may have won; its tree is the same commit — keep it if it matches.
+    if (existsSync(join(dir, "oats.json")) && digestOf(dir) === digest) { rmSync(staging, { recursive: true, force: true }); writeFileSync(record, `${digest}\n`); return dir; }
     if (existsSync(dir)) rmSync(dir, { recursive: true, force: true }); // a half tree from an interrupted direct write
     renameSync(staging, dir);
+    writeFileSync(record, `${digest}\n`);
     return dir;
   } catch (x) { try { rmSync(staging, { recursive: true, force: true }); } catch { /* nothing */ } throw x; }
 }
@@ -93,7 +113,7 @@ export async function ensureModuleTree(deployment, module, lock, { catalog = nul
  *     ensureTree(): Promise<dir> }   — or null when no module of the soul's
  *     resolution claims the namespace (the caller answers E_UNKNOWN_COMMAND).
  * Two modules claiming one namespace → E_DUPLICATE_NAMESPACE. Everything
- * prepareInstance can throw (E_SOUL_UNKNOWN, E_PACKAGE_UNAPPROVED,
+ * prepareInstance can throw (E_SOUL_UNKNOWN,
  * E_REMOTE_UNREADABLE, …) propagates untouched.
  */
 export async function resolveOperatorDispatch(contextDir, namespace, soulName, { remoteOptions, remote, catalog = null, fetch, prepare = prepareInstance } = {}) {