@awebai/oats 0.27.2 → 0.28.0

package/lib/core.mjs

@@ -1501,6 +1501,11 @@ export function stableSoulId({ soulId, home, soulDir, agentName } = {}) {
   return "";
 }
 export const workspaceSoulId = (repoKey, name) => `${repoKey}#${name}`;
+/** A triggered instance's event, inside its home's .oats/ (lib/triggers.mjs). */
+export const TRIGGER_EVENT_FILE = "trigger-event.json";
+/** A prepared soul entry's id: `<repoKey>#<name>` for a member or external soul, `package:<id>#<name>`
+ *  for a package soul (stable across the package's versions and independent of its repo). */
+const preparedSoulIdOf = (entry) => workspaceSoulId(typeof entry.package === "string" ? `package:${entry.package}` : entry.repoKey, entry.name);
 /** The soul directory an instance incarnates, as spawn recorded it (instance.json
  *  `soulDir`): a workspace soul's per-commit copy (agents/<soul>/souls/<commit12>) or
  *  the read-only soul inside a capability package. It is what every classic
@@ -1672,7 +1677,10 @@ function readSoul(agentDir, soulDir = soulOf(agentDir)) {
   }
   const soul = soulHarnessField(stripInternalAnnotations(parsed), p);
   soul._dir = agentDir;
-  soul.name = soul.name || basename(agentDir);
+  // A package soul homes at <package>--<soul> (lib/workspace.mjs packageSoulAgentName): that
+  // directory, not the soul.yaml name, is its agent name, so its instances never share a
+  // member soul's name or roster row.
+  soul.name = basename(agentDir).includes("--") ? basename(agentDir) : (soul.name || basename(agentDir));
   return soul;
 }
 export function findAgent(root, name) {
@@ -3270,14 +3278,22 @@ function* spawnBody(root, agent, o = {}) {
   // Capability lifecycle hooks (spawn) — the knowledge integration scaffolds instance
   // memory (STATE.md/log.md/notes/ are OKF conventions, not kernel ones); the
   // messaging integration mints the comms identity. Kernel stays memory-agnostic.
-  const preparedSoulId = o.prepared ? workspaceSoulId(o.prepared.soulEntry.repoKey, o.prepared.soulEntry.name) : undefined;
+  const preparedSoulId = o.prepared ? preparedSoulIdOf(o.prepared.soulEntry) : undefined;
+  // A trigger's event (lib/triggers.mjs): a private copy in the home, named to hooks and the harness
+  // as OATS_TRIGGER_EVENT_FILE. Its PR title/body are never in the task: the soul reads them from here.
+  let triggerEventFile = null;
+  if (o.triggerEvent && typeof o.triggerEvent === "object") {
+    triggerEventFile = join(home, ".oats", TRIGGER_EVENT_FILE);
+    mkdirSync(dirname(triggerEventFile), { recursive: true });
+    writeFileSync(triggerEventFile, JSON.stringify(o.triggerEvent, null, 2) + "\n", { mode: 0o600 });
+  }
   // Hooks read the soul the HOME links (the per-commit directory for a workspace
   // soul), never the swappable agents/<name>/soul pointer: a provider that pins a
   // path must pin this instance's content, and OATS_SOUL_ID is what it keys on.
   const hookRes = runLifecycleHooks("spawn", {
     home, instance, agentName: agent.name, soulDir: homeSoulTarget, soulId: preparedSoulId, contextDir: repoAbs,
     workspaceDir: workspaceOf(root), rootDir: root, resolved: resolvedCfg,
-    extraEnv: { OATS_TASK: task, OATS_REPO: repoAbs, OATS_BRANCH: branch || "", OATS_WORK: work, OATS_HARNESS: harness, OATS_RUNTIME: harness, OATS_KIND: agent.kind || "persistent" },
+    extraEnv: { OATS_TASK: task, OATS_REPO: repoAbs, OATS_BRANCH: branch || "", OATS_WORK: work, OATS_HARNESS: harness, OATS_RUNTIME: harness, OATS_KIND: agent.kind || "persistent", ...(triggerEventFile ? { OATS_TRIGGER_EVENT_FILE: triggerEventFile } : {}) },
   });
   warnings.push(...hookRes.warnings);
   // Which capability hooks RAN (in order) and how each ended — recorded on the
@@ -3498,6 +3514,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       hooks: { launch: { ...hookRes.launch }, env: { ...hookRes.env }, contributions: hookRes.contributions || [] },
       prompt: LAUNCH_PROMPT,
     };
+    if (triggerEventFile) recipe.env.OATS_TRIGGER_EVENT_FILE = triggerEventFile;
     const cmdline = renderLaunchRecipe(recipe, { home, instance });
 
     // Module skills as materialize landed them (.agents/skills/<module>/<skill>/),
@@ -3514,6 +3531,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       relativeTo: relation ? relativeTo : undefined,
       spawnOrigin: relation || (parentInstance && parentInstance !== instance) ? "instance" : "operator",
       policy: { childSpawns: ownChildPolicy },
+      ...(triggerEventFile ? { trigger: { id: o.triggerEvent.trigger, key: o.triggerEvent.key ?? null, source: o.triggerEvent.source, repo: o.triggerEvent.repo, number: o.triggerEvent.number, url: o.triggerEvent.url ?? null, event: o.triggerEvent.event, headSha: o.triggerEvent.headSha ?? null, observedAt: o.triggerEvent.observedAt ?? null, eventFile: triggerEventFile } } : {}),
       // K6c: a decision-bound spawn records what bound it, so a retry with the
       // same key replays this receipt instead of spawning again.
       // The FULL bound decision (placement + effective), exactly as the fence
@@ -3582,7 +3600,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       try { const prior = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); if (prior.modules) meta.modules = prior.modules; if (prior.providers) meta.providers = prior.providers; } catch { /* materialize wrote it; absent means nothing to carry */ }
       // M5/3a: the workspace's name and the deployment directory are recorded, so a home
       // answers them (inspect/operation run --home, OATS_WORKSPACE_NAME) without discovery.
