@awebai/oats 0.24.12 → 0.24.13

package/bin/oats.mjs

@@ -4545,7 +4545,11 @@ function scheduleCmd() {
       }
       default: throw scheduleError("E_BAD_ARGS", "usage: oats schedule list|show <id>|add <id> --file <spec.json>|update <id> --file <spec.json>|enable <id>|disable <id>|run <id> [--force]|remove <id> [--force]|reconcile <id> [--clear]|tick [--dry-run] [--host]|host install|uninstall|status [--dir <workspace>|--server <id>] [--json]");
     }
-  } catch (e) { cmdFail(e.code || "E_SCHEDULE_FAILED", e.message); }
+  } catch (e) {
+    // K8b: typed refusal details travel (identity mismatch: key/declared; a refused file: its integrity source).
+    const details = Object.fromEntries(["key", "declared", "source", "field"].filter((k) => e[k] !== undefined).map((k) => [k, e[k]]));
+    if (JSON_MODE) jsonFail(e.code || "E_SCHEDULE_FAILED", e.message, Object.keys(details).length ? details : undefined); else die(e.message);
+  }
 }
 
 async function sessionCmd() {
@@ -5034,7 +5038,7 @@ function versionCmd() {
     // on it (an older CLI without the surface must fail closed with a
     // reason, not an argument error). `features`: kernel abilities a peer
     // must see before relying on them (retire-home: retire --home).
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "catalog", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "session-recompose", "readiness-verify", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2"], instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 1, lifecycleApi: 1, readinessApi: 1, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 2, scheduleApi: SCHEDULE_API, operationsApi: 1, capturedDispatchApi: 1, capturedDispatchActions: ["inspect", "compose", "command", "operation", "spawn", "trust"] }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "catalog", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "session-recompose", "readiness-verify", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2"], instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 1, lifecycleApi: 1, readinessApi: 1, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 1, capturedDispatchApi: 1, capturedDispatchActions: ["inspect", "compose", "command", "operation", "spawn", "trust"] }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);

package/docs/design/2026-09-20-redesign-program-board.md

@@ -2,7 +2,7 @@
 
 **Purpose:** the one accurate view of every work stream in the redesign, what is on main, what is in flight, who owns it, and what blocks it. Lead: `oats-expert` (redesign lead). Updated whenever anything merges, is returned, or reality changes. Older per-lane boards are superseded by this file.
 
-**Last update:** 2026-09-22 21:40Z · K7b on main (PR89 `e808fbfc`; PR90 `17182cdb` open-time O_NOFOLLOW+fstat guard + DTO pins) · **K6h PR91 → main `dcd2bc89`**: kernel-field neutrality + receipt exclusions now opt-in for instance homes only (work/recovery trees fully significant) · **7b wiring head = `dcd2bc89`** · engineer wiring 7b → 8 · 0.24.12 after 7b Desktop PR · open: K11, attach-knowledge, auto-PR, branch enumeration
+**Last update:** 2026-09-22 23:45Z · v0.24.12 published · **slice 8 approved** (no polling; command-running GET `/api/schedules` to be REMOVED; remote history unsupported; captured edit = honest limitation; transcript = provenance only, read-only transcript verb = K12 Decision later) · **K8b PR95 → main `ee60d1e2`** (`schedule-read-2` / `scheduleHistoryApi 3`: runId by time, bounded fd state reads + 1 MiB budget, per-job isolation, scope/id echo, `session` provenance replaces `transcript`) · 12 receipts to engineer · engineer wiring 8 → then rest of frame 10 · open: K11, K12 transcript, attach-knowledge, auto-PR, branch enumeration
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 

package/docs/desktop-cli-api.md

@@ -245,7 +245,7 @@ torn lines and cleared claims silently. API 2:
 
 Desktop passes `--limit` (50|100|200) only; `--since` remains a human flag.
 
-## Schedule run history (`scheduleApi: 2`, OATS 0.24.8+) — K8
+## Schedule run history (`scheduleApi: 2`, `scheduleHistoryApi: 2` → **3**, OATS 0.24.8+) — K8
 
 `oats schedule show|list --json` entries gain **`recentRuns`**: the last 50
 settled runs (newest first) — every `lastRun` the scheduler recorded once its
@@ -259,6 +259,67 @@ Schedules view (frame 08) renders `recentRuns` as the recent-runs list and the
 transcript pointer as the handoff; captured-policy definitions are preserved
 as they are (definition fields are untouched by this addition).
 
