@awebai/oats 0.25.2 → 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 PUBLISHED** (workspace model A–C + team-review fixes) · 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/design/2026-09-23-workspace-module-contracts.md

@@ -564,3 +564,23 @@ in `next.clone` like any member that lacks a clone at the convention (the host
 is a member; a soul that lives in it may need a work clone). Under an explicit
 `oats-local.yaml` `standalone:` header the next steps say the view is standalone
 and list only that repo.
+
+### 0.25.3 — `OATS_SOUL_ID` (stable soul identity for providers)
+
+The per-commit soul cache (0.25.1, M1) made `realpath(<home>/soul)` change with every
+member commit; a provider that keyed durable state on that path (OKF 2.1.3 `owners.json`)
+refused the next spawn (`E_OWNER`). "Members are latest" and "the owner is a path" cannot
+both hold, so the kernel now hands hooks a **stable identity**:
+
+- `OATS_SOUL_ID` in the `spawn` / `retire` / `launch` hook environment: for a workspace soul
+  `<repo key>#<soul name>` exactly as the canonical key is spelled (e.g.
+  `github.com/awebai/aweb#aweb-protocol-expert`, local fixtures `local//abs/path.git#name`);
+  for a classic soul the realpath of `agents/<name>/soul` (today's value — 0.24 deployments
+  unchanged). Also recorded as `instance.json.workspace.soul.id`.
+- `OATS_SOUL` is the **content** the home links — for a workspace soul the per-commit
+  directory `agents/<name>/souls/<commit12>/`, never the swappable `agents/<name>/soul`
+  pointer. Providers read content from `OATS_SOUL` and key state on `OATS_SOUL_ID`.
+- Provider contract (OKF 2.1.4): `owners[owner] = OATS_SOUL_ID ?? realpath(OATS_SOUL ?? home/soul)`;
+  a prior row whose value is a path under `agents/<same soul name>/(soul|souls/<commit>)` is
+  migrated to the id once, not refused; any other mismatch stays `E_OWNER`.
+

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.3.md

@@ -0,0 +1,19 @@
+# OATS v0.25.3 — `OATS_SOUL_ID`
+
+Kernel/Pi **0.25.3**. Tag `v0.25.3` → the commit carrying these notes. No API change;
+`features[]` unchanged; one additive hook environment variable and one additive
+`instance.json` field.
+
+## Kernel
+
+- **`OATS_SOUL_ID`** — a soul's stable identity for capability hooks (`spawn`,
+  `retire`, `launch`): `<repo key>#<soul name>` for a workspace soul, the realpath of
+  `agents/<name>/soul` for a classic soul. Recorded as `instance.json.workspace.soul.id`.
+  Fixes the consequence of 0.25.1's per-commit soul cache found by the first outsider
+  rebuild: OKF 2.1.3 pins a soul's owner to `realpath(home/soul)`, which now changes with
+  every member commit → the next spawn of the same soul was refused `E_OWNER`. The provider
+  half (owners keyed by `OATS_SOUL_ID`, one-time migration of path pins) ships in OKF 2.1.4.
+- **`OATS_SOUL` is the content the home links** — for a workspace soul the per-commit
+  directory, never the swappable `agents/<name>/soul` pointer (spawn and retire hooks agree).
+
+Contract: `docs/design/2026-09-23-workspace-module-contracts.md` § "0.25.3 — OATS_SOUL_ID".

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

@@ -640,7 +640,7 @@ const LAUNCH_CONFIG_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Environment the kernel sets for every launch (identity, home, roots) and
  *  its reference aliases: a configuration may not name them. */