-      meta.workspace = { key: o.prepared.discovery?.key ?? null, name: o.prepared.discovery?.workspace?.name ?? null, deployment: o.prepared.deployment ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { id: workspaceSoulId(o.prepared.soulEntry.repoKey, o.prepared.soulEntry.name), repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, team: o.prepared.soulEntry.team ?? null, labels: [...(o.prepared.soulEntry.labels ?? (o.prepared.soulEntry.team ? [o.prepared.soulEntry.team] : []))] }, layers: layerRows(o.prepared.resolution) };
+      meta.workspace = { key: o.prepared.discovery?.key ?? null, name: o.prepared.discovery?.workspace?.name ?? null, deployment: o.prepared.deployment ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { id: preparedSoulIdOf(o.prepared.soulEntry), repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, team: o.prepared.soulEntry.team ?? null, labels: [...(o.prepared.soulEntry.labels ?? (o.prepared.soulEntry.team ? [o.prepared.soulEntry.team] : []))], ...(typeof o.prepared.soulEntry.package === "string" ? { name: o.prepared.soulEntry.name, qualifiedName: o.prepared.soulEntry.qualifiedName, package: { id: o.prepared.soulEntry.package, version: o.prepared.soulEntry.version, commit: o.prepared.soulEntry.commit, digest: o.prepared.soulEntry.digest, path: o.prepared.soulEntry.path } } : {}) }, layers: layerRows(o.prepared.resolution) };
       // Teams contract (decision 6): the eligible teams at spawn, recorded as EVIDENCE beside
       // `providers` (never inside that capability-keyed map). A home's hooks and operations get
       // the LIVE set (liveTeams); this is what they fall back to when discovery cannot answer.

package/lib/instance-inspect.mjs

@@ -15,7 +15,7 @@ import { accessSync, constants as fsConstants, existsSync, readFileSync, realpat
 import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { capabilityManifests, instanceSoulDir, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
-import { discoverOrStandalone, findSoulEntry, liveTeams, prepareInstance } from "./instance-resolution.mjs";
+import { agentDirOf, discoverOrStandalone, findSoulEntry, liveTeams, prepareInstance } from "./instance-resolution.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
 import { kernelCompatibility, teamLabelsOf, teamsOf } from "./resolve.mjs";
 import { loadLocal } from "./workspace.mjs";
@@ -94,7 +94,7 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
       // The derived deployment exactly — never an oats-local.yaml found further up.
       const found = loadLocal(deployment);
       if (real(dirname(found.path)) !== real(deployment)) throw Object.assign(new Error(`${deployment} has no oats-local.yaml`), { code: "E_HOME_MISMATCH" });
-      discovery = await discoverOrStandalone(found.local, { remoteOptions });
+      discovery = await discoverOrStandalone(found.local, { deployment, remoteOptions });
     }
     catch (e) { discoveryError = { code: e.code || "E_REMOTE_UNREADABLE", message: e.message }; }
   }
@@ -140,13 +140,13 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
   let discovery = prepared?.discovery ?? null, soulEntry = prepared?.soulEntry ?? null;
   if (!prepared) {
     // Still name the soul (and its member) when its resolution is refused.
-    discovery = await discoverOrStandalone(found.local, { remoteOptions });
+    discovery = await discoverOrStandalone(found.local, { deployment, remoteOptions });
     soulEntry = findSoulEntry(discovery, soul);
   }
   const res = prepared?.resolution;
   // A refused resolution still names its eligible teams: the labels and the workspace are known.
   const teams = res?.teams ?? teamsOf(discovery?.standalone === true ? null : discovery?.workspace ?? null, teamLabelsOf(soulEntry));