+### History API 3 (`scheduleHistoryApi: 3`, feature `schedule-read-2`, OATS 0.24.13+) — K8b
+
+Gate a Desktop history read on **both** `scheduleHistoryApi === 3` and
+`"schedule-read-2"` in `features[]` (`scheduleApi` stays 2 — mutation verbs are
+unchanged). API 2's reader keyed runs by outcome, read state files whole and
+unchecked, echoed a stored `definition.id` without checking it, and named a
+`transcript` that no reader backs. API 3:
+
+- **Run identity is time, not outcome.** `runId = sha256(scheduledFor|startedAt|attemptId)[0:24]`.
+  A run's later facts update its one row; `transitions[]` keeps the outcome
+  sequence (`["started","unknown","ended"]`); `settled: boolean`
+  (`pending: true` is never settled); `recordedAt`. Pre-API-3 rows are returned
+  with `runId: null, legacy: true, settled: null, transitions: null` and are
+  never merged. `lastRun` carries the same `runId` as its history row.
+- **Bounded, descriptor-safe state.** `oats-schedules.json` and
+  `.agents/schedules/state.json` are `lstat`ed (regular file only), opened
+  `O_NOFOLLOW|O_NONBLOCK`, `fstat`-verified (dev+ino), and read whole **only
+  within a 1 MiB budget** — over budget is a typed `E_SCHEDULE_STATE_OVERSIZE`
+  refusal with `details.source`, never truncated JSON. `list`/`show` carry
+  `integrity: {sources: [{path: "definitions"|"state", status: "ok"|"absent"|"refused"|"oversize"|"corrupt", bytes}]}`.
+  History is capped at 50 rows **at read** (`history: {status, stored, truncated}`);
+  one job's corrupt history (`history.status: "corrupt"`, `recentRuns: []`) or
+  bad identity (`unreadable: {code, message}`) never fails the other jobs in `list`.
+- **Subject truth.** `list` and `show` echo `scope` (the resolved schedule-owning
+  workspace) and canonical `id`. A definition whose own `id` differs from its
+  key → `E_SCHEDULE_IDENTITY` (`details.key`, `details.declared`). IDs must match
+  `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$` (`E_BAD_ARGS` otherwise, before any read).
+- **Session provenance, never a transcript.** The `transcript` key is gone.
+  Each run (and `lastRun`) carries
+  `session: {instance: string|null, home: string|null, incarnation: string|null, server: string|null, delivery: "launched"|"delivered-active"|"none"}`
+  — facts the recorder had at write time (an active-session wake names the
+  instance only when the input result did; `incarnation` = the home's
+  `instance.json.createdAt` at record time; `server` = the answering peer for a
+  remote command). **There is no reader behind this block**: a consumer renders
+  provenance and a precise unavailable reason. A read-only transcript verb is a
+  separate seam (K12), not implied by this API.
+
+```
+{"scope":"/abs/ws","scheduleApi":2,"scheduleHistoryApi":3,
+ "integrity":{"sources":[{"path":"definitions","status":"ok","bytes":812},{"path":"state","status":"ok","bytes":4410}]},
+ "schedules":[{"id":"nightly","scope":"/abs/ws","scheduleApi":2,"scheduleHistoryApi":3,…,
+   "history":{"status":"ok","stored":7,"truncated":false},
+   "recentRuns":[{"runId":"3f…","scheduledFor":"<iso>","startedAt":"<iso>","outcome":"ended","settled":true,"transitions":["started","ended"],"recordedAt":"<iso>",
+                  "session":{"instance":"dev-1","home":"/abs/home","incarnation":"<iso>","server":null,"delivery":"launched"}}]}],
+ "scheduler":{…}}
+```
+
+**Exact shapes (API 3):**
+- `schedule list --json` → `result = {scope, scheduleApi: 2, scheduleHistoryApi: 3, integrity, schedules: Entry[], scheduler}`.
+- `schedule show <id> --json` → `result = {schedule: Entry}` (one level of nesting; `integrity` is NOT on `show` — it is a scope fact reported by `list`).
+- `Entry` (readable) = definition fields (`id, kind, home, message|operation, cron, enabled, …`) + `{scope, scheduleApi: 2, scheduleHistoryApi: 3, executionStatus, nextRun: ISO|null, lastRun: Run|null, history, recentRuns: Run[], running: boolean, attempt?, pendingWake?}`.
+- `Entry` (unreadable, `list` only) = `{id, scope, scheduleApi: 2, scheduleHistoryApi: 3, unreadable: {code, message}, history: {status: "corrupt", stored: null, truncated: false}, recentRuns: []}` — no definition fields.
+- `history` = `{status: "ok", stored: integer, truncated: boolean}` | `{status: "corrupt", stored: null, truncated: false}`.
+- `Run` (API 3 row) = producer-written fields (`scheduledFor, startedAt, kind, outcome, …`) + `{runId: string, legacy: false, settled: boolean, recordedAt: ISO, transitions: string[], session}`; `transitions[]` elements are outcome strings in write order, first element = the first recorded outcome.
+- `Run` (legacy row) = producer-written fields + `{runId: null, legacy: true, settled: null, transitions: null, session}` — no `recordedAt`, no `key`.
+- `Run` (corrupt element) = `{runId: null, legacy: true, corrupt: true}` only.
+- `session` = `{instance: string|null, home: string|null, incarnation: ISO|null, server: string|null, delivery: "launched"|"delivered-active"|"none"}`; always present on rows and on `lastRun`.
+- `runId` is opaque to consumers: never recompute, never dedup client-side.
+- **Refusals** (`ok:false`): `E_SCHEDULE_STATE_OVERSIZE` / `E_SCHEDULE_INVALID` carry `error.details.source = {path, status, bytes}` (+ `field`); `E_SCHEDULE_IDENTITY` carries `error.details.key` and `error.details.declared`; `E_BAD_ARGS` (id shape) carries no details. A refusal has no `integrity` block — `list` refuses as a whole only when a scope file itself is unreadable.
+- **Open path** (both files): `lstat` → regular file → `open(O_RDONLY|O_NOFOLLOW|O_NONBLOCK)` → `fstat` regular + same dev/ino + `size ≤ 1 MiB` → read exactly `fstat.size` bytes by descriptor (a file that grows past the budget between lstat and fstat is refused, never partially read).
+
 ## Spawn preview (`oats spawn … --preview`, `spawnPreviewApi: 1`, OATS 0.24.8+)
 
 The Spawn modal's fields are backed by the kernel's own decision, taken **before

