@awebai/oats 0.22.10 → 0.22.14

package/bin/oats.mjs

@@ -39,8 +39,11 @@ 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";
+import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
 
 const args = process.argv.slice(2);
 const cmd = args[0];
@@ -2754,6 +2757,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 +2801,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 +2825,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 +2850,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 +2892,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");
@@ -2866,7 +2961,19 @@ async function sessionCmd() {
       if (file === true) throw Object.assign(new Error("--text-file needs a path"), { code: "E_BAD_ARGS" });
       if (!file && process.stdin.isTTY) throw Object.assign(new Error("provide --text-file or pipe input on stdin"), { code: "E_BAD_ARGS" });
       result = inputInstanceSession(home, readFileSync(file || 0, "utf8"));
-    } else throw Object.assign(new Error("usage: oats session inspect|input|attach|start --home /absolute/home [--text-file path] [--model id] [--json]"), { code: "E_BAD_ARGS" });
+    } else if (args[1] === "receive") {
+      // Bytes arrive on stdin (the routed upload pipes them through ssh),
+      // collected event-driven and bounded before anything is written.
+      const name = flag("name");
+      if (!name || name === true) throw Object.assign(new Error("session receive needs --name <file name>"), { code: "E_BAD_ARGS" });
+      if (!home || home === true) throw Object.assign(new Error("session receive needs --home </absolute/instance>"), { code: "E_BAD_ARGS" });
+      if (process.stdin.isTTY) throw Object.assign(new Error("session receive reads the attachment bytes from stdin"), { code: "E_BAD_ARGS" });
+      result = receiveAttachment(home, name, await readStreamBounded(process.stdin, MAX_ATTACHMENT_BYTES));
+    } else if (args[1] === "upload") {
+      const file = flag("file");
+      if (!file || file === true) throw Object.assign(new Error("session upload needs --file <local path>"), { code: "E_BAD_ARGS" });
+      result = uploadAttachment({ file, home: home === true ? undefined : home });
+    } else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|receive|upload --home /absolute/home [--text-file path] [--model id] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
     if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2));
   } catch (e) { cmdFail(e.code || "E_SESSION_FAILED", e.message); }
 }