-export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "OATS_AGENT", "OATS_SOUL", "OATS_ROOT", "OATS_CONTEXT", "OATS_WORKSPACE", "OATS_EVENT", "OATS_SETTINGS", "OATS_CLI_BIN", "PI_AGENT_INSTANCE", "PI_AGENT_HOME", "PI_AGENTS_ROOT"]);
+export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "OATS_AGENT", "OATS_SOUL", "OATS_SOUL_ID", "OATS_ROOT", "OATS_CONTEXT", "OATS_WORKSPACE", "OATS_EVENT", "OATS_SETTINGS", "OATS_CLI_BIN", "PI_AGENT_INSTANCE", "PI_AGENT_HOME", "PI_AGENTS_ROOT"]);
 export const LAUNCH_REF_PREFIX = "OATS_LAUNCH_REF_";
 const reservedLaunchEnv = (n) => RESERVED_LAUNCH_ENV.has(n) || n.startsWith(LAUNCH_REF_PREFIX);
 export function validateLaunchConfig(name, entry, where) {
@@ -4806,7 +4806,31 @@ function validateHookEnvironment(capabilityID, value, owners, declarations) {
   return accepted;
 }
 
-export function runLifecycleHooks(event, { home, instance, agentName, soulDir, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {}, assertRoots }) {
+/**
+ * A soul's STABLE identity for capability hooks (OATS_SOUL_ID): what a provider
+ * may key durable state on. Workspace soul: `<repo key>#<soul name>` — it does not
+ * change when the member commits (the per-commit soul directory does) or when the
+ * copy moves. Classic soul: the realpath of agents/<name>/soul, i.e. today's value,
+ * so 0.24 deployments are unchanged. Order: an explicit `soulId` (a prepared spawn),
+ * the home's recorded `instance.json.workspace.soul` (retire/launch of a workspace
+ * home), else the path.
+ */
+export function stableSoulId({ soulId, home, soulDir, agentName } = {}) {
+  if (typeof soulId === "string" && soulId) return soulId;
+  if (home) {
+    try {
+      const meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8"));
+      const s = meta?.workspace?.soul;
+      if (typeof s?.id === "string" && s.id) return s.id;
+      if (typeof s?.repoKey === "string" && s.repoKey) return `${s.repoKey}#${meta.agent ?? agentName ?? ""}`;
+    } catch { /* not a workspace home */ }
+  }
+  if (soulDir) { try { return realpathSync(soulDir); } catch { return soulDir; } }
+  return "";
+}
+export const workspaceSoulId = (repoKey, name) => `${repoKey}#${name}`;
+
+export function runLifecycleHooks(event, { home, instance, agentName, soulDir, soulId, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {}, assertRoots }) {
   const results = { meta: {}, briefs: [], warnings: [], order: [], launch: {}, env: {}, failures: [], contributions: [] };
   const envOwners = new Map();
   const envDeclarations = new Map((resolved.capabilities || []).map((cap) => [cap.id, { names: new Set(cap.environment || []), namespaces: [...(cap.environmentNamespaces || [])] }]));
@@ -4834,7 +4858,7 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, c
           // the package STORE root — do not conflate them.
           OATS_EVENT: event, OATS_INSTANCE: instance, OATS_INSTANCE_HOME: home, OATS_HOME: home, OATS_AGENT: agentName,
           OATS_CAPABILITY: cap.id, OATS_LAYER: cap.layer || "", OATS_ROOT: rootDir || "",
-          OATS_SOUL: soulDir || "", OATS_CONTEXT: contextDir, OATS_WORKSPACE: workspaceDir || "", OATS_LEVEL: cap.level || "",
+          OATS_SOUL: soulDir || "", OATS_SOUL_ID: stableSoulId({ soulId, home, soulDir, agentName }), OATS_CONTEXT: contextDir, OATS_WORKSPACE: workspaceDir || "", OATS_LEVEL: cap.level || "",
           OATS_TEAM_NAME: resolved.team?.name || "", OATS_TEAM_ID: resolved.team?.id || "", OATS_TEAM_SCOPE: resolved.team?.scope || "",
           ...extraEnv,
           // Hooks also run through direct core callers (not only bin/oats).
@@ -6938,8 +6962,12 @@ function* spawnBody(root, agent, o = {}) {
   // Capability lifecycle hooks (spawn) — the knowledge integration scaffolds instance
   // memory (STATE.md/log.md/notes/ are OKF conventions, not kernel ones); the
   // messaging integration mints the comms identity. Kernel stays memory-agnostic.
+  const preparedSoulId = o.prepared ? workspaceSoulId(o.prepared.soulEntry.repoKey, o.prepared.soulEntry.name) : undefined;
+  // Hooks read the soul the HOME links (the per-commit directory for a workspace
+  // soul), never the swappable agents/<name>/soul pointer: a provider that pins a
+  // path must pin this instance's content, and OATS_SOUL_ID is what it keys on.
   const hookRes = runLifecycleHooks("spawn", {
-    home, instance, agentName: agent.name, soulDir, contextDir: repoAbs,
+    home, instance, agentName: agent.name, soulDir: homeSoulTarget, soulId: preparedSoulId, contextDir: repoAbs,
     workspaceDir: workspaceOf(root), rootDir: root, resolved: resolvedCfg,
     extraEnv: { OATS_TASK: task, OATS_REPO: repoAbs, OATS_BRANCH: branch || "", OATS_WORK: work, OATS_RUNTIME: runtime, OATS_KIND: agent.kind || "persistent" },
   });
@@ -7043,7 +7071,7 @@ function* spawnBody(root, agent, o = {}) {
     catch (e) { return retainDirectory(e); }
     try {
       const comp = runLifecycleHooks("retire", {
-        home, instance, agentName: agent.name, soulDir, contextDir: repoAbs,
+        home, instance, agentName: agent.name, soulDir: homeSoulTarget, soulId: preparedSoulId, contextDir: repoAbs,
         workspaceDir: workspaceOf(root), rootDir: root, resolved: resolvedCfg,
         priorMeta: hookRes.meta || {},
       });
@@ -7242,7 +7270,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     // digests) in instance.json before this metadata is assembled — carry them.
     if (o.prepared) {
       try { const prior = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); if (prior.modules) meta.modules = prior.modules; if (prior.providers) meta.providers = prior.providers; } catch { /* materialize wrote it; absent means nothing to carry */ }
-      meta.workspace = { key: o.prepared.discovery?.key ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, team: o.prepared.soulEntry.team ?? null } };
+      meta.workspace = { key: o.prepared.discovery?.key ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { id: workspaceSoulId(o.prepared.soulEntry.repoKey, o.prepared.soulEntry.name), repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, team: o.prepared.soulEntry.team ?? null } };
     }
     const spawnWarnings = warnings;
 
@@ -9273,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;
@@ -9366,9 +9404,12 @@ export function retireInstance(root, name, o = {}) {
     const resolved = meta.capabilityRuntime
       ? { capabilities: meta.capabilityRuntime }
       : resolveOatsConfig(meta.repo, found.agent.name);
+    // The soul this HOME links (a workspace home links its per-commit directory;
+    // agents/<name>/soul may since point elsewhere) — the same value spawn's hook saw.
+    const homeSoulLink = (() => { try { return realpathSync(join(found.home, "soul")); } catch { return null; } })();
     hookResults = runLifecycleHooks("retire", {
       home: found.home, instance: name, agentName: found.agent.name,
-      soulDir: found.agent._soulDir || join(found.agent._dir, "soul"),
+      soulDir: homeSoulLink || found.agent._soulDir || join(found.agent._dir, "soul"),
       contextDir: meta.repo, workspaceDir: workspaceOf(root), rootDir: root, resolved, priorMeta: meta.capabilityMeta || {},
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.25.2",
+  "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",