@awebai/oats 0.25.3 → 0.25.4

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-23 20:00Z · **0.25.0 + 0.25.1 + 0.25.2 PUBLISHED** (workspace model A–C + team-review fixes + operator-rebuild round) · Phase D plan next · **Desktop engineer paused by the human** (10B-0 uncommitted foundation preserved; resume is the human's call; 0.24.14 to be cut from a maintenance branch off `e5cdaf95` when its PR lands) · parity pipeline ⏸.
+**Last update:** 2026-09-23 20:00Z · **0.25.0–0.25.3 PUBLISHED** (workspace model A–C; team-review fixes; operator-rebuild round; OATS_SOUL_ID) · **OKF 2.1.4 pending human GO** (owner pin by id, clone/timeout, retire-schedule seam; Antares writes the PRs) · Phase D plan next · **Desktop engineer paused by the human** (10B-0 uncommitted foundation preserved; resume is the human's call; 0.24.14 to be cut from a maintenance branch off `e5cdaf95` when its PR lands) · parity pipeline ⏸.
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 

package/docs/rebuild-to-v2.md

@@ -337,6 +337,13 @@ type a digest. An `--approve` that names an id or version the resolution does
 not contain is an error, not a silent skip; an entry the flags do not cover
 stays unapproved (exit `2`, as above).
 
+`<version>` is the value `sync --json` reports as `approvalNeeded[].version`,
+which is what the lock records as the package's `version`. For a **catalog**
+package that is the published version (`oats.okf@2.1.4`). For a **git** source
+pinned by commit (`git:github.com/awebai/oats-okf@<oid>`) it is the **full
+commit OID**, not the `git:` reference and not a tag name — copy it from the
+`approvalNeeded` line rather than from your workspace file.
+
 ## 7b. OKF 2: start a FRESH `state-dir` — do not re-point the old one
 
 OKF 2 pins each knowledge **owner** to a soul by path: at source registration

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

@@ -0,0 +1,21 @@
+# OATS 0.25.4
+
+Patch release: one kernel fix found by an operator rehearsal on 0.25.3.
+
+## Fixed
+
+- **Quarantine retry never re-ran the owed retire hook on a workspace-mode
+  home.** When a required spawn hook fails and its compensation is incomplete,
+  the kernel retains the home with a cleanup descriptor
+  (`.oats-rollback-incomplete.json`). Module materialization had already
+  written a pre-hook `instance.json` stub (`{ modules, providers,
+  resolutionRevision }`), and `oats retire` trusted that stub over the
+  descriptor — so `meta.repo` was undefined, the retry reported *"retire hook
+  <cap>: did not run on this retry"* and *"cleanup descriptor lost its context
+  repo"* on every attempt, and only `--force` could remove the home (leaving
+  the provider's external state to be cleaned by hand). The retry now reads
+  the cleanup descriptor whenever the live record is not a complete spawn
+  record; the owed hook runs, the home stays while it fails, and is removed
+  once it succeeds. Regression test in `test/spawn-workspace.test.mjs`.
+
+No contract changes. `oats version --json` is unchanged apart from the version.

package/lib/core.mjs

@@ -9301,7 +9301,17 @@ export function retireInstance(root, name, o = {}) {
     } catch { markerUnusable = true; }
   }
   const liveMeta = existsSync(metaPath) ? JSON.parse(readFileSync(metaPath, "utf8")) : undefined;
-  const meta = liveMeta || quarantine?.cleanup || {};
+  // A quarantined home may carry an instance.json that is NOT the spawn record:
+  // module materialization writes a pre-hook stub ({ modules, providers,
+  // resolutionRevision }) before the spawn hooks run, and a required-hook
+  // failure retains the home with that stub in place. Trusting it over the
+  // cleanup descriptor left meta.repo undefined, so the retry never re-ran the
+  // owed retire hook and reported "cleanup descriptor lost its context repo"
+  // on every attempt — only --force could clear the home (found by an operator
+  // rehearsal on 0.25.3). The descriptor is written FOR this retry; a live
+  // record only wins when it is a complete spawn record (repo + work present).
+  const liveIsSpawnRecord = !!liveMeta && nonEmptyString(liveMeta.repo) && WORK_MODES.includes(liveMeta.work);
+  const meta = liveIsSpawnRecord || !quarantine ? (liveMeta || quarantine?.cleanup || {}) : { ...liveMeta, ...quarantine.cleanup };
   // Compensation metadata is the SPAWN's, from whichever record survived — never
   // a failed retry's report, which says nothing about what still needs undoing.
   if (!liveMeta?.capabilityMeta && quarantine?.cleanup?.capabilityMeta) meta.capabilityMeta = quarantine.cleanup.capabilityMeta;

package/package.json

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