@awebai/oats 0.27.2 → 0.29.0

package/lib/schedule.mjs

@@ -29,6 +29,9 @@ import { fileURLToPath } from "node:url";
 import { Cron } from "croner";
 import { loadLocal } from "./workspace.mjs";
 import { noteRuntimeName } from "./deprecation.mjs";
+import { tickTriggers } from "./triggers.mjs";
+import { resolveMemberClone } from "./instance-resolution.mjs";
+import { AUTOMATION_ID_RE, automationContext, automationError, baseRow, localEntry, localId, soulOriginOf, splitId } from "./automations.mjs";
 import { RESERVED_LAUNCH_ENV, MAX_INSTANCE_NAME, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
 
 export const SCHEDULE_FILE = "oats-schedules.json";
@@ -65,6 +68,7 @@ const CAPTURED_SCHEDULE_REMOVED = "captured schedules are refused (the captured/
 export const HARNESS_CONFLICT = "harness and runtime (its pre-0.27 name) disagree: keep harness: and remove runtime:";
 export function shapeError(def) {
   if (!def || typeof def !== "object" || Array.isArray(def)) return "definition is not an object";
+  if (def.kind === "trigger") return "a trigger is managed by oats trigger, not oats schedule";
   if (!["spawn", "command", "wake", "operation"].includes(def.kind)) return `kind ${JSON.stringify(def.kind)} is not spawn, command, wake or operation`;
   if (typeof def.cron !== "string" || typeof def.tz !== "string") return "cron and tz must be strings";
   if (def.kind === "spawn" && typeof def.agent !== "string") return "agent must be a string";
@@ -246,7 +250,7 @@ export function withHostLock(fn, { retryMs = 0 } = {}) { return withDirLock(join
 /** Registry read-modify-write is serialized on its own short lock. */
 function withRegistryLock(fn) { return withDirLock(join(hostScheduleDir(), "registry.lock"), "the host schedule registry", fn, { retryMs: 3000 }); }
 /** Definitions and state are read-modify-write; CRUD serializes here briefly. */
-function withScopeLock(ws, fn) { return withDirLock(join(stateDir(ws), "scope.lock"), `schedules of ${ws}`, fn, { retryMs: 3000 }); }
+export function withScopeLock(ws, fn) { return withDirLock(join(stateDir(ws), "scope.lock"), `schedules of ${ws}`, fn, { retryMs: 3000 }); }
 
 export function acquireJobLock(ws, id, owner) {
   const dir = lockDir(ws, id);
@@ -288,6 +292,7 @@ function validateMessage(message, field) {
 /** Validate and normalize one definition against its scope. */
 export function validateDefinition(ws, def, { checkAgent = true } = {}) {
   if (!def || typeof def !== "object" || Array.isArray(def)) throw scheduleError("E_SCHEDULE_INVALID", "definition must be an object", { field: "definition" });
+  if (def.kind === "trigger") throw scheduleError("E_SCHEDULE_INVALID", "kind: a trigger is added with `oats trigger add`, not `oats schedule add`", { field: "kind" });
   const id = def.id;
   if (typeof id !== "string" || !ID_RE.test(id)) throw scheduleError("E_SCHEDULE_INVALID", "id: lowercase letters, digits and dashes, 1 to 40 characters", { field: "id" });
   const enabled = def.enabled === undefined ? true : def.enabled;
@@ -316,6 +321,7 @@ export function validateDefinition(ws, def, { checkAgent = true } = {}) {
       noteRuntimeName(`schedule ${id}: runtime (written as harness)`);
       def = { ...def, harness: def.runtime };
     }
+    if (def.launchConfig !== undefined) { if (typeof def.launchConfig !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(def.launchConfig)) throw scheduleError("E_SCHEDULE_INVALID", "launchConfig: the name of a launch configuration on the running host (oats-local.yaml launch-configs)", { field: "launchConfig" }); out.launchConfig = def.launchConfig; }
     if (def.harness !== undefined) { if (!HARNESSES.has(def.harness)) throw scheduleError("E_SCHEDULE_INVALID", "harness: pi, claude or codex", { field: "harness" }); out.harness = def.harness; }
     if (def.model !== undefined) { if (typeof def.model !== "string") throw scheduleError("E_SCHEDULE_INVALID", "model: string", { field: "model" }); out.model = def.model; }
     if (def.yolo !== undefined) { if (typeof def.yolo !== "boolean") throw scheduleError("E_SCHEDULE_INVALID", "yolo: boolean", { field: "yolo" }); out.yolo = def.yolo; }
@@ -351,11 +357,65 @@ export function validateDefinition(ws, def, { checkAgent = true } = {}) {
   return out;
 }
 
+/** The filesystem-safe key a workspace schedule is stored under in the local run state (job locks
+ *  are directories named by it): `<member>~<id>`. Repository names never carry `~`; local ids
+ *  (SCHEDULE_ID_RE) never do either. */
+export const scheduleStateKey = (qid) => String(qid).replace("/", "~");
+/** The jobs a tick, run or reconcile works on: the deployment's local jobs (stored under their
+ *  bare id) and, from the automations context (its `schedules`), the workspace schedules THIS host runs (stored
+ *  under scheduleStateKey(<member>/<id>), a filesystem-safe key: job locks are directories). */
+export function effectiveDefinitions(ws, ctx) {
+  const defs = readDefinitions(ws);
+  for (const a of ctx?.schedules || []) {
+    if (!a.placement.runsHere) continue;
+    const key = scheduleStateKey(a.id);
+    defs.jobs[key] = { ...a.definition, id: key, enabled: true, purpose: a.definition.purpose ?? a.name, workspace: { qid: a.id, name: a.name, member: a.member, origin: a.origin, runsOn: a.runsOn, owner: a.owner } };
+  }
+  return defs;
+}
+/** The stored key of a schedule argument (`local/<id>`, a bare local id, or `<member>/<id>`). */
+export function scheduleKeyOf(id) { const { scope, name } = splitId(id); return scope === "local" ? name : scheduleStateKey(`${scope}/${name}`); }
+/** A workspace schedule file (0.29.0; the shared header is lib/automations.mjs's):
+ *  `oats-schedules/<id>.yaml` or `*.oats-schedule.yaml`, `kind: oats-schedule`. Its body is the
+ *  run (`run: spawn | command`, cron, tz, …); a wake or an operation targets an instance home on
+ *  one machine and stays local. `expand` checks it against the deployment `dep`. */
+export function scheduleKind({ dep = null } = {}) {
+  return {
+    kind: "schedule", folder: "oats-schedules", suffix: "oats-schedule", fileKind: "oats-schedule",
+    bodyKeys: ["run", "cron", "tz", "agent", "task", "purpose", "launchConfig", "harness", "model", "yolo", "backend", "wake", "argv", "cwd"],
+    parseBody: (body) => {
+      const bad = (message) => Object.assign(new Error(message), { field: "run" });
+      const { run = "spawn", ...rest } = body;
+      if (run === "wake" || run === "operation") throw bad(`run: ${run} targets an instance home on one machine; declare it locally (oats schedule add), not in Git`);
+      if (run !== "spawn" && run !== "command") throw bad("run: spawn or command");
+      return { definition: { ...rest, kind: run } };
+    },
+    expand: (a) => validateWorkspaceSchedule(dep, a),
+  };
+}
+/** A workspace schedule, as a validated kernel definition for the snapshot: the file's run facts
+ *  checked like `oats schedule add` (the soul is resolved when it runs, through discovery); a
+ *  command's cwd is relative to the deployment. */
+export function validateWorkspaceSchedule(dep, a) {
+  const d = a.source?.definition || {};
+  const spec = { ...d, id: a.name, enabled: true };
+  if (spec.kind === "command") {
+    if (d.cwd !== undefined && (typeof d.cwd !== "string" || isAbsolute(d.cwd))) throw scheduleError("E_SCHEDULE_INVALID", "cwd: a directory relative to the deployment (a workspace schedule never names a machine path)", { field: "cwd" });
+    spec.cwd = resolve(dep, d.cwd ?? ".");
+  }
+  const out = validateDefinition(dep, spec, { checkAgent: false });
+  delete out.enabled;
+  return out;
+}
+
 /** The soul a spawn job launches, under the deployment's one agents root
  *  (a definition's agentsRoot, when given, must be that root). `repo` is the
  *  work repository and never selects a soul. */
 export function resolveScheduledAgent(ws, def) {
   const [root] = scopeRoots(ws);
+  // A workspace schedule (0.29.0) names its soul as `oats spawn <soul>` does: discovery resolves
+  // it (a member or package soul), whether or not this deployment has spawned it before.
+  if (def.workspace) return { root, agent: { name: def.agent }, discover: true };
   if (def.agentsRoot && resolve(def.agentsRoot) !== root) throw scheduleError("E_SCHEDULE_INVALID", `agentsRoot: ${def.agentsRoot} is not this deployment's agents root (${root})`, { field: "agentsRoot" });
   const agent = findAgent(root, def.agent);
   if (!agent) throw scheduleError("E_SCHEDULE_INVALID", `agent: no soul named ${JSON.stringify(def.agent)} under ${root}`, { field: "agent" });
@@ -424,20 +484,20 @@ export function findHomesInScope(ws, instance) {
 // --------------------------------------------------------------- runner
 
 function scheduleBlock(def, minute) {
-  return `\n\n## Scheduled run\n\nThis instance was launched by OATS schedule "${def.id}" for ${minute.toISOString()} (cron "${def.cron}" in ${def.tz}). It is disposable: finish the task above, bring your memory files up to date, and end with \`oats retire --self\`.\n`;
+  return `\n\n## Scheduled run\n\nThis instance was launched by OATS schedule "${def.workspace?.qid ?? def.id}" for ${minute.toISOString()} (cron "${def.cron}" in ${def.tz}). It is disposable: finish the task above, bring your memory files up to date, and end with \`oats retire --self\`.\n`;
 }
 /** The environment a scheduler-launched oats child runs with: the caller's
  *  frozen instance identity and capability snapshot removed (a tick or run-now
  *  may be invoked from inside an unrelated instance; dispatch belongs to the
  *  job's cwd and explicit selectors, never to that caller), host configuration
  *  such as OATS_HOME_DIR and credentials kept. Shared by command and spawn jobs. */
-function childEnv() {
+export function childEnv() {
   const env = { ...process.env };
   for (const key of [...RESERVED_LAUNCH_ENV,
     "OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
     "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
     "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_RETIRE_INTENT",
-    "OATS_TEAM_NAME", "OATS_TEAM_ID", "OATS_TEAM_SCOPE",
+    "OATS_TEAM_NAME", "OATS_TEAM_ID", "OATS_TEAM_SCOPE", "OATS_TRIGGER_EVENT_FILE",
   ]) delete env[key];
   return env;
 }
@@ -461,7 +521,8 @@ export function workspaceSpawnContext(ws) {
  *  `io.oatsBin`, `io.commandTimeoutMs` and `io.noLaunch` are the test seams. */
 function spawnViaCli(ws, root, agent, opts, context, io) {
   if (context.error) throw scheduleError(context.error.code, `this deployment realizes a workspace (${context.dir}) but its oats-local.yaml cannot be read: ${context.error.message}`);
-  const argv = ["spawn", agent.name, "--dir", context.dir, "--agents-root", root, "--purpose", opts.purpose, "--json"];
+  const argv = ["spawn", agent.name, "--dir", context.dir, ...(opts.discover ? [] : ["--agents-root", root]), "--purpose", opts.purpose, "--json"];
+  if (opts.launchConfig) argv.push("--launch-config", opts.launchConfig);
   if (opts.harness) argv.push("--harness", opts.harness);
   if (opts.model) argv.push("--model", opts.model);
   if (opts.backend) argv.push("--backend", opts.backend);
@@ -496,9 +557,9 @@ function spawnViaCli(ws, root, agent, opts, context, io) {
  *  deployment (workspace materialization: `.oats/modules`, module skills and
  *  injects). */
 function launchSpawn(ws, def, minute, io) {
-  const { root, agent } = resolveScheduledAgent(ws, def);
+  const { root, agent, discover } = resolveScheduledAgent(ws, def);
   const purpose = `${def.purpose || def.id}-${purposeSuffix(minute)}`;
-  const opts = { task: def.task.trimEnd() + scheduleBlock(def, minute), purpose, harness: def.harness, model: def.model, yolo: def.yolo, backend: def.backend, repo: def.repo, launch: io?.noLaunch === true ? false : true };
+  const opts = { discover, task: def.task.trimEnd() + scheduleBlock(def, minute), purpose, launchConfig: def.launchConfig, harness: def.harness, model: def.model, yolo: def.yolo, backend: def.backend, repo: def.repo, launch: io?.noLaunch === true ? false : true };
   let r;
   if (io?.spawn) r = io.spawn(root, agent, opts);
   else r = spawnViaCli(ws, root, agent, opts, workspaceSpawnContext(ws), io);
@@ -656,13 +717,13 @@ function observePrevious(ws, id, def, js, io, now, { mutate }) {
  *  reads only: no lock, state or definition is touched. Due jobs are
  *  visited least-recently-launched first so one job cannot monopolize the
  *  slot. An invalid definition is recorded on that job and the rest continue. */
-export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun = false, only, observeOnly = false, candidates } = {}) {
+export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun = false, only, observeOnly = false, candidates, ctx = null } = {}) {
   const minute = minuteStart(now);
   const key = minuteKey(minute);
   const registry = reg || readRegistry();
   const bound = registry.maxConcurrent || 1;
   const wsAll = wsList || [ws];
-  const defs = readDefinitions(ws);
+  const defs = effectiveDefinitions(ws, ctx);
   const st = readState(ws);
   const considered = [];
   const stateOf = (id) => (st.jobs[id] ||= {});
@@ -671,6 +732,8 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
   // are gone), then decide launches: a job ordered earlier must not see a
   // slot still held by a home that has already ended.
   // `candidates` (the host tick) means the host already observed every scope.
+  // Triggers (kind "trigger") live in the same file and are evaluated by tickTriggers, not here.
+  for (const [id, def] of Object.entries(defs.jobs)) if (def && def.kind === "trigger") delete defs.jobs[id];
   if (!candidates) for (const [id, def] of Object.entries(defs.jobs)) observePrevious(ws, id, def, stateOf(id), io, now, { mutate: !dryRun });
   if (observeOnly) { if (!dryRun) writeState(ws, st); return considered; }
   // Least recently LAUNCHED first: only an actual harness launch counts, a
@@ -763,6 +826,15 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
   return considered;
 }
 
+/** One scope's automations context (lib/automations.mjs automationContext) with its oats-local.yaml;
+ *  an unreadable oats-local.yaml means no workspace automations (the local jobs still run). */
+export function scopeAutomations(ws, { io, now = new Date(), refresh = false, cache = new Map() } = {}) {
+  let local = null;
+  try { local = loadLocal(ws).local; } catch { local = null; }
+  const clonePathOf = (repoKey) => resolveMemberClone({ deployment: ws, soulEntry: { repoKey }, local });
+  const ctx = automationContext(ws, { local, io: { ...(io || {}), childEnv }, now, refresh, cache, clonePathOf });
+  return Object.assign(ctx, { ws, local });
+}
 /** The host tick: every registered scope under the host lock. */
 export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
   const reg = readRegistry();
@@ -774,18 +846,29 @@ export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
     // every-minute job in the first registered scope cannot monopolize the
     // bound. An unreadable scope is recorded and the rest continue.
     const jobs = [];
+    // Each scope's workspace automations, placed on this host once per tick (one gh identity
+    // lookup per GitHub host), the snapshot refreshed first when it is ten minutes old.
+    const cache = new Map(), contexts = new Map();
+    for (const ws of wsList) contexts.set(ws, scopeAutomations(ws, { io, now, refresh: !dryRun, cache }));
+    for (const ctx of contexts.values()) if (ctx.refresh && !ctx.refresh.ok) considered.push({ workspace: ctx.ws, action: "error", error: `automations refresh: ${ctx.refresh.error}` });
     for (const ws of wsList) {
+      const ctx = contexts.get(ws);
       try {
-        considered.push(...tickWorkspace(ws, { now, io, reg, wsList, dryRun, observeOnly: true }));
-        const defs = readDefinitions(ws), st = readState(ws);
-        for (const id of Object.keys(defs.jobs)) jobs.push({ ws, id, key: launchOrderKey(st.jobs[id]) });
+        considered.push(...tickWorkspace(ws, { now, io, reg, wsList, dryRun, observeOnly: true, ctx }));
+        const defs = effectiveDefinitions(ws, ctx), st = readState(ws);
+        for (const [id, def] of Object.entries(defs.jobs)) if (def?.kind !== "trigger") jobs.push({ ws, id, key: launchOrderKey(st.jobs[id]) });
       } catch (e) { considered.push({ workspace: ws, action: "error", error: e.message }); }
     }
     jobs.sort((a, b) => a.key.localeCompare(b.key) || a.ws.localeCompare(b.ws) || a.id.localeCompare(b.id));
     for (const j of jobs) {
-      try { considered.push(...tickWorkspace(j.ws, { now, io, reg, wsList, dryRun, candidates: [j.id] })); }
+      try { considered.push(...tickWorkspace(j.ws, { now, io, reg, wsList, dryRun, candidates: [j.id], ctx: contexts.get(j.ws) })); }
       catch (e) { considered.push({ workspace: j.ws, id: j.id, action: "error", error: e.message }); }
     }
+    // Triggers: each scope's event-driven spawns, polled at their own interval (lib/triggers.mjs).
+    for (const ws of wsList) {
+      try { considered.push(...tickTriggers(ws, { now, io, dryRun, ctx: contexts.get(ws) })); }
+      catch (e) { considered.push({ workspace: ws, action: "error", error: `triggers: ${e.message}` }); }
+    }
     if (!dryRun) writeHostState({ ...readHostState(), lastTick: now.toISOString(), minute: minuteKey(minuteStart(now)) });
     return { tickedAt: now.toISOString(), minute: minuteKey(minuteStart(now)), considered, scheduler: schedulerStatus(undefined, io) };
   };
@@ -794,10 +877,11 @@ export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
 
 /** Run one job now, ignoring its cron, under the same lock and bound; the
  *  previous run is observed under the host lock before any lock is judged. */
-export function runNow(ws, id, { now = new Date(), io, force = false } = {}) {
-  const defs = readDefinitions(ws);
+export function runNow(ws, qid, { now = new Date(), io, force = false, ctx = null } = {}) {
+  const id = scheduleKeyOf(qid);
+  const defs = effectiveDefinitions(ws, ctx);
   const def = defs.jobs[id];
-  if (!def) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+  if (!def || def.kind === "trigger") throw notHere(ws, qid, ctx);
   if (!def.enabled && !force) throw scheduleError("E_SCHEDULE_DISABLED", `schedule ${id} is disabled; enable it or pass --force`);
   const reg = readRegistry();
   const wsList = reg.workspaces.includes(resolve(ws)) ? reg.workspaces : [...reg.workspaces, resolve(ws)];
@@ -809,10 +893,10 @@ export function runNow(ws, id, { now = new Date(), io, force = false } = {}) {
     if (js.attempt) throw scheduleError("E_SCHEDULE_UNRESOLVED", `schedule ${id} has a launch attempt without a recorded result; run oats schedule reconcile ${id} first`);
     if (def.kind !== "wake" && jobLockInfo(ws, id)) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is still running`);
     if (def.kind !== "wake" && liveLocks(wsList) >= reg.maxConcurrent) throw scheduleError("E_SCHEDULER_BUSY", `host concurrency ${reg.maxConcurrent} reached`);
-    const considered = tickWorkspace(ws, { now, io, reg, wsList, only: id });
+    const considered = tickWorkspace(ws, { now, io, reg, wsList, only: id, ctx });
     const after = readState(ws);
     if (after.jobs[id]) { after.jobs[id].lastAttemptedMinute = minuteKey(minuteStart(now)); writeState(ws, after); }
-    return { schedule: describe(ws, id, io), run: after.jobs[id]?.lastRun || null, considered };
+    return { schedule: describe(ws, qid, io, { ctx }), run: after.jobs[id]?.lastRun || null, considered };
   });
 }
 
@@ -821,15 +905,17 @@ export function runNow(ws, id, { now = new Date(), io, force = false } = {}) {
  *  identity), a command attempt only the instance its answer NAMED. Nothing
  *  is inferred from file times. An unnamed command effect stays unknown
  *  until the operator has checked by hand and passes `clear`. */
-export function reconcile(ws, id, { io, now = new Date(), clear = false } = {}) {
-  const defs = readDefinitions(ws);
+export function reconcile(ws, qid, { io, now = new Date(), clear = false, ctx = null } = {}) {
+  const id = scheduleKeyOf(qid);
+  const defs = effectiveDefinitions(ws, ctx);
   const def = defs.jobs[id];
-  if (!def) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+  if (!def || def.kind === "trigger") throw notHere(ws, qid, ctx);
+  const describeHere = () => describe(ws, qid, io, { ctx });
   return withHostLock(() => {
     const st = readState(ws);
     const js = st.jobs[id] || (st.jobs[id] = {});
     const attempt = js.attempt || (js.lastRun?.outcome === "unknown" ? { scheduledFor: js.lastRun.scheduledFor, startedAt: js.lastRun.startedAt, ...(js.lastRun.execution !== undefined ? { execution: js.lastRun.execution } : {}) } : undefined);
-    if (!attempt) return { schedule: describe(ws, id, io), reconciled: "nothing to reconcile" };
+    if (!attempt) return { schedule: describeHere(), reconciled: "nothing to reconcile" };
     try { validateAttemptExecution(attempt, jobLockInfo(ws, id)); }
     catch (error) { throw scheduleError("E_SCHEDULE_INVALID", error.message); }
     const attemptKind = def.kind;
@@ -849,9 +935,9 @@ export function reconcile(ws, id, { io, now = new Date(), clear = false } = {})
       if (js.lastRun?.instance) named = findHomesInScope(ws, js.lastRun.instance).map((home) => ({ instance: js.lastRun.instance, home }));
       if (named.length === 1) adopted = named[0];
       else if (named.length > 1) ambiguous = `${named.length} homes named ${js.lastRun.instance}: ${named.map((c) => c.home).join(", ")}`;
-      else if (!clear) return { schedule: describe(ws, id, io), reconciled: "unknown", remedy: `the command's effects cannot be proven from a matching admitted receipt; check the roster and the host by hand, then run oats schedule reconcile ${id} --clear to record launch-failed and free the slot, or oats schedule remove --force ${id}` };
+      else if (!clear) return { schedule: describeHere(), reconciled: "unknown", remedy: `the command's effects cannot be proven from a matching admitted receipt; check the roster and the host by hand, then run oats schedule reconcile ${id} --clear to record launch-failed and free the slot, or oats schedule remove --force ${id}` };
     }
-    if (ambiguous && !clear) return { schedule: describe(ws, id, io), reconciled: "unknown", remedy: `${ambiguous}; retire or adopt by hand, then run oats schedule reconcile ${id} --clear or oats schedule remove --force ${id}` };
+    if (ambiguous && !clear) return { schedule: describeHere(), reconciled: "unknown", remedy: `${ambiguous}; retire or adopt by hand, then run oats schedule reconcile ${id} --clear or oats schedule remove --force ${id}` };
     if (ambiguous) adopted = undefined;
     delete js.attempt;
     if (adopted) {
@@ -863,13 +949,61 @@ export function reconcile(ws, id, { io, now = new Date(), clear = false } = {})
       releaseJobLock(ws, id);
     }
     writeState(ws, st);
-    return { schedule: describe(ws, id, io), reconciled: adopted ? "adopted" : "cleared" };
+    return { schedule: describeHere(), reconciled: adopted ? "adopted" : "cleared" };
   });
 }
 
 // -------------------------------------------------------- definitions CRUD
 
 export const SCHEDULE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** A schedule id this host cannot run: unknown, or a workspace schedule placed elsewhere. */
+/** `oats schedule test <id>`: what running it on this host would do, without running it — its
+ *  placement, whether its soul resolves (the kernel's own `oats spawn <soul> --preview`, which
+ *  writes nothing) and when it is next due. Spawns nothing, records nothing, takes no lock. */
+export function testSchedule(ws, qid, io, { now = new Date(), ctx = null } = {}) {
+  const row = describe(ws, qid, io, { now, ctx });
+  const { scope, name } = splitId(qid);
+  const entry = scope === "local" ? null : (ctx?.schedules || []).find((x) => x.id === `${scope}/${name}`);
+  const def = entry ? { ...entry.definition, workspace: { qid: entry.id } } : readDefinitions(ws).jobs[name];
+  const problems = [];
+  if (row.invalid) problems.push(`${row.qualifiedId} is invalid: ${row.invalid.message}`);
+  if (!row.runsHere) problems.push(`${row.qualifiedId} does not run on this host (${row.reason ?? "disabled here"}${row.reasonDetail ? `: ${row.reasonDetail}` : ""})`);
+  if (!row.enabled) problems.push(`${row.qualifiedId} is disabled (oats schedule enable ${row.qualifiedId})`);
+  // The next cron match, whether or not this host runs it (placement says that).
+  let nextDue = null; try { nextDue = def?.cron ? nextRunAfter(def, now) : null; } catch (e) { problems.push(`cron: ${e.message}`); }
+  let soul = null;
+  if (def?.kind === "spawn") {
+    soul = { name: def.agent, origin: row.soul?.origin ?? null, resolves: false, error: null };
+    try {
+      const { root, discover } = resolveScheduledAgent(ws, def);
+      const context = workspaceSpawnContext(ws);
+      if (context.error) throw scheduleError(context.error.code, context.error.message);
+      const argv = ["spawn", def.agent, "--dir", context.dir, ...(discover ? [] : ["--agents-root", root]), "--preview", "--json"];
+      if (def.launchConfig) argv.push("--launch-config", def.launchConfig);
+      if (def.harness) argv.push("--harness", def.harness);
+      if (def.model) argv.push("--model", def.model);
+      const r = spawnSync(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: context.dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, killSignal: "SIGTERM", maxBuffer: 16 * 1024 * 1024, env: childEnv() });
+      const envelope = parseEnvelopeText(r.stdout);
+      if (!envelope || typeof envelope.ok !== "boolean") throw scheduleError("E_SPAWN_FAILED", `the spawn preview answered no valid envelope (exit ${r.status ?? r.signal})`);
+      if (!envelope.ok) throw scheduleError(envelope.error?.code || "E_SPAWN_FAILED", String(envelope.error?.message || "spawn preview failed"));
+      soul.resolves = true;
+    } catch (e) {
+      soul.error = { code: e.code || "E_SPAWN_FAILED", message: e.message };
+      problems.push(`soul ${def.agent} does not resolve: ${e.message}`);
+    }
+  }
+  return {
+    id: row.id, qualifiedId: row.qualifiedId, kind: row.kind,
+    placement: { runsHere: row.runsHere, reason: row.reason, ...(row.reasonDetail ? { reasonDetail: row.reasonDetail } : {}), enabledHere: row.enabledHere, runsOn: row.runsOn, owner: row.owner, host: ctx?.host?.name ?? null },
+    soul, nextDue, spawned: false, problems, ok: problems.length === 0,
+  };
+}
+function notHere(ws, qid, ctx) {
+  const { scope } = splitId(qid);
+  const a = scope !== "local" ? (ctx?.schedules || []).find((x) => x.id === qid) : null;
+  if (a) return automationError("E_AUTOMATION_NOT_HERE", `${qid} does not run on this host (${a.placement.reason ?? (a.invalid ? "invalid" : "disabled here")}${a.placement.detail ? `: ${a.placement.detail}` : a.invalid ? `: ${a.invalid.message}` : ""})`, { id: qid, reason: a.placement.reason, runsOn: a.runsOn, owner: a.owner });
+  return scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(qid)} in ${ws}${scope !== "local" && !ctx?.snapshot ? " (no automations snapshot yet: run oats sync)" : ""}`);
+}
 function incarnationOfHome(home) { try { const m = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); return typeof m?.createdAt === "string" ? m.createdAt : null; } catch { return null; } }
 /** K8b — session PROVENANCE of a run (facts the recorder had), never a
  *  transcript: there is no reader behind this block. */
@@ -893,11 +1027,22 @@ function projectHistory(js) {
   }
   return { history: { status: "ok", stored: stored.length, truncated: stored.length > RECENT_RUNS_MAX }, recentRuns: rows };
 }
-export function describe(ws, id, io, { defs, st, now = new Date() } = {}) {
-  if (typeof id !== "string" || !SCHEDULE_ID_RE.test(id)) throw scheduleError("E_BAD_ARGS", `schedule id must match ${SCHEDULE_ID_RE} (got ${JSON.stringify(id)})`);
-  defs ||= readDefinitions(ws); st ||= readState(ws);
+/** One schedule's row: the stored job's facts (a workspace schedule this host runs is a job
+ *  under its state key) plus the automations row (docs/desktop-cli-api.md "Automations"). A
+ *  workspace schedule another host runs has no local facts: its definition and placement only. */
+export function describe(ws, qid, io, { defs, st, now = new Date(), ctx = null } = {}) {
+  if (typeof qid !== "string" || !qid) throw scheduleError("E_BAD_ARGS", `oats schedule show <id> (local/<id> or <member>/<id>)`);
+  const { scope, name } = splitId(qid);
+  if (scope !== "local" && (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(scope) || !AUTOMATION_ID_RE.test(name))) throw scheduleError("E_BAD_ARGS", `a workspace schedule id is <member>/<id> (got ${JSON.stringify(qid)})`);
+  const entry = scope === "local" ? null : (ctx?.schedules || []).find((x) => x.id === `${scope}/${name}`);
+  if (scope !== "local" && !entry) throw notHere(ws, `${scope}/${name}`, ctx);
+  if (entry && !entry.placement.runsHere) return scheduleRow(ws, entry, { ...(entry.definition || {}), scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, nextRun: null, lastRun: null, running: false }, ctx);
+  const id = scope === "local" ? name : scheduleStateKey(entry.id);
+  if (scope === "local" && !SCHEDULE_ID_RE.test(id)) throw scheduleError("E_BAD_ARGS", `schedule id must match ${SCHEDULE_ID_RE} (got ${JSON.stringify(qid)})`);
+  defs ||= effectiveDefinitions(ws, ctx); st ||= readState(ws);
   const def = defs.jobs[id];
-  if (!def) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+  if (!def) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(qid)} in ${ws}`);
+  if (def.kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `${qid} is a trigger, not a schedule — use oats trigger show ${qid}`);
   // Subject truth: the definition's own id must be the key it is stored under.
   if (def.id !== undefined && def.id !== id) throw scheduleError("E_SCHEDULE_IDENTITY", `schedule stored under ${JSON.stringify(id)} declares id ${JSON.stringify(def.id)}`, { key: id, declared: def.id });
   const js = st.jobs[id] || {};
@@ -905,16 +1050,44 @@ export function describe(ws, id, io, { defs, st, now = new Date() } = {}) {
   const lock = jobLockInfo(ws, id);
   const intent = js.attempt || (lock ? (js.lastRun?.execution !== undefined ? { execution: js.lastRun.execution } : {}) : undefined);
   const { history, recentRuns } = projectHistory(js);
-  return { ...def, id, scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, executionStatus: scheduleExecutionStatus(def, intent, lock), nextRun, lastRun: js.lastRun ? { ...js.lastRun, runId: runIdOf(js.lastRun), session: sessionProvenanceOf(js.lastRun) } : null, history, recentRuns, running: !!lock, ...(js.attempt ? { attempt: js.attempt } : {}), ...(js.pendingWake ? { pendingWake: js.pendingWake } : {}) };
+  const { workspace: _w, ...stored } = def; void _w;
+  const base = { ...stored, id, scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, executionStatus: scheduleExecutionStatus(def, intent, lock), nextRun, lastRun: js.lastRun ? { ...js.lastRun, runId: runIdOf(js.lastRun), session: sessionProvenanceOf(js.lastRun) } : null, history, recentRuns, running: !!lock, ...(js.attempt ? { attempt: js.attempt } : {}), ...(js.pendingWake ? { pendingWake: js.pendingWake } : {}) };
+  return scheduleRow(ws, entry ?? localEntry("schedule", { ...def, id: name }, { dep: ws }), base, ctx);
+}
+/** A schedule's list row: its stored facts, the fields every trigger and schedule row share
+ *  (lib/automations.mjs baseRow) and the schedule's own: `kind` is its run (spawn, command, wake,
+ *  operation), the soul it spawns, the task, the cron and tz, the last run and the next due. */
+function scheduleRow(ws, entry, base, ctx) {
+  const { enabled: _e, ...rest } = base; void _e;
+  const def = entry.definition || {};
+  const soul = def.kind === "spawn" ? def.agent ?? null : null;
+  const local = entry.member === "local";
+  return {
+    ...rest, ...baseRow(entry),
+    // A local schedule keeps its bare id (the 0.28 contract every consumer reads); its qualified
+    // form is qualifiedId. A workspace schedule's id IS qualified: <member>/<id>.
+    id: local ? entry.name : entry.id, qualifiedId: entry.id,
+    kind: base.kind ?? def.kind ?? null,
+    soul: soul ? { name: soul, origin: soulOriginOf(ctx?.snapshot?.souls, soul) } : null,
+    task: def.task ?? null, cron: def.cron ?? null, tz: def.tz ?? null,
+    teams: [], launchConfig: def.launchConfig ?? null, harness: def.harness ?? null, model: def.model ?? null, concurrency: null,
+    lastRun: base.lastRun ?? null, nextDue: entry.placement.runsHere ? base.nextRun ?? null : null,
+    enabled: entry.enabled !== false,
+  };
 }
-export function listSchedules(ws, io, { now = new Date() } = {}) {
+export function listSchedules(ws, io, { now = new Date(), ctx = null } = {}) {
   const defs = readDefinitions(ws), st = readState(ws);
+  const all = effectiveDefinitions(ws, ctx);
   // One job's bad identity or history does not fail the others: it is reported as its own row.
-  const schedules = Object.keys(defs.jobs).sort().map((id) => {
-    try { return describe(ws, id, io, { defs, st, now }); }
-    catch (e) { return { id, scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, unreadable: { code: e.code || "E_SCHEDULE_INVALID", message: e.message }, history: { status: "corrupt", stored: null, truncated: false }, recentRuns: [] }; }
-  });
-  return { scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, integrity: scheduleIntegrity(ws), schedules, scheduler: schedulerStatus(ws, io) };
+  const row = (qid) => {
+    try { return describe(ws, qid, io, { defs: all, st, now, ctx }); }
+    catch (e) { return { id: splitId(qid).scope === "local" ? splitId(qid).name : qid, qualifiedId: qid, name: splitId(qid).name, scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, unreadable: { code: e.code || "E_SCHEDULE_INVALID", message: e.message }, history: { status: "corrupt", stored: null, truncated: false }, recentRuns: [] }; }
+  };
+  const local = Object.keys(defs.jobs).filter((id) => defs.jobs[id]?.kind !== "trigger").sort().map((id) => row(localId(id)));
+  const workspace = (ctx?.schedules || []).map((a) => row(a.id));
+  // Triggers share the definitions file but not this listing: a pointer, so they are never invisible.
+  const triggers = Object.values(defs.jobs).filter((d) => d?.kind === "trigger").length + (ctx?.triggers || []).length;
+  return { scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, integrity: scheduleIntegrity(ws), host: { name: ctx?.host?.name ?? null, ghUser: ctx?.ghUsers ? ctx.ghUsers() : {} }, schedules: [...local, ...workspace], triggers: { count: triggers, command: "oats trigger list" }, snapshot: ctx?.snapshot ? { takenAt: ctx.snapshot.takenAt, problems: (ctx.snapshot.problems || []).length } : null, scheduler: schedulerStatus(ws, io) };
 }
 export function addSchedule(ws, spec, io) {
   const def = validateDefinition(ws, spec);
@@ -924,41 +1097,44 @@ export function addSchedule(ws, spec, io) {
     const now = new Date().toISOString();
     defs.jobs[def.id] = { ...def, createdAt: now, updatedAt: now };
     writeDefinitions(ws, defs);
-    return describe(ws, def.id, io);
+    return describe(ws, localId(def.id), io);
   });
 }
 /** Update under the host lock (so the busy check cannot race a tick's
  *  admission) and the scope lock. What a run is tracked or reconciled by
  *  (kind, agent, agentsRoot, repo, purpose, home, cwd, argv) cannot change
  *  while the job holds a slot or has an unresolved attempt; timing and text can. */
-export function updateSchedule(ws, id, spec, io) {
+export function updateSchedule(ws, qid, spec, io) {
+  const id = localScheduleId(qid, "update");
   const def = validateDefinition(ws, { ...spec, id });
   return withHostLock(() => withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
-    if (!defs.jobs[id]) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+    if (!defs.jobs[id] || defs.jobs[id].kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}${defs.jobs[id] ? " (it is a trigger: use oats trigger)" : ""}`);
     const identity = (d) => JSON.stringify([d.kind, d.agent, d.agentsRoot, d.repo, d.purpose, d.home, d.cwd, d.argv, d.operation, d.definitionVersion, d.recurrencePolicy, d.execution, d.preparation]);
     const busy = !!jobLockInfo(ws, id) || !!readState(ws).jobs[id]?.attempt;
     if (busy && identity(defs.jobs[id]) !== identity(def)) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is running or has an unresolved attempt; its execution identity, kind, target and captured policy cannot change until it ends (cron, tz and enabled can)`);
     defs.jobs[id] = { ...def, createdAt: defs.jobs[id].createdAt, updatedAt: new Date().toISOString() };
     writeDefinitions(ws, defs);
-    return describe(ws, id, io);
+    return describe(ws, localId(id), io);
   }), { retryMs: 3000 });
 }
-export function setEnabled(ws, id, enabled, io) {
+export function setEnabled(ws, qid, enabled, io) {
+  const id = localScheduleId(qid, "change");
   return withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
-    if (!defs.jobs[id]) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+    if (!defs.jobs[id] || defs.jobs[id].kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}${defs.jobs[id] ? " (it is a trigger: use oats trigger)" : ""}`);
     defs.jobs[id] = { ...defs.jobs[id], enabled, updatedAt: new Date().toISOString() };
     writeDefinitions(ws, defs);
-    return describe(ws, id, io);
+    return describe(ws, localId(id), io);
   });
 }
 /** Remove under the host lock (state changes under a live tick are refused
  *  by the lock, not raced). */
-export function removeSchedule(ws, id, { force = false } = {}) {
+export function removeSchedule(ws, qid, { force = false } = {}) {
+  const id = localScheduleId(qid, "remove");
   return withHostLock(() => withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
-    if (!defs.jobs[id]) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+    if (!defs.jobs[id] || defs.jobs[id].kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}${defs.jobs[id] ? " (it is a trigger: use oats trigger)" : ""}`);
     const st = readState(ws), job = st.jobs[id];
     if ((jobLockInfo(ws, id) || job?.attempt || job?.lastRun?.outcome === "unknown") && !force) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is running or has unresolved effects; reconcile first, or --force forgets the job without stopping anything`);
     delete defs.jobs[id];
@@ -968,6 +1144,13 @@ export function removeSchedule(ws, id, { force = false } = {}) {
     return { removed: id };
   }));
 }
+/** The stored id of a LOCAL schedule argument; a workspace schedule is changed in Git (enabled or
+ *  disabled on this host through oats-local.yaml schedules.disabled). */
+function localScheduleId(qid, verb) {
+  const { scope, name } = splitId(qid);
+  if (scope !== "local") throw automationError("E_AUTOMATION_WORKSPACE", `${qid} is a workspace schedule, defined in Git: ${verb} its file there${verb === "remove" ? `, or stop it on this host: oats schedule disable ${qid}` : ""}`, { id: qid });
+  return name;
+}
 /** Save the wake job for a freshly spawned instance (id wake-<instance>). */
 export function saveWakeForHome(ws, { instance, home, wake }) {
   const id = `wake-${instance}`.slice(0, 40).replace(/-+$/, "");