@awebai/oats 0.23.2 → 0.24.0

package/lib/schedule.mjs

@@ -1,4 +1,5 @@
-/** OATS schedules v1: workspace-scoped definitions, host-owned execution.
+/** OATS schedules: legacy v1 plus explicit captured-execution v2,
+ * workspace-scoped definitions and host-owned execution.
  *
  *  A definition lives in <scope>/oats-schedules.json, where the scope is the
  *  team workspace (the config level declaring the team, else the outermost
@@ -24,10 +25,12 @@ import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Cron } from "croner";
-import { RESERVED_LAUNCH_ENV, ensureRoot, findAgent, findCapabilityAgent, findInstanceHomes, teamAgentRoots, configChain, spawnInstance, inspectInstanceSession, inputInstanceSession, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
+import { portableScope } from "./portable-state.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";
 
 export const SCHEDULE_FILE = "oats-schedules.json";
-export const SCHEDULE_API = 1;
+export const SCHEDULE_API = 2;
 const ID_RE = /^[a-z0-9-]{1,40}$/;
 const RUNTIMES = new Set(["pi", "claude", "codex"]);
 const BACKENDS = new Set(["tmux", "herdr"]);
@@ -38,6 +41,26 @@ const COMMAND_TIMEOUT_MS = 5 * 60 * 1000;
 export function scheduleError(code, message, extra) { return Object.assign(new Error(message), { code, ...(extra || {}) }); }
 /** A stored definition that is not even shaped like one (a hand edit): it
  *  is never observed or executed, and is reported invalid on that job only. */
