@awebai/oats 0.24.10 → 0.24.11

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";
@@ -4358,10 +4358,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).

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: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
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 

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

@@ -6898,8 +6898,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) {
@@ -7276,7 +7275,7 @@ function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = f
       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(!rel && e.name === "instance.json" ? kernelNeutralInstanceJson(readFileSync(path)) : readFileSync(path)); 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 +7334,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);

package/package.json

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