@awebai/oats 0.22.9 → 0.22.12

package/bin/oats.mjs

@@ -39,8 +39,10 @@ import {
   assertNoSymlinkedParents, copyFileAtomic, writeFileAtomic,
   runRequirementInstall, selectConfigTemplate, validateConfigTemplate, writeAdoptedTemplate,
 } from "../lib/packages.mjs";
-import { attachArgv, checkRemote, forgetSnapshot, getServer, inspectRemote, startRemote, listSnapshots, readServers, rosterGroups, routeCommand, targetOf, validateServer, writeServers, SERVERS_FILE } from "../lib/servers.mjs";
+import { attachArgv, checkRemote, forgetSnapshot, getServer, inspectRemote, startRemote, scheduleRemote, listSnapshots, readServers, rosterGroups, routeCommand, targetOf, validateServer, writeServers, SERVERS_FILE } from "../lib/servers.mjs";
 import { spawnSync as spawnSyncProc } from "node:child_process";
+import { 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 { hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/schedule-host.mjs";
 
 const args = process.argv.slice(2);
 const cmd = args[0];
@@ -2754,6 +2756,34 @@ function spawnCmd() {
   const relativeRoot = flag("relative-root");
   if (relativeRoot !== undefined && (relativeRoot === true || !String(relativeRoot).trim())) bail("E_BAD_ARGS", "--relative-root needs an agents-root path");
   if (relativeRoot && !relativeTo) bail("E_BAD_ARGS", "--relative-root only qualifies --relative-to/--parent");
+  // Wake at launch: --wake-file <private JSON {cron, tz, message, enabled}>
+  // is the backend bridge; --wake-every/--wake-cron/--wake-tz/--wake-message
+  // (or --wake-message-file) are the human sugar for the same object. The
+  // wake job is saved AFTER a successful spawn, bound to the returned home.
+  let wake;
+  try {
+    const wakeFile = flag("wake-file");
+    if (wakeFile === true) bail("E_BAD_ARGS", "--wake-file needs a path");
+    const wakeJson = flag("wake-json");
+    if (wakeJson === true) bail("E_BAD_ARGS", "--wake-json needs the wake object as JSON text");
+    if (wakeJson) {
+      let doc; try { doc = JSON.parse(wakeJson); } catch (e) { bail("E_SCHEDULE_INVALID", `--wake-json is not valid JSON: ${e.message}`); }
+      if (!doc || typeof doc !== "object") bail("E_SCHEDULE_INVALID", "--wake-json must hold {cron, tz, message, enabled}");
+      wake = { cron: doc.cron, tz: doc.tz, message: doc.message, enabled: doc.enabled === undefined ? true : doc.enabled };
+    } else if (wakeFile) {
+      if (!existsSync(wakeFile)) bail("E_BAD_ARGS", `--wake-file not found: ${wakeFile}`);
+      let doc; try { doc = JSON.parse(readFileSync(wakeFile, "utf8")); } catch (e) { bail("E_SCHEDULE_INVALID", `--wake-file is not valid JSON: ${e.message}`); }
+      if (!doc || typeof doc !== "object") bail("E_SCHEDULE_INVALID", "--wake-file must hold {cron, tz, message, enabled}");
+      wake = { cron: doc.cron, tz: doc.tz, message: doc.message, enabled: doc.enabled === undefined ? true : doc.enabled };
+    } else if (flag("wake-every") !== undefined || flag("wake-cron") !== undefined) {
+      const mf = flag("wake-message-file");
+      if (mf === true) bail("E_BAD_ARGS", "--wake-message-file needs a path");
+      if (mf && !existsSync(mf)) bail("E_BAD_ARGS", `--wake-message-file not found: ${mf}`);
+      const message = mf ? readFileSync(mf, "utf8") : flag("wake-message") === true ? undefined : flag("wake-message");
+      wake = wakeFromFlags({ every: flag("wake-every") === true ? undefined : flag("wake-every"), cron: flag("wake-cron") === true ? undefined : flag("wake-cron"), tz: flag("wake-tz") === true ? undefined : flag("wake-tz"), message });
+    }
+    if (wake && (typeof wake.message !== "string" || !wake.message.trim())) bail("E_SCHEDULE_INVALID", "wake message: non-empty text is required");
+  } catch (e) { if (e?.code?.startsWith?.("E_")) bail(e.code, e.message); throw e; }
   let r;
   try {
     r = spawnInstance(root, agent, {
@@ -2770,11 +2800,19 @@ function spawnCmd() {
     if (TYPED_CLI_FAILURES.has(e?.code)) throw e;
     bail(e.code === "E_RELATIVE_AMBIGUOUS" ? "E_RELATIVE_AMBIGUOUS" : "E_SPAWN_FAILED", e.message || e); throw e;
   }
+  // The instance exists from here on: a failed wake save is reported beside
+  // the full receipt, never hidden, and never causes a second spawn.
+  let wakeSchedule, wakeScheduleError;
+  if (wake) {
+    try { wakeSchedule = saveWakeForHome(scheduleScopeOf(workspaceOf(root)), { instance: r.instance, home: r.home, wake }); }
+    catch (e) { wakeScheduleError = { code: e.code || "E_SCHEDULE_FAILED", message: e.message }; r.warnings = [...(r.warnings || []), `wake schedule NOT saved: ${e.message}`]; }
+  }
   if (JSON_MODE) {
     // Desktop CLI API v1 spawn result — a FIXED shape (see docs/desktop-cli-api.md).
     jsonOk({
       instance: r.instance, agent: r.agent, home: r.home, work: r.work,
       branch: r.branch || null, launched: r.launched, warnings: r.warnings || [],
+      ...(wakeSchedule ? { wakeSchedule } : {}), ...(wakeScheduleError ? { wakeScheduleError } : {}),
       tmux: r.tmux || null, repo: r.repo || null, runtime: r.runtime || null,
       model: r.model || null, parent: r.parentInstance || null,
       sibling: r.siblingInstance || null, relation: r.relation || null,
@@ -2786,6 +2824,8 @@ function spawnCmd() {
   }
   console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? r.sessionTarget ? ` — Herdr pane "${r.sessionTarget.paneId}"` : ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
   console.log(`  home:   ${shortPath(r.home)}`);
+  if (wakeSchedule) console.log(`  wake:   schedule ${wakeSchedule.id} (${wakeSchedule.cron} ${wakeSchedule.tz}), next ${wakeSchedule.nextRun || "disabled"}`);
+  if (wakeScheduleError) console.error(`  wake:   NOT saved — ${wakeScheduleError.message} (the instance is created and launched; add the wake by hand with oats schedule add)`);
   if (!r.launched) console.log(`  launch: (cd ${shortPath(r.home)} && ${r.command})`);
   for (const w of r.warnings || []) console.log(`  WARNING: ${w}`);
   console.log(`  attach: ${r.attach}`);
@@ -2809,7 +2849,11 @@ function retireCmd() {
     // Stdout carries only the envelope in JSON mode (the Desktop parses it).
     if (hit && resolve(hit.root) !== resolve(root)) { root = hit.root; (args.includes("--json") ? console.error : console.log)(`(cross-repo: instance homes at ${shortPath(root)})`); }
   }
+  const retiringHome = homeFlag || findInstanceHome(root, name);
   const r = retireInstance(root, name, { home: homeFlag, self: isSelf, deleteBranch: args.includes("--delete-branch"), keepDir: args.includes("--keep-dir"), force: args.includes("--force") });
+  // A retired home's wake jobs are forgotten (definitions only; nothing is
+  // stopped by this); a deferred self-retire keeps them until the home is gone.
+  if (retiringHome && r.removedDir !== false && !r.deferred) { try { const gone = removeWakeForHome(scheduleScopeOf(workspaceOf(root)), retiringHome); if (gone.length) r.wakeSchedulesRemoved = gone; } catch (e) { r.warnings = [...(r.warnings || []), `wake schedules not cleaned: ${e.message}`]; } }
   // Deferred self-retire: nothing has been inspected, run, or removed yet. The
   // caller's window dies first; a detached process then retires the instance
   // as an external operator and writes its outcome beside the home.
@@ -2847,6 +2891,56 @@ function retireCmd() {
   if (isSelf) console.log("This window dies in ~8s — say any goodbyes now.");
 }
 
+/** `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() {
+  const sub = args[1];
+  const id = args[2] && !args[2].startsWith("--") ? args[2] : undefined;
+  // One schedule-owning scope for a directory: the team workspace (the
+  // config level declaring the team), else the outermost config level.
+  const ws = scheduleScopeOf(dirFlag());
+  const io = { hostStatus: () => hostUnitStatus() };
+  const out = (result) => { if (JSON_MODE) jsonOk(result); else console.log(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" }); } }
+    const f = flag("file");
+    if (!f || f === true) throw scheduleError("E_BAD_ARGS", "--file <spec.json> is required (a private JSON file with the definition)");
+    if (!existsSync(f)) throw scheduleError("E_BAD_ARGS", `spec file not found: ${f}`);
+    try { return JSON.parse(readFileSync(f, "utf8")); } catch (e) { throw scheduleError("E_SCHEDULE_INVALID", `${f} is not valid JSON: ${e.message}`, { field: "file" }); }
+  };
+  const needId = () => { if (!id) throw scheduleError("E_BAD_ARGS", `oats schedule ${sub} <id>`); return id; };
+  try {
+    switch (sub) {
+      case "list": return out(listSchedules(ws, io));
+      case "show": return out({ schedule: describeSchedule(ws, needId(), io) });
+      case "add": { const spec = readSpec(); if (id && spec.id === undefined) spec.id = id; if (id && spec.id !== id) throw scheduleError("E_SCHEDULE_INVALID", `id ${JSON.stringify(spec.id)} in the file does not match ${JSON.stringify(id)}`, { field: "id" }); return out({ schedule: addSchedule(ws, spec, io) }); }
+      case "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 "remove": return out(removeSchedule(ws, needId(), { force: args.includes("--force") }));
+      case "reconcile": return out(reconcileSchedule(ws, needId(), { io, clear: args.includes("--clear") }));
+      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 }));
+        return out({ tickedAt: new Date().toISOString(), considered, scheduler: schedulerStatus(ws, io) });
+      }
+      case "host": {
+        const op = args[2];
+        if (op === "install") { registerWorkspace(ws); installHostUnit(); return out({ scheduler: schedulerStatus(ws, io) }); }
+        if (op === "uninstall") { unregisterWorkspace(ws); if (!readRegistry().workspaces.length) uninstallHostUnit(); return out({ scheduler: schedulerStatus(ws, io) }); }
+        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]");
+    }
+  } catch (e) { cmdFail(e.code || "E_SCHEDULE_FAILED", e.message); }
+}
+
 async function sessionCmd() {
   try {
     const home = flag("home");
@@ -3161,7 +3255,7 @@ function versionCmd() {
     // on it (an older CLI without the surface must fail closed with a
     // reason, not an argument error). `features`: kernel abilities a peer
     // must see before relying on them (retire-home: retire --home).
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "roster", "harvest"], features: ["retire-home", "session-start"] }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "roster", "harvest", "schedule"], features: ["retire-home", "session-start", "schedule"], scheduleApi: SCHEDULE_API }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3316,6 +3410,32 @@ function serverRouteCmd() {
     if (hr.instance && hr.instance !== inst) console.log(`  the harvester ${hr.instance} runs on ${id}; retire it there when it is done, or let it self-retire`);
     return;
   }
+  if (cmd === "schedule") {
+    // Host-owned: the subcommand runs in the server's registered workspace.
+    // A local --file spec is read here and travels inline; the remote
+    // cannot read this machine's files.
+    const rest = [];
+    for (let i = 1; i < args.length; i++) {
+      const a = args[i];
+      if (a === "--server") { i++; continue; }
+      if (a === "--json") continue;
+      if (a === "--file") {
+        const f = args[++i];
+        if (!f || f.startsWith("--")) bail("E_BAD_ARGS", "--file needs a path");
+        if (!existsSync(f)) bail("E_BAD_ARGS", `spec file not found: ${f}`);
+        rest.push("--spec-json", readFileSync(f, "utf8"));
+        continue;
+      }
+      rest.push(a);
+    }
+    let out;
+    try { out = scheduleRemote(id, rest); } catch (e) { bail(e.code || "E_SSH", e.message); }
+    if (out.stderr?.trim()) process.stderr.write(out.stderr.endsWith("\n") ? out.stderr : out.stderr + "\n");
+    if (JSON_MODE) { console.log(JSON.stringify(out.envelope, null, 2)); if (!out.envelope.ok) process.exit(1); return; }
+    if (!out.envelope.ok) die(`${id}: ${out.envelope.error?.message || "schedule command failed"} (${out.envelope.error?.code || "E_REMOTE"})`);
+    console.log(JSON.stringify(out.envelope.result, null, 2));
+    return;
+  }
   if (cmd === "session") {
     const addr = { instance: flag("instance") === true ? undefined : flag("instance"), home: flag("home") === true ? undefined : flag("home") };
     if (args[1] === "inspect") {
@@ -3365,6 +3485,24 @@ function serverRouteCmd() {
       rest.push("--task", readFileSync(f, "utf8"));
       continue;
     }
+    // A wake spec for a routed spawn travels as validated JSON text; the
+    // host saves it in its own scope. Local files never travel as paths.
+    if (a === "--wake-file") {
+      const f = args[++i];
+      if (!f || f.startsWith("--")) bail("E_BAD_ARGS", "--wake-file needs a path");
+      if (!existsSync(f)) bail("E_BAD_ARGS", `wake file not found: ${f}`);
+      let doc; try { doc = JSON.parse(readFileSync(f, "utf8")); } catch (e) { bail("E_SCHEDULE_INVALID", `--wake-file is not valid JSON: ${e.message}`); }
+      if (!doc || typeof doc !== "object" || !["cron", "tz", "message"].every((k) => typeof doc[k] === "string" && doc[k].trim())) bail("E_SCHEDULE_INVALID", "--wake-file must hold {cron, tz, message, enabled}");
+      rest.push("--wake-json", JSON.stringify({ cron: doc.cron, tz: doc.tz, message: doc.message, enabled: doc.enabled === undefined ? true : doc.enabled }));
+      continue;
+    }
+    if (a === "--wake-message-file") {
+      const f = args[++i];
+      if (!f || f.startsWith("--")) bail("E_BAD_ARGS", "--wake-message-file needs a path");
+      if (!existsSync(f)) bail("E_BAD_ARGS", `wake message file not found: ${f}`);
+      rest.push("--wake-message", readFileSync(f, "utf8"));
+      continue;
+    }
     rest.push(a);
   }
   let routed;
@@ -3426,10 +3564,10 @@ try {
 // and exits 0 BEFORE any dispatch: a fresh operator inspects --help before
 // using a command, and `install --help` once ran the bare restore while
 // `okf harvest --help` spawned a harvester (BeadHub, 2026-09-05).
-const KERNEL_COMMANDS = new Set(["capture", "config", "create", "doctor", "experimental", "init", "inject", "install", "list", "migrate", "pane", "recall", "remove", "retire", "root", "server", "session", "setup", "spawn", "status", "trust", "type", "update", "use", "version"]);
+const KERNEL_COMMANDS = new Set(["capture", "config", "create", "doctor", "experimental", "init", "inject", "install", "list", "migrate", "pane", "recall", "remove", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "trust", "type", "update", "use", "version"]);
 const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
 if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
-if (flag("server") !== undefined && ["spawn", "retire", "status", "session", "okf"].includes(cmd)) serverRouteCmd();
+if (flag("server") !== undefined && ["spawn", "retire", "status", "session", "okf", "schedule"].includes(cmd)) serverRouteCmd();
 else if (cmd === "server") serverCmd();
 else if (cmd === "doctor") {
   const doctorDir = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
@@ -3459,6 +3597,7 @@ 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 === "spawn") { try { 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 === "create") createCmd();
@@ -3530,6 +3669,13 @@ Usage:
       [--work <mode>] [--runtime pi|claude|codex] gitignored; same memory + lifecycle)
       [--model <m>] [--yolo|--no-yolo] [--instructions-file <f>]
   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>
+      enable|disable|run|remove|reconcile <id>   workspace-scoped, host-owned schedules (spawn,
+      tick [--dry-run] [--host]                  command or wake jobs on a five-field cron with an
+      host install|uninstall|status              explicit IANA tz; see docs/schedules.md); --server
+                                                routes to that host's workspace
+  oats 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 start --home <absolute-home>  start a STOPPED instance again in its existing home
       [--model <m>] [--json]                 (same identity, worktree, notes and launch env; no
                                             spawn hooks); --model replaces the recorded model

package/docs/desktop.md

@@ -74,8 +74,8 @@ app focus, and Retry. Until a compatible CLI is verified, the Soul roster's
 **Spawn** buttons are disabled behind one card showing what was detected,
 what is required, **Choose oats…** (pick the binary yourself — the choice
 persists), **Retry**, a docs link, and the copyable install command. The
-app never installs anything itself. (Memory harvest runs through the same
-CLI boundary in the backend; it has no dedicated button in this release.)
+app never installs the CLI itself. Memory harvest runs through the same
+CLI boundary and is available from an instance's action menu.
 
 The probe/mutation contract is specified in
 [desktop-cli-api.md](desktop-cli-api.md).
@@ -95,6 +95,32 @@ first-class: they appear in the roster with a `local` chip, their brains
 and knowledge render, and they spawn like any other soul. Launch flags for
 scripted use: `--dir <workspace>` and `OATS_DESKTOP_PORT`.
 
+## Scheduling agents and wake messages
+
+Open **Schedules** in the selected workspace to launch a new agent on a cron,
+wake an existing agent with a message, or harvest its knowledge. **Schedule…**
+on a Soul roster card preselects that soul. Choose the task or message, repeat
+pattern and time zone; new agent jobs also offer runtime, model, permissions
+and session backend. The list shows the next run, last observed outcome and
+whether the host scheduler is enabled. Pause, edit, run now and delete operate
+on that workspace's saved jobs. Launching an agent is reported separately from
+the end of its run; neither means its task succeeded.
+
+The Spawn dialog also has an optional **Recurring wake-up** setting. It binds
+the schedule to the newly created home, preserving that agent's identity and
+work. A wake starts that same home if it is stopped, then sends the saved
+message through its terminal when ready. It sends no interrupt; the harness
+decides when to process submitted input. Missed cron times are skipped. If the
+agent is created but its wake schedule cannot be saved, the dialog reports both
+facts and directs you to Schedules without spawning another agent.
+
+Use **Enable host scheduler** when the view reports that the timer or workspace
+registration is missing. One host timer handles its registered workspaces with
+a shared limit on scheduled agent launches. The GUI can then be closed. For a
+registered remote workspace the timer and definitions live on that server, so
+they do not depend on the Mac staying awake. See [Schedules](schedules.md) for
+the CLI, cron semantics, observed outcomes and recovery commands.
+
 ## Migrating from the web panel / TUI pane
 
 0.18.2 removes the legacy `oats.web` browser panel, `oats pane`, and the

package/docs/release-notes/v0.22.10.md

@@ -0,0 +1,25 @@
+# OATS v0.22.10
+
+One Desktop defect an operator meets in the sidebar: the instance actions
+control was a native select that did not behave like the rest of the app.
+
+## Sidebar instance actions: an app-styled button and popover
+
+Each instance row's actions control (Harvest knowledge, Retire instance) was
+a native `<select>` labelled with an ellipsis. It rendered with the
+platform's own look, opened as a native menu, and its keyboard and focus
+behaviour did not match the app's other controls. It is now an app-styled
+button that opens a popover. The menu opens from the keyboard or pointer and
+moves focus into its items. Escape and choosing an action close it and return
+focus to the button; clicking outside also dismisses it.
+
+Safety is unchanged. The per-instance pending guard still holds: while a
+harvest or a retirement is in flight for an instance, every control for that
+instance stays disabled until the operation reports, so a second click
+cannot start a duplicate operation, and a roster refresh while an operation
+is pending re-renders the control still disabled. A remote instance with no
+saved route on this machine still has its actions disabled with the same
+explanation.
+
+Nothing else changes: no kernel, session start, start dialog or record
+schema change. Tag v0.22.9 and everything it shipped stand.

package/docs/release-notes/v0.22.11.md

@@ -0,0 +1,49 @@
+# OATS v0.22.11
+
+Schedules: cron-driven agent work that runs on the execution host, from
+the CLI and from Desktop, including while the GUI is closed.
+
+## Schedules (kernel)
+
+`oats schedule` keeps a per-workspace `oats-schedules.json` of jobs of three
+kinds: **spawn** launches a soul as a fresh disposable instance with a task,
+**command** runs an `oats` command in a directory (a harvest, for example),
+and **wake** starts a stopped instance if needed and sends it a message
+through its terminal. Cron expressions are five-field with an IANA time
+zone, evaluated by croner; missed minutes are skipped, never caught up.
+
+One host timer (`oats schedule host install`: a launchd agent or a systemd
+user timer) ticks every registered workspace once a minute under a shared
+limit on concurrent scheduled launches. A remote workspace's schedules live
+and run on that server; `--server` routes every subcommand there.
+`oats spawn --wake-file <json>` binds a wake schedule to the new home.
+
+Outcomes are what the kernel observed, not a claim that a task succeeded:
+launched, active, ended, stopped, launch-failed, delivered, started,
+skipped, and unknown. A launch whose effects the kernel cannot confirm (a
+timed-out or envelope-less command, an incomplete rollback) keeps its slot
+as unknown until `oats schedule reconcile <id>` adopts a named receipt or
+the operator clears it with `--clear`. A wake's launch slot follows the
+runtime through the session start receipt, so a persistent home whose
+process exited frees the slot. Locks are never reclaimed automatically;
+an unreadable or dead owner names the directory to remove.
+`oats version --json` advertises feature `schedule` and `scheduleApi: 1`.
+See docs/schedules.md.
+
+## Schedules (Desktop)
+
+A **Schedules** view per workspace: create, edit, pause, run now, check run
+state and delete jobs through a single JSON spec; the Soul roster's
+**Schedule…** preselects the soul; the spawn dialog offers a recurring wake
+for the new agent, forwarded inline to a remote server. Mutations require
+an explicit workspace. The reconcile result and its recovery instructions
+stay visible across polling. **Enable host scheduler** installs the timer
+and registers the workspace. See docs/desktop.md.
+
+## Tests
+
+The kernel adds `test/schedule.test.mjs` (fixture homes, injected
+spawn/start/input, dummy commands, fixture-only host unit paths) and
+`test/schedule-session.test.mjs`, which drives a real private tmux socket
+to prove literal delivery, same-minute deduplication and slot release when
+a runtime stops. Nothing in the suites touches a live timer.

package/docs/release-notes/v0.22.12.md

@@ -0,0 +1,53 @@
+# OATS v0.22.12
+
+The same reviewed content as the unpublished v0.22.11 tag, whose hosted
+run failed in test fixtures before anything was published; those fixtures
+are fixed here.
+
+Schedules: cron-driven agent work that runs on the execution host, from
+the CLI and from Desktop, including while the GUI is closed.
+
+## Schedules (kernel)
+
+`oats schedule` keeps a per-workspace `oats-schedules.json` of jobs of three
+kinds: **spawn** launches a soul as a fresh disposable instance with a task,
+**command** runs an `oats` command in a directory (a harvest, for example),
+and **wake** starts a stopped instance if needed and sends it a message
+through its terminal. Cron expressions are five-field with an IANA time
+zone, evaluated by croner; missed minutes are skipped, never caught up.
+
+One host timer (`oats schedule host install`: a launchd agent or a systemd
+user timer) ticks every registered workspace once a minute under a shared
+limit on concurrent scheduled launches. A remote workspace's schedules live
+and run on that server; `--server` routes every subcommand there.
+`oats spawn --wake-file <json>` binds a wake schedule to the new home.
+
+Outcomes are what the kernel observed, not a claim that a task succeeded:
+launched, active, ended, stopped, launch-failed, delivered, started,
+skipped, and unknown. A launch whose effects the kernel cannot confirm (a
+timed-out or envelope-less command, an incomplete rollback) keeps its slot
+as unknown until `oats schedule reconcile <id>` adopts a named receipt or
+the operator clears it with `--clear`. A wake's launch slot follows the
+runtime through the session start receipt, so a persistent home whose
+process exited frees the slot. Locks are never reclaimed automatically;
+an unreadable or dead owner names the directory to remove.
+`oats version --json` advertises feature `schedule` and `scheduleApi: 1`.
+See docs/schedules.md.
+
+## Schedules (Desktop)
+
+A **Schedules** view per workspace: create, edit, pause, run now, check run
+state and delete jobs through a single JSON spec; the Soul roster's
+**Schedule…** preselects the soul; the spawn dialog offers a recurring wake
+for the new agent, forwarded inline to a remote server. Mutations require
+an explicit workspace. The reconcile result and its recovery instructions
+stay visible across polling. **Enable host scheduler** installs the timer
+and registers the workspace. See docs/desktop.md.
+
+## Tests
+
+The kernel adds `test/schedule.test.mjs` (fixture homes, injected
+spawn/start/input, dummy commands, fixture-only host unit paths) and
+`test/schedule-session.test.mjs`, which drives a real private tmux socket
+to prove literal delivery, same-minute deduplication and slot release when
+a runtime stops. Nothing in the suites touches a live timer.

package/docs/schedules.md

@@ -0,0 +1,143 @@
+# Schedules
+
+A schedule launches an agent, runs an oats command, or wakes an existing
+instance on a cron. Definitions belong to a scope, the team workspace (the
+config level that declares the team, else the outermost `oats-config.yaml`
+level), and are committable; every `oats schedule` command run anywhere
+inside that scope, including from an instance home, reads and writes the
+same file. Execution belongs to the host that holds the scope, so a
+schedule on a registered server keeps running while your laptop sleeps.
+
+There is no daemon. One host timer (a launchd user agent on macOS, a systemd
+user timer on Linux) runs `oats schedule tick --host` once a minute; the tick
+is a short-lived process that evaluates only the current minute, launches
+what is due through the same `spawn`, `session start` and `session input`
+paths you use by hand, records what it observed, and exits. Minutes missed
+while the machine slept are skipped, never replayed. There are no retries
+and no queue.
+
+## Files
+
+- `<workspace>/oats-schedules.json` — the definitions (`{version: 1, jobs:
+  {<id>: ...}}`). Commit it if you want the schedule shared with the team.
+- `<workspace>/.agents/schedules/state.json` — last attempted minute and
+  last run per job (gitignored), plus one lock directory per running job.
+- `~/.oats/schedules/registry.json` — the host registry: which scopes the
+  host ticks, `maxConcurrent` (default 1) and the tick interval. One host
+  lock serializes ticks, run-now, reconcile and remove; it is never reclaimed
+  by another process: a lock whose owner is unreadable or gone is reported
+  with the directory to remove, and the holder removes its own lock on exit
+  and on SIGINT/SIGTERM. Definition edits take a short per-scope lock.
+
+## Kinds
+
+- **spawn** `{id, enabled, cron, tz, kind: "spawn", agent, agentsRoot?,
+  repo?, backend?, purpose?, task, runtime?, model?, yolo?, wake?}` — every
+  due minute launches one disposable instance of `agent` with the same
+  options `oats spawn` takes. `agentsRoot` names the exact agents root that
+  holds the soul (it must lie inside the workspace and defaults to the
+  workspace's own root); it is what tells same-named souls in different
+  member repositories apart. `repo` is the work repository, as `--repo`. The task gets a trailing schedule block naming the job and the
+  minute and ending with `oats retire --self`. An optional `wake` object
+  (`{cron, tz, message}`) attaches a wake schedule to each launched instance;
+  nothing is attached unless you ask.
+- **command** `{id, enabled, cron, tz, kind: "command", cwd, argv}` — runs
+  an oats-only argv (`argv[0]` is `oats`, no shell) in `cwd`, which must be
+  inside the workspace. The runner parses the command's envelope and tracks
+  any instance it names, so `["oats", "okf", "harvest"]` run in a source
+  instance's home is followed until the harvester it spawned is gone.
+  Command return is not task completion.
+- **wake** `{id, enabled, cron, tz, kind: "wake", home, message}` — every
+  due minute inspects the instance at `home` through its session receipts.
+  Running: `message` is delivered once with `session input`. Not running
+  (absent, dead pane or fallback shell): the same home is started with
+  `session start` and the message becomes the job's one pending delivery,
+  completed on a later tick, any tick, as soon as the session is active; the
+  home is started again only at due minutes, never every minute, so a
+  harness that keeps exiting is not restarted in a loop. A job holds at most
+  one pending delivery: a due minute while one is pending adds nothing.
+  Unobservable or still starting: skipped with the reason, delivery kept
+  pending. Whether a running harness is busy cannot be seen from the
+  terminal: delivery is terminal input (bracketed paste plus Enter), never an
+  interrupt, never Ctrl-C, never into a stopped or starting shell. Word wake
+  messages so that receiving one again is harmless.
+
+`cron` has five fields (minute hour day month weekday) and `tz` is a
+required IANA zone; both are evaluated by the croner library. `--wake-every
+N` at spawn time means `*/N * * * *`: every 7 fires at :00, :07, ... :56 and
+then :00 again, so 1, 5, 10, 15 and 30 give an even cadence.
+
+## Commands
+
+```sh
+oats schedule add <id> --file spec.json --dir <workspace> --json
+oats schedule update <id> --file spec.json
+oats schedule list | show <id> | enable <id> | disable <id> | remove <id>
+oats schedule run <id>            # now, under the same lock and bound
+oats schedule tick --dry-run      # what would run this minute, launching nothing
+oats schedule reconcile <id> [--clear]   # resolve an attempt whose result was never recorded
+oats schedule host install        # register this scope and install the ONE host timer (idempotent while active)
+oats schedule host status | uninstall
+oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?"   # or --wake-file spec.json
+```
+
+Every subcommand takes `--server <id>` instead of `--dir`: it then runs on
+that host, in its registered workspace, because schedules are host-owned.
+
+`list --json` answers `{schedules: [{id, ...definition, nextRun, lastRun,
+running}], scheduler: {installed, active, lastTick, maxConcurrent, ...}}`.
+`active` is what the OS reports about the timer, not whether a file exists.
+
+## What a run reports
+
+`launched` (spawn or command returned), `active` (the instance is running;
+a home whose retirement is pending still counts, its runtime may be alive),
+`ended` (its home is gone), `stopped` (home present, nothing running: needs
+attention, never removed for you), `launch-failed`, `unknown`, and for wake
+jobs `delivered`, `started` or `skipped`. The kernel never claims a task
+succeeded.
+
+`unknown` means the launch's side effects are unconfirmed: a command timed
+out or answered no envelope, an envelope named an instance the roster
+cannot place, or an attempt was never recorded. The job keeps its slot and
+is skipped until `oats schedule reconcile <id>`. Reconcile adopts only an
+attributable receipt: a spawn job's instance is named deterministically for
+its minute, a command job's only by the instance its answer named. Nothing
+is inferred from file times. A command whose answer named nothing stays
+unknown; check the roster and the host by hand, then
+`oats schedule reconcile <id> --clear` records launch-failed and frees the
+slot (or `remove --force` forgets the job).
+
+A wake job that starts a stopped home holds a launch slot while that
+runtime is starting, active, retiring or unobservable, and releases it when
+the runtime is proven stopped (the session start receipt's exit marker for
+that launch, or a home that no longer has a session) or the home is gone.
+A persistent home that outlives its process does not keep a slot. Delivering
+a message to a home that is already running takes no slot. The host tick
+observes every registered scope first, then admits due jobs in one
+host-wide order, least recently launched first (only an actual runtime
+launch counts; a skipped or pending job keeps its place at the front), so
+one frequent job in one scope cannot keep the only slot forever. An invalid
+or malformed definition is reported on that job and the rest of the tick
+continues.
+
+`disable` never stops anything. `update` never touches a running instance,
+and while a job holds a slot or has an unresolved attempt what its run is
+tracked or reconciled by (kind, agent, agentsRoot, repo, purpose, home, cwd,
+argv) cannot change; cron, tz, task, message, runtime, model and enabled
+can. A cold wake persists its slot before the session start runs and keeps
+it on any start exception, whatever its code (the kernel can refuse while
+recording, after the session exists); the next observation releases it once
+the runtime is proven stopped or absent, one tick at worst.
+`remove` refuses while the job's instance is still tracked (`--force`
+forgets the job without stopping anything). Retiring an instance removes the
+wake jobs bound to its home; a wake whose home is gone otherwise stays
+listed with its skipped reason.
+
+## Wake at spawn
+
+`oats spawn ... --wake-file <private JSON {cron, tz, message, enabled}>`
+saves a wake job `wake-<instance>` bound to the new home after the spawn
+succeeded. If the spawn succeeds but the save fails, the spawn result still
+carries the full instance receipt, plus `wakeScheduleError` and a warning;
+the instance is neither hidden nor spawned again.