@awebai/oats 0.24.12 → 0.25.0

package/lib/schedule.mjs

@@ -20,12 +20,14 @@
  *  succeeded. A launch whose side effects cannot be confirmed stays
  *  `unknown` with its slot held until `reconcile` proves what happened. */
 import { execFileSync, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 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 { 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";
 
@@ -127,11 +129,32 @@ export function stateDir(ws) { return join(ws, ".agents", "schedules"); }
 function statePath(ws) { return join(stateDir(ws), "state.json"); }
 function lockDir(ws, id) { return join(stateDir(ws), "locks", id); }
 
-function readJson(path, fallback) {
-  if (!existsSync(path)) return fallback;
-  try { return JSON.parse(readFileSync(path, "utf8")); }
-  catch (e) { throw scheduleError("E_SCHEDULE_INVALID", `${path} is not valid JSON: ${e.message}`, { field: "file" }); }
+export const SCHEDULE_HISTORY_API = 3;
+export const SCHEDULE_FILE_BUDGET = 1024 * 1024;
+/** K8b — bounded, descriptor-safe JSON read: lstat → regular file only →
+ *  O_NOFOLLOW|O_NONBLOCK open → fstat dev/ino identity → whole file only if
+ *  within budget (an over-budget file is REFUSED as a typed error, never
+ *  truncated into fabricated JSON). Returns { value, source }. */
+function readJsonBounded(path, fallback, label) {
+  let st;
+  try { st = lstatSync(path); }
+  catch (e) { if (e.code === "ENOENT") return { value: fallback, source: { path: label, status: "absent", bytes: 0 } }; throw scheduleError("E_SCHEDULE_INVALID", `${path} cannot be read: ${e.message}`, { field: "file", source: { path: label, status: "refused", bytes: 0 } }); }
+  if (!st.isFile()) throw scheduleError("E_SCHEDULE_INVALID", `${path} is not a regular file`, { field: "file", source: { path: label, status: "refused", bytes: 0 } });
+  if (st.size > SCHEDULE_FILE_BUDGET) throw scheduleError("E_SCHEDULE_STATE_OVERSIZE", `${path} is ${st.size} bytes; the read budget is ${SCHEDULE_FILE_BUDGET}`, { field: "file", source: { path: label, status: "oversize", bytes: st.size } });
+  let fd, text;
+  try {
+    fd = openSync(path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0));
+    const fst = fstatSync(fd);
+    if (!fst.isFile() || fst.dev !== st.dev || fst.ino !== st.ino || fst.size > SCHEDULE_FILE_BUDGET) throw new Error("swapped or grew past budget");
+    const buf = Buffer.alloc(fst.size); let got = 0;
+    while (got < fst.size) { const n = readSync(fd, buf, got, fst.size - got, got); if (n <= 0) break; got += n; }
+    text = buf.toString("utf8"); st = fst;
+  } catch (e) { throw scheduleError("E_SCHEDULE_INVALID", `${path} cannot be read safely: ${e.message}`, { field: "file", source: { path: label, status: "refused", bytes: st.size } }); }
+  finally { if (fd !== undefined) try { closeSync(fd); } catch { /* nothing to recover */ } }
+  try { return { value: JSON.parse(text), source: { path: label, status: "ok", bytes: st.size } }; }
+  catch (e) { throw scheduleError("E_SCHEDULE_INVALID", `${path} is not valid JSON: ${e.message}`, { field: "file", source: { path: label, status: "corrupt", bytes: st.size } }); }
 }
+function readJson(path, fallback) { return readJsonBounded(path, fallback, basename(path)).value; }
 function writeJson(path, value) {
   mkdirSync(dirname(path), { recursive: true });
   const tmp = `${path}.tmp-${process.pid}`;
@@ -139,27 +162,52 @@ function writeJson(path, value) {
   renameSync(tmp, path);
 }
 export function readDefinitions(ws) {
-  const doc = readJson(definitionsPath(ws), { version: 1, jobs: {} });
+  const doc = readJsonBounded(definitionsPath(ws), { version: 1, jobs: {} }, "definitions").value;
   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); }
-export function readState(ws) { const st = readJson(statePath(ws), { jobs: {} }); if (!st.jobs || typeof st.jobs !== "object") st.jobs = {}; return st; }
+export function readState(ws) { const st = readJsonBounded(statePath(ws), { jobs: {} }, "state").value; if (!st.jobs || typeof st.jobs !== "object") st.jobs = {}; return st; }
+/** Integrity facts for a scope's two files, without throwing. */
+export function scheduleIntegrity(ws) {
+  const sources = [];
+  for (const [path, label, fallback] of [[definitionsPath(ws), "definitions", { version: 1, jobs: {} }], [statePath(ws), "state", { jobs: {} }]]) {
+    try { sources.push(readJsonBounded(path, fallback, label).source); }
+    catch (e) { sources.push(e.source ?? { path: label, status: "refused", bytes: 0 }); }
+  }
+  return { sources };
+}
 /** K8 — bounded run history. Every time a job's lastRun reaches a settled
  *  outcome (not "active"/"starting"), it is appended once to `recentRuns`
  *  (newest first, max 50), keyed by scheduledFor+startedAt so re-saves of the
  *  same run never duplicate it. Recording happens on save: producers keep
  *  writing lastRun exactly as they do; nothing is inferred. */
 export const RECENT_RUNS_MAX = 50;
-function recordRecentRuns(st) {
+/** K8b — a run's identity is WHEN it was scheduled and started (plus the
+ *  attempt id when one exists), never its outcome: unknown→ended is one run
+ *  with two transitions, not two rows. */
+export function runIdOf(lr) {
+  if (!lr || typeof lr !== "object" || (!lr.scheduledFor && !lr.startedAt)) return null;
+  return createHash("sha256").update(`${lr.scheduledFor ?? ""}|${lr.startedAt ?? ""}|${lr.execution?.attemptId ?? lr.attemptId ?? ""}`).digest("hex").slice(0, 24);
+}
+const SETTLED_OUTCOMES = new Set(["ended", "stopped", "delivered", "skipped", "blocked", "invalid", "failed", "unknown", "refused", "completed"]);
+function recordRecentRuns(st, now = new Date()) {
   for (const js of Object.values(st.jobs || {})) {
     const lr = js.lastRun;
     if (!lr || typeof lr !== "object" || ["active", "starting"].includes(lr.outcome)) continue;
-    const key = `${lr.scheduledFor ?? ""}|${lr.startedAt ?? ""}|${lr.outcome ?? ""}`;
+    const runId = runIdOf(lr); if (!runId) continue;
     js.recentRuns ||= [];
-    if (js.recentRuns[0]?.key === key) { js.recentRuns[0] = { key, ...lr }; continue; } // same run, later fields
-    if (js.recentRuns.some((r) => r.key === key)) continue;
-    js.recentRuns.unshift({ key, ...lr });
+    const settled = SETTLED_OUTCOMES.has(lr.outcome) && lr.pending !== true;
+    const existing = js.recentRuns.find((r) => r.runId === runId);
+    if (existing) {
+      // same run, later facts: update in place, keep the outcome sequence
+      const prev = existing.outcome;
+      Object.assign(existing, lr, { runId, settled, recordedAt: now.toISOString() });
+      existing.transitions = [...(existing.transitions || [prev]), ...(prev !== lr.outcome ? [lr.outcome] : [])];
+      continue;
+    }
+    // legacy rows (pre-K8b, keyed by outcome) are left as they are: never merged, reported as legacy
+    js.recentRuns.unshift({ runId, ...lr, settled, recordedAt: now.toISOString(), transitions: [lr.outcome] });
     if (js.recentRuns.length > RECENT_RUNS_MAX) js.recentRuns.length = RECENT_RUNS_MAX;
   }
 }
@@ -427,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 }; }
@@ -467,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);
@@ -502,7 +623,10 @@ function launchCommand(ws, def, io) {
     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: envelope.ok === true, ...(instance ? { instance } : {}), ...(home ? { home } : {}), ...(envelope.ok ? {} : { error: envelope.error?.message || "command failed", 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.
+  const server = typeof res.server === "string" ? res.server : undefined;
+  return { kind: "command", launched: envelope.ok === true, ...(instance ? { instance } : {}), ...(home ? { home, incarnation: incarnationOfHome(home) } : {}), ...(server ? { server } : {}), ...(envelope.ok ? {} : { error: envelope.error?.message || "command failed", errorCode: envelope.error?.code }) };
 }
 
 /** Verify an immutable capsule and its current exact-artifact authorization
@@ -596,12 +720,16 @@ function performWake(def, io, { startIfStopped = true, canStart = true, reserve
     if (reserve && !reserve()) return { kind: "wake", action: "skipped", reason: "the job's slot is held by another process; delivery pending", pending: true };
     try {
       const r = (io?.start || startInstanceSession)(def.home);
-      return { kind: "wake", action: "started", instance: r.instance, target: r.target, reason: "session was stopped; the message is pending until the session is active", pending: true, startedRuntime: true };
+      return { kind: "wake", action: "started", instance: r.instance, target: r.target, home: def.home, incarnation: incarnationOfHome(def.home), reason: "session was stopped; the message is pending until the session is active", pending: true, startedRuntime: true };
     } catch (e) {
       return { kind: "wake", action: "skipped", reason: `start did not complete (${e.code || "error"}): ${e.message}; the slot is kept until the session is observed stopped or absent`, error: e.message, errorCode: e.code, pending: true, startedRuntime: "unconfirmed" };
     }
   }
-  try { (io?.input || inputInstanceSession)(def.home, def.message); return { kind: "wake", action: "delivered", pending: false }; }
+  try {
+    const r = (io?.input || inputInstanceSession)(def.home, def.message);
+    // Delivery custody: name the instance ONLY when the input result names it; the home's current incarnation at record time.
+    return { kind: "wake", action: "delivered", pending: false, ...(typeof r?.instance === "string" ? { instance: r.instance } : {}), home: def.home, incarnation: incarnationOfHome(def.home) };
+  }
   catch (e) { return { kind: "wake", action: "skipped", reason: `input refused: ${e.message}`, pending: true }; }
 }
 
@@ -887,20 +1015,52 @@ export function reconcile(ws, id, { io, now = new Date(), clear = false } = {})
 
 // -------------------------------------------------------- definitions CRUD
 
+export const SCHEDULE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function incarnationOfHome(home) { try { const m = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); return typeof m?.createdAt === "string" ? m.createdAt : null; } catch { return null; } }
+/** K8b — session PROVENANCE of a run (facts the recorder had), never a
+ *  transcript: there is no reader behind this block. */
+function sessionProvenanceOf(r) {
+  if (!r || typeof r !== "object") return null;
+  const delivery = r.startedRuntime ? "launched" : r.action === "delivered" || r.outcome === "delivered" || r.completedPending ? "delivered-active" : r.launched === true || r.instance ? "launched" : "none";
+  return { instance: typeof r.instance === "string" ? r.instance : null, home: typeof r.home === "string" ? r.home : null, incarnation: typeof r.incarnation === "string" ? r.incarnation : null, server: typeof r.server === "string" ? r.server : null, delivery };
+}
+/** Read-time projection of one job's stored history: bounded to
+ *  RECENT_RUNS_MAX, legacy rows marked, corruption isolated to the job. */
+function projectHistory(js) {
+  const stored = js?.recentRuns;
+  if (stored === undefined || stored === null) return { history: { status: "ok", stored: 0, truncated: false }, recentRuns: [] };
+  if (!Array.isArray(stored)) return { history: { status: "corrupt", stored: null, truncated: false }, recentRuns: [] };
+  const rows = [];
+  for (const r of stored.slice(0, RECENT_RUNS_MAX)) {
+    if (!r || typeof r !== "object") { rows.push({ runId: null, legacy: true, corrupt: true }); continue; }
+    const { key, ...rest } = r;
+    const legacy = typeof r.runId !== "string";
+    rows.push({ ...rest, runId: legacy ? null : r.runId, legacy, ...(legacy ? { settled: null, transitions: null } : {}), session: sessionProvenanceOf(rest) });
+  }
+  return { history: { status: "ok", stored: stored.length, truncated: stored.length > RECENT_RUNS_MAX }, recentRuns: rows };
+}
 export function describe(ws, id, io, { defs, st, now = new Date() } = {}) {
+  if (typeof id !== "string" || !SCHEDULE_ID_RE.test(id)) throw scheduleError("E_BAD_ARGS", `schedule id must match ${SCHEDULE_ID_RE} (got ${JSON.stringify(id)})`);
   defs ||= readDefinitions(ws); st ||= readState(ws);
   const def = defs.jobs[id];
   if (!def) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
+  // Subject truth: the definition's own id must be the key it is stored under.
+  if (def.id !== undefined && def.id !== id) throw scheduleError("E_SCHEDULE_IDENTITY", `schedule stored under ${JSON.stringify(id)} declares id ${JSON.stringify(def.id)}`, { key: id, declared: def.id });
   const js = st.jobs[id] || {};
   let nextRun = null; try { nextRun = def.enabled ? nextRunAfter(def, now) : null; } catch { nextRun = null; }
   const lock = jobLockInfo(ws, id);
   const intent = js.attempt || (lock ? (js.lastRun?.execution ? { schemaVersion: SCHEDULE_ATTEMPT_VERSION, execution: js.lastRun.execution } : {}) : undefined);
-  const recentRuns = (js.recentRuns || []).map(({ key, ...r }) => ({ ...r, ...(r.instance && r.home ? { transcript: { instance: r.instance, home: r.home, kind: "session" } } : {}) }));
-  return { ...def, scheduleApi: 2, executionStatus: scheduleExecutionStatus(def, intent, lock), nextRun, lastRun: js.lastRun || null, recentRuns, running: !!lock, ...(js.attempt ? { attempt: js.attempt } : {}), ...(js.pendingWake ? { pendingWake: js.pendingWake } : {}) };
+  const { history, recentRuns } = projectHistory(js);
+  return { ...def, 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 } : {}) };
 }
 export function listSchedules(ws, io, { now = new Date() } = {}) {
   const defs = readDefinitions(ws), st = readState(ws);
-  return { schedules: Object.keys(defs.jobs).sort().map((id) => describe(ws, id, io, { defs, st, now })), scheduler: schedulerStatus(ws, io) };
+  // One job's bad identity or history does not fail the others: it is reported as its own row.
+  const schedules = Object.keys(defs.jobs).sort().map((id) => {
+    try { return describe(ws, id, io, { defs, st, now }); }
+    catch (e) { return { id, scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, unreadable: { code: e.code || "E_SCHEDULE_INVALID", message: e.message }, history: { status: "corrupt", stored: null, truncated: false }, recentRuns: [] }; }
+  });
+  return { scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, integrity: scheduleIntegrity(ws), schedules, scheduler: schedulerStatus(ws, io) };
 }
 export function addSchedule(ws, spec, io) {
   const def = validateDefinition(ws, spec);