@awebai/oats 0.27.2 → 0.29.0

package/bin/oats.mjs

@@ -27,18 +27,20 @@ import {
   LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
   capabilityManifests, capabilityTrust, capabilityExecutablePath,
   officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
-  findInstanceHome, findInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, launchConfigsAt, explicitInstanceName, findModuleCapabilityAgent, capabilityAgentFromDir, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
+  findInstanceHome, findInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, launchConfigsAt, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
 } from "../lib/core.mjs";
 import {
-  writeFileAtomic, LOCK_FILE, readLock, writeLock, resolvePackages,
+  writeFileAtomic, LOCK_FILE, readLock, writeLock, resolvePackages, memoizedRemote,
   classifyPackageValue, parsePackageRequest } from "../lib/packages.mjs";
-import { loadLocal, validateWorkspace, validateLocal } from "../lib/workspace.mjs";
+import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, workspaceWarnings } from "../lib/workspace.mjs";
 import { parseConfigData } from "../lib/config-data.mjs";
 import * as remoteModule from "../lib/remote.mjs";
 import YAML from "yaml";
 import { attachArgv, checkRemote, forgetSnapshot, getServer, inspectRemote, startRemote, restartRemote, launchConfigRemote, scheduleRemote, listSnapshots, readServers, rosterGroups, routeCommand, targetOf, validateServer, writeServers, SERVERS_FILE } from "../lib/servers.mjs";
 import { spawnSync as spawnSyncProc } from "node:child_process";
-import { parseEnvelopeText, scheduleScopeOf, listSchedules, describe as describeSchedule, addSchedule, updateSchedule, setEnabled as setScheduleEnabled, removeSchedule, runNow as runScheduleNow, reconcile as reconcileSchedule, tickHost, tickWorkspace, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } from "../lib/schedule.mjs";
+import { tickTriggers } from "../lib/triggers.mjs";
+import * as A from "../lib/automations.mjs";
+import { parseEnvelopeText, scheduleScopeOf, listSchedules, describe as describeSchedule, testSchedule, addSchedule, updateSchedule, setEnabled as setScheduleEnabled, removeSchedule, runNow as runScheduleNow, reconcile as reconcileSchedule, tickHost, tickWorkspace, scopeAutomations, scheduleKind, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } from "../lib/schedule.mjs";
 import { hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/schedule-host.mjs";
 import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
 
@@ -48,10 +50,32 @@ const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli }
 import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
 import { readEvents } from "../lib/instance-events.mjs";
 
-const args = process.argv.slice(2);
+const rawArgs = process.argv.slice(2);
+/** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
+const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "json", "keep-dir", "keep-env", "no-child-spawns", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "self", "verbose", "yes", "yolo"]);
+/** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
+ *  routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
+ *  `--flag=` or a switch given a value. */
+function expandInlineValues(argv) {
+  const out = [];
+  let problem;
+  for (const a of argv) {
+    const eq = a.indexOf("=");
+    if (!a.startsWith("--") || eq <= 2) { out.push(a); continue; }
+    const name = a.slice(2, eq), value = a.slice(eq + 1);
+    problem ??= KERNEL_SWITCHES.has(name) ? `--${name} takes no value (got ${a})` : value === "" ? `--${name}= needs a value` : undefined;
+    out.push(`--${name}`, value);
+  }
+  return { argv: out, problem };
+}
+const { argv: args, problem: argvProblem } = expandInlineValues(rawArgs);
 let cmd = args[0];
 const HELP_WORDS = new Set(["help", "--help", "-h"]);
-const KERNEL_COMMANDS = new Set(["capture", "capabilities", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "update", "version", "workspace"]);
+const KERNEL_COMMANDS = new Set(["automations", "trigger", "capture", "capabilities", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "update", "version", "workspace"]);
+/** Commands whose argv another parser reads (packages/record and packages/experimental parse process.argv). */
+const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental"]);
+/** Commands `--server <id>` runs on a registered server. */
+const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config"]);
 const flag = (name) => {
   const i = args.indexOf(`--${name}`);
   return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : true) : undefined;