+export function scheduleExecutionStatus(def, intent, lock) {
+  const versioned = def?.definitionVersion !== undefined || def?.recurrencePolicy !== undefined || def?.execution !== undefined || def?.preparation !== undefined;
+  let result;
+  if (!versioned) result = { kind: "legacy", capture: "unknown", migrationRequired: true };
+  else {
+    const invalid = shapeError(def);
+    if (invalid) result = { kind: "invalid", capture: "unknown", migrationRequired: true, reason: invalid };
+    else if (def.recurrencePolicy === "prepare-on-tick") result = { kind: "prepare-on-tick", capture: "not-captured", migrationRequired: false, reason: "explicit preparation runs at admission" };
+    else result = { kind: "captured", capture: "recorded", migrationRequired: false, schemaVersion: def.execution.schemaVersion, contentIntegrity: executionContentIntegrity(def.execution), resolution: def.execution.resolution };
+  }
+  if (!intent) return result;
+  try {
+    const execution = validateAttemptExecution(intent, lock);
+    return { ...result, intent: execution ? { kind: "captured", capture: "recorded", migrationRequired: false, schemaVersion: intent.schemaVersion, executionId: execution.executionId, resolution: execution.resolution }
+      : { kind: "legacy", capture: "unknown", migrationRequired: true } };
+  } catch (error) {
+    return { ...result, intent: { kind: "invalid", capture: "unknown", migrationRequired: true, reason: error.message, errorCode: error.code } };
+  }
+}
+
 export function shapeError(def) {
   if (!def || typeof def !== "object" || Array.isArray(def)) return "definition is not an object";
   if (!["spawn", "command", "wake", "operation"].includes(def.kind)) return `kind ${JSON.stringify(def.kind)} is not spawn, command, wake or operation`;
@@ -46,6 +69,29 @@ export function shapeError(def) {
   if (def.kind === "command" && (typeof def.cwd !== "string" || !Array.isArray(def.argv))) return "cwd and argv are required";
   if (def.kind === "wake" && (typeof def.home !== "string" || typeof def.message !== "string")) return "home and message are required";
   if (def.kind === "operation" && (typeof def.operation !== "string" || typeof def.home !== "string")) return "operation and home are required";
+  if (def.definitionVersion !== undefined || def.recurrencePolicy !== undefined || def.execution !== undefined || def.preparation !== undefined) {
+    if (def.definitionVersion !== SCHEDULE_DEFINITION_VERSION) return `definitionVersion must be ${SCHEDULE_DEFINITION_VERSION}`;
+    if (!RECURRENCE_POLICIES.includes(def.recurrencePolicy)) return "recurrencePolicy must be capture or prepare-on-tick";
+    if (!["command", "wake"].includes(def.kind)) return "versioned execution currently supports command and captured wake definitions only";
+    if (def.kind === "wake" && def.recurrencePolicy !== "capture") return "wake definitions require capture policy";
+    if (def.recurrencePolicy === "capture") {
+      if (def.preparation !== undefined) return "capture policy cannot carry prepare-on-tick input";
+      try {
+        validateExecutionTemplate(def.execution);
+        const expected = def.kind === "command"
+          ? buildCommandExecutionTemplate({ cwd: def.cwd, argv: def.argv, inputRefs: def.execution.inputRefs, responsibleHuman: def.execution.responsibleHuman })
+          : buildWakeExecutionTemplate({ home: def.home, message: def.message,
+            executionBinding: { schemaVersion: 1, deployment: def.execution.deployment, resolution: def.execution.resolution },
+            inputRefs: def.execution.inputRefs, responsibleHuman: def.execution.responsibleHuman });
+        if (executionContentIntegrity(expected).value !== executionContentIntegrity(def.execution).value) return "execution template differs from the saved target";
+      } catch (error) { return `execution template is invalid: ${error.message}`; }
+    } else {
+      if (def.execution !== undefined) return "prepare-on-tick cannot carry a pinned execution template";
+      try { validatePreparationInput(def.preparation); } catch (error) { return `preparation input is invalid: ${error.message}`; }
+      try { commandArgvWithExecutionBinding(def.argv, { schemaVersion: 1, deployment: def.preparation.deployment, resolution: { schemaVersion: 1, id: `sha256-${"0".repeat(64)}` } }); }
+      catch (error) { return `prepare-on-tick command is invalid: ${error.message}`; }
+    }
+  }
   return null;
 }
 
@@ -94,7 +140,7 @@ function writeJson(path, value) {
 }
 export function readDefinitions(ws) {
   const doc = readJson(definitionsPath(ws), { version: 1, jobs: {} });
-  if (doc.version !== 1 || typeof doc.jobs !== "object" || doc.jobs === null || Array.isArray(doc.jobs)) throw scheduleError("E_SCHEDULE_INVALID", `${definitionsPath(ws)} must be {version: 1, jobs: {}}`, { field: "file" });
+  if (![1, 2].includes(doc.version) || typeof doc.jobs !== "object" || doc.jobs === null || Array.isArray(doc.jobs)) throw scheduleError("E_SCHEDULE_INVALID", `${definitionsPath(ws)} must be {version: 1|2, jobs: {}}`, { field: "file" });
   return doc;
 }
 export function writeDefinitions(ws, doc) { writeJson(definitionsPath(ws), doc); }
@@ -238,6 +284,46 @@ export function validateDefinition(ws, def, { checkAgent = true } = {}) {
     if (typeof def.home !== "string" || !isAbsolute(def.home) || !inside(ws, def.home) || !existsSync(join(def.home, "instance.json"))) throw scheduleError("E_SCHEDULE_INVALID", "home: an existing instance home inside the scope", { field: "home" });
     out.operation = def.operation; out.home = resolve(def.home);
   } else throw scheduleError("E_SCHEDULE_INVALID", "kind: spawn, command, wake or operation", { field: "kind" });
+  const versioned = def.definitionVersion !== undefined || def.recurrencePolicy !== undefined || def.execution !== undefined || def.preparation !== undefined;
+  if (versioned) {
+    if (def.definitionVersion !== SCHEDULE_DEFINITION_VERSION) throw scheduleError("E_SCHEDULE_INVALID", `definitionVersion: ${SCHEDULE_DEFINITION_VERSION} required for captured schedules`, { field: "definitionVersion" });
+    if (!RECURRENCE_POLICIES.includes(def.recurrencePolicy)) throw scheduleError("E_SCHEDULE_INVALID", "recurrencePolicy: capture or prepare-on-tick", { field: "recurrencePolicy" });
+    if (!["command", "wake"].includes(def.kind)) throw scheduleError("E_SCHEDULE_INVALID", "versioned execution currently supports command and captured wake jobs; spawn and operation await their captured consumer adapters", { field: "recurrencePolicy" });
+    if (def.kind === "wake" && def.recurrencePolicy !== "capture") throw scheduleError("E_SCHEDULE_INVALID", "versioned wake jobs require capture policy", { field: "recurrencePolicy" });
+    out.definitionVersion = SCHEDULE_DEFINITION_VERSION;
+    out.recurrencePolicy = def.recurrencePolicy;
+    if (def.recurrencePolicy === "capture") {
+      if (def.preparation !== undefined) throw scheduleError("E_SCHEDULE_INVALID", "preparation belongs only to prepare-on-tick", { field: "preparation" });
+      let execution;
+      try {
+        const responsibleHuman = Object.hasOwn(def, "responsibleHuman") ? def.responsibleHuman : def.execution?.responsibleHuman;
+        if (responsibleHuman === undefined) throw new Error("responsibleHuman must be explicit for captured execution (null means messaging disabled)");
+        if (def.kind === "command") execution = buildCommandExecutionTemplate({ cwd: out.cwd, argv: out.argv,
+          inputRefs: def.inputRefs ?? def.execution?.inputRefs ?? {}, responsibleHuman });
+        else {
+          const meta = readJson(join(out.home, "instance.json"), null);
+          if (!meta?.executionBinding) throw scheduleError("migration-required", "wake target has no captured executionBinding", { field: "executionBinding" });
+          validateExecutionBinding(meta.executionBinding);
+          execution = buildWakeExecutionTemplate({ home: out.home, message: out.message, executionBinding: meta.executionBinding,
+            inputRefs: def.inputRefs ?? def.execution?.inputRefs ?? {}, responsibleHuman });
+        }
+        if (def.execution !== undefined) {
+          validateExecutionTemplate(def.execution);
+          if (executionContentIntegrity(def.execution).value !== executionContentIntegrity(execution).value) throw new Error("template differs from target, binding, inputs or responsible human");
+        }
+      } catch (error) {
+        if (error.code === "migration-required") throw error;
+        throw scheduleError("E_SCHEDULE_INVALID", `execution: ${error.message}`, { field: "execution" });
+      }
+      out.execution = execution;
+    } else {
+      if (def.execution !== undefined) throw scheduleError("E_SCHEDULE_INVALID", "execution: prepare-on-tick captures only when a future tick is admitted", { field: "execution" });
+      try {
+        out.preparation = validatePreparationInput(def.preparation);
+        commandArgvWithExecutionBinding(out.argv, { schemaVersion: 1, deployment: out.preparation.deployment, resolution: { schemaVersion: 1, id: `sha256-${"0".repeat(64)}` } });
+      } catch (error) { throw scheduleError("E_SCHEDULE_INVALID", `preparation: ${error.message}`, { field: "preparation" }); }
+    }
+  }
   return out;
 }
 
