@awebai/oats 0.24.10 → 0.24.12

package/bin/oats.mjs

@@ -30,7 +30,7 @@ import {
   approveCapability, approveAvailableCapability, updatePackage, removePackage, migrateLegacyLock, applyLegacyLockMigration,
   packageIntegrity, capabilityArtifactIntegrity, verifyCapabilityInstallation, installedCapabilityDir, installedCapabilitiesDir, ownedCapabilitiesDir, loadPackageManifestAt,
   resolveOatsConfig, resolveWorkMode, composeInstanceAgentsMd, planInstanceResources, parseYamlNested, assertSafeConfigValue, assertSafeConfigWriteKey, stripInternalAnnotations, withConfigFile, packagedInject, teamAgentRoots,
-  findTeamAgent, findTeamInstance, findCapabilityAgent, findInstanceHome, findInstanceHomes, listCapabilityAgents, workspaceOf, stopInstanceSession, recomposeInstanceInstructions, refreshRetirementBaselineHome,
+  findTeamAgent, findTeamInstance, findCapabilityAgent, findInstanceHome, findInstanceHomes, listCapabilityAgents, workspaceOf, stopInstanceSession, recomposeInstanceInstructions,
   ensureRoot, findRoot, findAgent, listAgents, listInstances, listAgentDefs, createAgent as coreCreateAgent,
   spawnInstance, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, upsertLocalAgent, defaultRepo, RELATIONS, validateLaunchConfig, resolveLaunchSelection, resolveLaunchExecutable, checkLaunchExecutable, missingLaunchEnvRefs, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_RUNTIMES, LAUNCH_RECIPE_VERSION, parseLaunchCommand, resolveYolo, planLaunch, redactLaunchCommand, restartInstanceSession,
 } from "../lib/core.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})` : ""}`);
