@awebai/oats 0.39.4 → 0.40.1

package/lib/schedule-command-child.mjs

@@ -0,0 +1,58 @@
+/** Private entry point for schedule-command.mjs; no CLI or provider contract.
+ * stdin carries launch arguments, stdout carries the observed command result.
+ * Command output has separate pipes so it cannot forge that result. */
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { signalGroup } from "./process-group.mjs";
+
+const { file, args, timeout, graceMs, maxBuffer } = JSON.parse(readFileSync(0, "utf8"));
+const result = await new Promise((resolve) => {
+  let child, status = null, signal = null, error;
+  let exited = false, closed = false, stopping = false, hardEnd = false, settled = false;
+  let deadline, escalation, probe, groupEmpty = false;
+  const chunks = { stdout: [], stderr: [] }, sizes = { stdout: 0, stderr: 0 };
+  const groupAlive = () => {
+    if (groupEmpty || !child?.pid) return false;
+    if (process.platform === "win32") return !exited;
+    try { process.kill(-child.pid, 0); return true; }
+    catch { groupEmpty = true; return false; }
+  };
+  const send = (sig) => {
+    if (process.platform === "win32") { if (!exited) child.kill(sig); }
+    else if (groupAlive()) signalGroup(child, sig);
+  };
+  const finish = () => {
+    if (settled || (!closed && !hardEnd) || (!exited && child?.pid)) return;
+    // A leader can close while a pipe-free descendant ignores TERM. Keep the
+    // supervisor alive until the grace ends or its group is observed empty.
+    if (stopping && !hardEnd && groupAlive()) return;
+    settled = true;
+    clearTimeout(deadline); clearTimeout(escalation); clearInterval(probe);
+    resolve({ status, signal, stdout: Buffer.concat(chunks.stdout).toString("utf8"), stderr: Buffer.concat(chunks.stderr).toString("utf8"), ...(error ? { error } : {}) });
+  };
+  const stop = (cause) => {
+    if (stopping || settled) return;
+    stopping = true; error = cause;
+    send("SIGTERM");
+    escalation = setTimeout(() => {
+      send("SIGKILL"); hardEnd = true;
+      // A detached descendant can escape the group yet retain inherited pipes.
+      // Its pipes must not prevent returning after the direct child's exit.
+      child.stdout.destroy(); child.stderr.destroy();
+      finish();
+    }, graceMs);
+    probe = setInterval(() => { if (closed) finish(); }, Math.min(50, graceMs));
+  };
+  try { child = spawn(file, args, { detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"] }); }
+  catch (e) { error = { code: e.code, message: e.message }; closed = true; finish(); return; }
+  for (const stream of ["stdout", "stderr"]) child[stream].on("data", (chunk) => {
+    const room = maxBuffer - sizes[stream];
+    if (room > 0) { const kept = chunk.subarray(0, room); chunks[stream].push(kept); sizes[stream] += kept.length; }
+    if (chunk.length > room) stop({ code: "ENOBUFS", message: `schedule command ${stream} exceeded ${maxBuffer} bytes` });
+  });
+  child.once("error", (e) => { error ??= { code: e.code, message: e.message }; });
+  child.once("exit", (code, sig) => { exited = true; status = code; signal = sig; finish(); });
+  child.once("close", () => { closed = true; finish(); });
+  deadline = setTimeout(() => stop({ code: "ETIMEDOUT", message: `schedule command exceeded ${timeout} ms` }), timeout);
+});
+process.stdout.write(JSON.stringify(result));

package/lib/schedule-command.mjs

@@ -0,0 +1,26 @@
+/** Synchronous scheduler child execution with an asynchronous timeout supervisor.
+ * The tick and its lock callbacks stay synchronous; only the supervisor owns
+ * the child, observes its exit and runs the TERM/KILL timers. Its stdout is a
+ * private result channel, never the command's stdout. */
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { TERM_GRACE_MS } from "./process-group.mjs";
+
+const SUPERVISOR = fileURLToPath(new URL("./schedule-command-child.mjs", import.meta.url));
+export function runScheduleCommand(file, args, { cwd, env, timeout = 300_000, graceMs = TERM_GRACE_MS, maxBuffer = 16 * 1024 * 1024 } = {}) {
+  for (const [name, value] of Object.entries({ timeout, graceMs, maxBuffer })) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 2 ** 31 - 1) throw new TypeError(`${name} must be a positive 32-bit integer`);
+  }
+  const r = spawnSync(process.execPath, [SUPERVISOR], {
+    cwd, env, encoding: "utf8", input: JSON.stringify({ file, args, timeout, graceMs, maxBuffer }),
+    // Each output stream is byte-bounded. JSON can expand a byte to six bytes.
+    maxBuffer: maxBuffer * 12 + 65536,
+  });
+  if (!r.error && r.status === 0) {
+    try { return JSON.parse(r.stdout); } catch { /* no trusted supervisor receipt */ }
+  }
+  // A failed supervisor is not evidence that its command exited. The scheduler
+  // conservatively retains the attempt and slot when there is no receipt.
+  return { status: null, signal: null, stdout: "", stderr: String(r.stderr || ""),
+    error: { code: r.error?.code || "E_SCHEDULE_RUNNER", message: r.error?.message || "schedule child supervisor returned no result" } };
+}

package/lib/schedule.mjs

@@ -19,8 +19,9 @@
  *  observed (launched, active, ended, stopped, launch-failed, unknown;
  *  delivered, started, skipped for wake) and never claim that a task
  *  succeeded. A launch whose side effects cannot be confirmed stays
- *  `unknown` with its slot held until `reconcile` proves what happened. */
-import { spawnSync } from "node:child_process";
+ *  `unknown`, its job blocked until `reconcile` proves what happened; it keeps
+ *  its host slot too, unless it is a command whose process exit was observed. */
+import { runScheduleCommand } from "./schedule-command.mjs";
 import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
@@ -33,12 +34,12 @@ import { herdrSettingRemoved } from "./errors.mjs";
 import { withDirLock as withSharedDirLock } from "./dir-lock.mjs";
 import { tickTriggers } from "./triggers.mjs";
 import { resolveMemberClone } from "./instance-resolution.mjs";
-import { AUTOMATION_ID_RE, MODEL_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";
+import { SCHEDULE_NAME_RE, readSnapshot, MODEL_RE, automationContext, automationError, baseRow, localEntry, localId, soulOriginOf, splitId } from "./automations.mjs";
+import { RESERVED_LAUNCH_ENV, MAX_INSTANCE_NAME, shq, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
 
 export const SCHEDULE_FILE = "oats-schedules.json";
 export const SCHEDULE_API = 2;
-const ID_RE = /^[a-z0-9-]{1,40}$/;
+const ID_RE = SCHEDULE_NAME_RE;
 const HARNESSES = new Set(["pi", "claude", "codex"]);
 const MESSAGE_MAX = 256 * 1024;
 const OATS_BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "oats.mjs");
@@ -204,22 +205,51 @@ export function writeState(ws, st) { recordRecentRuns(st); writeJson(statePath(w
 
 // ------------------------------------------------------- host registry
 
-export function readRegistry() {
-  const reg = readJson(join(hostScheduleDir(), "registry.json"), { version: 1, maxConcurrent: 1, tickIntervalSec: 60, workspaces: [] });
+const DEFAULT_MAX_CONCURRENT = 5;
+const scheduleCap = (reg) => reg.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+
+/** Call under registry.lock: persisted caps are explicit operator choices.
+ * Pre-v2 registries wrote 1 even when the operator chose nothing. Migrate it
+ * once; a subsequent explicit 1 is distinguished by capsVersion: 2. */
+function readRegistryLocked() {
+  const path = join(hostScheduleDir(), "registry.json");
+  const reg = readJson(path, { version: 1, capsVersion: 2, tickIntervalSec: 60, workspaces: [] });
   if (!Array.isArray(reg.workspaces)) reg.workspaces = [];
-  if (!Number.isInteger(reg.maxConcurrent) || reg.maxConcurrent < 1) reg.maxConcurrent = 1;
+  if (reg.maxConcurrent !== undefined && (!Number.isSafeInteger(reg.maxConcurrent) || reg.maxConcurrent < 1)) delete reg.maxConcurrent;
   if (!Number.isInteger(reg.tickIntervalSec) || reg.tickIntervalSec < 60) reg.tickIntervalSec = 60;
-  // The host cap on trigger-spawned live instances (re-review B #5): absent = unbounded (each
-  // trigger's own concurrency.max still applies). Separate from maxConcurrent: a running scheduled
-  // job never holds a trigger, and trigger homes never hold a schedule. Hand-edited, so refused loudly.
+  // Trigger and schedule caps are independent; absent trigger cap is unbounded.
   if (reg.triggersMaxConcurrent !== undefined && !(Number.isSafeInteger(reg.triggersMaxConcurrent) && reg.triggersMaxConcurrent >= 1)) {
-    throw scheduleError("E_SCHEDULE_INVALID", `${join(hostScheduleDir(), "registry.json")}: triggersMaxConcurrent must be a positive integer, or absent for no host cap (got ${JSON.stringify(reg.triggersMaxConcurrent)})`, { field: "triggersMaxConcurrent" });
+    throw scheduleError("E_SCHEDULE_INVALID", `${path}: triggersMaxConcurrent must be a positive integer, or absent for no host cap (got ${JSON.stringify(reg.triggersMaxConcurrent)})`, { field: "triggersMaxConcurrent" });
+  }
+  if ((reg.capsVersion ?? 1) < 2) {
+    if (reg.maxConcurrent === 1) delete reg.maxConcurrent;
+    reg.capsVersion = 2;
+    writeRegistry(reg);
   }
   return reg;
 }
+export function readRegistry() { return withRegistryLock(readRegistryLocked); }
+/** Raw write: callers doing read-modify-write hold registry.lock. */
 export function writeRegistry(reg) { writeJson(join(hostScheduleDir(), "registry.json"), reg); }
-export function registerWorkspace(ws) { return withRegistryLock(() => { const reg = readRegistry(); const abs = resolve(ws); if (!reg.workspaces.includes(abs)) { reg.workspaces.push(abs); writeRegistry(reg); } return reg; }); }
-export function unregisterWorkspace(ws) { return withRegistryLock(() => { const reg = readRegistry(); reg.workspaces = reg.workspaces.filter((w) => w !== resolve(ws)); writeRegistry(reg); return reg; }); }
+export function registerWorkspace(ws, caps = {}) {
+  for (const [field, reset] of [["maxConcurrent", "default"], ["triggersMaxConcurrent", "none"]]) {
+    const value = caps[field];
+    if (value !== undefined && value !== reset && !(Number.isSafeInteger(value) && value >= 1)) {
+      throw scheduleError("E_BAD_ARGS", `${field} must be a positive safe integer or ${reset}`, { field });
+    }
+  }
+  return withRegistryLock(() => {
+    const reg = readRegistryLocked(), before = JSON.stringify(reg), abs = resolve(ws);
+    for (const [field, reset] of [["maxConcurrent", "default"], ["triggersMaxConcurrent", "none"]]) {
+      if (caps[field] === reset) delete reg[field];
+      else if (caps[field] !== undefined) reg[field] = caps[field];
+    }
+    if (!reg.workspaces.includes(abs)) reg.workspaces.push(abs);
+    if (JSON.stringify(reg) !== before) writeRegistry(reg);
+    return reg;
+  });
+}
+export function unregisterWorkspace(ws) { return withRegistryLock(() => { const reg = readRegistryLocked(); reg.workspaces = reg.workspaces.filter((w) => w !== resolve(ws)); writeRegistry(reg); return reg; }); }
 export function readHostState() { return readJson(join(hostScheduleDir(), "state.json"), {}); }
 export function writeHostState(st) { writeJson(join(hostScheduleDir(), "state.json"), st); }
 
@@ -268,6 +298,11 @@ export function validateCron(cron, tz, field = "cron") {
   try { return new Cron(cron.trim(), { timezone: tz, paused: true }); }
   catch (e) { throw scheduleError("E_SCHEDULE_INVALID", `${field}: ${e.message}`, { field }); }
 }
+/** A definition's `description`: a label for people (list, show, the Desktop), never read by a run. */
+const DESCRIPTION_MAX = 200;
+function validateDescription(description) {
+  if (typeof description !== "string" || !description.length || [...description].length > DESCRIPTION_MAX || /[\p{Cc}\u2028\u2029]/u.test(description)) throw scheduleError("E_SCHEDULE_INVALID", `description: one line of 1 to ${DESCRIPTION_MAX} characters, without control characters`, { field: "description" });
+}
 function validateMessage(message, field) {
   if (typeof message !== "string" || !message.trim() || message.includes("\0") || Buffer.byteLength(message) > MESSAGE_MAX) throw scheduleError("E_SCHEDULE_INVALID", `${field}: non-empty text without NUL, at most 256 KiB`, { field });
 }
@@ -286,11 +321,12 @@ export function validateDefinition(ws, def, { checkAgent = true, backendSource }
   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" });
+  if (typeof id !== "string" || !ID_RE.test(id)) throw scheduleError("E_SCHEDULE_INVALID", "id: lowercase letters, digits and dashes, 1 to 100 characters", { field: "id" });
   const enabled = def.enabled === undefined ? true : def.enabled;
   if (typeof enabled !== "boolean") throw scheduleError("E_SCHEDULE_INVALID", "enabled: boolean", { field: "enabled" });
   validateCron(def.cron, def.tz);
   const out = { id, enabled, cron: def.cron.trim(), tz: def.tz.trim(), kind: def.kind };
+  if (def.description !== undefined) { validateDescription(def.description); out.description = def.description; }
   if (def.kind === "spawn") {
     if (typeof def.agent !== "string" || !def.agent.trim() || def.agent.trim().startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", "agent: soul name required (not an option)", { field: "agent" });
     out.agent = def.agent.trim();
@@ -535,9 +571,9 @@ function spawnViaCli(ws, root, agent, opts, context, io) {
   writeFileSync(taskFile, opts.task, { mode: 0o600 });
   argv.push(`--task-file=${taskFile}`);
   let r;
-  try { 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() }); }
+  try { r = runScheduleCommand(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: context.dir, timeout: io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, graceMs: io?.commandGraceMs, maxBuffer: 16 * 1024 * 1024, env: childEnv() }); }
   finally { try { rmSync(taskFile, { force: true }); } catch { /* best effort */ } }
-  const timedOut = r.error?.code === "ETIMEDOUT" || (r.status === null && r.signal === "SIGTERM");
+  const timedOut = r.error?.code === "ETIMEDOUT" || (r.status === null && ["SIGTERM", "SIGKILL"].includes(r.signal));
   const envelope = parseEnvelopeText(r.stdout);
   // The child may have created (and launched) a home before dying: unconfirmed, never a confirmed failure.
   // The thrown message reports RETAINED effects so the tick keeps the attempt and its slot for reconcile.
@@ -591,25 +627,31 @@ export function parseEnvelopeText(text) {
 }
 /** Run one command job: oats-only argv in the job's cwd. A timeout or an
  *  unparseable answer means the side effects are unconfirmed: `unknown`,
- *  never `launch-failed`. `io.oatsBin` and `io.commandTimeoutMs` are test seams. */
+ *  never `launch-failed`. An unconfirmed answer carries `exit` ({status,
+ *  signal}) when the process's exit was observed. The supervisor sends SIGTERM
+ *  at the timeout and SIGKILL after the grace, and observes the direct child's
+ *  exit before returning. `io.command`, `io.oatsBin`, `io.commandTimeoutMs`
+ *  and `io.commandGraceMs` are test seams; `io.command` counts as exited. */
 function launchCommand(ws, def, io) {
   const argv = def.argv.includes("--json") ? def.argv.slice(1) : [...def.argv.slice(1), "--json"];
-  let envelope, timedOut = false, raw = "";
-  if (io?.command) envelope = io.command({ cwd: def.cwd, argv });
+  let envelope, timedOut = false, raw = "", exit;
+  if (io?.command) { envelope = io.command({ cwd: def.cwd, argv }); exit = { status: null, signal: null }; }
   else {
-    const r = spawnSync(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: def.cwd, encoding: "utf8", timeout: io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, killSignal: "SIGTERM", maxBuffer: 16 * 1024 * 1024, env: childEnv() });
-    timedOut = r.error?.code === "ETIMEDOUT" || (r.status === null && r.signal === "SIGTERM");
+    const r = runScheduleCommand(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: def.cwd, timeout: io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, graceMs: io?.commandGraceMs, maxBuffer: 16 * 1024 * 1024, env: childEnv() });
+    timedOut = r.error?.code === "ETIMEDOUT" || (r.status === null && ["SIGTERM", "SIGKILL"].includes(r.signal));
+    if (r.status !== null || r.signal !== null) exit = { status: r.status, signal: r.signal };
     raw = String(r.stdout || "");
     envelope = parseEnvelopeText(raw);
   }
+  const exited = exit ? { exit } : {};
   // No envelope, a malformed one, or a timeout: the process may still have
   // created a home. That is unconfirmed, never a confirmed failure.
-  if (timedOut || !envelope || typeof envelope !== "object" || typeof envelope.ok !== "boolean") return { kind: "command", launched: false, unconfirmed: true, error: timedOut ? "command timed out; its side effects are unconfirmed" : "command answered no valid envelope; its side effects are unconfirmed" };
+  if (timedOut || !envelope || typeof envelope !== "object" || typeof envelope.ok !== "boolean") return { kind: "command", launched: false, unconfirmed: true, ...exited, error: timedOut ? "command timed out; its side effects are unconfirmed" : "command answered no valid envelope; its side effects are unconfirmed" };
   const res = envelope?.result || {};
   const instance = typeof res.instance === "string" ? res.instance : undefined;
   let home = typeof res.home === "string" ? res.home : undefined;
   if (instance && !home) { const found = findHomesInScope(ws, instance); if (found.length === 1) home = found[0]; }
-  if (envelope.ok && instance && !home) return { kind: "command", launched: true, instance, unconfirmed: true, error: `the envelope names instance ${instance} but no home for it is in this scope's roster; run oats schedule reconcile once it appears` };
+  if (envelope.ok && instance && !home) return { kind: "command", launched: true, instance, unconfirmed: true, ...exited, error: `the envelope names instance ${instance} but no home for it is in this scope's roster; run oats schedule reconcile once it appears` };
   // A valid ok:false answer that reports an incomplete rollback (a harvest
   // spawn whose compensation could not stop or remove everything), or an
   // operation runner's unconfirmed outcome (timeout, no valid receipt, a
@@ -619,7 +661,7 @@ function launchCommand(ws, def, io) {
   if (!envelope.ok && (UNCONFIRMED_ERROR_CODES.has(envelope.error?.code) || envelope.error?.details?.unconfirmed === true || reportsRetainedEffects(envelope.error?.message))) {
     const partial = envelope.error?.details?.envelope?.result;
     const named = instance || (partial && typeof partial.instance === "string" ? partial.instance : undefined);
-    return { kind: "command", launched: false, unconfirmed: true, ...(named ? { instance: named } : {}), error: `command outcome unconfirmed: ${envelope.error?.message}`, errorCode: envelope.error?.code };
+    return { kind: "command", launched: false, unconfirmed: true, ...exited, ...(named ? { instance: named } : {}), error: `command outcome unconfirmed: ${envelope.error?.message}`, errorCode: envelope.error?.code };
   }
   // Provenance the recorder has at write time: the answering server (remote
   // spawn) and the launched home's incarnation. Never a transcript.
@@ -721,7 +763,7 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
   const minute = minuteStart(now);
   const key = minuteKey(minute);
   const registry = reg || readRegistry();
-  const bound = registry.maxConcurrent || 1;
+  const bound = scheduleCap(registry);
   const wsAll = wsList || [ws];
   const defs = effectiveDefinitions(ws, ctx);
   const st = readState(ws);
@@ -776,7 +818,11 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
       let invalid;
       try { validateAttemptExecution(js.attempt, jobLockInfo(ws, id)); } catch (error) { invalid = error; }
       record(id, invalid ? "invalid" : "skipped", { reason: invalid ? `admitted attempt is invalid (${invalid.code || "error"}): ${invalid.message}` : "an earlier launch has no recorded result; run oats schedule reconcile", ...(invalid ? { errorCode: invalid.code } : {}) });
-      js.lastRun = { ...(js.lastRun || {}), outcome: "unknown", error: invalid ? `invalid admitted attempt: ${invalid.message}` : "launch attempt without a recorded result", ...(invalid ? { errorCode: invalid.code } : {}), scheduledFor: js.attempt.scheduledFor };
+      // Older kernels kept the cause only on lastRun. Adopt it only for this
+      // attempt: a crash before recording the result can leave a prior run there.
+      const sameRun = js.lastRun?.outcome === "unknown" && js.lastRun.scheduledFor === js.attempt.scheduledFor && js.lastRun.startedAt === js.attempt.startedAt;
+      js.attempt.error ??= (sameRun ? js.lastRun.error : null) ?? "launch attempt without a recorded result";
+      js.lastRun = { ...(sameRun ? js.lastRun : { kind: def.kind }), outcome: "unknown", error: invalid ? `invalid admitted attempt: ${invalid.message}` : js.attempt.error, ...(invalid ? { errorCode: invalid.code } : {}), scheduledFor: js.attempt.scheduledFor, startedAt: js.attempt.startedAt };
       continue;
     }
     if (def.kind === "wake") {
@@ -813,8 +859,14 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
       run = { kind: def.kind, launched: false, error: e.message, errorCode: e.code, unconfirmed: def.kind !== "spawn" || reportsRetainedEffects(e.message) };
     }
     if (run.unconfirmed) {
-      // Side effects unconfirmed: keep the attempt and the slot; reconcile decides.
-      js.lastRun = { scheduledFor: minute.toISOString(), startedAt: now.toISOString(), ...run, outcome: "unknown" };
+      // Side effects unconfirmed: keep the attempt, with its first error; reconcile decides.
+      // A command (or operation) whose process exit was observed runs nothing any more,
+      // so it frees its host slot; its attempt still blocks the job itself. Anything else
+      // (a spawn, a command that threw) keeps the slot.
+      const { exit, ...facts } = run;
+      js.attempt = { ...js.attempt, error: run.error, ...(exit ? { exited: true, exitStatus: exit.status, exitSignal: exit.signal } : {}) };
+      js.lastRun = { scheduledFor: minute.toISOString(), startedAt: now.toISOString(), ...facts, outcome: "unknown" };
+      if (exit) releaseJobLock(ws, id);
       record(id, "unknown", { error: run.error });
       continue;
     }
@@ -894,7 +946,7 @@ export function runNow(ws, qid, { now = new Date(), io, force = false, ctx = nul
     writeState(ws, st);
     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`);
+    if (def.kind !== "wake" && liveLocks(wsList) >= scheduleCap(reg)) throw scheduleError("E_SCHEDULER_BUSY", `host concurrency ${scheduleCap(reg)} reached`);
     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); }
@@ -933,8 +985,7 @@ export function reconcile(ws, qid, { io, now = new Date(), clear = false, ctx =
       if (homes.length === 1) adopted = { instance: `${def.agent}-${purpose}`, home: homes[0] };
       else if (homes.length > 1) ambiguous = `${homes.length} homes named ${def.agent}-${purpose}: ${homes.join(", ")}`;
     } else if (attemptKind === "command" || attemptKind === "operation") {
-      let named = [];
-      if (js.lastRun?.instance) named = findHomesInScope(ws, js.lastRun.instance).map((home) => ({ instance: js.lastRun.instance, home }));
+      const named = namedHomes(ws, js);
       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: 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}` };
@@ -955,6 +1006,60 @@ export function reconcile(ws, qid, { io, now = new Date(), clear = false, ctx =
   });
 }
 
+/** The homes in the scope of the instance a command attempt's answer named: its only adoptable
+ *  receipt. Exactly one is adoptable; none or several leave its effects unproven. */
+function namedHomes(ws, js) {
+  const instance = js.lastRun?.instance;
+  return instance ? findHomesInScope(ws, instance).map((home) => ({ instance, home })) : [];
+}
+
+/** `oats doctor`: every launch attempt without a recorded result (what reconcile acts on: an
+ *  attempt, or a lastRun left `unknown`) in the deployment `dep` and in the other scopes this host
+ *  ticks, which share its slots. Each is a warning with its age, whether it holds a host slot and
+ *  the reconcile command; `--clear` when it is a command whose effects no named home proves.
+ *  Reads state only. → { problems, information } */
+export function unresolvedScheduleAttempts(dep, { now = new Date() } = {}) {
+  const problems = [], information = [];
+  const here = resolve(dep);
+  let scopes = [here];
+  try { scopes = [here, ...readRegistry().workspaces.filter((w) => resolve(w) !== here && existsSync(w))]; }
+  catch (e) { information.push(`the host schedule registry could not be read, so only this deployment's schedules were checked: ${e.message}`); }
+  for (const ws of scopes) {
+    let defs, st;
+    try { defs = readDefinitions(ws); st = readState(ws); }
+    catch (e) { information.push(`the schedules of ${ws} could not be read: ${e.message}`); continue; }
+    // Read the last discovery snapshot directly: placement and refresh would
+    // require credentials/network, and unresolved work matters even when offline.
+    const workspaceKinds = new Map((readSnapshot(ws)?.schedules || []).map((entry) => [entry.id, entry.definition?.kind]));
+    for (const [key, js] of Object.entries(st.jobs)) {
+      if (!js?.attempt && js?.lastRun?.outcome !== "unknown") continue;
+      // A workspace schedule's state key is <member>~<id> (scheduleStateKey); a local one is its id.
+      const workspace = key.includes("~");
+      if (!workspace && !defs.jobs[key]) continue;
+      const id = workspace ? key.replace("~", "/") : key;
+      const kind = (workspace ? workspaceKinds.get(id) : defs.jobs[key]?.kind) ?? js.lastRun?.kind ?? null;
+      const scheduledFor = js.attempt?.scheduledFor ?? js.lastRun?.scheduledFor ?? null;
+      const startedAt = js.attempt?.startedAt ?? js.lastRun?.startedAt ?? null;
+      const started = Date.parse(startedAt);
+      const ageSeconds = Number.isNaN(started) ? null : Math.max(0, Math.floor((now.getTime() - started) / 1000));
+      const holdsSlot = !!jobLockInfo(ws, key);
+      const error = js.attempt?.error ?? js.lastRun?.error ?? null;
+      const unproven = (kind === "command" || kind === "operation") && namedHomes(ws, js).length !== 1;
+      const dir = ws === here ? "" : ` --dir ${/^[\w./@%+=:,-]+$/.test(ws) ? ws : shq(ws)}`;
+      const remedy = `oats schedule reconcile ${id}${unproven ? " --clear" : ""}${dir}`;
+      const message = `schedule ${id}${ws === here ? "" : ` (in ${ws})`}: ${kind ? `a ${kind}` : "a"} launch attempt for ${scheduledFor} has no recorded result (started ${startedAt}${ageSeconds === null ? "" : `, ${formatAge(ageSeconds)} ago`})${error ? `: ${error}` : ""}. The job does not run again until it is reconciled, and ${holdsSlot ? "it holds a host slot (counted against maxConcurrent)" : "it holds no host slot"}. ${unproven ? `Its effects can't be proven: check the roster and the host by hand, then run ${remedy}` : `Run ${remedy}`}`;
+      problems.push({ code: "schedule-unresolved", severity: "warning", scope: ws, id, kind, scheduledFor, startedAt, ageSeconds, holdsSlot, exited: js.attempt?.exited === true, error, remedy, message });
+    }
+  }
+  return { problems, information };
+}
+function formatAge(s) {
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`;
+  return `${Math.floor(s / 86400)}d ${Math.floor((s % 86400) / 3600)}h`;
+}
+
 // -------------------------------------------------------- definitions CRUD
 
 export const SCHEDULE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
@@ -985,7 +1090,7 @@ export function testSchedule(ws, qid, io, { now = new Date(), ctx = null } = {})
       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 r = runScheduleCommand(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: context.dir, timeout: io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, graceMs: io?.commandGraceMs, 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"));
@@ -1036,7 +1141,7 @@ function projectHistory(js) {
 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)})`);
+  if (scope !== "local" && (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(scope) || !SCHEDULE_NAME_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);
@@ -1056,7 +1161,7 @@ export function describe(ws, qid, io, { defs, st, now = new Date(), ctx = null }
   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 } : {}) };
   const herdr = entry ? null : storedHerdrBackend(ws, id, def);
-  return scheduleRow(ws, entry ?? localEntry("schedule", { ...def, id: name }, { dep: ws, ...(herdr ? { invalid: { code: herdr.code, message: herdr.message, field: herdr.field } } : {}) }), base, ctx);
+  return scheduleRow(ws, entry ?? { ...localEntry("schedule", { ...def, id: name }, { dep: ws, ...(herdr ? { invalid: { code: herdr.code, message: herdr.message, field: herdr.field } } : {}) }), description: def.description ?? null }, 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,
@@ -1157,7 +1262,7 @@ function localScheduleId(qid, verb) {
 }
 /** 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(/-+$/, "");
+  const id = `wake-${instance}`.slice(0, 100).replace(/-+$/, "");
   const spec = { id, enabled: wake.enabled === undefined ? true : wake.enabled, cron: wake.cron, tz: wake.tz, kind: "wake", home, message: wake.message };
   return addSchedule(ws, spec);
 }
@@ -1192,5 +1297,5 @@ export function schedulerStatus(ws, io) {
   const host = readHostState();
   let unit = { installed: false, active: false };
   try { unit = (io?.hostStatus || (() => ({ installed: false, active: false, unavailable: true })))(); } catch (e) { unit = { installed: false, active: false, error: e.message }; }
-  return { installed: !!unit.installed, active: !!unit.active, ...(unit.unit ? { unit: unit.unit } : {}), ...(unit.error ? { error: unit.error } : {}), lastTick: host.lastTick || null, maxConcurrent: reg.maxConcurrent, tickIntervalSec: reg.tickIntervalSec, ...(ws ? { workspace: resolve(ws), registered: reg.workspaces.includes(resolve(ws)) } : {}), workspaces: reg.workspaces, live: liveLocks(reg.workspaces.filter((w) => existsSync(w))) };
+  return { installed: !!unit.installed, active: !!unit.active, ...(unit.unit ? { unit: unit.unit } : {}), ...(unit.error ? { error: unit.error } : {}), lastTick: host.lastTick || null, maxConcurrent: scheduleCap(reg), triggersMaxConcurrent: reg.triggersMaxConcurrent ?? null, tickIntervalSec: reg.tickIntervalSec, ...(ws ? { workspace: resolve(ws), registered: reg.workspaces.includes(resolve(ws)) } : {}), workspaces: reg.workspaces, live: liveLocks(reg.workspaces.filter((w) => existsSync(w))) };
 }

package/lib/servers.mjs

@@ -1072,8 +1072,20 @@ export function scheduleRemote(serverId, oatsArgs, io = {}) {
   io = { ...io, serverId };
   const server = io.server || getServer(serverId);
   const target = targetOf(server);
-  const remote = checkRemote(target, io);
-  if (!remote.features.includes("schedule")) throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise schedules; upgrade it there`);
+  const setsHostCaps = oatsArgs[0] === "host" && oatsArgs[1] === "install" && oatsArgs.some((arg) =>
+    ["--max-concurrent", "--triggers-max-concurrent"].some((name) => arg === name || arg.startsWith(`${name}=`)));
+  const capsUnsupported = () => serverError("E_REMOTE_INCOMPATIBLE", `remote oats at ${target.sshHost} (${serverId}) does not confirm required features schedule and schedule-host-caps; upgrade oats on that destination before setting or resetting host caps`);
+  let remote;
+  try {
+    remote = checkRemote(target, io);
+    if (!remote.features.includes("schedule")) throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise schedules; upgrade it there`);
+  } catch (e) {
+    // Unknown probe formats cannot establish cap support. Keep transport
+    // failures distinct, and preserve the existing contract for no-cap calls.
+    if (setsHostCaps && ["E_REMOTE_ENVELOPE", "E_REMOTE_INCOMPATIBLE"].includes(e.code)) throw capsUnsupported();
+    throw e;
+  }
+  if (setsHostCaps && !remote.features.includes("schedule-host-caps")) throw capsUnsupported();
   if (["add", "update"].includes(oatsArgs[0])) {
     const indexes = oatsArgs.flatMap((arg, index) => arg === "--spec-json" ? [index] : []);
     if (indexes.length > 1) throw serverError("E_BAD_ARGS", "remote schedule spec must be unambiguous");

package/package-catalog.json

@@ -28,7 +28,7 @@
     },
     "oats.engineering": {
       "url": "https://github.com/awebai/oats-engineering.git",
-      "ref": "v1.8.0",
+      "ref": "v1.8.1",
       "path": "oats-package"
     },
     "oats.cloning": {
@@ -38,7 +38,7 @@
     },
     "oats.framework": {
       "url": "https://github.com/awebai/oats.git",
-      "ref": "oats-framework/v1.5.0",
+      "ref": "oats-framework/v1.6.0",
       "path": "oats-package"
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.39.4",
+  "version": "0.40.1",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",

package/skills/oats-getting-started/SKILL.md

@@ -60,7 +60,7 @@ members:
   - git:github.com/acme/agents          # the host is a member too
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.5.0                # bare versions resolve through the official catalog
+  oats.framework: v1.6.0                # bare versions resolve through the official catalog
   oats.okf: v4.1.1
 defaults:
   capabilities: { oats.core: { from: package } }