@@ -3161,7 +3268,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", "session-upload"], features: ["retire-home", "session-start", "schedule", "session-upload"], scheduleApi: SCHEDULE_API }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3316,6 +3423,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") {
@@ -3342,7 +3475,19 @@ function serverRouteCmd() {
       console.log(`Started ${r.instance || r.home} on ${id} (${r.backend}${r.model ? `, model ${r.model}` : ""}, ${r.reused === "pane" ? "in its existing pane" : r.reused === "adopted" ? "adopted the pending session" : "new window"})`);
       return;
     }
-    if (args[1] !== "attach") bail("E_USAGE", "--server routes `session inspect`, `session start` and `session attach`; input runs on the execution host (the wake broker calls it there)");
+    if (args[1] === "upload") {
+      // Bytes stream to `session receive` on the execution host over the
+      // same route as attach; the answer's checksum is verified here.
+      const file = flag("file");
+      if (!file || file === true) bail("E_BAD_ARGS", "session upload needs --file <local path>");
+      let r;
+      try { r = uploadAttachment({ file, server: id, ...addr }); } catch (e) { bail(e.code || "E_UPLOAD_FAILED", e.message); }
+      if (r.stderr) process.stderr.write(r.stderr + "\n");
+      if (JSON_MODE) { jsonOk(r); return; }
+      console.log(`Uploaded ${r.name} (${r.bytes} bytes) to ${r.instance || r.home} on ${id}: ${r.path}`);
+      return;
+    }
+    if (args[1] !== "attach") bail("E_USAGE", "--server routes `session inspect`, `session start`, `session upload` and `session attach`; input runs on the execution host (the wake broker calls it there)");
     let route;
     try { route = attachArgv(id, addr, { skipVersionCheck: args.includes("--print") }); }
     catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
@@ -3365,6 +3510,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 +3589,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 +3622,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();
@@ -3525,11 +3689,27 @@ Usage:
   oats session start --server <id>           start a stopped remote instance in its existing home
       --instance <name> | --home <abs>       over its saved route; the server must advertise
       [--model <m>] [--json]                 session-start (oats 0.22.9 or later)
+  oats session upload --server <id>          copy a local file into a remote instance's private
+      --instance <name> | --home <abs>       attachments over its saved route (bytes stream on
+      --file <path> [--json]                 ssh stdin; sha256 verified); the server must
+                                            advertise session-upload (oats 0.22.13 or later)
   oats create <name> [--local]               create an agent soul; --local = full
       [--description <d>] [--repo <r>]      soul under local-agents/ (uncommitted,
       [--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 upload --file <path>          store a copy of a local file as a private attachment
+      --home <absolute-home> [--json]         in the instance home (.oats-attachments/); answers
+                                            {path, bytes, sha256}; never types into the session
+  oats session receive --home <abs> --name   store attachment bytes read from stdin (the routed
+      <file> [--json]                       upload's remote half)
   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/design/2026-09-07-architecture-reassessment.md

@@ -0,0 +1,131 @@
+# Architecture reassessment: usable agents with replaceable services
+
+Assessment of main `76c0ea4`, September 7, 2026. Requested by Juan after
+operating the Desktop; incorporates Pepe's terminal, shortcut, split and soul
+management feedback. This records the direction and implementation gaps, not a
+claim that every item below has shipped.
+
+The requirements authority for this assessment is Juan's September 3
+“Architecture simplification and generlization” in his OATS project KB:
+souls carry instructions and capabilities; a harvester converts ephemeral
+state into knowledge accessible through the selected knowledge capability;
+packages distribute souls and capabilities; OATS constructs and operates
+instances across runtimes and platforms. The private Bookshelf README points
+to September 1's adoption/sovereignty strategy. Its relevant constraint is that
+changing a runtime or service provider must not erase the team's relationships
+or working knowledge. The older August proposals about genomes, clothes and
+turn-record experiments are background, not reasons to expand this release.
+
+## Decision
+
+Keep the existing package and capability-layer mechanism. Correct the places
+where the CLI and GUI bypass it. The architecture is broadly right; the
+operator experience and some service boundaries are incomplete. More
+abstractions will not fix a terminal that cannot accept a screenshot.
+
+| Component | Owns | Must not assume |
+|---|---|---|
+| OATS kernel | Soul/instance construction, configuration, lifecycle, host placement, scheduling, capability resolution | A particular knowledge provider, messaging service, or GUI |
+| Session backend | Durable terminal, attach/detach, resize, literal input, observation | OATS soul/package semantics or task success |
+| Knowledge capability | Knowledge access and representation; its harvester and promotion policy | Every installation uses OKF or stores memory in the same files |
+| Messaging capability / aweb | Durable messages, identities, event subscriptions and delivery policy | A particular model harness or an open Desktop window |
+| Task capability | Durable work and task semantics | A particular terminal backend |
+| Desktop | Inspect effective configuration; explicit operator actions; terminal input, files, layout | Provider names, SSH commands, or a second lifecycle implementation |
+
+Scheduling belongs to OATS, and a scheduled harvest is one use of scheduling.
+Harvesting behavior belongs to the knowledge capability. Starting an agent,
+writing a prompt, and producing reviewed knowledge are different outcomes.
+The UI must retain those distinctions.
+
+## What already fits, and what does not
+
+`lib/core.mjs` already selects exclusive knowledge/messaging/tasks layers by
+manifest, resolves scoped capability settings, dispatches lifecycle hooks, and
+materializes runtime instructions. Jira and Linear demonstrate that a layer
+can have alternative implementations. OKF's harvester is already an exported
+capability agent. There is no reason to replace this machinery.
+
+The remaining coupling is concrete:
+
+- The retire receipt reads `hookResults.meta["oats.okf"].harvested`, although
+  current OKF does not supply a retire hook. Remove the dead provider-specific
+  inference; do not invent successful harvesting at retirement.
+- Remote capability routing recognizes `okf harvest` specifically in
+  `bin/oats.mjs` and `lib/servers.mjs`.
+- Desktop harvest actions and scheduled-harvest definitions construct
+  `oats okf harvest`; the editor recognizes that exact argv.
+- The “brain” view presents `STATE.md`, `log.md` and `notes/` as universal
+  knowledge structure. These are conventions of the current setup.
+
+The next service contract should expose the **effective knowledge provider and
+its supported operations for a specific soul/home**. Discovering a capability
+command namespace alone is insufficient: it does not promise a `harvest` verb
+or a shared file layout. A provider may offer harvest, different operations,
+or read-only access. Desktop must show only declared operations and route
+execution through the selected CLI capability. The same resolution must apply
+locally, remotely, and when a scheduled operation runs.
+
+Keep that change small: explicit operation metadata, scoped discovery, and one
+invocation route using the existing capability engine. Do not add a plugin
+framework, generic workflow language, or a second knowledge store. Demonstrate
+replaceability with a tiny alternative-provider fixture that uses a different
+command and storage layout; a full second product is unnecessary.
+
+## tmux and Herdr
+
+The current kernel defaults to a shared tmux session (`pi-agents`) with a
+window per instance. An agent does not require another tmux server. The GUI
+creates a temporary session linking only the selected window. That isolates
+viewers: switching a terminal elsewhere cannot redirect a GUI tab to another
+agent, and an agent exiting cannot silently expose a sibling under its label.
+The `oatsdesk-*` name in Juan's screenshot is this viewer. Its status bar can
+be hidden with a viewer-local setting. Do not alter global tmux settings or
+merge/move live agent sessions to solve a display defect.
+
+Herdr 0.8.2 is a separate terminal runtime, not a tmux-compatible superset.
+Its documented direct terminal attachment, socket API, events and SSH support
+are useful. Its semantic agent state comes from detection and/or integrations;
+it is richer evidence, not proof that a particular message was consumed.
+The [socket API](https://herdr.dev/docs/socket-api/) explicitly distinguishes
+agent-state waits from arbitrary command completion. The
+[remote documentation](https://herdr.dev/docs/persistence-remote/) also
+separates a local thin client from running a client entirely on the server;
+only the former can directly bridge the local desktop clipboard.
+
+Keep one OATS session contract and both existing adapters for now. Do not add
+another supervisor above them. Qualify Herdr's actual literal multi-line
+input, exact occupant checks, detach, resize, process exit and remote behavior
+before selecting it as the default for new instances. Inspect `pane run`
+implementation before replacing it merely because its name sounds like shell
+execution. Removing tmux is a later deployment choice, not a prerequisite for
+consistent UI or remote agents. Existing tmux agents stay where they are.
+
+## Desktop correction sequence
+
+1. **Terminal essentials.** Hide viewer chrome, accept dropped files and pasted
+   images without pressing Enter, upload remote files to the execution host,
+   preserve the destination tab across async work, and show transfer failures.
+   Keep a single GUI and bounded viewers. This is the immediate implementation.
+2. **Keyboard and splits.** Restore Ctrl+Tab navigation inside Mac terminals;
+   let an already-open terminal fill an empty split without a second attach;
+   expose draggable and keyboard-operable separators. Follow up specific
+   keyboard reports with real input tests, especially terminal editing keys
+   and non-US layouts. App shortcuts must not silently steal terminal edits.
+3. **Souls & capabilities.** Replace the launch-centric roster with a management
+   surface showing souls, installed capabilities, effective layer providers,
+   source/version, scoped activation and runtime defaults. Inspect and launch
+   are distinct actions. Edits use existing CLI operations with the exact scope
+   visible; installing a capability must not silently activate it. This is not
+   a marketplace or Team Builder project.
+4. **Provider-neutral operations.** Introduce the scoped operation contract
+   above, then use it for manual harvest, schedules and knowledge inspection.
+   No second hardcoded default is accepted as a generalization.
+5. **Operating rollout.** Enable schedules per team with the owner's learning
+   policy. Capture-lock recovery is a separate reliability issue affecting
+   unattended harvesting; it does not block arbitrary scheduled wakes.
+
+Acceptance must include real Electron file objects, actual terminal bytes,
+remote transfer hashes, split focus/resize without extra PTYs, and a provider
+replacement fixture. Unit tests of mocked argv alone do not establish these
+boundaries. Reuse the existing agents and GUI sparingly; no model is needed to
+exercise attachment transport or terminal layout.

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
@@ -185,3 +211,19 @@ certificate auto-discovery disabled) and
 marked build-verify mode (inventory + strict codesign verification +
 node-pty ABI, no GUI launch); a local
 interactive run may also exercise the launch phase.
+
+### Attach files and screenshots
+
+Drop a file onto an agent terminal to insert its path into that agent's draft.
+Pasting an image from the clipboard uses the same attachment path. Neither
+operation presses Enter. Text paste continues to use the terminal's normal
+paste behavior. A drop targets the pane under the pointer, including a visible
+pane in a split.
+
+Local files are referenced in place. Clipboard images are saved privately in
+Desktop's application-data `attachments` directory and retained so an agent can
+read them later. For remote terminals, Desktop calls the installed CLI's
+`session upload` operation; it inserts the returned path only after the file
+has reached the execution host. Both CLI installations must advertise
+`session-upload`. A failed transfer leaves the draft unchanged and shows an
+error in the terminal. Each drop/paste accepts up to 16 files totaling 25 MB.

package/docs/execution-targets.md

@@ -181,6 +181,27 @@ pane in that exact window. Herdr additionally verifies the original terminal ID.
 The broker owns busy/approval policy and must not interpret `submitted` as
 processing acknowledgement.
 
+### Attachments
+
+A viewer that drops a file or pastes an image gives the agent a path, never
+terminal input. `oats session upload --file <local> --home <abs>` stores a
+copy as a private file under `<home>/.oats-attachments/` (directory 0700,
+file 0600, `name-2` on collision) and answers `{path, bytes, sha256}`; the
+caller pastes `path` into the still-live session itself. With `--server <id>`
+and `--instance <name>` (or `--home`), the same saved route as attach is
+resolved, the remote must list `session-upload` in both its `remote` and
+`features` probe arrays, and the bytes travel on ssh stdin into `oats session
+receive --home <abs> --name <file>` on the execution host. Each side holds
+the whole file in memory up to the 64 MiB kernel bound (this is a bounded
+transfer, not end-to-end streaming); the receiver reads stdin event-driven,
+refuses above the bound before writing, and allocates the destination
+exclusively (`name-2`, `name-3` when taken), so simultaneous uploads of one
+name never overwrite each other and a planted symlink is never followed. The
+attachments directory must be a real directory inside the home. The local
+side refuses the result unless the remote's size and sha256 equal the local
+file's. A remote file is never a local path over SSH. Attachments live and
+die with the home.
+
 Capability spawn hooks register a pending home before runtime allocation;
 inspection becomes available once its receipt is persisted. Retire hooks
 unregister after quiescence. The broker must tolerate this lifecycle order and

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.