@awebai/oats 0.24.11 → 0.24.13

package/bin/oats.mjs

@@ -3144,8 +3144,9 @@ function instanceCmd() {
     if (limit === true || since === true) return bail("E_BAD_ARGS", usage);
     try {
       const { resolveInstance } = await_import_lifecycle();
-      let home = homeOpt;
-      if (!home) home = resolveInstance(dirFlag(), root, name).home;
+      // K7b: --home is an ADDRESS claim, checked like K1 — it must be a home of
+      // exactly this name under the scope (E_HOME_MISMATCH otherwise).
+      const home = resolveInstance(dirFlag(), root, name, homeOpt ? { home: homeOpt } : {}).home;
       const ev = readEvents(home, { ...(limit !== undefined ? { limit: Math.max(1, Math.min(2000, Number(limit) || 200)) } : {}), ...(since ? { since } : {}) });
       if (JSON_MODE) { jsonOk(ev); return; }
       console.log(`${ev.instance}: ${ev.returned} of ${ev.count} event(s)${ev.truncated ? " (window truncated)" : ""}${ev.waitingOnYou ? ` — waiting on you since ${ev.waitingOnYou.since} (${ev.waitingOnYou.producer})` : ""}`);
@@ -4544,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() {
@@ -5033,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", "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: 1, 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:30Z · **v0.24.10 PUBLISHED** (tag `d47dda94`; tarball shasum `030bcc3e`; bump PR86 → main `27f9f334`; artifact probe: preview API 2 → keyed apply → explicit-branch same-key replay → E_IDEMPOTENCY_CONFLICT → concurrent E_PLACEMENT_TAKEN/winner → keyed home retires clean) · **6b COMPLETE**: READ (PR78) + APPLY companion (PR85) · kernel K6b–K6f (PR76/80/81/82/83/84) · engineer → **7b (K7 instance events) proposal** → 8 · open contracts: 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

@@ -156,7 +156,7 @@ returns a bounded unified diff:
 
 No forge (PR/checks/reviews) data here: forge connections are an ADE/workstation integration (P1 decision), read by the Desktop server through the forge's own CLI; the kernel only reports the instance's `remote` so the ADE can pick a backend.
 
-## Instance events (`oats instance events`, `eventsApi: 1`, OATS 0.24.8+) — K7
+## Instance events (`oats instance events`, `eventsApi: 1` → **2**, OATS 0.24.8+) — K7
 
 Typed lifecycle events per instance, **written by the kernel action that made
 them true**, with the receipt it produced. Nothing is inferred from
@@ -185,7 +185,67 @@ home's removal, so a retired instance's `retired` event is still readable).
 - Window is bounded (`--limit`, default 200; `truncated` says so). A torn line
   appears as `kind: "unreadable"` rather than vanishing.
 
-## Schedule run history (`scheduleApi: 2`, OATS 0.24.8+) — K8
+### Events API 2 (`eventsApi: 2`, feature `instance-events-2`, OATS 0.24.12+) — K7b
+
+Gate a Desktop read on **both** `eventsApi === 2` and `"instance-events-2"` in
+`features[]`. API 1 is not a sufficient fence for a bounded read: its reader
+opened and read a source whole, followed symlinks, kept foreign rows and lost
+torn lines and cleared claims silently. API 2:
+
+- **Bounded, descriptor-safe read.** Each source (`home` =
+  `<home>/.oats-events.jsonl`, `workspace` = `<ws>/.agents/events/<agent>--<instance>.jsonl`)
+  is `lstat`ed first; anything but a regular file is **refused unopened**.
+  The open itself is `O_RDONLY|O_NOFOLLOW|O_NONBLOCK` and the descriptor is
+  `fstat`ed: it must be a regular file with the same device+inode lstat saw
+  (closes the lstat→open swap). At most the last 4 MiB is read by descriptor.
+  **Canonical source shape**: `{path: "home"|"workspace", status: "ok"|"absent"|"refused"|"tail", bytes}`
+  — `"tail"` means only the last 4 MiB was read (partial first line dropped);
+  there is no separate `tail` boolean.
+- **Row fields.** `incarnation` is the writing home's `instance.json.createdAt`
+  (ISO) or `null` for rows written before the tag; the result's top-level
+  `incarnation` is the current home's `createdAt` or `null` if unreadable. A
+  row with `incarnation: null` never matches the current incarnation, so it
+  cannot contribute a current waiting claim. **An unknown current incarnation
+  (top-level `incarnation: null`) admits NO claim**: `waitingOnYou: null`,
+  `waitingClaims: []`, rows still returned as history. A consumer must refuse
+  a null-incarnation response that nevertheless carries claims. Dedup identity is
+  `producer|at|kind|incarnation|data`.
+- **`waitingClaims[]` row shape**: `{producer: string, waiting: boolean, since: ISO, reason: string|null}`
+  — one row per producer with a claim in the current incarnation, INCLUDING
+  cleared ones (`waiting: false`, `reason: null`, `since` = the clearing row's
+  `at`). `waitingOnYou` = the newest `waiting: true` row or `null`.
+- **Address history.** `--home <abs>` must be a home of exactly `<instance>` under
+  the scope (`E_HOME_MISMATCH` otherwise, like K1). Rows whose `instance`/`home`
+  are not the admitted address are dropped and counted (`integrity.foreignRows`).
+  Every row carries `incarnation` (the writing home's `instance.json.createdAt`);
+  the result echoes the current home's `incarnation`. Rows tagged with an earlier
+  incarnation ARE returned — they are this address's history — so a consumer can
+  label them "earlier instance at this address". No current home → no read
+  (archived access is a separate contract).
+- **`waitingOnYou` is a producer STATE for the current incarnation**, decided per
+  producer by that producer's latest row that carries the field: an explicit
+  `false` clears, a row without the field does not; earlier incarnations never
+  contribute; computed over the FULL admitted read (a `--limit` window cannot
+  hide a clear). `waitingClaims[]` lists every producer's current claim
+  (`{producer, waiting, since, reason}`); `waitingOnYou` is the newest positive.
+  Still `null` today — no producer emits it.
+- **Provenance and corruption never disappear.** Dedup is by
+  `producer|at|kind|incarnation|data` (the same facts from two producers are two
+  rows). `integrity.unreadableRows` counts torn/invalid lines regardless of
+  `--since` or the window. `count` = admitted rows after `--since`, `returned` =
+  the window, `truncated` = window cut OR any source read as a tail.
+
+```
+{"eventsApi":2,"instance":"dev-1","home":"/abs/home","incarnation":"<iso>","count":7,"returned":7,"truncated":false,
+ "integrity":{"unreadableRows":0,"foreignRows":0,"sources":[{"path":"home","status":"ok","bytes":1234},{"path":"workspace","status":"ok","bytes":1234}]},
+ "events":[{"eventsApi":2,"at":"<iso>","instance":"dev-1","home":"/abs/home","incarnation":"<iso>","producer":"kernel","kind":"spawned","data":{...}}, ...],
+ "lastEvent":{"kind":"launched","at":"<iso>","producer":"kernel","incarnation":"<iso>"},
+ "waitingOnYou":null,"waitingClaims":[],"notes":[...]}
+```
+
+Desktop passes `--limit` (50|100|200) only; `--since` remains a human flag.
+
+## 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
@@ -199,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.12.md

@@ -0,0 +1,57 @@
+# OATS v0.24.12 — instance events API 2 and the Desktop activity popover
+
+Kernel/Pi/Desktop **0.24.12**. Tag `v0.24.12` → 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 — `instance-events-2` (`eventsApi: 2`)
+
+`oats instance events` was a working reader with four defects found by the
+Desktop engineer's exact-source review; each is closed under a new advertised
+name because a strengthened guarantee must be distinguishable from the installed
+CLI that lacks it.
+
+- **Bounded, descriptor-safe read.** Each log source is `lstat`ed first; anything
+  but a regular file is refused unopened. The open is `O_NOFOLLOW|O_NONBLOCK` and
+  the descriptor is `fstat`ed against lstat's device+inode (closes the
+  lstat→open swap). At most the last 4 MiB is read by descriptor
+  (`integrity.sources[].status: ok|absent|refused|tail`).
+- **Address history, incarnation-tagged.** `--home` must be a home of exactly
+  the named instance (`E_HOME_MISMATCH`). Rows of another address are dropped and
+  counted (`integrity.foreignRows`). Every row carries `incarnation` (the writing
+  home's `instance.json.createdAt`); the result echoes the current one, so a
+  recreated same-address instance's earlier rows are visible *as earlier*.
+- **`waitingOnYou` is a producer state**, per (producer, current incarnation):
+  that producer's latest row carrying the field decides, an explicit `false`
+  clears, earlier incarnations never contribute, and it is computed over the full
+  admitted read so a `--limit` window cannot hide a clear. `waitingClaims[]`
+  shows every producer's current claim. **An unknown current incarnation
+  (unreadable `instance.json`) admits no claim at all.** Still `null` today — no
+  producer emits it.
+- **Provenance and corruption never disappear.** Dedup includes the producer;
+  `integrity.unreadableRows` counts torn lines regardless of `--since` or the
+  window; `count`/`returned`/`truncated` are consistent.
+
+## Kernel — retirement fingerprint scope (K6h)
+
+0.24.11's kernel-field neutrality for `instance.json` — and the pre-existing
+`.oats-*` receipt exclusions — were keyed on a root-level *filename*, so they
+also applied to directory work trees and recovery trees. Both are now opt-in
+(`{ instanceHome: true }`), passed by exactly the four instance-home callers;
+work and recovery trees are fully significant. A comparison blind spot (directory
+work was already always recovered when non-empty), not a deletion.
+
+## Desktop
+
+- **Reported lifecycle activity** in the selected-instance popover: an explicit
+  *Load / Refresh activity* control (no roster or per-card fan-out) shows the
+  kernel's dated events with source, integrity (refused/tail/torn/foreign
+  visibly incomplete), earlier/unknown incarnation labels, and attributed
+  waiting claims as *claims as of a timestamp* — never as current runtime
+  authority. Gated on `eventsApi === 2` and `instance-events-2`; two coalesced
+  process-wide read slots; one observation retained per open popup; a failed
+  refresh keeps visibly stale rows rather than a false empty.
+
+## Upgrade
+
+`npm i -g @awebai/oats@0.24.12`, then `oats doctor`.

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/core.mjs

@@ -73,6 +73,8 @@ import { invokeProviderBinding } from "./provider-binding-broker.mjs";
 import { withCapturedBindingFile } from "./captured-binding-file.mjs";
 import { validateCapturedSourceReceipt, withCapturedSourceReceiptFile } from "./captured-source-receipt-file.mjs";
 export { withCapturedBindingFile, validateCapturedSourceReceipt, withCapturedSourceReceiptFile };
+/** Retirement/rollback tree fingerprint (exported for scope tests: kernel-field neutrality is opt-in per instance home). */
+export { fingerprintTree };
 import { executableSurfaceOf, hasExecutableSurface } from "./capability-execution.mjs";
 import { createCapabilityMaterializer } from "./package-materialization.mjs";
 import { resolvePackageClosure } from "./package-closure.mjs";
@@ -7257,7 +7259,7 @@ const GIT_MAX_BUFFER = 512 * 1024 * 1024;
  *  otherwise every stop or event write would read as "changed home bytes". */
 const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json"]);
 const KERNEL_HOME_RECEIPT_PATTERNS = [/^\.oats-stop-receipt\..+\.json$/, /^\.oats-agents-md\..+\.previous$/];
-function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = false } = {}) {
+function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = false, instanceHome = false } = {}) {
   const hash = createHash("sha256");
   const rootStat = lstatSync(root);
   if (!rootStat.isDirectory()) {
@@ -7269,13 +7271,13 @@ function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = f
   }
   const walk = (dir, rel = "") => {
     for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-      if ((!rel && excludeRoot.has(e.name)) || (!rel && (KERNEL_HOME_RECEIPTS.has(e.name) || KERNEL_HOME_RECEIPT_PATTERNS.some((p) => p.test(e.name)))) || (excludeGitMetadata && e.name === ".git")) continue;
+      if ((!rel && excludeRoot.has(e.name)) || (instanceHome && !rel && (KERNEL_HOME_RECEIPTS.has(e.name) || KERNEL_HOME_RECEIPT_PATTERNS.some((p) => p.test(e.name)))) || (excludeGitMetadata && e.name === ".git")) continue;
       const childRel = rel ? join(rel, e.name) : e.name;
       const path = join(dir, e.name);
       const st = lstatSync(path);
       hash.update(childRel); hash.update("\0"); hash.update(String(st.mode & 0o7777)); hash.update("\0");
       if (st.isSymbolicLink()) { hash.update("link\0"); hash.update(readlinkSync(path)); hash.update("\0"); }
-      else if (st.isFile()) { hash.update("file\0"); hash.update(!rel && e.name === "instance.json" ? kernelNeutralInstanceJson(readFileSync(path)) : readFileSync(path)); hash.update("\0"); }
+      else if (st.isFile()) { hash.update("file\0"); hash.update(instanceHome && !rel && e.name === "instance.json" ? kernelNeutralInstanceJson(readFileSync(path)) : readFileSync(path)); /* kernel-field neutrality applies ONLY when the tree IS an instance home; a work tree's instance.json is the agent's bytes */ hash.update("\0"); }
       else if (st.isDirectory()) { hash.update("dir\0"); walk(path, childRel); }
       else throw oatsError("E_WORK_INSPECTION_FAILED", `${path} has an unsupported filesystem type`);
     }
@@ -7360,7 +7362,7 @@ function writeRetirementBaseline(home, work, mode, workMode, capabilities, runti
     ...(incarnationId ? { incarnationId, executionBinding } : {}),
     ...(mode === "directory" ? { directoryWork: true, directoryRoots: { home: directoryIdentity(home), work: directoryIdentity(work) } } : {}),
     home: realPathOrNearest(home),
-    homeFingerprint: fingerprintTree(home, { excludeRoot: new Set(["work"]) }),
+    homeFingerprint: fingerprintTree(home, { excludeRoot: new Set(["work"]), instanceHome: true }),
     disposableReceipts,
     generatedWorkFingerprint: isWorktree ? generatedWorkFingerprint(work, status, disposableReceipts.map((r) => r.root)) : undefined,
     runtime: {
@@ -8453,7 +8455,7 @@ function inspectRetirementWork(home, work, isWorktree, { branchDeletion, directo
   const baselineValid = baseline?.version === RETIRE_BASELINE_VERSION && baseline.home === realPathOrNearest(home);
   if (!baselineValid) {
     classes.push("unknown instance-home provenance");
-  } else if (baseline.homeFingerprint !== fingerprintTree(home, { excludeRoot: new Set(["work"]) })) {
+  } else if (baseline.homeFingerprint !== fingerprintTree(home, { excludeRoot: new Set(["work"]), instanceHome: true })) {
     classes.push("changed instance-home bytes");
   }
   // A mutable mode must not turn owned directory bytes into an excluded shared
@@ -8478,7 +8480,7 @@ function inspectRetirementWork(home, work, isWorktree, { branchDeletion, directo
     if (nestedGitRoots(work).length) classes.push("nested repository state");
   }
   const stateFingerprint = createHash("sha256")
-    .update(fingerprintTree(home, { excludeRoot: new Set(["work"]) }))
+    .update(fingerprintTree(home, { excludeRoot: new Set(["work"]), instanceHome: true }))
     .update("\0").update(directory ? (directoryFingerprint || "missing") : isWorktree && existsSync(work) ? worktreeStatus(work) : "")
     .digest("hex");
   return { classes: [...new Set(classes)], home, work, directory, directoryFingerprint, stateFingerprint, branchExists: branchCommits !== null, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
@@ -8604,7 +8606,7 @@ function preserveRetirementWork(observation, meta, instance) {
     }
     const recoveredHome = join(staging, "home");
     copyRecoveryTree(observation.home, recoveredHome, { excludeRoot: new Set(["work"]) });
-    if (fingerprintTree(observation.home, { excludeRoot: new Set(["work"]) }) !== fingerprintTree(recoveredHome)) {
+    if (fingerprintTree(observation.home, { excludeRoot: new Set(["work"]), instanceHome: true }) !== fingerprintTree(recoveredHome, { instanceHome: true })) {
       throw new Error("home recovery verification disagreed with the source");
     }
     let branchDrift;

package/lib/instance-events.mjs

@@ -5,11 +5,24 @@
  * receipt it produced. Nothing here is inferred from transcripts, task files or
  * prose; "waiting on you" is reported only when a producer says so — today no
  * producer does, and the view says `null`, not a guess. Retirement's event
- * outlives the home in the workspace-level log. */
-import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+ * outlives the home in the workspace-level log.
+ *
+ * eventsApi 2 (`instance-events-2`) — the read is BOUNDED and ADDRESSED:
+ *  - a source is `lstat`ed first and opened only if it is a regular file; the
+ *    reader reads at most the last MAX_BYTES by descriptor, never the whole file;
+ *  - rows are the ADDRESS's history: a row whose instance/home is not the
+ *    admitted address is dropped and counted (`integrity.foreignRows`), a torn
+ *    line is counted (`integrity.unreadableRows`) — never sorted or windowed away;
+ *  - every row is tagged with the `incarnation` (the home's instance.json
+ *    `createdAt`) that wrote it; the result echoes the current one, so a
+ *    recreated same-address instance's earlier rows are visible as earlier;
+ *  - `waitingOnYou` is a producer STATE per (producer, current incarnation):
+ *    that producer's latest row carrying the field decides, an explicit `false`
+ *    clears, and it is computed over the full admitted read, before windowing. */
+import { appendFileSync, closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
-export const EVENTS_API = 1;
+export const EVENTS_API = 2;
 const HOME_LOG = ".oats-events.jsonl";
 const MAX_BYTES = 4 * 1024 * 1024;
 
@@ -23,11 +36,16 @@ function workspaceLogPath(home) {
   return join(workspace, ".agents", "events", `${basename(agentDir)}--${basename(home)}.jsonl`);
 }
 
+/** The incarnation of the home at `home`: its instance.json `createdAt`, or null. */
+export function incarnationOf(home) {
+  try { const m = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); return typeof m?.createdAt === "string" ? m.createdAt : null; } catch { return null; }
+}
+
 /** Append one typed event. Never throws into the caller's action: an event is
  *  evidence, not authority — a failed write is reported in the return value. */
-export function appendEvent(home, event, { workspaceOnly = false } = {}) {
+export function appendEvent(home, event, { workspaceOnly = false, incarnation } = {}) {
   if (!EVENT_KINDS.includes(event.kind)) return { ok: false, reason: `unknown event kind ${event.kind}` };
-  const row = { eventsApi: EVENTS_API, at: new Date().toISOString(), instance: basename(home), home, producer: event.producer || "kernel", kind: event.kind, ...(event.data !== undefined ? { data: event.data } : {}) };
+  const row = { eventsApi: EVENTS_API, at: new Date().toISOString(), instance: basename(home), home, incarnation: incarnation === undefined ? incarnationOf(home) : incarnation, producer: event.producer || "kernel", kind: event.kind, ...(event.data !== undefined ? { data: event.data } : {}) };
   const line = JSON.stringify(row) + "\n";
   const results = [];
   // Retirement fingerprints the home against its baseline and preserves any
@@ -44,33 +62,81 @@ export function appendEvent(home, event, { workspaceOnly = false } = {}) {
   return { ok: results.some((r) => r.ok), row, results };
 }
 
-function readLog(path) {
-  if (!existsSync(path)) return { rows: [], truncated: false, bytes: 0 };
-  const size = statSync(path).size;
-  const text = readFileSync(path, "utf8");
-  const rows = [];
-  for (const line of text.split("\n")) { if (!line.trim()) continue; try { const r = JSON.parse(line); if (r && r.eventsApi === EVENTS_API && typeof r.kind === "string") rows.push(r); } catch { /* a torn line is skipped, counted */ rows.push({ eventsApi: EVENTS_API, kind: "unreadable", at: null, producer: "kernel", data: { reason: "torn or invalid line" } }); } }
-  return { rows, truncated: size > MAX_BYTES, bytes: size };
+/** Bounded, descriptor-safe read of one log: lstat → regular file only → read
+ *  at most the last MAX_BYTES. Returns rows plus the source's integrity facts. */
+function readLog(path, label) {
+  let st;
+  try { st = lstatSync(path); } catch (e) { return e.code === "ENOENT" ? { rows: [], unreadable: 0, source: { path: label, status: "absent", bytes: 0 } } : { rows: [], unreadable: 0, source: { path: label, status: "refused", bytes: 0 } }; }
+  if (!st.isFile()) return { rows: [], unreadable: 0, source: { path: label, status: "refused", bytes: 0 } }; // symlink, FIFO, device, directory: never opened
+  let fd;
+  try {
+    // Close the lstat→open swap: open WITHOUT following a symlink and without
+    // blocking on a FIFO, then verify by descriptor that what was opened is the
+    // regular file lstat saw (same device+inode). Anything else is refused.
+    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) throw new Error("swapped");
+    st = fst; // the size of what is actually open
+  } catch { if (fd !== undefined) try { closeSync(fd); } catch { /* nothing to recover */ } return { rows: [], unreadable: 0, source: { path: label, status: "refused", bytes: 0 } }; }
+  const tail = st.size > MAX_BYTES;
+  const length = tail ? MAX_BYTES : st.size;
+  const buf = Buffer.alloc(length);
+  try {
+    let got = 0; while (got < length) { const n = readSync(fd, buf, got, length - got, (tail ? st.size - MAX_BYTES : 0) + got); if (n <= 0) break; got += n; }
+  } catch { return { rows: [], unreadable: 0, source: { path: label, status: "refused", bytes: st.size } }; }
+  finally { try { closeSync(fd); } catch { /* nothing to recover */ } }
+  const text = buf.toString("utf8");
+  const lines = text.split("\n");
+  if (tail) lines.shift(); // the first line of a tail is (almost surely) partial; it is not counted as torn — the tail itself is reported
+  const rows = []; let unreadable = 0;
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    try { const r = JSON.parse(line); if (r && typeof r === "object" && Number.isInteger(r.eventsApi) && r.eventsApi >= 1 && typeof r.kind === "string" && typeof r.at === "string") rows.push(r); else unreadable++; } catch { unreadable++; }
+  }
+  return { rows, unreadable, source: { path: label, status: tail ? "tail" : "ok", bytes: st.size } };
 }
 
-/** Events for one instance, newest last, from both logs (deduplicated by
- *  at+kind), with a bounded window. `waitingOnYou` is a producer claim or null. */
+/** Events for one instance ADDRESS, newest last, from both logs, with a bounded
+ *  window; integrity is reported independently of the selected rows. */
 export function readEvents(home, { limit = 200, since = null } = {}) {
-  const a = readLog(join(home, HOME_LOG)), b = readLog(workspaceLogPath(home));
-  const seen = new Set(); const rows = [];
-  for (const r of [...a.rows, ...b.rows]) { const k = `${r.at}|${r.kind}|${JSON.stringify(r.data ?? null)}`; if (seen.has(k)) continue; seen.add(k); rows.push(r); }
-  rows.sort((x, y) => String(x.at ?? "").localeCompare(String(y.at ?? "")));
-  const filtered = since ? rows.filter((r) => r.at && r.at > since) : rows;
+  const instance = basename(home);
+  const incarnation = incarnationOf(home);
+  const a = readLog(join(home, HOME_LOG), "home"), b = readLog(workspaceLogPath(home), "workspace");
+  const seen = new Set(); const rows = []; let foreign = 0;
+  for (const r of [...a.rows, ...b.rows]) {
+    if (r.instance !== instance || r.home !== home) { foreign++; continue; } // another address's row in this log: history of THIS address only
+    const k = `${r.producer ?? "kernel"}|${r.at}|${r.kind}|${r.incarnation ?? ""}|${JSON.stringify(r.data ?? null)}`; // same facts from two producers are two rows
+    if (seen.has(k)) continue; seen.add(k); rows.push({ ...r, incarnation: r.incarnation ?? null });
+  }
+  rows.sort((x, y) => x.at.localeCompare(y.at));
+  // Waiting: a producer STATE for the CURRENT incarnation, decided by that
+  // producer's latest row that carries the field, over the FULL admitted read.
+  // An UNKNOWN current incarnation (unreadable instance.json) admits NO claim:
+  // unknown stays unknown, it never resurrects an earlier incarnation's positive.
+  const claims = new Map();
+  for (const r of (incarnation === null ? [] : rows)) {
+    if (r.incarnation !== incarnation) continue;
+    if (!r.data || typeof r.data.waitingOnYou !== "boolean") continue;
+    const p = r.producer ?? "kernel";
+    claims.set(p, r.data.waitingOnYou ? { producer: p, waiting: true, since: r.at, reason: typeof r.data.reason === "string" ? r.data.reason : null } : { producer: p, waiting: false, since: r.at, reason: null });
+  }
+  const waitingClaims = [...claims.values()];
+  const positive = waitingClaims.filter((c) => c.waiting).sort((x, y) => x.since.localeCompare(y.since)).at(-1) ?? null;
+  const filtered = since ? rows.filter((r) => r.at > since) : rows;
   const window = filtered.slice(-limit);
   const last = window.at(-1) ?? null;
-  const waiting = window.filter((r) => r.data && r.data.waitingOnYou === true).at(-1) ?? null;
   return {
-    eventsApi: EVENTS_API, instance: basename(home), home, count: filtered.length, returned: window.length, truncated: filtered.length > window.length || a.truncated || b.truncated,
-    events: window, lastEvent: last ? { kind: last.kind, at: last.at, producer: last.producer } : null,
-    waitingOnYou: waiting ? { since: waiting.at, producer: waiting.producer, reason: waiting.data.reason ?? null } : null,
+    eventsApi: EVENTS_API, instance, home, incarnation, count: filtered.length, returned: window.length,
+    truncated: filtered.length > window.length || a.source.status === "tail" || b.source.status === "tail",
+    integrity: { unreadableRows: a.unreadable + b.unreadable, foreignRows: foreign, sources: [a.source, b.source] },
+    events: window, lastEvent: last ? { kind: last.kind, at: last.at, producer: last.producer ?? "kernel", incarnation: last.incarnation } : null,
+    waitingOnYou: positive ? { since: positive.since, producer: positive.producer, reason: positive.reason } : null,
+    waitingClaims,
     notes: [
       "events are producer-attributed facts written by the kernel action that made them true; nothing is inferred from transcripts or task files",
-      "waitingOnYou is null unless a producer reported it — null means unknown, not 'not waiting'",
+      "this is the ADDRESS's history: rows tagged with an earlier incarnation belong to a previous instance at this address",
+      "waitingOnYou is null unless a producer reported it for the current incarnation — null means unknown, not 'not waiting'; an explicit false clears that producer's claim; an unknown current incarnation (null) admits no claim at all",
+      "integrity counts torn and foreign rows and names each source's status; truncated is true when the window cut rows or a source was read as a tail",
     ],
   };
 }

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.11",
+  "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",