@@ -4358,10 +4359,10 @@ function spawnCmd() {
     // K6e: record the wake outcome in the home so a same-key replay can report
     // it instead of leaving "saved or not?" to inference.
     if (r.spawnIdempotencyKey) {
-      try { const f = join(r.home, "instance.json"); const m = JSON.parse(readFileSync(f, "utf8")); m.wake = { requested: true, saved: !wakeScheduleError, error: wakeScheduleError ?? null }; writeFileSync(f, JSON.stringify(m, null, 2) + "\n"); r.wake = m.wake; refreshRetirementBaselineHome(r.home); } catch { /* the receipt still says it */ }
+      try { const f = join(r.home, "instance.json"); const m = JSON.parse(readFileSync(f, "utf8")); m.wake = { requested: true, saved: !wakeScheduleError, error: wakeScheduleError ?? null }; writeFileSync(f, JSON.stringify(m, null, 2) + "\n"); r.wake = m.wake; } catch { /* the receipt still says it */ }
     }
   } else if (r.spawnIdempotencyKey && r.replayed !== true) {
-    try { const f = join(r.home, "instance.json"); const m = JSON.parse(readFileSync(f, "utf8")); m.wake = { requested: false, saved: null, error: null }; writeFileSync(f, JSON.stringify(m, null, 2) + "\n"); r.wake = m.wake; refreshRetirementBaselineHome(r.home); } catch { /* nothing to record */ }
+    try { const f = join(r.home, "instance.json"); const m = JSON.parse(readFileSync(f, "utf8")); m.wake = { requested: false, saved: null, error: null }; writeFileSync(f, JSON.stringify(m, null, 2) + "\n"); r.wake = m.wake; } catch { /* nothing to record */ }
   }
   if (JSON_MODE) {
     // Desktop CLI API v1 spawn result — a FIXED shape (see docs/desktop-cli-api.md).
@@ -5033,7 +5034,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", "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"] }));
     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 19:10Z · **v0.24.9 PUBLISHED** (tag `04a4f709`; both packages on npm, tarball shasum `6333c01c`; bump PR79 → main `a5cc390e`; artifact probe: readiness/preview API 2/bound apply/E_DECISION_STALE/retire retention/no-git verify all pass, caller alive, soul intact) · **6b READ MERGED** (PR78) · K6b ✅ · PR77 ✅ · engineer → **6b APPLY companion proposal** → 7b → 8 · open contracts: K11, attach-knowledge, auto-PR, branch enumeration
+**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
 
 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,6 +185,66 @@ 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.
 
+### 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`, OATS 0.24.8+) — K8
 
 `oats schedule show|list --json` entries gain **`recentRuns`**: the last 50

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

@@ -0,0 +1,30 @@
+# OATS v0.24.11 — retirement recovery: kernel-owned fields only, nothing re-blessed after launch
+
+Kernel/Pi/Desktop **0.24.11**. Tag `v0.24.11` → the commit carrying these
+notes; the version-bump commit lands after the tag. **Upgrade from 0.24.10 —
+it can lose an agent's early home bytes at retire.**
+
+## Fix
+
+0.24.10 (PR84) made a fresh keyed spawn retire clean by re-hashing the **whole
+home** after the kernel's own post-spawn writes (completion marker, wake
+record). That re-stamp ran after the tmux launch, so anything the agent wrote
+in the launch→completion interval — `STATE.md`, notes — was blessed into the
+retirement baseline and **not recovered** at retire. Found by the Desktop
+engineer's exact-source inert analysis of the merged fix.
+
+Now the re-stamp is gone. The baseline fingerprint hashes the root
+`instance.json` with exactly the kernel-owned post-spawn fields
+(`spawnCompleted`, `wake`) removed. Kernel writes never read as the agent's
+changes; **nothing else in the home is ever re-blessed**; there is no
+observation of the home after launch. Regression: authored bytes written at
+launch are recovered under `changed instance-home bytes` with the bytes
+intact; a plain keyed spawn still retires with `workRecovery: null`.
+
+Rule recorded for the framework: the retirement baseline may account only for
+bytes the kernel can *prove* it wrote — never for what it *observes* after the
+agent may have started.
+
+## Upgrade
+
+`npm i -g @awebai/oats@0.24.11`, then `oats doctor`.

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/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";
@@ -6898,8 +6900,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     if (o.idempotencyKey !== undefined) {
       // Only now is the spawn a finished receipt a same-key retry may replay.
       meta.spawnCompleted = true;
-      writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
-      refreshRetirementBaselineHome(home); // a kernel write, not the agent's
+      writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n"); // a kernel-owned field: the baseline fingerprint ignores it
     }
     return { ...meta, ...(o.expectDecision !== undefined ? { replayed: false } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: spawnHerdr ? `HERDR_SOCKET_PATH=${shq(spawnHerdr.socket)} ${shq(spawnHerdr.binary)} terminal attach ${shq(spawnHerdr.terminalId)}` : backend === "herdr" ? "not launched" : `tmux attach -t ${session}`, warnings: spawnWarnings.length ? spawnWarnings : undefined };
   } catch (error) {
@@ -7258,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()) {
@@ -7270,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(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`);
     }
@@ -7335,17 +7336,21 @@ function retirementDisposableRoots(work, workMode, capabilities) {
   return roots;
 }
 
-/** Re-stamp ONLY the home fingerprint of an existing baseline after a KERNEL
- *  write to the home (completion marker, wake record). Retirement compares the
- *  home against this baseline; kernel-owned metadata written after spawn must
- *  not read as the agent's "changed instance-home bytes". Everything else in
- *  the baseline (work fingerprint, mode, capabilities) is untouched. */
-export function refreshRetirementBaselineHome(home) {
-  const path = retirementBaselinePath(home);
-  let baseline; try { baseline = JSON.parse(readFileSync(path, "utf8")); } catch { return false; }
-  baseline.homeFingerprint = fingerprintTree(home, { excludeRoot: new Set(["work"]) });
-  writeFileSync(path, JSON.stringify(baseline, null, 2) + "\n", { mode: 0o600 });
-  return true;
+/** The fields the KERNEL writes into a home's instance.json after the spawn's
+ *  retirement baseline was taken (completion marker, wake record). The
+ *  baseline fingerprint hashes instance.json with exactly these removed, so a
+ *  kernel write does not read as the agent's change — and NOTHING ELSE in the
+ *  home is ever re-blessed: an agent's STATE.md written seconds after launch
+ *  is still recovered at retire. (Replaces a whole-home re-stamp that could
+ *  bless authored bytes written in the launch→completion interval.) */
+const KERNEL_POST_SPAWN_FIELDS = ["spawnCompleted", "wake"];
+function kernelNeutralInstanceJson(bytes) {
+  try {
+    const m = JSON.parse(String(bytes));
+    if (!m || typeof m !== "object" || Array.isArray(m)) return bytes;
+    for (const k of KERNEL_POST_SPAWN_FIELDS) delete m[k];
+    return Buffer.from(JSON.stringify(m));
+  } catch { return bytes; }
 }
 function writeRetirementBaseline(home, work, mode, workMode, capabilities, runtime, { exclusive = false, incarnationId, executionBinding } = {}) {
   if (mode === "directory") assertDirectoryRoots(home);
@@ -7357,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: {
@@ -8450,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
@@ -8475,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 };
@@ -8601,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/package.json

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