-  const cached = soulEntry?.commit ? join(deployment, "agents", soulEntry.name, "souls", String(soulEntry.commit).slice(0, 12)) : null;
+  const cached = soulEntry?.commit ? join(deployment, "agents", agentDirOf(soulEntry), "souls", String(soulEntry.commit).slice(0, 12)) : null;
   return {
     kind: "soul", home: null, meta: null, deployment, agentsRoot: join(deployment, "agents"), teams, teamsSource: "live",
     subject: { kind: "soul", soul: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null, team: soulEntry.team ?? null },

package/lib/instance-resolution.mjs

@@ -28,7 +28,7 @@ import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync, symlinkSync,
 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, readPackageManifests, 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
@@ -117,6 +145,8 @@ export async function liveTeams(home, meta, { remoteOptions, remote } = {}) {
   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");
+  // 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;
 }
@@ -389,8 +424,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 +439,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 +466,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.
@@ -499,7 +543,7 @@ export async function prepareCapabilityAgent(contextDir, agent, { discovery, pkg
   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 view = discovery ?? await discoverOrStandalone(local, { lock, remoteOptions });
   const cap = agent.capability;
   let module, payload, origins, localModules = null;
   const anchor = pkg ? null : agent._manifestSource;
@@ -652,7 +696,7 @@ export async function resolvePackageCapabilityAgent(contextDir, name, { remoteOp
   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;
+  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 || []) {

package/lib/materialize.mjs

@@ -584,12 +584,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/packages.mjs

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

package/lib/resolve.mjs

@@ -472,6 +472,15 @@ function lookupPackage(lock, name, via, soul, declared) {
   return providing;
 }
 
+/** `from: here` in a package soul: the capability must be one its OWN locked package provides. */
+function ownPackageEntry(lock, name, via, soul, id) {
+  const where = { capability: name, from: "here", soul: soul.name, via, package: id };
+  const entry = isObject(lock?.packages) ? lock.packages[id] : null;
+  if (!isObject(entry)) throw fail("E_PACKAGE_MISSING", `${name}: from: here in package soul ${id}/${soul.name} needs ${id} in the lock — run \`oats sync\``, { ...where, reason: "no-lock" });
+  if (!entry.capabilities.includes(name)) throw fail("E_CAPABILITY_MISSING", `${name}: from: here in package soul ${id}/${soul.name}, but package ${id} v${entry.version} provides [${entry.capabilities.join(", ")}]`, { ...where, version: entry.version, listed: [...entry.capabilities] });
+  return { id, entry };
+}
+
 /** The repo ref a locked package is read from: the lock's recorded url, else the catalog's url for catalog ids, else the key for git refs. */
 export function packageRef(id, entry, catalog, remote) {
   const cat = isObject(catalog) ? (isObject(catalog.packages) && !("url" in catalog.packages) ? catalog.packages : catalog) : {};
@@ -582,8 +591,12 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
   const emptied = new Set(SLOTS.filter((slot) => definition[slot] === "none"));
   for (const { name, from, via } of declared) {
     let module;
-    if (from === "package") {
-      const { id, entry } = lookupPackage(lock, name, via, soul, discovery?.standalone === true ? null : (isObject(workspace?.packages) ? workspace.packages : {}));
+    const ownPackage = from === "here" && typeof soulEntry.package === "string";
+    if (from === "package" || ownPackage) {
+      // `from: here` in a package soul is its own package, at the locked commit (§2.2).
+      const { id, entry } = ownPackage
+        ? ownPackageEntry(lock, name, via, soul, soulEntry.package)
+        : lookupPackage(lock, name, via, soul, discovery?.standalone === true ? null : (isObject(workspace?.packages) ? workspace.packages : {}));
       const ref = packageRef(id, entry, catalog, remote);
       const details = { capability: name, id, version: entry.version, commit: entry.commit, path: entry.path };
       const { capabilities } = await readPackageManifests(remote, ref, entry.commit, entry.path, details);
@@ -783,6 +796,11 @@ function assertSoulDiscovered(discovery, soulEntry) {
   const { name, repoKey } = soulEntry;
   const where = { soul: name, repoKey };
   const sameSoul = (s) => isObject(s) && s.name === name && s.repoKey === repoKey && (s.commit ?? null) === (soulEntry.commit ?? null);
+  if (typeof soulEntry.package === "string") {
+    // A package soul: the discovery listed it from the lock, at this package's locked commit.
+    if ((discovery?.packageSouls || []).some((s) => sameSoul(s) && s.package === soulEntry.package)) return;
+    throw fail("E_PACKAGE_MISSING", `soul ${soulEntry.package}/${name}: the discovery does not list it at ${short(soulEntry.commit)} — the soul entry is stale; run \`oats sync\` and discover again`, { ...where, package: soulEntry.package, reason: "stale" });
+  }
   if ((discovery?.external || []).some((e) => sameSoul(e?.soul))) return;
   const row = memberRow(discovery, repoKey);
   if (!row) throw fail("E_NOT_A_MEMBER", `soul ${name}: ${repoKey} is not a member of the workspace${discovery?.key ? ` ${discovery.key}` : ""} (nor an external soul) — a soul is spawned from a confirmed member or an external entry`, { ...where, reason: "not-listed" });