@@ -305,6 +391,14 @@ export function findHomesInScope(ws, instance) {
   const homes = new Set();
   for (const root of scopeRoots(ws)) {
     try { for (const h of findInstanceHomes(root, instance)) homes.add(resolve(h.home || h)); } catch { /* unreadable root */ }
+    // Durable homes remain discoverable after their source soul definition is
+    // removed. The live-soul index is a convenience, never reconciliation
+    // authority for an already admitted execution.
+    if (existsSync(root)) for (const e of readdirSync(root, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      const h = join(root, e.name, "instances", instance);
+      if (existsSync(join(h, "instance.json"))) homes.add(resolve(h));
+    }
     const local = join(dirname(root), "local-agents");
     if (existsSync(local)) for (const e of readdirSync(local, { withFileTypes: true })) { if (!e.isDirectory()) continue; const h = join(local, e.name, "instances", instance); if (existsSync(join(h, "instance.json"))) homes.add(resolve(h)); }
   }
@@ -361,7 +455,7 @@ function launchCommand(ws, def, io) {
     // 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_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
+      "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",
@@ -392,6 +486,72 @@ function launchCommand(ws, def, io) {
   }
   return { kind: "command", launched: envelope.ok === true, ...(instance ? { instance } : {}), ...(home ? { home } : {}), ...(envelope.ok ? {} : { error: envelope.error?.message || "command failed", errorCode: envelope.error?.code }) };
 }
+
+/** Verify an immutable capsule and its current exact-artifact authorization
+ * before the scheduler acquires a slot or invokes a child. Legacy definitions
+ * retain their old release boundary; prepare-on-tick remains fail-closed until
+ * the preparation owner supplies its transaction API. */
+function homeExecutionBinding(home) {
+  const meta = readJson(join(home, "instance.json"), null);
+  if (!meta?.executionBinding) throw scheduleError("migration-required", "wake target has no captured executionBinding");
+  try { return validateExecutionBinding(meta.executionBinding); }
+  catch (error) { throw scheduleError("E_SCHEDULE_INVALID", `wake target executionBinding is invalid: ${error.message}`); }
+}
+function validateAttemptExecution(attempt, lock) {
+  if (attempt?.execution === undefined) {
+    if (attempt?.schemaVersion !== undefined) throw scheduleError("migration-required", "versioned scheduled attempt has no captured execution");
+    if (lock?.executionId !== undefined) throw scheduleError("E_SCHEDULE_INVALID", "captured job lock has no matching admitted capsule");
+    return undefined;
+  }
+  if (attempt.schemaVersion !== SCHEDULE_ATTEMPT_VERSION) throw scheduleError("migration-required", "scheduled attempt uses an unsupported version");
+  const execution = validateExecutionCapsule(attempt.execution);
+  if (lock && lock.executionId !== execution.executionId) throw scheduleError("E_SCHEDULE_INVALID", "job lock does not name the admitted execution intent");
+  return execution;
+}
+function validateActiveExecution(js, lock) {
+  if (lock?.unreadable) throw scheduleError("E_SCHEDULE_INVALID", "job lock custody is unreadable");
+  if (js.attempt) return validateAttemptExecution(js.attempt, lock);
+  if (lock && (js.lastRun?.execution || lock.executionId !== undefined)) {
+    return validateAttemptExecution(js.lastRun?.execution ? { schemaVersion: SCHEDULE_ATTEMPT_VERSION, execution: js.lastRun.execution } : {}, lock);
+  }
+}
+function receiptMatchesExecution(receipt, execution) {
+  return !!receipt?.execution && receipt.execution.executionId === execution.executionId
+    && executionContentIntegrity(validateExecutionCapsule(receipt.execution)).value === executionContentIntegrity(execution).value;
+}
+function admitExecution(def, io, { createIntent = true } = {}) {
+  if (def.definitionVersion === undefined) return undefined;
+  if (def.definitionVersion !== SCHEDULE_DEFINITION_VERSION) throw scheduleError("migration-required", "scheduled definition uses an unsupported execution version");
+  let execution;
+  if (def.recurrencePolicy === "prepare-on-tick") {
+    if (!createIntent) return undefined; // dry-run never prepares or publishes
+    const prepare = io && Object.hasOwn(io, "prepare") ? io.prepare : prepareCapturedComposition;
+    if (typeof prepare !== "function") throw scheduleError("migration-required", "prepare-on-tick needs the preparation transaction adapter before this tick can be admitted");
+    const request = validatePreparationInput(def.preparation);
+    const requestedDeployment = portableScope(request.deployment); // Freeze identity before preparation, including platform path aliases.
+    const prepared = prepare(request);
+    if (!prepared || typeof prepared !== "object" || !prepared.executionBinding || !Object.hasOwn(prepared, "responsibleHuman")) {
+      throw scheduleError("needs-configuration", "preparation did not produce a complete executionBinding and responsibleHuman", { problems: prepared?.problems || [] });
+    }
+    const binding = validateExecutionBinding(prepared.executionBinding);
+    let sameDeployment = false;
+    try { sameDeployment = portableScope(binding.deployment) === requestedDeployment && portableScope(request.deployment) === requestedDeployment; } catch { /* absent/changed scope is not the admitted deployment */ }
+    if (!sameDeployment) throw scheduleError("E_SCHEDULE_INVALID", "prepared executionBinding changed the requested deployment");
+    binding.deployment = requestedDeployment; // Persist canonical authority, not a retargetable spelling.
+    if (prepared.resolution && prepared.resolution.id !== binding.resolution.id) throw scheduleError("E_SCHEDULE_INVALID", "prepared resolution differs from executionBinding");
+    const argv = commandArgvWithExecutionBinding(def.argv, binding);
+    execution = buildCommandExecutionTemplate({ cwd: def.cwd, argv, inputRefs: prepared.inputRefs ?? {}, responsibleHuman: prepared.responsibleHuman });
+  } else execution = validateExecutionTemplate(def.execution);
+  const action = capturedDispatchAction(execution);
+  if (action.kind === "wake") {
+    const binding = homeExecutionBinding(execution.target.home);
+    if (binding.deployment !== execution.deployment || binding.resolution.id !== execution.resolution.id) throw scheduleError("E_SCHEDULE_INVALID", "wake target executionBinding differs from its captured template");
+  }
+  const request = { deployment: execution.deployment, resolution: execution.resolution, action };
+  (io?.admit || loadCapturedDispatch)(request);
+  if (action.kind === "wake") throw scheduleError("migration-required", "captured wake lifecycle dispatch is not integrated yet");
+  return createIntent ? admitExecutionTemplate(execution) : undefined;
+}
 /** One wake. `startIfStopped` false between due minutes (a harness that
  *  keeps exiting is not restarted every minute); `canStart` false when the
  *  host bound is reached (a new runtime takes a slot; a delivery does not). */
@@ -437,9 +597,10 @@ function performWake(def, io, { startIfStopped = true, canStart = true, reserve
  *  marker) or its home is gone: a persistent home outliving its process
  *  does not keep a slot. */
 function observePrevious(ws, id, def, js, io, now, { mutate }) {
-  if (shapeError(def)) return;
-  const lr = js.lastRun;
   const lock = jobLockInfo(ws, id);
+  validateActiveExecution(js, lock); // No observation may erase invalid custody.
+  if (js.attempt || shapeError(def)) return; // Unconfirmed effects need reconcile.
+  const lr = js.lastRun;
   const home = def.kind === "wake" ? (lock?.home || lr?.home || def.home) : (lock?.home || lr?.home);
   const tracked = def.kind === "wake" ? !!lock : !!home && ["launched", "active", "starting", "stopped", "unknown"].includes(lr?.outcome);
   if (!tracked || !home) return;
@@ -485,11 +646,29 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
   for (const id of order) {
     const def = defs.jobs[id];
     const js = stateOf(id);
+    validateActiveExecution(js, jobLockInfo(ws, id)); // Also covers host pre-observed candidates.
     let due, cronError;
     const shape = shapeError(def);
     if (shape) { cronError = shape; due = false; }
     else { try { due = only ? true : dueAt(def, minute); } catch (e) { cronError = e.message; due = false; } }
     if (cronError) { if (!dryRun) js.lastRun = { ...(js.lastRun || {}), outcome: "invalid", error: `definition cannot be evaluated: ${cronError}` }; record(id, "invalid", { error: cronError }); continue; }
+    // A captured wake is bound to the target home's exact executionBinding,
+    // but remains gated until lifecycle exposes captured wake dispatch. Keep
+    // this before both pending delivery and due-start branches so neither can
+    // fall through to the legacy home path.
+    const versionedWakeDue = def.kind === "wake" && def.definitionVersion !== undefined && !dryRun
+      && (def.enabled || only) && ((js.pendingWake && !only) || only || (due && js.lastAttemptedMinute !== key));
+    if (versionedWakeDue) {
+      let error;
+      try { admitExecution(def, io, { createIntent: false }); } catch (caught) { error = caught; }
+      if (error) {
+        if (only || due) js.lastAttemptedMinute = key;
+        js.lastRun = { scheduledFor: minute.toISOString(), startedAt: now.toISOString(), kind: "wake", launched: false, outcome: "blocked", error: error.message, errorCode: error.code || "E_SCHEDULE_ADMISSION" };
+        record(id, "blocked", { error: error.message, errorCode: error.code || "E_SCHEDULE_ADMISSION" });
+        continue;
+      }
+      throw scheduleError("migration-required", "captured wake unexpectedly passed its lifecycle integration gate");
+    }
     if (def.kind === "wake" && js.pendingWake && def.enabled && !dryRun && !only) {
       const dueNow = due && js.lastAttemptedMinute !== key;
       const held = !!jobLockInfo(ws, id);
@@ -507,12 +686,24 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
     if (js.lastAttemptedMinute === key && !only) continue;
     if (!due) continue;
     if (dryRun) {
-      const reason = js.attempt ? "an earlier launch has no recorded result; run oats schedule reconcile" : jobLockInfo(ws, id) && def.kind !== "wake" ? "still running" : liveLocks(wsAll) >= bound && def.kind !== "wake" ? "host busy" : undefined;
-      record(id, reason ? "skipped" : "due", reason ? { reason } : {});
+      let admission;
+      if (!js.attempt && !jobLockInfo(ws, id) && (def.kind === "wake" || liveLocks(wsAll) < bound)) {
+        try { admitExecution(def, io, { createIntent: false }); } catch (error) { admission = error; }
+      }
+      const reason = js.attempt ? "an earlier launch has no recorded result; run oats schedule reconcile" : jobLockInfo(ws, id) && def.kind !== "wake" ? "still running" : liveLocks(wsAll) >= bound && def.kind !== "wake" ? "host busy" : admission ? `admission blocked (${admission.code || "error"}): ${admission.message}` : undefined;
+      record(id, reason ? (admission ? "blocked" : "skipped") : "due", reason ? { reason, ...(admission ? { errorCode: admission.code } : {}) } : {});
       continue;
     }
     js.lastAttemptedMinute = key;
-    if (js.attempt) { record(id, "skipped", { reason: "an earlier launch has no recorded result; run oats schedule reconcile" }); js.lastRun = { ...(js.lastRun || {}), outcome: "unknown", error: "launch attempt without a recorded result", scheduledFor: js.attempt.scheduledFor }; continue; }
+    if (js.attempt) {
+      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 } : {}) });
+      if (!js.attempt.execution || receiptMatchesExecution(js.lastRun, js.attempt.execution)) {
+        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 };
+      }
+      continue;
+    }
     if (def.kind === "wake") {
       // A delivery to a running session takes no slot; starting a stopped
       // one does, and the slot is held (the job lock) until that home ends.
@@ -527,12 +718,26 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
     }
     if (jobLockInfo(ws, id)) { record(id, "skipped", { reason: "still running" }); continue; }
     if (liveLocks(wsAll) >= bound) { record(id, "skipped", { reason: "host busy" }); continue; }
-    if (!acquireJobLock(ws, id, { scheduledFor: minute.toISOString() })) { record(id, "skipped", { reason: "still running" }); continue; }
-    js.attempt = { scheduledFor: minute.toISOString(), startedAt: now.toISOString(), wallClock: new Date().toISOString() };
+    let execution;
+    try { execution = admitExecution(def, io); }
+    catch (error) {
+      js.lastRun = { scheduledFor: minute.toISOString(), startedAt: now.toISOString(), kind: def.kind, launched: false, outcome: "blocked", error: error.message, errorCode: error.code || "E_SCHEDULE_ADMISSION" };
+      record(id, "blocked", { error: error.message, errorCode: error.code || "E_SCHEDULE_ADMISSION" });
+      continue;
+    }
+    // Persist the admitted authority before even reserving the launch slot.
+    // A crash in the following gap leaves an inspectable unresolved attempt,
+    // never an ownerless lock whose intended software cannot be recovered.
+    js.attempt = { ...(execution ? { schemaVersion: SCHEDULE_ATTEMPT_VERSION } : {}), scheduledFor: minute.toISOString(), startedAt: now.toISOString(), wallClock: new Date().toISOString(), ...(execution ? { execution } : {}) };
+    writeState(ws, st);
+    if (!acquireJobLock(ws, id, { scheduledFor: minute.toISOString(), ...(execution ? { executionId: execution.executionId } : {}) })) {
+      delete js.attempt; writeState(ws, st); record(id, "skipped", { reason: "still running" }); continue;
+    }
     js.lastLaunchedAt = now.toISOString();
     writeState(ws, st);
     let run;
-    try { run = def.kind === "spawn" ? launchSpawn(ws, def, minute, io) : launchCommand(ws, def.kind === "operation" ? operationAsCommand(def) : def, io); }
+    const admitted = execution ? { ...def, cwd: execution.target.cwd, argv: execution.target.argv } : def;
+    try { run = def.kind === "spawn" ? launchSpawn(ws, def, minute, io) : launchCommand(ws, def.kind === "operation" ? operationAsCommand(def) : admitted, io); }
     catch (e) {
       // spawnInstance compensates its own failures, but its rollback can be
       // INCOMPLETE (a pane it could not stop, a quarantined home it kept):
@@ -542,13 +747,13 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
     }
     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" };
+      js.lastRun = { scheduledFor: minute.toISOString(), startedAt: now.toISOString(), ...(execution ? { execution } : {}), ...run, outcome: "unknown" };
       record(id, "unknown", { error: run.error });
       continue;
     }
     delete js.attempt;
     const outcome = run.launched ? "launched" : "launch-failed";
