@awebai/oats 0.28.0 → 0.29.1

package/bin/oats.mjs

@@ -27,10 +27,10 @@ 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, discoverPackageSouls, workspaceWarnings } from "../lib/workspace.mjs";
 import { parseConfigData } from "../lib/config-data.mjs";
@@ -39,7 +39,8 @@ 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 { tickTriggers } from "../lib/triggers.mjs";
-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 * 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";
 
@@ -70,7 +71,7 @@ function expandInlineValues(argv) {
 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. */
@@ -957,7 +958,8 @@ function instanceCmd() {
       console.log(`  upstream: ${observed.upstream.ref ? `${observed.upstream.ref} +${observed.upstream.ahead} -${observed.upstream.behind}` : "none (ahead/behind unknown)"}`);
       console.log(`  base: ${observed.base.ref ? `${observed.base.ref} +${observed.base.ahead} -${observed.base.behind} (merge-base ${observed.base.mergeBase?.slice(0, 12)})` : "unknown"}`);
       console.log(`  files: ${observed.files.length} (${Object.entries(observed.summary).filter(([, n]) => n).map(([k, n]) => `${n} ${k}`).join(", ") || "clean"})`);
-      for (const f of observed.files) console.log(`    ${f.xy} ${f.origPath ? `${f.origPath} -> ` : ""}${f.path}  [${f.id}]`);
+      const lines = (f) => (f.binary ? "  binary" : Number.isInteger(f.additions) ? `  +${f.additions} -${f.deletions}` : "");
+      for (const f of observed.files) console.log(`    ${f.xy} ${f.origPath ? `${f.origPath} -> ` : ""}${f.path}${lines(f)}  [${f.id}]`);
       for (const n of observed.notes) console.log(`  note: ${n}`);
       return;
     }
@@ -1072,6 +1074,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). */
@@ -1080,15 +1086,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 });
+    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 });
@@ -1164,11 +1170,17 @@ async function performSync(ctx, bail, { onDiscovered } = {}) {
   // 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 };
 }
 
@@ -1207,11 +1219,91 @@ function printSyncReport(ctx, synced) {
   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));
@@ -1325,6 +1417,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`);
@@ -1337,10 +1433,47 @@ async function workspaceCmd() {
   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));
@@ -1349,6 +1482,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`);
@@ -1359,6 +1496,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
@@ -1383,7 +1574,7 @@ async function statusDrift(data) {
   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, ...(typeof stamp.package === "string" ? { package: stamp.package, version: stamp.version ?? null } : {}) }); }
