@awebai/oats 0.24.13 → 0.25.1

package/lib/schedule.mjs

@@ -27,6 +27,7 @@ import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Cron } from "croner";
 import { portableScope } from "./portable-state.mjs";
+import { loadLocal } from "./workspace.mjs";
 import { RESERVED_LAUNCH_ENV, ensureRoot, findAgent, findCapabilityAgent, findInstanceHomes, teamAgentRoots, configChain, spawnInstance, inspectInstanceSession, inputInstanceSession, startInstanceSession, retirePendingMarkerPath, loadCapturedDispatch, prepareCapturedComposition } from "./core.mjs";
 import { RECURRENCE_POLICIES, SCHEDULE_ATTEMPT_VERSION, SCHEDULE_DEFINITION_VERSION, admitExecutionTemplate, buildCommandExecutionTemplate, buildWakeExecutionTemplate, capturedDispatchAction, commandArgvWithExecutionBinding, executionContentIntegrity, validateExecutionBinding, validateExecutionCapsule, validateExecutionTemplate, validatePreparationInput } from "./schedule-capsule.mjs";
 
@@ -474,13 +475,97 @@ export function findHomesInScope(ws, instance) {
 function scheduleBlock(def, minute) {
   return `\n\n## Scheduled run\n\nThis instance was launched by OATS schedule "${def.id}" for ${minute.toISOString()} (cron "${def.cron}" in ${def.tz}). It is disposable: finish the task above, bring your memory files up to date, and end with \`oats retire --self\`.\n`;
 }
-/** Launch one spawn job. `io.spawn(root, agent, opts)` overrides spawnInstance for tests. */
+/** The environment a scheduler-launched oats child runs with: the caller's
+ *  frozen instance identity and capability snapshot removed (a tick or run-now
+ *  may be invoked from inside an unrelated instance; dispatch belongs to the
+ *  job's cwd and explicit selectors, never to that caller), host configuration
+ *  such as OATS_HOME_DIR and credentials kept. Shared by command and spawn jobs. */
+function childEnv() {
+  const env = { ...process.env };
+  for (const key of [...RESERVED_LAUNCH_ENV,
+    "OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
+    "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
+    "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_RETIRE_INTENT",
+    "OATS_TEAM_NAME", "OATS_TEAM_ID", "OATS_TEAM_SCOPE",
+  ]) delete env[key];
+  return env;
+}
+/** Is this spawn a WORKSPACE-model spawn (module contract §5, decision 7)?
+ *  Two marks, either suffices: the deployment realizes a workspace
+ *  (`oats-local.yaml` walking up from the agents root or the scope — the same
+ *  detection `oats spawn` uses), or the soul under the agents root was copied
+ *  from a member repo by ensureWorkspaceSoul (`.oats-soul-source.json` beside
+ *  it). An unreadable oats-local.yaml is still a workspace deployment: the
+ *  spawn must go the workspace way and report E_WORKSPACE_SCHEMA, never fall
+ *  back to a classic home. Returns null for a classic (bare agents root) spawn. */
+export function workspaceSpawnContext(ws, root, agent) {
+  for (const dir of [dirname(root), ws]) {
+    try { const found = loadLocal(dir); return { kind: "local", local: found.path, dir: dirname(found.path) }; }
+    catch (e) { if (e?.code !== "E_LOCAL_MISSING") return { kind: "local", local: null, dir, error: { code: e.code || "E_WORKSPACE_SCHEMA", message: e.message } }; }
+  }
+  const stamp = agent?._dir ? join(agent._dir, ".oats-soul-source.json") : join(root, agent?.name || "", ".oats-soul-source.json");
+  if (agent?.name && existsSync(stamp)) return { kind: "soul-source", local: null, dir: dirname(root), stamp };
+  return null;
+}
+/** A workspace spawn materializes EXACTLY like `oats spawn` — prepareInstance →
+ *  ensureWorkspaceSoul → spawnInstanceAsync (resolve over the remotes, copy every
+ *  module whole into the home, compose AGENTS.md from the modules' injects).
+ *  That chain is asynchronous (it reads Git remotes); the tick chain is
+ *  synchronous by design (one short-lived process under the host lock, no
+ *  daemon). So the tick delegates to the kernel's own CLI as a child process,
+ *  like a command job: `oats spawn <soul> --json …` in the deployment, and
+ *  reads back the one JSON envelope. The child holds no host lock (a spawn
+ *  takes only the scope lock, briefly, for a wake it saves — and the schedule
+ *  passes no wake flags: the wake is saved here, from the run record).
+ *  `io.oatsBin`, `io.commandTimeoutMs` and `io.noLaunch` are the test seams. */
+function spawnViaCli(ws, root, agent, opts, context, io) {
+  if (context.error) throw scheduleError(context.error.code, `this deployment realizes a workspace (${context.dir}) but its oats-local.yaml cannot be read: ${context.error.message}`);
+  const argv = ["spawn", agent.name, "--dir", context.dir, "--agents-root", root, "--purpose", opts.purpose, "--json"];
+  if (opts.runtime) argv.push("--runtime", opts.runtime);
+  if (opts.model) argv.push("--model", opts.model);
+  if (opts.backend) argv.push("--backend", opts.backend);
+  if (opts.repo) argv.push("--repo", opts.repo);
+  if (opts.yolo === true) argv.push("--yolo"); else if (opts.yolo === false) argv.push("--no-yolo");
+  if (opts.launch === false) argv.push("--no-launch");
+  // The task is multi-line text of arbitrary size: it travels as a private file, never in argv.
+  mkdirSync(join(stateDir(ws), "tasks"), { recursive: true });
+  const taskFile = join(stateDir(ws), "tasks", `${opts.purpose}-${process.pid}.md`);
+  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() }); }
+  finally { try { rmSync(taskFile, { force: true }); } catch { /* best effort */ } }
+  const timedOut = r.error?.code === "ETIMEDOUT" || (r.status === null && r.signal === "SIGTERM");
+  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.
+  if (timedOut) throw scheduleError("E_SPAWN_UNCONFIRMED", "workspace spawn timed out; its effects could not be confirmed (a home may have been created) — run oats schedule reconcile");
+  if (!envelope || typeof envelope !== "object" || typeof envelope.ok !== "boolean") throw scheduleError("E_SPAWN_UNCONFIRMED", `workspace spawn answered no valid envelope (exit ${r.status ?? r.signal}); its effects could not be confirmed — run oats schedule reconcile${r.stderr ? `: ${String(r.stderr).trim().split("\n").pop()}` : ""}`);
+  if (!envelope.ok) {
+    const e = envelope.error || {};
+    // E_SPAWN_INCOMPLETE: the kernel created a home it could not finish or roll back — retained effects.
+    const retained = e.code === "E_SPAWN_INCOMPLETE" || e.details?.home;
+    throw scheduleError(e.code || "E_SPAWN_FAILED", retained ? `${e.message} (home retained; effects unconfirmed)` : String(e.message || "spawn failed"), { details: e.details });
+  }
+  const res = envelope.result || {};
+  return { instance: res.instance, home: res.home, launched: res.launched, materialized: "workspace" };
+}
+/** Launch one spawn job. `io.spawn(root, agent, opts)` overrides the whole
+ *  launcher for tests. Otherwise a workspace deployment goes through the
+ *  kernel's own `oats spawn` (workspace materialization: `.oats/modules`,
+ *  module skills and injects — never a classic home); a bare agents root goes
+ *  through the synchronous classic spawnInstance, whose failures throw here. */
 function launchSpawn(ws, def, minute, io) {
   const { root, agent } = resolveScheduledAgent(ws, def);
   const purpose = `${def.purpose || def.id}-${purposeSuffix(minute)}`;
-  const opts = { task: def.task.trimEnd() + scheduleBlock(def, minute), purpose, runtime: def.runtime, model: def.model, yolo: def.yolo, backend: def.backend, repo: def.repo, launch: true };
-  const r = (io?.spawn || spawnInstance)(root, agent, opts);
-  const run = { instance: r.instance, home: r.home, launched: !!r.instance, kind: "spawn" };
+  const opts = { task: def.task.trimEnd() + scheduleBlock(def, minute), purpose, runtime: def.runtime, model: def.model, yolo: def.yolo, backend: def.backend, repo: def.repo, launch: io?.noLaunch === true ? false : true };
+  let r;
+  if (io?.spawn) r = io.spawn(root, agent, opts);
+  else {
+    const context = workspaceSpawnContext(ws, root, agent);
+    r = context ? spawnViaCli(ws, root, agent, opts, context, io) : spawnInstance(root, agent, opts);
+  }
+  const run = { instance: r.instance, home: r.home, launched: !!r.instance, kind: "spawn", ...(r.materialized ? { materialized: r.materialized } : {}) };
   if (def.wake && r.home) {
     try { run.wakeSchedule = saveWakeForHome(ws, { instance: r.instance, home: r.home, wake: def.wake }); }
     catch (e) { run.wakeScheduleError = { code: e.code || "E_SCHEDULE_INVALID", message: e.message }; }
@@ -514,18 +599,7 @@ function launchCommand(ws, def, io) {
   let envelope, timedOut = false, raw = "";
   if (io?.command) envelope = io.command({ cwd: def.cwd, argv });
   else {
-    const env = { ...process.env };
-    // A schedule may be ticked/run-now from inside an unrelated instance.
-    // Dispatch belongs to the job's cwd/explicit selectors, never that
-    // caller's frozen capability snapshot (including legacy OATS_HOME).
-    // Keep host configuration such as OATS_HOME_DIR and credentials intact.
-    for (const key of [...RESERVED_LAUNCH_ENV,
-      "OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
-      "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
-      "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_RETIRE_INTENT",
-      "OATS_TEAM_NAME", "OATS_TEAM_ID", "OATS_TEAM_SCOPE",
-    ]) delete env[key];
-    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 });
+    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");
     raw = String(r.stdout || "");
     envelope = parseEnvelopeText(raw);