@awebai/oats 0.27.1 → 0.28.0

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" });

package/lib/schedule.mjs

@@ -29,6 +29,7 @@ import { fileURLToPath } from "node:url";
 import { Cron } from "croner";
 import { loadLocal } from "./workspace.mjs";
 import { noteRuntimeName } from "./deprecation.mjs";
+import { tickTriggers } from "./triggers.mjs";
 import { RESERVED_LAUNCH_ENV, MAX_INSTANCE_NAME, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
 
 export const SCHEDULE_FILE = "oats-schedules.json";
@@ -65,6 +66,7 @@ const CAPTURED_SCHEDULE_REMOVED = "captured schedules are refused (the captured/
 export const HARNESS_CONFLICT = "harness and runtime (its pre-0.27 name) disagree: keep harness: and remove runtime:";
 export function shapeError(def) {
   if (!def || typeof def !== "object" || Array.isArray(def)) return "definition is not an object";
+  if (def.kind === "trigger") return "a trigger is managed by oats trigger, not oats schedule";
   if (!["spawn", "command", "wake", "operation"].includes(def.kind)) return `kind ${JSON.stringify(def.kind)} is not spawn, command, wake or operation`;
   if (typeof def.cron !== "string" || typeof def.tz !== "string") return "cron and tz must be strings";
   if (def.kind === "spawn" && typeof def.agent !== "string") return "agent must be a string";
@@ -246,7 +248,7 @@ export function withHostLock(fn, { retryMs = 0 } = {}) { return withDirLock(join
 /** Registry read-modify-write is serialized on its own short lock. */
 function withRegistryLock(fn) { return withDirLock(join(hostScheduleDir(), "registry.lock"), "the host schedule registry", fn, { retryMs: 3000 }); }
 /** Definitions and state are read-modify-write; CRUD serializes here briefly. */
-function withScopeLock(ws, fn) { return withDirLock(join(stateDir(ws), "scope.lock"), `schedules of ${ws}`, fn, { retryMs: 3000 }); }
+export function withScopeLock(ws, fn) { return withDirLock(join(stateDir(ws), "scope.lock"), `schedules of ${ws}`, fn, { retryMs: 3000 }); }
 
 export function acquireJobLock(ws, id, owner) {
   const dir = lockDir(ws, id);
@@ -288,6 +290,7 @@ function validateMessage(message, field) {
 /** Validate and normalize one definition against its scope. */
 export function validateDefinition(ws, def, { checkAgent = true } = {}) {
   if (!def || typeof def !== "object" || Array.isArray(def)) throw scheduleError("E_SCHEDULE_INVALID", "definition must be an object", { field: "definition" });
+  if (def.kind === "trigger") throw scheduleError("E_SCHEDULE_INVALID", "kind: a trigger is added with `oats trigger add`, not `oats schedule add`", { field: "kind" });
   const id = def.id;
   if (typeof id !== "string" || !ID_RE.test(id)) throw scheduleError("E_SCHEDULE_INVALID", "id: lowercase letters, digits and dashes, 1 to 40 characters", { field: "id" });
   const enabled = def.enabled === undefined ? true : def.enabled;
@@ -431,13 +434,13 @@ function scheduleBlock(def, minute) {
  *  may be invoked from inside an unrelated instance; dispatch belongs to the
  *  job's cwd and explicit selectors, never to that caller), host configuration
  *  such as OATS_HOME_DIR and credentials kept. Shared by command and spawn jobs. */
-function childEnv() {
+export function childEnv() {
   const env = { ...process.env };
   for (const key of [...RESERVED_LAUNCH_ENV,
     "OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
     "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
     "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_RETIRE_INTENT",
-    "OATS_TEAM_NAME", "OATS_TEAM_ID", "OATS_TEAM_SCOPE",
+    "OATS_TEAM_NAME", "OATS_TEAM_ID", "OATS_TEAM_SCOPE", "OATS_TRIGGER_EVENT_FILE",
   ]) delete env[key];
   return env;
 }
@@ -671,6 +674,8 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
   // are gone), then decide launches: a job ordered earlier must not see a
   // slot still held by a home that has already ended.
   // `candidates` (the host tick) means the host already observed every scope.
+  // Triggers (kind "trigger") live in the same file and are evaluated by tickTriggers, not here.
+  for (const [id, def] of Object.entries(defs.jobs)) if (def && def.kind === "trigger") delete defs.jobs[id];
   if (!candidates) for (const [id, def] of Object.entries(defs.jobs)) observePrevious(ws, id, def, stateOf(id), io, now, { mutate: !dryRun });
   if (observeOnly) { if (!dryRun) writeState(ws, st); return considered; }
   // Least recently LAUNCHED first: only an actual harness launch counts, a
@@ -778,7 +783,7 @@ export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
       try {
         considered.push(...tickWorkspace(ws, { now, io, reg, wsList, dryRun, observeOnly: true }));
         const defs = readDefinitions(ws), st = readState(ws);
-        for (const id of Object.keys(defs.jobs)) jobs.push({ ws, id, key: launchOrderKey(st.jobs[id]) });
+        for (const [id, def] of Object.entries(defs.jobs)) if (def?.kind !== "trigger") jobs.push({ ws, id, key: launchOrderKey(st.jobs[id]) });
       } catch (e) { considered.push({ workspace: ws, action: "error", error: e.message }); }
     }
     jobs.sort((a, b) => a.key.localeCompare(b.key) || a.ws.localeCompare(b.ws) || a.id.localeCompare(b.id));
@@ -786,6 +791,11 @@ export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
       try { considered.push(...tickWorkspace(j.ws, { now, io, reg, wsList, dryRun, candidates: [j.id] })); }
       catch (e) { considered.push({ workspace: j.ws, id: j.id, action: "error", error: e.message }); }
     }
+    // Triggers: each scope's event-driven spawns, polled at their own interval (lib/triggers.mjs).
+    for (const ws of wsList) {
+      try { considered.push(...tickTriggers(ws, { now, io, dryRun })); }
+      catch (e) { considered.push({ workspace: ws, action: "error", error: `triggers: ${e.message}` }); }
+    }
     if (!dryRun) writeHostState({ ...readHostState(), lastTick: now.toISOString(), minute: minuteKey(minuteStart(now)) });
     return { tickedAt: now.toISOString(), minute: minuteKey(minuteStart(now)), considered, scheduler: schedulerStatus(undefined, io) };
   };
@@ -797,7 +807,7 @@ export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
 export function runNow(ws, id, { now = new Date(), io, force = false } = {}) {
   const defs = readDefinitions(ws);
   const def = defs.jobs[id];
-  if (!def) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+  if (!def || def.kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
   if (!def.enabled && !force) throw scheduleError("E_SCHEDULE_DISABLED", `schedule ${id} is disabled; enable it or pass --force`);
   const reg = readRegistry();
   const wsList = reg.workspaces.includes(resolve(ws)) ? reg.workspaces : [...reg.workspaces, resolve(ws)];
@@ -824,7 +834,7 @@ export function runNow(ws, id, { now = new Date(), io, force = false } = {}) {
 export function reconcile(ws, id, { io, now = new Date(), clear = false } = {}) {
   const defs = readDefinitions(ws);
   const def = defs.jobs[id];
-  if (!def) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+  if (!def || def.kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
   return withHostLock(() => {
     const st = readState(ws);
     const js = st.jobs[id] || (st.jobs[id] = {});
@@ -898,6 +908,7 @@ export function describe(ws, id, io, { defs, st, now = new Date() } = {}) {
   defs ||= readDefinitions(ws); st ||= readState(ws);
   const def = defs.jobs[id];
   if (!def) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+  if (def.kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `${id} is a trigger, not a schedule — use oats trigger show ${id}`);
   // Subject truth: the definition's own id must be the key it is stored under.
   if (def.id !== undefined && def.id !== id) throw scheduleError("E_SCHEDULE_IDENTITY", `schedule stored under ${JSON.stringify(id)} declares id ${JSON.stringify(def.id)}`, { key: id, declared: def.id });
   const js = st.jobs[id] || {};
@@ -910,11 +921,13 @@ export function describe(ws, id, io, { defs, st, now = new Date() } = {}) {
 export function listSchedules(ws, io, { now = new Date() } = {}) {
   const defs = readDefinitions(ws), st = readState(ws);
   // One job's bad identity or history does not fail the others: it is reported as its own row.
-  const schedules = Object.keys(defs.jobs).sort().map((id) => {
+  const schedules = Object.keys(defs.jobs).filter((id) => defs.jobs[id]?.kind !== "trigger").sort().map((id) => {
     try { return describe(ws, id, io, { defs, st, now }); }
     catch (e) { return { id, scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, unreadable: { code: e.code || "E_SCHEDULE_INVALID", message: e.message }, history: { status: "corrupt", stored: null, truncated: false }, recentRuns: [] }; }
   });
-  return { scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, integrity: scheduleIntegrity(ws), schedules, scheduler: schedulerStatus(ws, io) };
+  // Triggers share the definitions file but not this listing: a pointer, so they are never invisible.
+  const triggers = Object.values(defs.jobs).filter((d) => d?.kind === "trigger").length;
+  return { scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, integrity: scheduleIntegrity(ws), schedules, triggers: { count: triggers, command: "oats trigger list" }, scheduler: schedulerStatus(ws, io) };
 }
 export function addSchedule(ws, spec, io) {
   const def = validateDefinition(ws, spec);
@@ -935,7 +948,7 @@ export function updateSchedule(ws, id, spec, io) {
   const def = validateDefinition(ws, { ...spec, id });
   return withHostLock(() => withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
-    if (!defs.jobs[id]) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+    if (!defs.jobs[id] || defs.jobs[id].kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}${defs.jobs[id] ? " (it is a trigger: use oats trigger)" : ""}`);
     const identity = (d) => JSON.stringify([d.kind, d.agent, d.agentsRoot, d.repo, d.purpose, d.home, d.cwd, d.argv, d.operation, d.definitionVersion, d.recurrencePolicy, d.execution, d.preparation]);
     const busy = !!jobLockInfo(ws, id) || !!readState(ws).jobs[id]?.attempt;
     if (busy && identity(defs.jobs[id]) !== identity(def)) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is running or has an unresolved attempt; its execution identity, kind, target and captured policy cannot change until it ends (cron, tz and enabled can)`);
@@ -947,7 +960,7 @@ export function updateSchedule(ws, id, spec, io) {
 export function setEnabled(ws, id, enabled, io) {
   return withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
-    if (!defs.jobs[id]) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+    if (!defs.jobs[id] || defs.jobs[id].kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}${defs.jobs[id] ? " (it is a trigger: use oats trigger)" : ""}`);
     defs.jobs[id] = { ...defs.jobs[id], enabled, updatedAt: new Date().toISOString() };
     writeDefinitions(ws, defs);
     return describe(ws, id, io);
@@ -958,7 +971,7 @@ export function setEnabled(ws, id, enabled, io) {
 export function removeSchedule(ws, id, { force = false } = {}) {
   return withHostLock(() => withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
-    if (!defs.jobs[id]) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+    if (!defs.jobs[id] || defs.jobs[id].kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}${defs.jobs[id] ? " (it is a trigger: use oats trigger)" : ""}`);
     const st = readState(ws), job = st.jobs[id];
     if ((jobLockInfo(ws, id) || job?.attempt || job?.lastRun?.outcome === "unknown") && !force) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is running or has unresolved effects; reconcile first, or --force forgets the job without stopping anything`);
     delete defs.jobs[id];