-    js.lastRun = { scheduledFor: minute.toISOString(), startedAt: now.toISOString(), ...run, outcome };
+    js.lastRun = { scheduledFor: minute.toISOString(), startedAt: now.toISOString(), ...(execution ? { execution } : {}), ...run, outcome };
     if (!run.launched || !run.home) releaseJobLock(ws, id);
     record(id, outcome, { ...(run.error ? { error: run.error } : {}), ...(run.instance ? { instance: run.instance } : {}) });
   }
@@ -621,29 +826,40 @@ export function reconcile(ws, id, { io, now = new Date(), clear = false } = {})
   return withHostLock(() => {
     const st = readState(ws);
     const js = st.jobs[id] || (st.jobs[id] = {});
-    const attempt = js.attempt || (js.lastRun?.outcome === "unknown" ? { scheduledFor: js.lastRun.scheduledFor, startedAt: js.lastRun.startedAt } : undefined);
+    const attempt = js.attempt || (js.lastRun?.outcome === "unknown" ? { ...(js.lastRun.execution ? { schemaVersion: SCHEDULE_ATTEMPT_VERSION } : {}), scheduledFor: js.lastRun.scheduledFor, startedAt: js.lastRun.startedAt, ...(js.lastRun.execution ? { execution: js.lastRun.execution } : {}) } : undefined);
     if (!attempt) return { schedule: describe(ws, id, io), reconciled: "nothing to reconcile" };
+    try { validateAttemptExecution(attempt, jobLockInfo(ws, id)); }
+    catch (error) { throw scheduleError("E_SCHEDULE_INVALID", `admitted execution capsule is invalid: ${error.message}`); }
+    const attemptKind = attempt.execution?.action.kind || def.kind;
     let adopted, ambiguous;
-    if (def.kind === "spawn" && attempt.scheduledFor) {
+    if (attemptKind === "spawn" && attempt.scheduledFor) {
       const purpose = `${def.purpose || def.id}-${purposeSuffix(new Date(attempt.scheduledFor))}`;
       const homes = findHomesInScope(ws, `${def.agent}-${purpose}`);
       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 (def.kind === "command" || def.kind === "operation") {
-      const named = js.lastRun?.instance ? findHomesInScope(ws, js.lastRun.instance).map((home) => ({ instance: js.lastRun.instance, home })) : [];
+    } else if (attemptKind === "command" || attemptKind === "operation") {
+      let named = [];
+      if (attempt.execution) {
+        // Only this admission's receipt may establish effects. Never borrow the
+        // previous run's name or consult current-config roster discovery.
+        if (receiptMatchesExecution(js.lastRun, attempt.execution) && typeof js.lastRun.home === "string" && isAbsolute(js.lastRun.home)) {
+          const home = resolve(js.lastRun.home), meta = readJson(join(home, "instance.json"), null);
+          if (meta?.instance === js.lastRun.instance && typeof meta.home === "string" && resolve(meta.home) === home) named = [{ instance: meta.instance, home }];
+        }
+      } else if (js.lastRun?.instance) named = findHomesInScope(ws, js.lastRun.instance).map((home) => ({ instance: js.lastRun.instance, home }));
       if (named.length === 1) adopted = named[0];
       else if (named.length > 1) ambiguous = `${named.length} homes named ${js.lastRun.instance}: ${named.map((c) => c.home).join(", ")}`;
-      else if (!clear) return { schedule: describe(ws, id, io), reconciled: "unknown", remedy: `the command's effects cannot be proven absent from here (its answer named no instance); check the roster and the host by hand, then run oats schedule reconcile ${id} --clear to record launch-failed and free the slot, or oats schedule remove --force ${id}` };
+      else if (!clear) return { schedule: describe(ws, id, io), reconciled: "unknown", remedy: `the command's effects cannot be proven from a matching admitted receipt; check the roster and the host by hand, then run oats schedule reconcile ${id} --clear to record launch-failed and free the slot, or oats schedule remove --force ${id}` };
     }
     if (ambiguous && !clear) return { schedule: describe(ws, id, io), reconciled: "unknown", remedy: `${ambiguous}; retire or adopt by hand, then run oats schedule reconcile ${id} --clear or oats schedule remove --force ${id}` };
     if (ambiguous) adopted = undefined;
     delete js.attempt;
     if (adopted) {
       const seen = observeHome(adopted.home, io);
-      js.lastRun = { scheduledFor: attempt.scheduledFor, startedAt: js.lastRun?.startedAt || attempt.startedAt, kind: def.kind, launched: true, ...adopted, outcome: seen.outcome, ...(seen.error ? { error: seen.error } : {}) };
-      if (seen.outcome !== "ended") { if (!jobLockInfo(ws, id)) acquireJobLock(ws, id, { scheduledFor: attempt.scheduledFor, reconciled: true }); } else releaseJobLock(ws, id);
+      js.lastRun = { scheduledFor: attempt.scheduledFor, startedAt: js.lastRun?.startedAt || attempt.startedAt, kind: attemptKind, ...(attempt.execution ? { execution: attempt.execution } : {}), launched: true, ...adopted, outcome: seen.outcome, ...(seen.error ? { error: seen.error } : {}) };
+      if (seen.outcome !== "ended") { if (!jobLockInfo(ws, id)) acquireJobLock(ws, id, { scheduledFor: attempt.scheduledFor, reconciled: true, ...(attempt.execution ? { executionId: attempt.execution.executionId } : {}) }); } else releaseJobLock(ws, id);
     } else {
-      js.lastRun = { scheduledFor: attempt.scheduledFor, startedAt: js.lastRun?.startedAt || attempt.startedAt, kind: def.kind, launched: false, outcome: "launch-failed", error: clear ? "cleared by the operator after checking by hand" : "no instance found in the scope's roster for the unrecorded attempt" };
+      js.lastRun = { scheduledFor: attempt.scheduledFor, startedAt: js.lastRun?.startedAt || attempt.startedAt, kind: attemptKind, ...(attempt.execution ? { execution: attempt.execution } : {}), launched: false, outcome: "launch-failed", error: clear ? "cleared by the operator after checking by hand" : "no instance found in the scope's roster for the unrecorded attempt" };
       releaseJobLock(ws, id);
     }
     writeState(ws, st);
@@ -659,7 +875,9 @@ export function describe(ws, id, io, { defs, st, now = new Date() } = {}) {
   if (!def) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
   const js = st.jobs[id] || {};
   let nextRun = null; try { nextRun = def.enabled ? nextRunAfter(def, now) : null; } catch { nextRun = null; }
-  return { ...def, nextRun, lastRun: js.lastRun || null, running: !!jobLockInfo(ws, id), ...(js.attempt ? { attempt: js.attempt } : {}), ...(js.pendingWake ? { pendingWake: js.pendingWake } : {}) };
+  const lock = jobLockInfo(ws, id);
+  const intent = js.attempt || (lock ? (js.lastRun?.execution ? { schemaVersion: SCHEDULE_ATTEMPT_VERSION, execution: js.lastRun.execution } : {}) : undefined);
+  return { ...def, executionStatus: scheduleExecutionStatus(def, intent, lock), nextRun, lastRun: js.lastRun || null, running: !!lock, ...(js.attempt ? { attempt: js.attempt } : {}), ...(js.pendingWake ? { pendingWake: js.pendingWake } : {}) };
 }
 export function listSchedules(ws, io, { now = new Date() } = {}) {
   const defs = readDefinitions(ws), st = readState(ws);
@@ -670,6 +888,8 @@ export function addSchedule(ws, spec, io) {
   return withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
     if (defs.jobs[def.id]) throw scheduleError("E_SCHEDULE_EXISTS", `schedule ${def.id} already exists in ${ws}`);
+    if (defs.version === 2 && def.definitionVersion === undefined) throw scheduleError("migration-required", "version 2 schedule files require an explicit recurrence policy for new definitions");
+    if (def.definitionVersion === SCHEDULE_DEFINITION_VERSION) defs.version = 2;
     const now = new Date().toISOString();
     defs.jobs[def.id] = { ...def, createdAt: now, updatedAt: now };
     writeDefinitions(ws, defs);
@@ -685,9 +905,11 @@ export function updateSchedule(ws, id, spec, io) {
   return withHostLock(() => withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
     if (!defs.jobs[id]) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
-    const identity = (d) => JSON.stringify([d.kind, d.agent, d.agentsRoot, d.repo, d.purpose, d.home, d.cwd, d.argv, d.operation]);
+    if (defs.jobs[id].definitionVersion !== undefined && def.definitionVersion === undefined) throw scheduleError("migration-required", "a versioned schedule definition cannot be downgraded to legacy execution");
+    if (def.definitionVersion === SCHEDULE_DEFINITION_VERSION) defs.version = 2;
+    const identity = (d) => JSON.stringify([d.kind, d.agent, d.agentsRoot, d.repo, d.purpose, d.home, d.cwd, d.argv, d.operation, d.definitionVersion, d.recurrencePolicy, d.execution, d.preparation]);
     const busy = !!jobLockInfo(ws, id) || !!readState(ws).jobs[id]?.attempt;
-    if (busy && identity(defs.jobs[id]) !== identity(def)) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is running or has an unresolved attempt; its kind, agent, agentsRoot, repo, purpose, home, cwd and argv cannot change until it ends (cron, tz, task, message, runtime, model and enabled can)`);
+    if (busy && identity(defs.jobs[id]) !== identity(def)) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is running or has an unresolved attempt; its execution identity, kind, target and captured policy cannot change until it ends (cron, tz and enabled can)`);
     defs.jobs[id] = { ...def, createdAt: defs.jobs[id].createdAt, updatedAt: new Date().toISOString() };
     writeDefinitions(ws, defs);
     return describe(ws, id, io);
@@ -708,27 +930,26 @@ export function removeSchedule(ws, id, { force = false } = {}) {
   return withHostLock(() => withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
     if (!defs.jobs[id]) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
-    if (jobLockInfo(ws, id) && !force) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is still running; wait for it to end, or --force forgets the job without stopping anything`);
+    const st = readState(ws), job = st.jobs[id];
+    if ((jobLockInfo(ws, id) || job?.attempt || job?.lastRun?.outcome === "unknown") && !force) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is running or has unresolved effects; reconcile first, or --force forgets the job without stopping anything`);
     delete defs.jobs[id];
     writeDefinitions(ws, defs);
-    const st = readState(ws); delete st.jobs[id]; writeState(ws, st);
+    delete st.jobs[id]; writeState(ws, st);
     releaseJobLock(ws, id);
     return { removed: id };
   }));
 }
 /** Save the wake job for a freshly spawned instance (id wake-<instance>). */
-export function saveWakeForHome(ws, { instance, home, wake }) {
+export function saveWakeForHome(ws, { instance, home, wake, executionBinding, responsibleHuman }) {
   const id = `wake-${instance}`.slice(0, 40).replace(/-+$/, "");
   const spec = { id, enabled: wake.enabled === undefined ? true : wake.enabled, cron: wake.cron, tz: wake.tz, kind: "wake", home, message: wake.message };
-  const def = validateDefinition(ws, spec);
-  return withScopeLock(ws, () => {
-    const defs = readDefinitions(ws);
-    if (defs.jobs[id]) throw scheduleError("E_SCHEDULE_EXISTS", `schedule ${id} already exists in ${ws}`);
-    const now = new Date().toISOString();
-    defs.jobs[id] = { ...def, createdAt: now, updatedAt: now };
-    writeDefinitions(ws, defs);
-    return describe(ws, id);
-  });
+  if (executionBinding !== undefined || responsibleHuman !== undefined) {
+    if (executionBinding === undefined || responsibleHuman === undefined) throw scheduleError("needs-configuration", "captured wake creation needs both executionBinding and responsibleHuman");
+    const binding = validateExecutionBinding(executionBinding), actual = homeExecutionBinding(home);
+    if (binding.deployment !== actual.deployment || binding.resolution.id !== actual.resolution.id) throw scheduleError("E_SCHEDULE_INVALID", "spawn result executionBinding differs from the new home");
+    Object.assign(spec, { definitionVersion: SCHEDULE_DEFINITION_VERSION, recurrencePolicy: "capture", responsibleHuman });
+  }
+  return addSchedule(ws, spec); // Same whole-file version/policy gate as manual add.
 }
 /** Retirement hook: wake definitions bound to this home are removed (nothing is stopped). */
 export function removeWakeForHome(ws, home) {

package/lib/servers.mjs

@@ -21,6 +21,8 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { parseStrictJson } from "./portable-values.mjs";
+import { capturedSelector } from "./captured-selector.mjs";
 
 const OATS_HOME_DIR = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
 export const SERVERS_FILE = () => join(OATS_HOME_DIR(), "servers.json");
@@ -233,6 +235,7 @@ export function checkRemote(target, io = {}) {
     remote: list("remote", []),
     features: list("features", []),
     operationsApi: probe.operationsApi === 1 ? 1 : null,
+    scheduleApi: [1, 2].includes(probe.scheduleApi) ? probe.scheduleApi : null,
     advertised: Array.isArray(probe.runtimes),
   };
 }
@@ -761,6 +764,18 @@ export function scheduleRemote(serverId, oatsArgs, io = {}) {
   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`);
+  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");
+    let versioned = oatsArgs.includes("--file"); // Cannot classify remote file bytes here.
+    if (indexes.length) {
+      const spec = parseStrictJson(oatsArgs[indexes[0] + 1]);
+      if (!spec || typeof spec !== "object" || Array.isArray(spec)) throw serverError("E_BAD_ARGS", "remote schedule spec must be an object");
+      versioned ||= ["definitionVersion", "recurrencePolicy", "execution", "preparation"].some(key => Object.hasOwn(spec, key));
+      if (Array.isArray(spec.argv)) versioned ||= !!capturedSelector(spec.argv.slice(1), {});
+    }
+    if (versioned && remote.scheduleApi !== 2) throw serverError("E_REMOTE_INCOMPATIBLE", "captured schedule mutation requires advertised scheduleApi 2; no request was forwarded");
+  }
   const args = ["schedule", ...oatsArgs.filter((a) => a !== "--json"), "--dir", target.workspace, "--json"];
   const { envelope, stderr } = runRemote(target, args, io);
   return { envelope: envelope.ok ? { ...envelope, result: { ...envelope.result, server: serverId } } : envelope, stderr, target };

package/lib/soul-constraints.mjs

@@ -0,0 +1,40 @@
+/** Source-derived hard field constraints, shared by preparation and verification.
+ * No defaults are resolved here and no source/artifact is acquired. */
+import { invalidShape, pointerKey } from "./portable-shape.mjs";
+import { validateRepoAnchor } from "./source-spec.mjs";
+import { FUNDAMENTAL_SLOTS } from "./portable-policy.mjs";
+
+export const capabilityChoiceKey = (id) => `/capabilities/${pointerKey(id)}`;
+export const settingChoiceKey = (id, name) => `/settings/${pointerKey(id)}/${pointerKey(name)}`;
+export const layerChoiceKey = (slot) => `/layers/${slot}`;
+
+/** A repo: relation belongs to the declaring source, not the consumer's cwd or
+ * another authority's identically spelled relative path. Operator inputs need
+ * an explicit source context because their origin is not a repository document. */
+export function sourceSelectionValue(id, parsed, pointer, sourceContext) {
+  const source = parsed.sources[`${pointer}/source`];
+  if (!source) invalidShape(`${pointer}/source`, "missing normalized selection source");
+  if (source.kind !== "repo") return { capability: id, source };
+  const anchor = sourceContext ?? parsed.origins[`${pointer}/source`]?.document;
+  if (!anchor || typeof anchor.source !== "string") invalidShape(`${pointer}/source`, "repo source needs an explicit declaring repository snapshot", "needs-configuration");
+  const snapshot = validateRepoAnchor({ source: anchor.source, revision: anchor.revision });
+  return { capability: id, source: { ...source, anchor: snapshot } };
+}
+
+export function soulConstraints(parsed) {
+  const result = [], source = parsed.declaration.requires ?? {};
+  const origin = (pointer) => ({ ...parsed.origins[pointer], kind: "soul-requirement" });
+  const selection = (id, item, pointer, key) => {
+    result.push({ key, kind: "equals", value: sourceSelectionValue(id, parsed, pointer), origin: origin(pointer) });
+    for (const [name, value] of Object.entries(item.settings ?? {})) {
+      result.push({ key: settingChoiceKey(id, name), kind: "equals", value, origin: origin(`${pointer}/settings/${pointerKey(name)}`) });
+    }
+  };
+  for (const [id, item] of Object.entries(source.capabilities ?? {})) selection(id, item, `/requires/capabilities/${pointerKey(id)}`, capabilityChoiceKey(id));
+  for (const slot of FUNDAMENTAL_SLOTS) {
+    if (!Object.hasOwn(source, slot)) continue;
+    if (source[slot] === "any") result.push({ key: layerChoiceKey(slot), kind: "required", origin: origin(`/requires/${slot}`) });
+    else selection(source[slot].capability, source[slot], `/requires/${slot}`, layerChoiceKey(slot));
+  }
+  return result;
+}