package/docs/release-notes/v0.24.13.md

@@ -0,0 +1,51 @@
+# OATS v0.24.13 — schedule history API 3 and the Desktop schedules table
+
+Kernel/Pi/Desktop **0.24.13**. Tag `v0.24.13` → the commit carrying these
+notes; the version-bump commit lands after the tag. Consumers gate on
+`oats version --json` `features[]` names and API integers — never on the version.
+
+## Kernel — `schedule-read-2` (`scheduleHistoryApi: 3`; `scheduleApi` stays 2)
+
+`oats schedule list|show` history had four defects found by the Desktop
+engineer's exact-source review; each is closed under a new advertised name.
+
+- **A run's identity is when it was scheduled and started, never its outcome.**
+  `runId = sha256(scheduledFor|startedAt|attemptId)[0:24]`; a run's later facts
+  update its one row; `transitions[]` keeps the outcome sequence
+  (`["started","unknown","ended"]` is one run, not three); `settled`,
+  `recordedAt`. Pre-API-3 rows are returned `legacy: true` with `runId: null`
+  and are never merged.
+- **Bounded, descriptor-safe state.** Both scope files are `lstat`ed (regular
+  file only), opened `O_NOFOLLOW|O_NONBLOCK`, `fstat`-verified (dev+ino) and
+  read whole **only within a 1 MiB budget** — over budget is a typed
+  `E_SCHEDULE_STATE_OVERSIZE` refusal, never truncated JSON. `list` carries
+  `integrity.sources[]`; history is capped at 50 rows at read
+  (`history: {status, stored, truncated}`); one job's corrupt history or bad
+  identity is its own row and never fails the others.
+- **Subject truth.** `list`/`show` echo the resolved `scope` and canonical `id`;
+  a definition whose own `id` differs from its key → `E_SCHEDULE_IDENTITY`; ids
+  are validated before any read. Typed refusal details travel through the CLI's
+  JSON failure.
+- **Session provenance, never a transcript.** The `transcript` pointer named a
+  reader that does not exist and is gone. Every run carries
+  `session: {instance|null, home|null, incarnation|null, server|null, delivery}`
+  — what the recorder knew at write time. A read-only transcript verb is a
+  separate seam (K12), not implied by this API.
+
+## Desktop
+
+- **Schedules** view: the compact table (enabled, schedule, target, cadence,
+  next run, last reported outcome, actions) with **Recent runs** for the
+  workspace (≤50), read once on entry and on explicit Refresh — no polling.
+  History enables nothing; `ended` is not success and `delivered` is not
+  consumption; missing time facts are shown as unreported. Session provenance
+  is displayed with a precise unavailable reason — no transcript, terminal or
+  link. Remote history and editing a captured wake are shown as honest
+  limitations. Gated on `scheduleHistoryApi === 3` and `schedule-read-2`.
+- **Security**: the command-running `GET /api/schedules` is removed (405, no
+  command, no default workspace); legacy POST `list|show` aliases run through
+  the same strict admission, budgets and two coalesced read slots.
+
+## Upgrade
+
+`npm i -g @awebai/oats@0.24.13`, then `oats doctor`.

package/lib/schedule.mjs

@@ -20,7 +20,8 @@
  *  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";
@@ -127,11 +128,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 +161,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;
   }
 }
@@ -502,7 +549,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 +646,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 +941,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);

package/package.json

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