-    catch { /* not a workspace soul (classic, capability agent, or unreadable stamp) */ }
+    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 };
@@ -1546,7 +1737,7 @@ 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 {
@@ -1581,50 +1772,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}`);
@@ -1653,9 +1806,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");
@@ -1715,10 +1865,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;
@@ -1782,7 +1932,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;
   }
@@ -1935,7 +2085,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
@@ -1944,7 +2094,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" }); } }
@@ -1956,20 +2110,41 @@ function scheduleCmd() {
   const needId = () => { if (!id) throw scheduleError("E_BAD_ARGS", `oats schedule ${sub} <id>`); return id; };
   try {
     switch (sub) {
-      case "list": { const r = listSchedules(ws(), io); 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) });
-      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 }), ...tickTriggers(ws(), { io, 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": {
@@ -1979,7 +2154,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).
@@ -1998,16 +2173,28 @@ async function triggerCmd() {
   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>]) | list | show <id> | enable <id> | disable <id> | remove <id> | test <id> | status [<id>]  [--dir <deployment>] [--json]";
-  const line = (t) => `${t.id}  ${t.enabled ? "enabled " : "disabled"}  ${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}` : ""}`;
+  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()), (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()) });
-      case "enable": return out({ trigger: T.setTriggerEnabled(ws(), needId(), true) }, (r) => line(r.trigger));
-      case "disable": return out({ trigger: T.setTriggerEnabled(ws(), needId(), false) }, (r) => line(r.trigger));
-      case "remove": return out(T.removeTrigger(ws(), needId()), (r) => `removed trigger ${r.removed}${r.live.length ? ` (its live instances keep running: ${r.live.join(", ")})` : ""}`);
-      case "status": return out(T.triggerStatus(ws(), id), (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 "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 {
@@ -2015,8 +2202,9 @@ async function triggerCmd() {
           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 }), (r) => [
+        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}`}`,
@@ -2043,7 +2231,17 @@ async function triggerCmd() {
           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;
-        } else spec = await triggerFromPackage(T, String(from), sets, 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);
@@ -2056,28 +2254,8 @@ async function triggerCmd() {
 /** 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 m = /^([a-z0-9][a-z0-9._-]*):([a-z0-9][a-z0-9._-]*)$/.exec(from);
-  if (!m) throw T.triggerError("E_BAD_ARGS", `--from ${JSON.stringify(from)}: write <package>:<template>, e.g. oats.okf:harvest-review`);
-  const [, pkg, template] = m;
-  const deployment = scheduleScopeOf(dirFlag());
-  const lock = readLock(deployment);
-  const entry = lock.packages[pkg];
-  if (!entry) throw T.triggerError("E_PACKAGE_MISSING", `package ${pkg} is not in ${LOCK_FILE} — declare it in packages: and run \`oats sync\``, { details: { package: pkg } });
-  const { lockedPackageRef, bindRemote } = await import("../lib/packages.mjs");
-  const ref = lockedPackageRef(entry);
-  const remote = bindRemote(remoteModule, remoteOptionsFromEnv());
-  const read = async (rel, what) => {
-    let bytes;
-    try { ({ bytes } = await remote.readRemoteFile(ref, entry.commit, `${entry.path}/${rel}`)); }
-    catch (e) { throw T.triggerError(e?.code === "E_REMOTE_PATH_MISSING" ? "E_PACKAGE_MANIFEST" : (e?.code || "E_REMOTE_UNREADABLE"), `${pkg} v${entry.version}: ${what} ${entry.path}/${rel} cannot be read: ${e.message}`, { details: { package: pkg, path: rel } }); }
-    try { return JSON.parse(Buffer.from(bytes).toString("utf8")); } catch (e) { throw T.triggerError("E_PACKAGE_MANIFEST", `${pkg} v${entry.version}: ${what} ${entry.path}/${rel} is not valid JSON: ${e.message}`, { details: { package: pkg, path: rel } }); }
-  };
-  const manifest = await read("oats-package.json", "the package manifest");
-  const listed = Array.isArray(manifest.triggers) ? manifest.triggers : [];
-  const row = listed.find((t) => t && t.id === template);
-  if (!row || typeof row.file !== "string" || !row.file || row.file.split("/").includes("..") || row.file.startsWith("/")) throw T.triggerError("E_TRIGGER_UNKNOWN", `package ${pkg} v${entry.version} has no trigger template ${JSON.stringify(template)} (templates: ${listed.map((t) => t?.id).filter(Boolean).join(", ") || "none"})`, { details: { package: pkg, template, templates: listed.map((t) => t?.id).filter(Boolean) } });
-  const doc = await read(row.file, `trigger template ${template}`);
-  return T.instantiateTemplate(doc, sets, { id: idFlag, provenance: { package: pkg, version: entry.version, commit: entry.commit, template } });
+  const { bindRemote } = await import("../lib/packages.mjs");
+  return T.packageTriggerTemplate(readLock(scheduleScopeOf(dirFlag())), from, sets, { id: idFlag, remote: bindRemote(remoteModule, remoteOptionsFromEnv()) });
 }
 
 async function sessionCmd() {
@@ -2326,7 +2504,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() {
@@ -2340,14 +2518,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); }
@@ -2386,14 +2564,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
@@ -2438,6 +2616,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.
@@ -2507,7 +2687,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", "package-souls", "triggers"], 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)`);
@@ -2921,8 +3101,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);
@@ -3011,7 +3192,7 @@ 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
@@ -3020,6 +3201,13 @@ Usage:
       | 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
@@ -3053,6 +3241,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