@@ -154,7 +178,7 @@ function operationalKnowledgeNote(composition, soulName) {
  *  home-relative (`.oats/modules/<cap>/<inject>`), where an instance carries them. */
 async function doctorComposition(ctx, soulName, ws, bail) {
   if (!soulName) return undefined;
-  const { prepareInstance, previewWorkspaceSoul, materializePrepared, discoverOrStandalone } = await import("../lib/instance-resolution.mjs");
+  const { prepareInstance, previewWorkspaceSoul, materializePrepared, discoverOrStandalone, agentDirOf } = await import("../lib/instance-resolution.mjs");
   const deployment = dirname(ws.local.path);
   const root = join(deployment, "agents");
   const remoteOptions = remoteOptionsFromEnv();
@@ -162,11 +186,11 @@ async function doctorComposition(ctx, soulName, ws, bail) {
   // A bail exits the process without unwinding: the temporary copies are removed at exit too.
   process.once("exit", () => { for (const c of cleanups) { try { c(); } catch { /* best effort */ } } });
   try {
-    const discovery = await discoverOrStandalone(loadLocal(deployment).local, { remoteOptions });
+    const discovery = await discoverOrStandalone(loadLocal(deployment).local, { deployment, remoteOptions });
     const prepared = await prepareInstance(deployment, soulName, { remoteOptions, discovery });
     const pv = await previewWorkspaceSoul(prepared, root);
     cleanups.push(pv.cleanup);
-    const agent = findAgentAt(root, prepared.soulEntry.name, pv.soulDir);
+    const agent = findAgentAt(root, agentDirOf(prepared.soulEntry), pv.soulDir);
     if (!agent) bail("E_SOUL_UNKNOWN", `soul "${soulName}" was fetched but is not readable as a soul`);
     const composition = composeInstanceAgentsMd(pv.soulDir, deployment, agent.name, agent.work || "checkout", agent.kind, prepared);
     const scratch = realpathSync(mkdtempSync(join(tmpdir(), "oats-doctor-home-")));
@@ -1035,7 +1059,7 @@ function standaloneCatalogVersion(ref) {
 async function discoverForCli(ctx, bail) {
   // The standalone case (decisions 10/25) is a discovery too: the repo's own view
   // plus the kernel's oats.core default — discoverOrStandalone decides.
-  try { const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs"); return await discoverOrStandalone(ctx.local, { remoteOptions: ctx.remoteOptions }); }
+  try { const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs"); return await discoverOrStandalone(ctx.local, { deployment: ctx.deploymentDir, remoteOptions: ctx.remoteOptions }); }
   catch (e) {
     if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance);
     throw e;
@@ -1049,6 +1073,10 @@ const memberLabel = (key) => String(key).split("/").filter(Boolean).pop()?.repla
 const teamLabel = (team) => team ?? "unassigned";
 const originOf = (item) => (item.package ? `package ${item.package} v${item.version}` : `member ${item.repoKey} @ ${short(item.commit)}`);
 
+/** A soul's spawn default harness and model (feature desktop-facts): its definition's, else the kernel's (pi, the
+ *  harness's native model) — what `oats spawn <soul>` takes with no --harness/--model/--launch-config. */
+const soulDefaults = (def) => ({ harness: def?.harness ?? "pi", model: def?.model ?? null, harnessFrom: def?.harness ? "soul" : "kernel-default" });
+
 /** Rows of every soul and capability of confirmed members (+ external souls) + locked package
  *  capabilities. Souls have no private mode (0.26.0); a private member capability is listed with
  *  `private: true` — repo-owned: usable only by its own repo's souls (E_CAPABILITY_PRIVATE). */
@@ -1057,12 +1085,15 @@ function workspaceItems(discovery, lock) {
   const capabilities = [];
   for (const m of discovery.members) {
     if (!m.confirmed && !(discovery.standalone === true && m.key === discovery.key)) continue;
-    for (const s of m.souls) souls.push({ name: s.name, origin: originOf(s), kind: "member", repoKey: s.repoKey, commit: s.commit, team: teamLabel(s.team), labels: [...(s.labels ?? (s.team ? [s.team] : []))], private: s.private, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null });
+    for (const s of m.souls) souls.push({ name: s.name, origin: originOf(s), kind: "member", repoKey: s.repoKey, commit: s.commit, team: teamLabel(s.team), labels: [...(s.labels ?? (s.team ? [s.team] : []))], private: s.private, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null, ...soulDefaults(s.definition) });
     for (const c of m.capabilities) capabilities.push({ name: c.name, origin: originOf(c), kind: "member", repoKey: c.repoKey, commit: c.commit, team: teamLabel(c.team), private: c.private, path: c.path, layer: c.manifest.layer ?? null, version: c.manifest.version ?? null });
   }
   for (const ext of discovery.external || []) {
     const s = ext.soul;
-    souls.push({ name: s.name, origin: `external ${s.repoKey} @ ${short(s.commit)}`, kind: "external", repoKey: s.repoKey, commit: s.commit, team: teamLabel(s.team), labels: [...(s.labels ?? (s.team ? [s.team] : []))], private: s.private, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null });
+    souls.push({ name: s.name, origin: `external ${s.repoKey} @ ${short(s.commit)}`, kind: "external", repoKey: s.repoKey, commit: s.commit, team: teamLabel(s.team), labels: [...(s.labels ?? (s.team ? [s.team] : []))], private: s.private, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null, ...soulDefaults(s.definition) });
+  }
+  for (const s of discovery.packageSouls || []) {
+    souls.push({ name: s.name, qualifiedName: s.qualifiedName, origin: originOf(s), kind: "package", package: s.package, version: s.version, repoKey: s.repoKey, commit: s.commit, team: teamLabel(s.team), labels: [...(s.labels ?? [])], private: false, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null, ...soulDefaults(s.definition) });
   }
   for (const [id, entry] of Object.entries(lock?.packages || {})) {
     for (const name of entry.capabilities) capabilities.push({ name, origin: originOf({ package: id, version: entry.version }), kind: "package", package: id, version: entry.version, commit: entry.commit, team: teamLabel(null), private: false });
@@ -1083,7 +1114,7 @@ function memberRows(discovery) {
 
 /** Package rows for `sync` / `workspace status` from the lock. */
 function packageRows(lock) {
-  return Object.entries(lock.packages).map(([id, p]) => ({ id, version: p.version, source: p.source, commit: p.commit, integrity: p.integrity, capabilities: p.capabilities }));
+  return Object.entries(lock.packages).map(([id, p]) => ({ id, version: p.version, source: p.source, commit: p.commit, integrity: p.integrity, capabilities: p.capabilities, souls: (p.souls ?? []).map((x) => x.name) }));
 }
 
 /** Print a padded table: rows are arrays of strings. */
@@ -1124,14 +1155,31 @@ async function performSync(ctx, bail, { onDiscovered } = {}) {
   const lock = resolved.lock;
   let lockFile;
   try { lockFile = writeLock(ctx.deploymentDir, lock); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
+  // Package souls come from the lock: list what THIS sync locked, not what the previous lock held.
+  if (discovery.standalone !== true) {
+    let pkg;
+    try { pkg = await discoverPackageSouls(discovery.workspace, lock, { remoteOptions: ctx.remoteOptions }); }
+    catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance); throw e; }
+    const kept = (list) => list.filter((p) => typeof p.package !== "string");
+    discovery.packageSouls = pkg.souls;
+    discovery.problems = [...kept(discovery.problems), ...pkg.problems];
+    discovery.warnings = workspaceWarnings(discovery.workspace, discovery.members, discovery.external || [], pkg.souls);
+    problems.splice(0, problems.length, ...kept(problems), ...pkg.problems);
+  }
   // The deployment's instance root: <deployment>/agents/ (findRoot's marker). A hand-written
   // oats-local.yaml + sync is a complete deployment; spawn must not answer E_NO_DEPLOYMENT after it.
   try { mkdirSync(join(ctx.deploymentDir, "agents"), { recursive: true }); } catch { /* reported by spawn's E_NO_DEPLOYMENT remedy if it matters */ }
+  // Workspace automations (0.29.0): discovered with the members and the new lock (a trigger
+  // template instantiates at the locked package commit), kept as the snapshot the host tick reads.
+  let automations;
+  try { automations = await takeAutomationSnapshot(ctx, discovery, lock); }
+  catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
+  problems.push(...automations.problems);
   const members = memberRows(discovery);
   const packages = packageRows(lock);
   const changes = resolved.changes;
   const items = workspaceItems(discovery, lock);
-  const report = { syncApi: 1, standalone: discovery.standalone === true || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, url: discovery.url, commit: discovery.commit, observedAt: discovery.observedAt, local: ctx.localPath, lock: lockFile }, members, packages, changes, problems, warnings: discovery.warnings ?? [] };
+  const report = { syncApi: 1, automations: automationCounts(automations), standalone: discovery.standalone === true || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, url: discovery.url, commit: discovery.commit, observedAt: discovery.observedAt, local: ctx.localPath, lock: lockFile }, members, packages, changes, problems, warnings: discovery.warnings ?? [] };
   return { report, lock, discovery, items, lockFile, problems };
 }
 
@@ -1152,6 +1200,7 @@ function printSyncReport(ctx, synced) {
   const { report, discovery, items, lockFile } = synced;
   const { members, packages, changes } = report;
   const disabled = new Set(ctx.local.souls?.disabled || []);
+  const isDisabled = (s) => disabled.has(s.name) || disabled.has(s.qualifiedName ?? `${memberLabel(s.repoKey)}/${s.name}`);
   console.log(`workspace  ${discovery.workspace?.name ?? `(${standaloneNote(discovery)})`}  (${discovery.key} @ ${short(discovery.commit)})`);
   console.log(`members    ${members.map((m) => m.confirmed ? `${m.name} ✓↔ (@ ${short(m.commit)})` : `${m.name} ✗ (${m.status})`).join("   ") || "(none)"}`);
   console.log(`packages   ${packages.map((p) => `${p.id} ${p.version} ✓ (@ ${short(p.commit)})`).join("   ") || "(none)"}`);
@@ -1162,17 +1211,98 @@ function printSyncReport(ctx, synced) {
   const externalSouls = items.souls.filter((s) => s.kind === "external");
   // Souls have no private mode (0.26.0); the private count is of repo-owned member capabilities.
   const repoOwned = items.capabilities.filter((c) => c.kind === "member" && c.private);
-  const disabledHere = items.souls.filter((s) => disabled.has(s.name));
-  console.log(`souls      ${items.souls.length} discovered (${memberSouls.length} members, ${externalSouls.length} external, ${disabledHere.length} disabled here) · ${repoOwned.length} private capabilit${repoOwned.length === 1 ? "y" : "ies"}${repoOwned.length ? ` (${repoOwned.map((c) => `${c.name}, ${memberLabel(c.repoKey)} only`).join("; ")})` : ""}`);
+  const packageSouls = items.souls.filter((s) => s.kind === "package");
+  const disabledHere = items.souls.filter(isDisabled);
+  console.log(`souls      ${items.souls.length} discovered (${memberSouls.length} members, ${externalSouls.length} external, ${packageSouls.length ? `${packageSouls.length} package, ` : ""}${disabledHere.length} disabled here) · ${repoOwned.length} private capabilit${repoOwned.length === 1 ? "y" : "ies"}${repoOwned.length ? ` (${repoOwned.map((c) => `${c.name}, ${memberLabel(c.repoKey)} only`).join("; ")})` : ""}`);
   const teams = new Map();
   for (const s of items.souls) { const t = teams.get(s.team) || { souls: 0, capabilities: 0 }; t.souls++; teams.set(s.team, t); }
   for (const c of items.capabilities.filter((c) => c.kind === "member")) { const t = teams.get(c.team) || { souls: 0, capabilities: 0 }; t.capabilities++; teams.set(c.team, t); }
   console.log(`teams      ${[...teams.entries()].sort(([a], [b]) => (a < b ? -1 : 1)).map(([team, n]) => `${team} ${n.souls} soul${n.souls === 1 ? "" : "s"}${n.capabilities ? `, ${n.capabilities} capabilit${n.capabilities === 1 ? "y" : "ies"}` : ""}`).join(" · ") || "(none)"}`);
+  const ac = report.automations;
+  if (ac.triggers || ac.schedules) console.log(`automations ${ac.triggers} trigger${ac.triggers === 1 ? "" : "s"}, ${ac.schedules} schedule${ac.schedules === 1 ? "" : "s"} in the members (oats trigger list · oats schedule list)`);
   for (const p of synced.problems ?? discovery.problems) console.log(`problem    ${p.code}  ${p.repoKey ? `${memberLabel(p.repoKey)}:` : ""}${p.path}  ${p.message}`);
   for (const w of discovery.warnings ?? []) console.log(`warning    ${w.code}  ${w.message}`);
   console.log(`\nlock       ${shortPath(lockFile)}`);
 }
 
+/** Discover the workspace automations of a discovery and write the snapshot the host tick reads
+ *  (lib/automations.mjs). A trigger's `from:` instantiates the package template at the lock's
+ *  commit; a schedule is checked against this deployment. → the snapshot */
+async function takeAutomationSnapshot(ctx, discovery, lock) {
+  const kinds = await automationKinds(ctx.deploymentDir, lock, ctx.remoteOptions);
+  const found = await A.discoverAutomations(discovery, { remote: kinds.remote, memberName: memberLabel, kinds: [kinds.trigger, kinds.schedule], previous: A.readSnapshot(ctx.deploymentDir) });
+  const snap = A.snapshotOf(discovery, found, { souls: A.soulIndexOf(discovery, memberLabel) });
+  // A workspace with no triggers or schedules leaves nothing behind (onboard creates what the
+  // kernel needs and nothing else); a snapshot that existed is replaced, so a removal lands.
+  const empty = !snap.triggers.length && !snap.schedules.length && !snap.problems.length;
+  if (!empty || A.readSnapshot(ctx.deploymentDir)) A.writeSnapshot(ctx.deploymentDir, snap);
+  return snap;
+}
+/** The two kinds' descriptors (lib/triggers.mjs triggerKind, lib/schedule.mjs scheduleKind). */
+async function automationKinds(dep, lock, remoteOptions) {
+  const T = await import("../lib/triggers.mjs");
+  const { bindRemote } = await import("../lib/packages.mjs");
+  const remote = bindRemote(remoteModule, remoteOptions);
+  return { remote, trigger: T.triggerKind({ lock, remote }), schedule: scheduleKind({ dep }) };
+}
+const automationCounts = (snap) => ({ triggers: snap.triggers.length, schedules: snap.schedules.length, problems: snap.problems.length, takenAt: snap.takenAt });
+
+/** `oats automations refresh [--dir] [--json]`: re-discover the workspace automations and rewrite
+ *  the snapshot (what `oats sync` does for them, without touching the lock). The host tick runs it
+ *  when the snapshot is ten minutes old. */
+async function automationsCmd() {
+  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
+  if (args[1] !== "refresh") return bail("E_USAGE", "usage: oats automations refresh [--dir <deployment>] [--json]");
+  const ctx = workspaceContext(bail);
+  const discovery = await discoverForCli(ctx, bail);
+  let lock;
+  try { lock = readLock(ctx.deploymentDir); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
+  let snap;
+  try { snap = await takeAutomationSnapshot(ctx, discovery, lock); }
+  catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
+  const result = { automationsApi: A.AUTOMATIONS_API, snapshot: A.snapshotPath(ctx.deploymentDir), ...automationCounts(snap), problems: snap.problems };
+  if (JSON_MODE) return jsonOk(result);
+  console.log(`automations ${result.triggers} trigger(s), ${result.schedules} schedule(s) — snapshot ${shortPath(result.snapshot)}`);
+  for (const p of snap.problems) console.log(`problem    ${p.code}  ${p.repoKey ? `${memberLabel(p.repoKey)}:` : ""}${p.path}  ${p.message}`);
+}
+
+/** `oats trigger|schedule add --workspace <member> --runs-on <host> --owner <host>/<login>`: the
+ *  workspace file, written into the member's checkout when `--dir` (or the cwd) is inside one, else
+ *  printed. What is written must read back as the same automation (parseAutomationFile + expand). */
+async function addWorkspaceAutomation(desc, { id, body }) {
+  const bail = (code, msg, details) => { throw Object.assign(new Error(msg), { code, details }); };
+  const member = flag("workspace"), runsOn = flag("runs-on"), owner = flag("owner"), description = flag("description");
+  if (typeof member !== "string" || !member) bail("E_BAD_ARGS", "--workspace needs a member name");
+  if (typeof runsOn !== "string" || !A.HOST_NAME_RE.test(runsOn)) bail("E_BAD_ARGS", "--runs-on <host>: the host.name (oats-local.yaml) of the machine that runs it");
+  if (!A.parseOwner(owner)) bail("E_BAD_ARGS", "--owner <host>/<login>: the GitHub account it acts as, e.g. github.com/acme-kb-bot");
+  const ctx = workspaceContext(bail);
+  const discovery = await discoverForCli(ctx, bail);
+  const row = (discovery.members || []).find((m) => m.confirmed && (memberLabel(m.key) === member || m.key === member));
+  if (!row) bail("E_AUTOMATION_MEMBER", `${member} is not a confirmed member of this workspace (members: ${(discovery.members || []).filter((m) => m.confirmed).map((m) => memberLabel(m.key)).join(", ") || "none"})`, { member });
+  const name = memberLabel(row.key);
+  const content = A.automationFileText(desc, { id, description: typeof description === "string" ? description : undefined, runsOn, owner, body });
+  const parsed = A.parseAutomationFile(desc, { stem: id, path: `${desc.folder}/${id}.yaml`, bytes: Buffer.from(content), member: name, repoKey: row.key, commit: row.commit });
+  if (parsed.problem) bail(parsed.problem.code, parsed.problem.message, { path: parsed.problem.path });
+  await desc.expand(parsed.entry);
+  const sameRepo = (url) => { try { return remoteModule.parseRepoRef(url).key === row.key; } catch { return false; } };
+  const at = A.memberCheckoutFor(dirFlag(), desc, id, { sameRepo });
+  const file = { member: name, repoKey: row.key, path: `${desc.folder}/${id}.yaml`, content };
+  if (!at) return { file, written: false, id: `${name}/${id}` };
+  if (existsSync(at.file)) bail(desc.kind === "trigger" ? "E_TRIGGER_EXISTS" : "E_SCHEDULE_EXISTS", `${at.file} already exists; edit it in place`, { path: at.file });
+  mkdirSync(dirname(at.file), { recursive: true });
+  writeFileSync(at.file, content);
+  return { file: { ...file, written: at.file }, written: true, id: `${name}/${id}` };
+}
+const printWorkspaceAdd = (r) => r.written
+  ? `wrote ${shortPath(r.file.written)} — commit and push it; after \`oats sync\` (or within ten minutes) ${r.id} runs on its host`
+  : `# ${r.file.path} in ${r.file.member} (${r.file.repoKey}) — this directory is not a checkout of it; save this there, commit and push:\n${r.file.content}`;
+/** Enable/disable a WORKSPACE trigger or schedule on this host: oats-local.yaml
+ *  `triggers.disabled` / `schedules.disabled`. */
+function setDisabledHereCli(ws, kind, qid, enabled) {
+  const { path } = loadLocal(ws);
+  return A.setDisabledHere(path, kind, qid, !enabled, { validate: validateLocal });
+}
+
 /** `oats sync [--dir] [--json]` — contract §6. */
 async function syncCmd() {
   const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
@@ -1286,6 +1416,10 @@ async function workspaceCmd() {
   const unsynced = declared.filter((id) => !locked.has(id));
   const stale = packages.filter((p) => !declared.includes(p.id)).map((p) => p.id);
   const result = { workspaceStatusApi: 1, standalone: standalone || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, url: discovery.url, commit: discovery.commit, observedAt: discovery.observedAt, local: ctx.localPath, teams: Object.keys(discovery.workspace?.teams || {}) }, members, packages, declaredPackages: declared, unsynced, stale, external: (discovery.external || []).map((e) => ({ source: e.source, soul: e.soul.name, team: teamLabel(e.soul.team) })), problems: discovery.problems, warnings: discovery.warnings ?? [] };
+  // Workspace automations (0.29.0), from the snapshot `oats sync` took, placed on this host.
+  const actx = scopeAutomations(ctx.deploymentDir, {});
+  result.automations = { host: actx.host.name, snapshot: actx.snapshot ? { takenAt: actx.snapshot.takenAt, problems: actx.snapshot.problems.length } : null, rows: [...actx.triggers, ...actx.schedules].map((a) => ({ kind: a.kind, id: a.id, runsOn: a.runsOn, owner: a.owner, runsHere: a.placement.runsHere, reason: a.placement.reason, enabledHere: a.placement.enabledHere, origin: a.origin, ...(a.invalid ? { invalid: a.invalid } : {}) })) };
+  await workspaceStatusFacts(result, discovery, lock, ctx);
   if (JSON_MODE) { jsonOk(result); return; }
   console.log(`workspace ${workspaceName(discovery)}  (${discovery.key} @ ${short(discovery.commit)})  local ${shortPath(ctx.localPath)}\n`);
   if (standalone) console.log(`  (${standaloneNote(discovery)})\n`);
@@ -1294,14 +1428,51 @@ async function workspaceCmd() {
   for (const m of members.filter((m) => !m.confirmed)) console.log(`    ${m.name}: ${m.detail}`);
   console.log("\nPackages:");
   if (!packages.length) console.log(unsynced.length ? `  (none locked yet — \`oats sync\` resolves ${unsynced.join(", ")})` : "  (none)");
-  else printTable(["package", "version", "source", "commit", "capabilities"], packages.map((p) => [p.id, p.version, p.source, short(p.commit), p.capabilities.join(",")]));
+  else printTable(["package", "version", "source", "commit", "capabilities", "souls"], packages.map((p) => [p.id, p.version, p.source, short(p.commit), p.capabilities.join(","), p.souls.join(",") || "—"]));
   if (packages.length && unsynced.length) console.log(`  declared but not locked (run \`oats sync\`): ${unsynced.join(", ")}`);
   if (stale.length) console.log(`  locked but no longer declared (run \`oats sync\`): ${stale.join(", ")}`);
   if (result.external.length) console.log(`\nExternal: ${result.external.map((e) => `${e.soul} (${e.source.replace(/@([0-9a-f]{40})$/, (_, o) => `@${short(o)}`)}, ${e.team})`).join("   ")}`);
+  if (result.automations.rows.length) {
+    console.log(`\nAutomations (this host: ${result.automations.host ?? "unnamed — set host.name in oats-local.yaml"}):`);
+    printTable(["kind", "id", "runs on", "owner", "here"], result.automations.rows.map((r) => [r.kind, r.id, r.runsOn, r.owner, r.runsHere ? "runs here" : r.invalid ? "invalid" : r.reason ?? "disabled here"]));
+  }
   if (discovery.problems.length) { console.log("\nProblems:"); for (const p of discovery.problems) console.log(`  ${p.code}  ${p.repoKey ? `${memberLabel(p.repoKey)}:` : ""}${p.path}  ${p.message}`); }
   if (discovery.warnings?.length) { console.log("\nWarnings:"); for (const w of discovery.warnings) console.log(`  ${w.code}  ${w.message}`); }
 }
 
+/** `oats workspace status` facts (feature desktop-facts): the workspace and team defaults as rows; this
+ *  computer (member clones and the rule that found each, disabled souls, the lock); file locations with
+ *  browsable urls; each catalog package's newer version, when the official catalog has one. */
+async function workspaceStatusFacts(result, discovery, lock, ctx) {
+  const { memberCloneOf } = await import("../lib/instance-resolution.mjs");
+  const { browseUrl } = remoteModule;
+  const defaults = discovery.standalone === true ? {} : (discovery.workspace?.defaults ?? {});
+  const rows = (entries) => Object.entries(entries && typeof entries === "object" ? entries : {}).map(([name, v]) => ({ name, from: v === "off" ? null : v?.from ?? null, off: v === "off" })).sort((a, b) => (a.name < b.name ? -1 : 1));
+  const slot = (d) => (d && typeof d === "object" ? Object.entries(d).map(([name, v]) => ({ name, from: v?.from ?? null }))[0] ?? null : d ?? null);
+  result.defaults = {
+    slots: Object.fromEntries(LAYERS.map((l) => [l, slot(defaults[l])])),
+    capabilities: rows(defaults.capabilities),
+    byTeam: Object.fromEntries(Object.entries(defaults.byTeam && typeof defaults.byTeam === "object" ? defaults.byTeam : {}).map(([label, t]) => [label, { capabilities: rows(t?.capabilities) }])),
+  };
+  result.workspace.file = discovery.standalone === true ? null : { path: "oats-workspace.yaml", url: browseUrl(discovery.key, discovery.commit, "oats-workspace.yaml") };
+  for (const m of result.members) Object.assign(m, { url: browseUrl(m.key, m.commit), membershipFile: { path: "oats-membership.yaml", url: browseUrl(m.key, m.commit, "oats-membership.yaml") } });
+  result.clones = result.members.map((m) => {
+    try { return { key: m.key, name: m.name, ...memberCloneOf(ctx.deploymentDir, ctx.local, m.key) }; }
+    catch (e) { if (e?.code === "E_CLONE_MISMATCH") return { key: m.key, name: m.name, path: null, rule: null, problem: { code: e.code, message: e.message } }; throw e; }
+  });
+  result.disabledSouls = [...(Array.isArray(ctx.local?.souls?.disabled) ? ctx.local.souls.disabled : [])];
+  result.lock = { path: join(ctx.deploymentDir, LOCK_FILE), lockfileVersion: lock.lockfileVersion ?? null };
+  const { compareSemver } = await import("../lib/servers.mjs");
+  let catalog = null; try { catalog = officialPackageCatalog(); } catch { catalog = null; }
+  const cat = catalog && typeof catalog === "object" ? (catalog.packages && typeof catalog.packages === "object" && !("url" in catalog.packages) ? catalog.packages : catalog) : {};
+  for (const p of result.packages) {
+    const ref = p.source === `catalog:${p.id}` ? cat[p.id]?.ref : undefined;
+    const tag = standaloneCatalogVersion(ref);
+    const version = tag ? tag.replace(/^v/, "") : null;
+    p.latest = version && typeof p.version === "string" && compareSemver(version, p.version) > 0 ? { version, ref } : null;
+  }
+}
+
 /** `oats capabilities` / `oats souls` [--dir] [--json] — contract §6. */
 async function itemsCmd(kind) {
   const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
@@ -1310,6 +1481,10 @@ async function itemsCmd(kind) {
   let lock;
   try { lock = readLock(ctx.deploymentDir); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
   const items = workspaceItems(discovery, lock)[kind];
+  // One command's reads at a commit are shared: many souls resolve over the same manifests and listings.
+  const remote = memoizedRemote(remoteModule);
+  if (kind === "capabilities") await capabilityFacts(items, discovery, lock, ctx, remote);
+  if (kind === "souls") await soulFacts(items, discovery, lock, ctx, remote);
   const standalone = discovery.standalone === true;
   if (JSON_MODE) { jsonOk({ [`${kind}Api`]: 1, standalone: standalone || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, commit: discovery.commit }, [kind]: items, problems: discovery.problems }); return; }
   console.log(`${kind} of workspace ${workspaceName(discovery)} (${discovery.key} @ ${short(discovery.commit)})${standalone ? `  — ${standaloneNote(discovery)}` : ""}\n`);
@@ -1320,6 +1495,60 @@ async function itemsCmd(kind) {
   if (kind === "capabilities" && unsynced.length) console.log(`\n  package capabilities of ${unsynced.join(", ")} appear after \`oats sync\``);
 }
 
+/** Capability rows' manifest facts (feature desktop-facts): layer, description, and what each provides
+ *  (skills, commands, hooks by name) — member rows from discovery's manifest, package rows from the manifest
+ *  at the locked commit (the sync cache; no network beyond sync's). An unreadable package leaves its rows' facts null. */
+async function capabilityFacts(rows, discovery, lock, ctx, remote = remoteModule) {
+  const { capabilityProvides, lockedPackageCapabilities, memberRef } = await import("../lib/resolve.mjs");
+  const remoteOptions = ctx.remoteOptions;
+  const catalog = (() => { try { return officialPackageCatalog(); } catch { return null; } })();
+  const packages = new Map();
+  for (const [id, entry] of Object.entries(lock?.packages || {})) {
+    try { packages.set(id, await lockedPackageCapabilities(id, entry, { catalog, remote, remoteOptions })); } catch { packages.set(id, null); }
+  }
+  // A member capability's fingerprint is its Git tree at the commit (one listing per member commit); a
+  // package's is the package integrity (the lock).
+  const trees = new Map();
+  const treeOf = async ({ repoKey, commit }, ref, dir) => {
+    const key = `${repoKey}\0${commit}`;
+    if (!trees.has(key)) {
+      const member = discovery.members.find((m) => m.key === repoKey);
+      const dirs = rows.filter((r) => r.kind !== "package" && r.repoKey === repoKey && r.commit === commit).map((r) => member?.capabilities.find((c) => c.name === r.name)?.path).filter(Boolean);
+      trees.set(key, remoteModule.remoteTreeOids(ref, commit, [...new Set(dirs)], remoteOptions).catch(() => new Map()));
+    }
+    return (await trees.get(key)).get(dir) ?? null;
+  };
+  for (const row of rows) {
+    let manifest = null, ref = null, dir = null;
+    if (row.kind === "package") {
+      const read = packages.get(row.package), cap = read?.capabilities.find((c) => c.name === row.name);
+      if (cap) ({ manifest, dir } = cap), ref = read.ref;
+    } else {
+      const cap = discovery.members.find((m) => m.key === row.repoKey)?.capabilities.find((c) => c.name === row.name);
+      if (cap) { manifest = cap.manifest; dir = cap.path; ref = memberRef(discovery, remoteModule, row.repoKey); }
+    }
+    const provides = manifest ? await capabilityProvides({ ref, commit: row.commit, dir, manifest, remote, remoteOptions }) : { skills: null, commands: null, hooks: null };
+    const repoKey = row.kind === "package" && ref ? (() => { try { return remoteModule.parseRepoRef(ref).key; } catch { return null; } })() : row.repoKey;
+    const file = dir ? { path: `${dir}/oats.json`, url: remoteModule.browseUrl(repoKey, row.commit, `${dir}/oats.json`) } : null;
+    const tree = row.kind !== "package" && ref && dir ? await treeOf(row, ref, dir) : null;
+    Object.assign(row, { layer: manifest?.layer ?? row.layer ?? null, description: manifest?.description ?? null, ...provides, file, tree });
+  }
+}
+
+/** Souls rows' spawnability (feature desktop-facts): the refusal a spawn of each would meet, computed from
+ *  discovery and the lock without spawning (soulSpawnability). */
+async function soulFacts(rows, discovery, lock, ctx, remote = remoteModule) {
+  const { soulSpawnability } = await import("../lib/instance-resolution.mjs");
+  const entryOf = (row) => row.kind === "package" ? (discovery.packageSouls || []).find((p) => p.qualifiedName === row.qualifiedName)
+    : row.kind === "external" ? (discovery.external || []).map((e) => e.soul).find((x) => x.name === row.name && x.repoKey === row.repoKey)
+    : discovery.members.find((m) => m.key === row.repoKey)?.souls.find((x) => x.name === row.name);
+  for (const row of rows) {
+    const entry = entryOf(row);
+    row.file = { path: `${row.path}/soul.yaml`, url: remoteModule.browseUrl(row.repoKey, row.commit, `${row.path}/soul.yaml`) };
+    Object.assign(row, entry ? await soulSpawnability(ctx.local, discovery, lock, entry, { remoteOptions: ctx.remoteOptions, remote }) : { spawnable: false, problem: { code: "E_SOUL_UNKNOWN", message: `${row.name} is not in this discovery` } });
+  }
+}
+
 // ---------- roster: status / spawn / retire / create ----------
 /** Workspace drift for `oats status` (decision 17: shown, not prevented). ONE discovery over
  *  the remotes serves every instance; `driftOf` compares each instance's recorded modules to
@@ -1343,8 +1572,8 @@ async function statusDrift(data) {
   const souls = new Map();
   for (const a of data) {
     if (!a.dir) continue;
-    try { const stamp = JSON.parse(readFileSync(join(a.dir, ".oats-soul-source.json"), "utf8")); if (stamp && typeof stamp.repoKey === "string") souls.set(a.name, { repoKey: stamp.repoKey, commit: typeof stamp.commit === "string" ? stamp.commit : null, path: stamp.path ?? null }); }
-    catch { /* not a workspace soul (classic, capability agent, or unreadable stamp) */ }
+    try { const stamp = JSON.parse(readFileSync(join(a.dir, ".oats-soul-source.json"), "utf8")); if (stamp && typeof stamp.repoKey === "string") souls.set(a.name, { repoKey: stamp.repoKey, commit: typeof stamp.commit === "string" ? stamp.commit : null, path: stamp.path ?? null, ...(typeof stamp.package === "string" ? { package: stamp.package, version: stamp.version ?? null } : {}) }); }
+    catch { /* not a workspace soul (classic, or an unreadable stamp) */ }
   }
   const anything = data.some((a) => (a.instances || []).some((i) => hasModules(i) || hasSoul(i)));
   if (!anything) return { drift: new Map(), soul: new Map(), souls, unreachable: null };
@@ -1354,7 +1583,7 @@ async function statusDrift(data) {
   let discovery;
   // The standalone view (decisions 10/25) is a discovery too: drift of a standalone
   // instance is computed against its member's current state, not reported "unreachable".
-  try { const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs"); discovery = await discoverOrStandalone(ctx.local, { remoteOptions: remoteOptionsFromEnv() }); }
+  try { const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs"); discovery = await discoverOrStandalone(ctx.local, { lock, remoteOptions: remoteOptionsFromEnv() }); }
   catch (e) {
     const reason = e?.details?.reason ? `${e.code}: ${e.details.reason}` : (e?.code || e?.message || "unknown");
     return { drift: new Map(), soul: new Map(), souls, unreachable: { code: e?.code ?? null, reason, message: e?.message ?? String(e) } };
@@ -1369,6 +1598,7 @@ async function statusDrift(data) {
   }
   // The roster's soul row reflects the CURRENT member commit too (the pointer may lag a moved member).
   for (const [, stamp] of souls) {
+    if (typeof stamp.package === "string") { const now = (discovery.packageSouls || []).find((p) => p.package === stamp.package && p.path === stamp.path); if (now) stamp.current = now.commit; continue; }
     const member = discovery.members.find((m) => m && m.key === stamp.repoKey);
     if (member && typeof member.commit === "string" && (member.confirmed || (discovery.standalone === true && member.key === discovery.key))) stamp.current = member.commit;
   }
@@ -1385,6 +1615,12 @@ function driftLine(row) {
 }
 /** The `soul:` line of an instance — decision 17 for the soul source. */
 function soulDriftLine(row, agentName) {
+  if (row.package) {
+    const base = `soul: ${row.name ?? agentName} from package ${row.package} v${row.version} @ ${short7(row.commit)}`;
+    if (row.status === "moved") return `${base}  [package moved since (now v${row.current?.version} @ ${short7(row.current?.commit)})]`;
+    if (row.status === "missing") return `${base}  [${row.reason === "soul-absent" ? "soul no longer shipped by the package" : "package no longer locked"}]`;
+    return base;
+  }
   const base = `soul: ${row.name ?? agentName} from ${memberLabel(row.repoKey)} @ ${short7(row.commit)}`;
   if (row.status === "moved") return `${base}  [member moved since (now @ ${short7(row.current?.commit)})]`;
   if (row.status === "missing") return `${base}  [${row.reason === "soul-absent" ? "soul no longer present" : `member ${row.reason || "unconfirmed"}`}]`;
@@ -1394,6 +1630,7 @@ function soulDriftLine(row, agentName) {
 function soulRepoLabel(a, ws) {
   const stamp = ws?.souls?.get(a.name);
   if (!stamp) return a.repo || "?";
+  if (typeof stamp.package === "string") return `package ${stamp.package} v${stamp.version} @ ${short7(stamp.commit)}`;
   const moved = stamp.current && stamp.commit && stamp.current !== stamp.commit ? ` (member now @ ${short7(stamp.current)})` : "";
   return `${memberLabel(stamp.repoKey)} @ ${short7(stamp.commit)}${moved}`;
 }
@@ -1417,7 +1654,7 @@ async function status() {
         const rows = ws.drift.get(key);
         if (rows) i.modules = rows.map((r) => ({ name: r.module, from: r.from, commit: r.recorded?.commit ?? null, current: r.current, status: r.status, ...(r.reason ? { reason: r.reason } : {}) }));
         const s = ws.soul.get(key);
-        if (s) i.soul = { repoKey: s.repoKey, commit: s.commit, current: s.current?.commit ?? null, status: s.status, ...(s.reason ? { reason: s.reason } : {}) };
+        if (s) i.soul = { repoKey: s.repoKey, commit: s.commit, current: s.current?.commit ?? null, status: s.status, ...(s.reason ? { reason: s.reason } : {}), ...(s.package ? { package: s.package, version: s.version, currentVersion: s.current?.version ?? null } : {}) };
       }
     }
     console.log(JSON.stringify({ root, agents: data, ...(ws ? { workspace: ws.unreachable ? { reachable: false, ...ws.unreachable } : { reachable: true } } : {}), ...(problems.length ? { problems } : {}), ...envelopeWarnings() }, null, 2)); return;
@@ -1499,16 +1736,16 @@ async function spawnCmd() {
   // the per-commit cache, or fetches it to a temporary copy (reported as soulFetched).
   const providerPairs = [];
   for (let i = 0; i < args.length; i++) if (args[i] === "--provider") { if (!args[i + 1] || !args[i + 2]) bail("E_BAD_ARGS", "--provider needs <capability> <key>=<value>"); providerPairs.push([args[i + 1], args[i + 2]]); i += 2; }
-  let wsPrepared, soulFetched = false, wsSoulUnknown = null, wsDiscovery;
+  let wsPrepared, soulFetched = false, wsDiscovery;
   {
     let discovery = null;
     try {
-      const { prepareInstance, ensureWorkspaceSoul, previewWorkspaceSoul, parseProviderFlags, discoverOrStandalone } = await import("../lib/instance-resolution.mjs");
+      const { prepareInstance, ensureWorkspaceSoul, previewWorkspaceSoul, parseProviderFlags, discoverOrStandalone, agentDirOf } = await import("../lib/instance-resolution.mjs");
       const remoteOptions = remoteOptionsFromEnv();
-      const { local } = loadLocal(dirFlag());
-      discovery = wsDiscovery = await discoverOrStandalone(local, { remoteOptions });
+      const { local, path: localPath } = loadLocal(dirFlag());
+      discovery = wsDiscovery = await discoverOrStandalone(local, { deployment: dirname(localPath), remoteOptions });
       wsPrepared = await prepareInstance(dirFlag(), name, { spawn: { providers: parseProviderFlags(providerPairs) }, remoteOptions, discovery });
-      const soulName = wsPrepared.soulEntry.name;
+      const soulName = agentDirOf(wsPrepared.soulEntry);
       let soulDir;
       if (isPreview) {
         // A preview writes nothing in the deployment: the soul comes from the
@@ -1534,50 +1771,12 @@ async function spawnCmd() {
         const file = officialCatalogFile();
         bail(e.code, `${e.details?.capability ?? "oats.core"}: the catalog has no package providing oats.core (OATS_PACKAGE_CATALOG=${file}) — standalone spawns resolve only the kernel's default package from the catalog`, { ...(e.details ?? {}), standalone: true, reason: "no-catalog", catalog: file });
       }
-      // Not a workspace soul: a capability-defined agent (a module's `agents:`
-      // soul, resolved below from a materialized copy) may still answer to this name.
-      if (e?.code === "E_SOUL_UNKNOWN" && !isPreview) { wsSoulUnknown = e; }
-      else if (e?.code?.startsWith?.("E_")) bail(e.code, e.message, e.details);
+      if (e?.code?.startsWith?.("E_")) bail(e.code, e.message, e.details);
       else throw e;
     }
   }
   if (agentsRootFlag !== undefined && !agent) bail("E_SOUL_UNKNOWN", `soul "${name}" is not at agents root ${String(agentsRootFlag)}`);
   if (isPreview && !agent) bail("E_SOUL_UNKNOWN", `soul "${name}" is not in ${shortPath(root)}; a preview never creates or imports a soul (known: ${listAgents(root).map((a) => a.name).join(", ") || "none"})`);
-  // Capability agent (lead decision c3 Q1): a prepared spawn of its providing module only.
-  let capabilityPrepared, capabilityPkg = null;
-  if (!agent) {
-    // Workspace model: the agent is declared by a capability some INSTANCE already
-    // materialized (the --parent home first, then any home under this root) —
-    // OKF's memory-harvest worker spawned by a knowledge source, for example.
-    const anchorName = flag("parent") || flag("relative-to");
-    const anchorHome = anchorName ? (findInstanceHome(root, String(anchorName)) ?? null) : null;
-    let modAgent;
-    try { modAgent = findModuleCapabilityAgent(root, name, { anchorHome }); }
-    catch (e) { bail(e.code || "E_CAPABILITY_BROKEN", e.message, e.details); }
-    if (modAgent) {
-      agent = modAgent;
-      note(`(capability agent: "${name}" from ${modAgent.capability}, materialized in ${shortPath(modAgent._manifestSource)} — fresh soul, instances home under ${shortPath(join(root, name, "instances"))})`);
-    } else {
-      // No instance carries it: resolve from the deployment's LOCK — a locked
-      // package whose capability declares agents/<name> is fetched into the
-      // deployment's module store and read from there.
-      try {
-        const { resolvePackageCapabilityAgent } = await import("../lib/instance-resolution.mjs");
-        const hit = await resolvePackageCapabilityAgent(dirFlag(), name, { remoteOptions: remoteOptionsFromEnv(), discovery: wsDiscovery, catalog: (() => { try { return officialPackageCatalog(); } catch { return null; } })() });
-        if (hit) {
-          agent = capabilityAgentFromDir(hit.dir, name, root, { module: { from: { kind: "package", package: hit.package, version: hit.version, commit: hit.commit } } });
-          if (agent) { capabilityPkg = hit; note(`(capability agent: "${name}" from ${hit.capability} — package ${hit.package} v${hit.version}, fetched to ${shortPath(hit.dir)} — fresh soul, instances home under ${shortPath(join(root, name, "instances"))})`); }
-        }
-      } catch (e) { if (e?.code?.startsWith?.("E_")) bail(e.code, e.message, e.details); throw e; }
-    }
-    if (agent) {
-      try {
-        const { prepareCapabilityAgent } = await import("../lib/instance-resolution.mjs");
-        capabilityPrepared = await prepareCapabilityAgent(dirFlag(), agent, { discovery: wsDiscovery, pkg: capabilityPkg, remoteOptions: remoteOptionsFromEnv(), catalog: (() => { try { return officialPackageCatalog(); } catch { return null; } })() });
-      } catch (e) { if (e?.code?.startsWith?.("E_")) bail(e.code, e.message, e.details); throw e; }
-    }
-  }
-  if (!agent && wsSoulUnknown) bail(wsSoulUnknown.code, wsSoulUnknown.message, wsSoulUnknown.details);
   checkDirectoryOptions(requestedWork || agent?.work);
   if (!agent) bail("E_UNKNOWN_AGENT", `unknown agent "${name}" (known: ${listAgents(root).map((a) => a.name).join(", ") || "none"}) — a soul is a member repository's souls/<name>; add it there and run \`oats sync\``);
   for (const information of agent.notes || []) note(`[${information.code}] ${information.message}`);
@@ -1606,9 +1805,6 @@ async function spawnCmd() {
   if ((flag("work") === "attached") && relation && relation !== "child") bail("E_BAD_ARGS", "attached agents are always children of the work-tree owner — only --parent <instance> (or --relation child) is valid with --work attached");
   // NOTE: explicit "unrelated" is passed through to the kernel.
   if (relativeTo && relation !== "unrelated") {
-    // findInstanceHome also sees capability-defined agents' instance homes
-    // (<root>/<name>/ without a soul) — e.g. a reviewer passing
-    // --parent "$OATS_INSTANCE" from a capability agent.
     if (!findInstanceHome(root, relativeTo)) bail(parent ? "E_PARENT_NOT_FOUND" : "E_RELATIVE_NOT_FOUND", `${parent ? "--parent" : "--relative-to"} "${relativeTo}" does not match any known instance`);
   }
   const taskText = flag("task");
@@ -1616,6 +1812,17 @@ async function spawnCmd() {
   const taskFileFlag = flag("task-file");
   if (taskFileFlag === true) bail("E_BAD_ARGS", "--task-file needs a path");
   if (taskFileFlag && !existsSync(taskFileFlag)) bail("E_BAD_ARGS", `--task-file not found: ${taskFileFlag}`);
+  // --trigger-event <file>: the event a trigger spawns this instance for (lib/triggers.mjs). It is
+  // copied to <home>/.oats/trigger-event.json (OATS_TRIGGER_EVENT_FILE) and recorded as instance.json.trigger.
+  let triggerEvent;
+  { const f = flag("trigger-event");
+    if (f === true) bail("E_BAD_ARGS", "--trigger-event needs a path");
+    if (f !== undefined) {
+      if (!existsSync(f)) bail("E_BAD_ARGS", `--trigger-event not found: ${f}`);
+      try { triggerEvent = JSON.parse(readFileSync(f, "utf8")); } catch (e) { bail("E_BAD_ARGS", `--trigger-event is not valid JSON: ${e.message}`); }
+      const ok = triggerEvent && typeof triggerEvent === "object" && !Array.isArray(triggerEvent) && typeof triggerEvent.trigger === "string" && typeof triggerEvent.source === "string" && typeof triggerEvent.repo === "string" && Number.isInteger(triggerEvent.number) && typeof triggerEvent.event === "string";
+      if (!ok) bail("E_BAD_ARGS", "--trigger-event must hold { trigger, source, repo, number, url, event, headSha, labels, observedAt }");
+    } }
   const relativeRoot = flag("relative-root");
   if (relativeRoot !== undefined && (relativeRoot === true || !String(relativeRoot).trim())) bail("E_BAD_ARGS", "--relative-root needs an agents-root path");
   if (relativeRoot && !relativeTo) bail("E_BAD_ARGS", "--relative-root only qualifies --relative-to/--parent");
@@ -1657,10 +1864,10 @@ async function spawnCmd() {
   // convention <deployment>/<member name>. Never an ambient Git checkout around the
   // deployment. Resolved once here so a preview sees exactly what the apply would.
   let preparedRepo;
-  if (wsPrepared || capabilityPrepared) {
+  if (wsPrepared) {
     try {
       const { toCapabilityRows, modulesPreview, requireMemberClone } = await import("../lib/instance-resolution.mjs");
-      prepared = wsPrepared ?? capabilityPrepared;
+      prepared = wsPrepared;
       prepared.capabilityRows = []; // filled after materialization (paths live in the home); preview uses modulesPreview
       prepared.preview = modulesPreview(prepared.resolution, root, agent.name);
       prepared.toCapabilityRows = toCapabilityRows;
@@ -1684,6 +1891,7 @@ async function spawnCmd() {
       work: requestedWork, workDir, harness: harnessFlag(), backend, herdrSocket, yolo, model: flag("model"), branch,
       launchConfig: valueFlag("launch-config"),
       launch: !args.includes("--no-launch"),
+      ...(triggerEvent ? { triggerEvent } : {}),
       // K6: --preview decides everything and touches nothing; --base <ref>
       // selects a worktree's start point; --model @native-default is the
       // explicit "harness's own default" (distinct from omitting --model).
@@ -1723,7 +1931,7 @@ async function spawnCmd() {
     if (e?.code === "E_IDEMPOTENCY_CONFLICT") { bail(e.code, e.message, { instance: e.instance, home: e.home }); throw e; }
     if (e?.code === "E_PLACEMENT_TAKEN") { bail(e.code, e.message, { instance: e.instance, home: e.home }); throw e; }
     if (e?.code === "E_INSTANCE_NAME_TAKEN") { bail(e.code, e.message, { instance: e.instance, home: e.home ?? null, ...(e.session ? { session: e.session } : {}) }); throw e; }
-    if (e?.code === "E_INSTANCE_NAME_INVALID") { bail(e.code, e.message); throw e; }
+    if (e?.code === "E_INSTANCE_NAME_INVALID") { bail(e.code, e.message, e.details); throw e; }
     if (e?.code === "E_SPAWN_INCOMPLETE") { bail(e.code, e.message, { instance: e.instance, home: e.home, launched: e.launched }); throw e; }
     bail(["E_BAD_ARGS", "E_RELATIVE_AMBIGUOUS"].includes(e.code) ? e.code : "E_SPAWN_FAILED", e.message || e); throw e;
   }
@@ -1876,7 +2084,7 @@ function retireCmd() {
 /** `oats schedule ...`: workspace-scoped definitions, host-owned execution
  *  (lib/schedule.mjs). Every subcommand answers the envelope; nothing here
  *  launches unless a job is due or run-now is asked. */
-function scheduleCmd() {
+async function scheduleCmd() {
   const sub = args[1];
   const id = args[2] && !args[2].startsWith("--") ? args[2] : undefined;
   // One schedule-owning scope for a directory: its deployment (the directory
@@ -1885,7 +2093,11 @@ function scheduleCmd() {
   let scope;
   const ws = () => (scope ??= scheduleScopeOf(dirFlag()));
   const io = { hostStatus: () => hostUnitStatus() };
-  const out = (result) => { if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2)); };
+  // The workspace automations of this deployment (the snapshot) placed on this host.
+  let actx;
+  const ctx = () => (actx ??= scopeAutomations(ws(), { io }));
+  const isWorkspace = (qid) => A.splitId(qid).scope !== "local";
+  const out = (result, text) => { if (JSON_MODE) jsonOk(result); else console.log(text ? text(result) : JSON.stringify(result, null, 2)); };
   const readSpec = () => {
     const inline = flag("spec-json");
     if (inline && inline !== true) { try { return JSON.parse(inline); } catch (e) { throw scheduleError("E_SCHEDULE_INVALID", `--spec-json is not valid JSON: ${e.message}`, { field: "file" }); } }
@@ -1897,20 +2109,41 @@ function scheduleCmd() {
   const needId = () => { if (!id) throw scheduleError("E_BAD_ARGS", `oats schedule ${sub} <id>`); return id; };
   try {
     switch (sub) {
-      case "list": return out(listSchedules(ws(), io));
-      case "show": return out({ schedule: describeSchedule(ws(), needId(), io) });
-      case "add": { const spec = readSpec(); if (id && spec.id === undefined) spec.id = id; if (id && spec.id !== id) throw scheduleError("E_SCHEDULE_INVALID", `id ${JSON.stringify(spec.id)} in the file does not match ${JSON.stringify(id)}`, { field: "id" }); return out({ schedule: addSchedule(ws(), spec, io) }); }
+      case "list": { const r = listSchedules(ws(), io, { ctx: ctx() }); out(r); if (!JSON_MODE && r.triggers.count) console.log(`${r.triggers.count} trigger${r.triggers.count === 1 ? " is" : "s are"} not listed here: ${r.triggers.command}`); return; }
+      case "show": return out({ schedule: describeSchedule(ws(), needId(), io, { ctx: ctx() }) });
+      case "test": return out({ test: testSchedule(ws(), needId(), io, { ctx: ctx() }) }, (r) => `${r.test.qualifiedId}: ${r.test.placement.runsHere ? "runs here" : `not here (${r.test.placement.reason ?? "disabled here"})`}${r.test.soul ? `; soul ${r.test.soul.name} ${r.test.soul.resolves ? "resolves" : `does NOT resolve (${r.test.soul.error?.code})`}` : ""}; next due ${r.test.nextDue ?? "never"}${r.test.problems.length ? `\n  ${r.test.problems.join("\n  ")}` : ""}\n(spawned nothing)`);
+      case "add": {
+        const spec = readSpec();
+        if (flag("workspace") !== undefined) {
+          const wid = id ?? spec.id;
+          if (typeof wid !== "string") throw scheduleError("E_BAD_ARGS", "oats schedule add <id> --workspace <member> …: the id names the file (oats-schedules/<id>.yaml)");
+          const { id: _i, enabled: _e, kind, ...rest } = spec; void _i; void _e;
+          const r = await addWorkspaceAutomation(scheduleKind({ dep: ws() }), { id: wid, body: { run: kind ?? "spawn", ...rest } });
+          return out(r, printWorkspaceAdd);
+        }
+        if (id && spec.id === undefined) spec.id = id;
+        if (id && spec.id !== id) throw scheduleError("E_SCHEDULE_INVALID", `id ${JSON.stringify(spec.id)} in the file does not match ${JSON.stringify(id)}`, { field: "id" });
+        return out({ schedule: addSchedule(ws(), spec, io) });
+      }
       case "update": return out({ schedule: updateSchedule(ws(), needId(), readSpec(), io) });
-      case "enable": return out({ schedule: setScheduleEnabled(ws(), needId(), true, io) });
-      case "disable": return out({ schedule: setScheduleEnabled(ws(), needId(), false, io) });
-      case "run": return out(runScheduleNow(ws(), needId(), { io, force: args.includes("--force") }));
+      case "enable":
+      case "disable": {
+        const on = sub === "enable";
+        if (!isWorkspace(needId())) return out({ schedule: setScheduleEnabled(ws(), id, on, io) });
+        describeSchedule(ws(), id, io, { ctx: ctx() }); // an unknown id is refused before the file changes
+        setDisabledHereCli(ws(), "schedule", A.qualifiedId(id), on);
+        actx = undefined;
+        return out({ schedule: describeSchedule(ws(), id, io, { ctx: ctx() }) });
+      }
+      case "run": return out(runScheduleNow(ws(), needId(), { io, force: args.includes("--force"), ctx: ctx() }));
       case "remove": return out(removeSchedule(ws(), needId(), { force: args.includes("--force") }));
-      case "reconcile": return out(reconcileSchedule(ws(), needId(), { io, clear: args.includes("--clear") }));
+      case "reconcile": return out(reconcileSchedule(ws(), needId(), { io, clear: args.includes("--clear"), ctx: ctx() }));
       case "tick": {
         const dryRun = args.includes("--dry-run");
         if (args.includes("--host")) return out(tickHost({ io, dryRun }));
         const reg = readRegistry();
-        const considered = withHostLock(() => tickWorkspace(ws(), { io, reg, wsList: reg.workspaces.includes(ws()) ? reg.workspaces : [...reg.workspaces, ws()], dryRun }));
+        const tctx = scopeAutomations(ws(), { io, refresh: !dryRun });
+        const considered = withHostLock(() => [...(tctx.refresh && !tctx.refresh.ok ? [{ workspace: ws(), action: "error", error: `automations refresh: ${tctx.refresh.error}` }] : []), ...tickWorkspace(ws(), { io, reg, wsList: reg.workspaces.includes(ws()) ? reg.workspaces : [...reg.workspaces, ws()], dryRun, ctx: tctx }), ...tickTriggers(ws(), { io, dryRun, ctx: tctx })]);
         return out({ tickedAt: new Date().toISOString(), considered, scheduler: schedulerStatus(ws(), io) });
       }
       case "host": {
@@ -1920,7 +2153,7 @@ function scheduleCmd() {
         if (op === "status") return out({ scheduler: schedulerStatus(ws(), io) });
         throw scheduleError("E_BAD_ARGS", "oats schedule host install|uninstall|status");
       }
-      default: throw scheduleError("E_BAD_ARGS", "usage: oats schedule list|show <id>|add <id> --file <spec.json>|update <id> --file <spec.json>|enable <id>|disable <id>|run <id> [--force]|remove <id> [--force]|reconcile <id> [--clear]|tick [--dry-run] [--host]|host install|uninstall|status [--dir <workspace>|--server <id>] [--json]");
+      default: throw scheduleError("E_BAD_ARGS", "usage: oats schedule list|show <id>|test <id>|add <id> --file <spec.json> [--workspace <member> --runs-on <host> --owner <host>/<login>]|update <id> --file <spec.json>|enable <id>|disable <id>|run <id> [--force]|remove <id> [--force]|reconcile <id> [--clear]|tick [--dry-run] [--host]|host install|uninstall|status [--dir <workspace>|--server <id>] [--json]");
     }
   } catch (e) {
     // K8b: typed refusal details travel (identity mismatch: key/declared; a refused file: its integrity source).
@@ -1929,6 +2162,101 @@ function scheduleCmd() {
   }
 }
 
+/** `oats trigger …` (lib/triggers.mjs): event-driven spawns stored beside the schedules of the
+ *  deployment scope and evaluated by the same host tick. Every subcommand answers the envelope. */
+async function triggerCmd() {
+  const sub = args[1];
+  const id = args[2] && !args[2].startsWith("--") ? args[2] : undefined;
+  const T = await import("../lib/triggers.mjs");
+  let scope;
+  const ws = () => (scope ??= scheduleScopeOf(dirFlag()));
+  const out = (result, text) => { if (JSON_MODE) jsonOk(result); else console.log(text ? text(result) : JSON.stringify(result, null, 2)); };
+  const needId = () => { if (!id) throw T.triggerError("E_BAD_ARGS", `oats trigger ${sub} <id>`); return id; };
+  const usage = "usage: oats trigger add (--file <trigger.json> | --from <package>:<template> [--set <name>=<value>]… [--id <id>]) [--workspace <member> --runs-on <host> --owner <host>/<login>] | list | show <id> | enable <id> | disable <id> | remove <id> | test <id> | status [<id>]  [--dir <deployment>] [--json]   (<id>: local/<id> or <member>/<id>)";
+  const where = (t) => (t.origin?.kind === "workspace" ? (t.runsHere ? `runs here as ${t.owner}` : `${t.reason === "assigned-elsewhere" ? `runs on ${t.runsOn}` : t.reason ?? "disabled here"}`) : t.enabledHere ? "local" : "local, disabled");
+  const line = (t) => `${t.id}  ${where(t)}  ${t.on?.source ?? "?"} ${t.on?.repo ?? "?"} [${(t.on?.events || []).join(",")}]${t.on?.labels?.length ? ` labels ${t.on.labels.join(",")}` : ""} every ${t.on?.poll ?? "?"} → spawn ${t.spawn?.soul ?? "?"}${t.spawn?.teams?.length ? ` in ${t.spawn.teams.join(",")}` : ""}${t.invalid ? `  INVALID: ${t.invalid.message}` : ""}`;
+  // The workspace automations of this deployment (the snapshot) placed on this host.
+  let actx;
+  const ctx = () => (actx ??= scopeAutomations(ws(), {}));
+  const isWorkspace = (qid) => A.splitId(qid).scope !== "local";
+  try {
+    switch (sub) {
+      case "list": return out(T.listTriggers(ws(), ctx(), { io: { hostStatus: () => hostUnitStatus() } }), (r) => r.triggers.length ? r.triggers.map(line).join("\n") : "(no triggers — oats trigger add --file <trigger.json> | --from <package>:<template>)");
+      case "show": return out({ trigger: T.describeTrigger(ws(), needId(), ctx()) });
+      case "enable":
+      case "disable": {
+        const on = sub === "enable";
+        if (!isWorkspace(needId())) return out({ trigger: T.setTriggerEnabled(ws(), id, on, ctx()) }, (r) => line(r.trigger));
+        T.describeTrigger(ws(), id, ctx()); // an unknown id is refused before the file changes
+        setDisabledHereCli(ws(), "trigger", A.qualifiedId(id), on);
+        actx = undefined;
+        return out({ trigger: T.describeTrigger(ws(), id, ctx()) }, (r) => line(r.trigger));
+      }
+      case "remove": return out(T.removeTrigger(ws(), needId(), ctx()), (r) => `removed trigger ${r.removed}${r.live.length ? ` (its live instances keep running: ${r.live.join(", ")})` : ""}`);
+      case "status": return out(T.triggerStatus(ws(), id, ctx()), (r) => r.triggers.map((t) => `${t.id}  last poll ${t.lastPoll ? `${t.lastPoll.at} ${t.lastPoll.ok ? `ok (${t.lastPoll.matching}/${t.lastPoll.prs} PRs match)` : `FAILED: ${t.lastPoll.error}`}` : "never"}  pending ${t.pending.length}  fired ${t.firedTotal}  live ${t.live.map((l) => l.instance).join(",") || "none"}${t.lastError ? `\n    last error ${t.lastError.at}: ${t.lastError.message}` : ""}`).join("\n") || "(no triggers)");
+      case "test": {
+        let workspaceTeams = null;
+        try {
+          const { observeWorkspace } = await import("../lib/workspace.mjs");
+          const { local } = loadLocal(ws());
+          if (typeof local.workspace === "string") workspaceTeams = Object.keys((await observeWorkspace(local.workspace, { remoteOptions: remoteOptionsFromEnv() })).workspace.teams || {});
+        } catch { /* reported as unknown (null) */ }
+        return out(T.testTrigger(ws(), needId(), { workspaceTeams, ctx: ctx() }), (r) => [
+          `trigger ${r.id}: ${r.ok ? "ready" : "NOT ready"} (nothing was spawned)`,
+          `  placement  ${r.placement.runsOn ? `runs on ${r.placement.runsOn} as ${r.placement.owner}; this host is ${r.placement.host ?? "(unnamed)"} — ${r.placement.runsHere ? "runs here" : r.placement.reason ?? "disabled here"}` : "local (this host)"}`,
+          `  gh auth    ${r.gh.ok ? `ok — ${r.gh.account ?? "?"} via ${r.gh.credentialSource}` : `FAILED${r.gh.detail ? ` — ${r.gh.detail}` : ""}`}`,
+          `  repo       ${r.repo.key} ${r.repo.readable ? `readable; push ${r.repo.permissions.push} maintain ${r.repo.permissions.maintain} admin ${r.repo.permissions.admin}` : `NOT readable: ${r.repo.error}`}`,
+          `  soul       ${r.soul.name} ${r.soul.resolves ? `resolves${r.soul.messaging ? ` (messaging ${r.soul.messaging})` : ""}` : `does NOT resolve: ${r.soul.error.code} ${r.soul.error.message}`}`,
+          `  teams      ${r.teams.requested.join(", ") || "(none)"}${r.teams.undeclared?.length ? `  undeclared: ${r.teams.undeclared.join(", ")}` : ""}`,
+          `  would fire ${r.wouldFire.length ? r.wouldFire.map((w) => `${w.event} #${w.number}${w.held ? ` (held: ${w.held})` : ""}`).join(", ") : "nothing now"}`,
+          ...r.problems.map((p) => `  problem    ${p}`),
+          ...(r.warnings ?? []).map((w) => `  warning    ${w}`),
+        ].join("\n"));
+      }
+      case "add": {
+        const file = flag("file"), from = flag("from");
+        if ((file === undefined) === (from === undefined)) throw T.triggerError("E_BAD_ARGS", `oats trigger add needs exactly one of --file <trigger.json> or --from <package>:<template>\n${usage}`);
+        const sets = {};
+        for (let i = 0; i < args.length; i++) if (args[i] === "--set") {
+          const kv = args[i + 1];
+          if (typeof kv !== "string" || !kv.includes("=")) throw T.triggerError("E_BAD_ARGS", "--set needs <name>=<value>");
+          sets[kv.slice(0, kv.indexOf("="))] = kv.slice(kv.indexOf("=") + 1); i++;
+        }
+        const idFlag = flag("id");
+        if (idFlag === true) throw T.triggerError("E_BAD_ARGS", "--id needs a trigger id");
+        let spec;
+        if (file !== undefined) {
+          if (file === true || !existsSync(file)) throw T.triggerError("E_BAD_ARGS", `--file ${file === true ? "needs a path" : `not found: ${file}`}`);
+          if (Object.keys(sets).length) throw T.triggerError("E_BAD_ARGS", "--set fills a package template's parameters; with --file, edit the file");
+          try { spec = JSON.parse(readFileSync(file, "utf8")); } catch (e) { throw T.triggerError("E_TRIGGER_INVALID", `${file} is not valid JSON: ${e.message}`, { details: { field: "file" } }); }
+          if (idFlag !== undefined) spec.id = idFlag;
+        }
+        if (flag("workspace") !== undefined) {
+          // A workspace trigger (0.29.0): the file in the member, from/set when made from a template.
+          const kinds = await automationKinds(ws(), readLock(ws()), remoteOptionsFromEnv());
+          const wid = typeof idFlag === "string" ? idFlag : from !== undefined ? String(from).split(":")[1] : spec?.id;
+          if (typeof wid !== "string") throw T.triggerError("E_BAD_ARGS", "--workspace: name the trigger with --id (or an id in the file)");
+          const body = from !== undefined ? { from: String(from), ...(Object.keys(sets).length ? { set: sets } : {}) } : (({ id: _i, kind: _k, enabled: _e, template: _t, createdAt: _c, updatedAt: _u, ...rest }) => rest)(spec);
+          const r = await addWorkspaceAutomation(kinds.trigger, { id: wid, body });
+          return out(r, printWorkspaceAdd);
+        }
+        if (spec === undefined) spec = await triggerFromPackage(T, String(from), sets, idFlag);
+        return out({ trigger: T.addTrigger(ws(), spec) }, (r) => `added ${line(r.trigger)}\n(\`oats trigger test ${r.trigger.id}\` checks gh, the repository, the soul and the teams on this host)`);
+      }
+      default: throw T.triggerError("E_BAD_ARGS", usage);
+    }
+  } catch (e) {
+    const details = { ...(e.details && typeof e.details === "object" ? e.details : {}), ...(e.field !== undefined ? { field: e.field } : {}) };
+    if (JSON_MODE) jsonFail(e.code || "E_TRIGGER_FAILED", e.message, Object.keys(details).length ? details : undefined); else die(e.message);
+  }
+}
+/** A package trigger template (`triggers: [{ id, file }]` in the locked package's oats-package.json),
+ *  read at the lock's commit and instantiated with the --set parameters. */
+async function triggerFromPackage(T, from, sets, idFlag) {
+  const { bindRemote } = await import("../lib/packages.mjs");
+  return T.packageTriggerTemplate(readLock(scheduleScopeOf(dirFlag())), from, sets, { id: idFlag, remote: bindRemote(remoteModule, remoteOptionsFromEnv()) });
+}
+
 async function sessionCmd() {
   try {
     if (flag("native-record") !== undefined) throw Object.assign(new Error("--native-record outcome inspection is gone (the captured/portable path was removed in 0.26)"), { code: "E_BAD_ARGS" });
@@ -2175,7 +2503,7 @@ async function capabilityCommand() {
     // No home, so no recorded soul: the soul's per-commit copy is OATS_SOUL when a spawn
     // already fetched exactly this commit; otherwise the command gets none (never ambient).
     const cachedSoul = hit.soul?.commit ? join(hit.deployment, "agents", hit.soul.name, "souls", String(hit.soul.commit).slice(0, 12)) : null;
-    return runManifestCommand({ capability: hit.module.name, ...hit.manifest }, hit.settings, teamCtx, hit.ensureTree, cachedSoul && existsSync(join(cachedSoul, "soul.yaml")) ? realpathSync(cachedSoul) : undefined);
+    return runManifestCommand({ capability: hit.module.name, ...hit.manifest }, { settings: hit.settings, origins: hit.resolution?.payloadOrigins?.[hit.module.name] }, teamCtx, hit.ensureTree, cachedSoul && existsSync(join(cachedSoul, "soul.yaml")) ? realpathSync(cachedSoul) : undefined);
   }
 
   async function dispatch() {
@@ -2189,14 +2517,14 @@ async function capabilityCommand() {
     // braces: the ids come from instance.json, which spawn wrote from resolved
     // manifests. Null-prototype because the dispatcher indexes it with the
     // namespace the operator typed on the command line.
-    let capSettings = Object.create(null);
+    let capSettings = Object.create(null), capOrigins = Object.create(null);
     let deployment = null;
     let soulDir;
     try {
       if (metaFile && existsSync(metaFile)) {
         const meta = JSON.parse(readFileSync(metaFile, "utf8"));
         activeIds = (meta.capabilities || []).map((c) => c.id);
-        for (const c of meta.capabilities || []) capSettings[c.id] = c.settings || {};
+        for (const c of meta.capabilities || []) { capSettings[c.id] = c.settings || {}; capOrigins[c.id] = c.settingsOrigins || {}; }
         // Workspace-model homes only (lead decision c3 Q2).
         if (isCapturedHome(meta)) { const e = capturedHomeRefusal(instanceHome, "nothing was dispatched"); bail(e.code, e.message, e.details); }
         if (!isWorkspaceHome(meta)) { const e = preWorkspaceHome(instanceHome, "nothing was dispatched"); bail(e.code, e.message); }
@@ -2235,14 +2563,14 @@ async function capabilityCommand() {
       const live = await liveTeams(instanceHome, homeMeta.meta, { remoteOptions: remoteOptionsFromEnv() });
       teamCtx = homeTeamCtx(live.teams, live.source);
     }
-    return runManifestCommand(m, capSettings[m.capability] || {}, teamCtx, () => m._dir, soulDir);
+    return runManifestCommand(m, { settings: capSettings[m.capability] || {}, origins: capOrigins[m.capability] }, teamCtx, () => m._dir, soulDir);
   }
 
   /** Help / unknown-command / spec validation / exec — shared by every context.
    *  `m` is the manifest (with `capability`; `_dir` may be absent until `ensureDir`
    *  resolves the directory holding the executable — the operator branch fetches
    *  the module tree only when a command is actually going to run). */
-  async function runManifestCommand(m, settings, teamCtx, ensureDir, soulDir) {
+  async function runManifestCommand(m, { settings, origins }, teamCtx, ensureDir, soulDir) {
     const sub = args[1];
     const cmds = Object.keys(m.commands);
     // `oats <ns> --help` and `oats <ns> <cmd> --help` answer from the manifest
@@ -2279,7 +2607,7 @@ async function capabilityCommand() {
     // OATS_SOUL is the recorded soul or nothing: an ambient value inherited from the
     // invoking process names some other soul (a coordinator's own), never this one.
     const { OATS_SOUL: _ambientSoul, ...inherited } = process.env;
-    const r = spawnSync("node", [abs, ...rest, ...args.slice(2)], { stdio: "inherit", env: {
+    const r = spawnSync("node", [abs, ...rest, ...rawArgs.slice(2)], { stdio: "inherit", env: {
       ...inherited, OATS_CAPABILITY: m.capability,
       // Package-runtime boundary: dispatched commands receive the active
       // capability's EFFECTIVE settings (instance snapshot, resolved context, or
@@ -2287,6 +2615,8 @@ async function capabilityCommand() {
       // lifecycle hooks — capabilities read their settings here instead of
       // importing the kernel resolver.
       OATS_SETTINGS: JSON.stringify(settings || {}),
+      // Where each leaf came from (JSON pointer → { kind, at }), as lifecycle hooks get it.
+      OATS_SETTINGS_ORIGINS: JSON.stringify(origins || {}),
       // PATH is not a trusted runtime boundary (maintainer finding 1): pass the
       // canonical absolute executable of THIS CLI; official consumers execFile
       // it directly and never resolve `oats` from PATH or a shell.
@@ -2356,7 +2686,7 @@ function versionCmd() {
     // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
     // runs on resolve/materialize (contract §6); a feature the binary does not implement is
     // never listed.
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "teams", "settings-declared", "capabilities-private", "layers-from", "harness"], workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2 }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "teams", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2 }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -2495,7 +2825,7 @@ async function serverRouteCmd() {
   // so its explicit --dir travels; every other routed command takes its
   // scope from the registration.
   const explicitScopeOk = ["inspect", "operation", "launch-config"].includes(cmd);
-  if (!explicitScopeOk && (flag("dir") !== undefined || args.some((a) => a.startsWith("--dir=")))) bail("E_BAD_ARGS", "--dir cannot be combined with --server: the remote workspace comes from the server registration");
+  if (!explicitScopeOk && flag("dir") !== undefined) bail("E_BAD_ARGS", "--dir cannot be combined with --server: the remote workspace comes from the server registration");
   if (cmd === "launch-config") {
     const action = args[1];
     const value = (name) => { const v = flag(name); if (v === true) bail("E_BAD_ARGS", `--${name} needs a value`); return v; };
@@ -2715,13 +3045,16 @@ try {
 // resolved against the current context instead. `version` answers regardless:
 // host protocol negotiation describes this executable.
 {
+  // The kernel's own argv only: a capability command's flags are its provider's to parse.
+  const kernelArgv = (KERNEL_COMMANDS.has(cmd) && !OWN_ARGV_COMMANDS.has(cmd)) || (ROUTED_COMMANDS.has(cmd) && flag("server") !== undefined);
+  if (argvProblem && kernelArgv) cmdFail("E_BAD_ARGS", argvProblem);
   const end = args.indexOf("--"), head = end < 0 ? args : args.slice(0, end);
-  const selector = head.find((a) => /^--(deployment|resolution|artifact-set)(=|$)/.test(a));
+  const selector = head.find((a) => /^--(deployment|resolution|artifact-set)$/.test(a));
   const refuse = (message, details) => { if (JSON_MODE) jsonFail("E_UNSUPPORTED_MODE", message, details); die(message); };
-  if (selector) refuse(`${selector.split("=")[0]}: a captured selector is refused (the captured/portable path was removed in 0.26); run the command in its workspace deployment or instance home instead`, { selector: selector.split("=")[0] });
+  if (selector) refuse(`${selector}: a captured selector is refused (the captured/portable path was removed in 0.26); run the command in its workspace deployment or instance home instead`, { selector });
   const inherited = ["OATS_RESOLUTION", "OATS_DEPLOYMENT"].filter((k) => process.env[k]);
   if (inherited.length && cmd !== "version") refuse(`this environment carries a captured context (${inherited.join(", ")}): the captured/portable path was removed in 0.26, and nothing is run against the current context in its place — retire the captured home and re-spawn it from the deployment`, { inherited });
-  if (cmd === "inspect" && head.some((a) => a === "--request" || a.startsWith("--request="))) {
+  if (cmd === "inspect" && head.includes("--request")) {
     const message = "oats inspect --request (portable onboarding inspection) is gone (the captured/portable path was removed in 0.26); use `oats onboard` / `oats sync` to set up a workspace and `oats spawn <soul> --preview` to see what a spawn would resolve";
     if (JSON_MODE) jsonFail("E_UNKNOWN_COMMAND", message, { removed: "inspect --request", replacement: "oats onboard / oats sync; oats spawn --preview" });
     die(message);
@@ -2738,7 +3071,7 @@ else {
 // `okf harvest --help` spawned a harvester (BeadHub, 2026-09-05).
 const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
 if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
-if (flag("server") !== undefined && ["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config"].includes(cmd)) await serverRouteCmd();
+if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
 else if (cmd === "server") serverCmd();
 else if (cmd === "inspect") await inspectCmd();
 else if (cmd === "operation") await operationCmd();
@@ -2767,7 +3100,9 @@ else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
 // Same rule as the inner catch: a typed CLI failure surfaces with its own code
 // through the shared boundary, never re-badged as a spawn-mechanism failure.
 else if (cmd === "session") await sessionCmd();
-else if (cmd === "schedule") scheduleCmd();
+else if (cmd === "schedule") await scheduleCmd();
+else if (cmd === "trigger") await triggerCmd();
+else if (cmd === "automations") await automationsCmd();
 else if (cmd === "spawn") { try { await spawnCmd(); } catch (e) { if (TYPED_CLI_FAILURES.has(e?.code)) throw e; if (JSON_MODE) jsonFail("E_SPAWN_FAILED", e.message || e); throw e; } }
 else if (cmd === "retire") retireCmd();
 else if (cmd === "capture" || cmd === "recall" || cmd === "setup") await recordCmd(cmd);
@@ -2856,11 +3191,22 @@ Usage:
                                             next steps (clone members you work IN, spawn
                                             oats-operator-expert); creates no soul, spawns nothing
   oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
-  oats schedule list|show <id>|add <id> --file <spec.json>|update <id> --file <spec.json>
+  oats schedule list|show <id>|test <id>|add <id> --file <spec.json>|update <id> --file <spec.json>
       enable|disable|run|remove|reconcile <id>   workspace-scoped, host-owned schedules (spawn,
       tick [--dry-run] [--host]                  command or wake jobs on a five-field cron with an
       host install|uninstall|status              explicit IANA tz; see docs/schedules.md); --server
                                                 routes to that host's workspace
+  oats trigger add (--file <json> | --from <package>:<template> [--set k=v]) | list | show | enable
+      | disable | remove <id> | test <id> | status [<id>]   event-driven spawns (github.pull_request
+                                                polled with the host's gh by the schedule tick;
+                                                see docs/schedules.md#triggers)
+  oats trigger|schedule add … --workspace <member> --runs-on <host> --owner <host>/<login>
+                                                a trigger/schedule declared in Git (<member>/<id>):
+                                                writes oats-triggers|oats-schedules/<id>.yaml in a
+                                                checkout of the member, else prints it
+  oats automations refresh [--json]          re-discover the workspace triggers and schedules
+                                                (the snapshot the host tick reads; oats sync does
+                                                it too)
   oats spawn ... --wake-file <json> | --wake-every <N> --wake-message <text>  save a wake schedule
                                                 bound to the new instance's home (docs/schedules.md)
   oats session upload --file <path>          store a copy of a local file as a private attachment
@@ -2894,6 +3240,9 @@ Usage:
       [--name <slug>]                        the exact instance name (no <agent>- prefix;
                                             not with --purpose); must be a slug, not a
                                             soul name, and unused in the deployment
+      [--provider <capability> <key>=<value>]  a provider setting for this spawn only
+                                            (repeatable; dotted keys nest; recorded in
+                                            instance.json providers.<capability>)
   oats retire <instance> [--force]           retire an instance (window, hooks,
       [--self] [--delete-branch]            worktree, home); --self = retire the
       [--keep-dir] [--json]                 CALLING instance: the window dies, then