@awebai/oats 0.24.9 → 0.24.10

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,
+  findTeamAgent, findTeamInstance, findCapabilityAgent, findInstanceHome, findInstanceHomes, listCapabilityAgents, workspaceOf, stopInstanceSession, recomposeInstanceInstructions, refreshRetirementBaselineHome,
   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";
@@ -4323,6 +4323,8 @@ function spawnCmd() {
       ...(flag("base") !== undefined && flag("base") !== true ? { baseRef: flag("base") } : {}),
       // A confirmed preview binds this apply (K6b): drift → E_DECISION_STALE, nothing created.
       ...(flag("expect-decision") !== undefined && flag("expect-decision") !== true ? { expectDecision: String(flag("expect-decision")) } : {}),
+      // K6c: with --idempotency-key, a retry of the SAME confirmed decision replays the recorded home instead of spawning twice.
+      ...(flag("idempotency-key") !== undefined && flag("idempotency-key") !== true ? { idempotencyKey: String(flag("idempotency-key")) } : {}),
     });
     if (args.includes("--preview")) { if (JSON_MODE) { jsonOk(r); return; } console.log(`preview ${r.agent} → ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch} from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}) runtime ${r.runtime}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}; nothing was created`); return; }
   } catch (e) {
@@ -4342,14 +4344,24 @@ function spawnCmd() {
     if (["E_BRANCH_EXISTS", "E_BASE_UNKNOWN"].includes(e?.code)) { bail(e.code, e.message); throw e; }
     // K6b: the confirmed decision drifted — the fresh decision travels with the refusal so a GUI re-previews.
     if (e?.code === "E_DECISION_STALE") { bail(e.code, e.message, { decision: e.decision }); throw e; }
+    if (e?.code === "E_IDEMPOTENCY_CONFLICT") { bail(e.code, e.message, { instance: e.instance, home: e.home }); throw e; }
+    if (e?.code === "E_PLACEMENT_TAKEN") { bail(e.code, e.message, { instance: e.instance, home: e.home }); throw e; }
+    if (e?.code === "E_SPAWN_INCOMPLETE") { bail(e.code, e.message, { instance: e.instance, home: e.home, launched: e.launched }); throw e; }
     bail(["E_BAD_ARGS", "E_RELATIVE_AMBIGUOUS"].includes(e.code) ? e.code : "E_SPAWN_FAILED", e.message || e); throw e;
   }
   // The instance exists from here on: a failed wake save is reported beside
   // the full receipt, never hidden, and never causes a second spawn.
   let wakeSchedule, wakeScheduleError;
-  if (wake) {
+  if (wake && r.replayed !== true) { // a replayed receipt re-saves nothing
     try { wakeSchedule = saveWakeForHome(scheduleScopeOf(workspaceOf(root)), { instance: r.instance, home: r.home, wake }); }
     catch (e) { wakeScheduleError = { code: e.code || "E_SCHEDULE_FAILED", message: e.message }; r.warnings = [...(r.warnings || []), `wake schedule NOT saved: ${e.message}`]; }
+    // 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 */ }
+    }
+  } 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 */ }
   }
   if (JSON_MODE) {
     // Desktop CLI API v1 spawn result — a FIXED shape (see docs/desktop-cli-api.md).
@@ -4363,6 +4375,9 @@ function spawnCmd() {
       spawnOrigin: r.spawnOrigin, attach: r.attach,
       ...(r.sessionTarget ? { sessionTarget: r.sessionTarget } : {}),
       ...(r.yolo !== undefined ? { yolo: r.yolo } : {}),
+      // K6b/K6c: what bound this spawn, and whether this receipt is a replay of an earlier one.
+      ...(r.decision ? { decision: r.decision } : {}), ...(r.replayed !== undefined ? { replayed: r.replayed } : {}),
+      ...(r.wake !== undefined ? { wake: r.wake } : {}), // {requested, saved|null, error}: saved:null = outcome not recorded
       launchConfig: r.launch?.launchConfig ?? null, launch: r.launch || null, // already redacted by the kernel
     });
     return;
@@ -5018,7 +5033,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"], instanceGitApi: 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", "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"] }));
     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 17:30Z · main `1b8349e5` · Slice 5 ✅ (PR71) · security follow-up ✅ (PR73) · K5 pins ✅ (PR74/75) · **K6b ✅ (PR76: `spawnPreviewApi 2` / `spawn-preview-2` — side-effect-free preview, `--agents-root`, `--expect-decision`/`E_DECISION_STALE`, bounded preflight)** · **PR77 ✅ killGroup pid-0 guard (HIGH; engineer-found)** · OKF 2.1.3 ✅ · engineer → **6b READ wiring** (API 2 gate) → 6b apply companion (proposal) → 7b → 8 · open contracts: K11 admission, attach-knowledge (OKF node refs), auto-PR (P1 write approval), branch enumeration · **0.24.9** after 6b read (release-notes file FIRST)
+**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
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 

package/docs/desktop-cli-api.md

@@ -269,6 +269,58 @@ the pre-fix marker and is never accepted for dispatch.
   own process group and is group-killed on timeout; `preflight {status:
   complete|timeout, budgetMs, elapsedMs}` says which. A hanging runtime cannot
   hang a preview.
+- **Confirmed apply contract** (0.24.10+, feature `spawn-apply-2`,
+  `spawnApplyApi: 1`) — what a GUI may promise at "Confirm spawn":
+  - `decision` gains **`effective {repo, work, runtime, model, launchConfig,
+    yolo, backend, childSpawns, relation{kind, anchor{instance, agentsRoot}}}`**
+    and `revision` hashes placement + effective. An inherited default that would
+    change what launches (the soul's model edited between preview and apply,
+    say) → `E_DECISION_STALE`. A GUI does not re-resolve anything itself.
+  - **No effect before the fence**: backend presence and `ensureHerdr` run only
+    AFTER a successful `--expect-decision` binding and after the placement
+    reservation. A stale apply with `--backend herdr` starts nothing. (The
+    parent-policy refusal still appends `child-spawn-refused` to the PARENT's
+    log on a non-preview apply — that is an audit of a real refusal, not an
+    effect on the target.)
+  - **Exclusive placement**: the home is reserved with a non-recursive `mkdir`
+    immediately after the decision check; a concurrent spawn that lost refuses
+    **`E_PLACEMENT_TAKEN`** having touched nothing. Two concurrent applies of
+    one decision yield exactly one home. There is no wider lock; this
+    reservation is the guarantee.
+  - Gate confirmation AND the exec owner on `spawn-preview-2` +
+    `spawn-apply-2` + `spawn-idempotency`; a legacy local request on such a CLI
+    is refused by the Desktop (`E_PLAN_REQUIRED`), not routed around the fence.
+- **Replay custody** (0.24.10+, feature **`spawn-idempotency-2`** — gate on
+  this, not on `spawn-idempotency`, whose replay could be blocked by
+  `E_BRANCH_EXISTS`): key recovery runs **first**, right after the name is
+  decided and before any placement/branch/base/preflight/backend work — so a
+  retry of a spawn that created its explicit branch still reaches its receipt.
+  The key-bearing home records `spawnCompleted:false` at its first write and
+  `true` only after launch + lineage + final events; a same-key retry of an
+  unfinished spawn refuses **`E_SPAWN_INCOMPLETE`** (`details.{instance, home,
+  launched}`; remedy is the session surface, never another spawn). The key
+  lives in the home by design: durable across the GUI's restart, gone with a
+  retired home — after a retire, "check result" is a roster question. The wake
+  outcome is recorded (`wake {requested, saved, error}`) and returned on
+  replay; `saved:null` means *not recorded* (crash in the interval) — render
+  "Agent created; wake outcome unavailable — check Schedules", never
+  saved/not-saved without the record.
+- **Retention stays clean**: the completion marker and the wake record are
+  kernel writes to `instance.json` made after the spawn's retirement baseline;
+  the kernel re-stamps the baseline's home fingerprint after each, so a fresh
+  keyed home retires with **no** `changed instance-home bytes` — only the
+  agent's own changes ever read as work to recover.
+- **Idempotent apply** (0.24.10+, feature `spawn-idempotency`): `spawn …
+  --expect-decision <rev> --idempotency-key <key>` records the key and the
+  decision in the new home's `instance.json`; a **retry with the same key**
+  replays the recorded receipt (`replayed: true`, same instance/home, no second
+  spawn, no wake re-saved) — found by key across the soul's instances, never by
+  name (the planned name may have been auto-suffixed past it, which is exactly
+  the retry case). The same key with a *different* decision refuses
+  **`E_IDEMPOTENCY_CONFLICT`** (`details.instance/home` of the prior spawn); a
+  different key with a fresh decision is a genuinely new confirmation. Mint the
+  key server-side on the first confirmation and keep it for that intent's
+  retries (as 2c does); a lost response is a replay, never a guess by name.
 - Still absent (named follow-ups, not parity-done): attach-knowledge node refs
   (provider contract), auto-PR (P1/ADE write approval), branch enumeration
   (producer seam).

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

@@ -0,0 +1,55 @@
+# OATS v0.24.10 — confirmed, idempotent spawn (apply contract) and the Desktop Review → Confirm spawn flow
+
+Kernel/Pi/Desktop **0.24.10**. Tag `v0.24.10` → 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 — the spawn apply contract (K6c–K6f)
+
+A Desktop can now let a person **review** exactly what a spawn will do and then
+**confirm** it, with the kernel guaranteeing that what runs is what was
+reviewed — and that a lost response never spawns twice.
+
+- **`spawn-apply-2`** (`spawnApplyApi: 1`): the previewed `decision` binds
+  **effective launch facts** (`repo, work, runtime, model, launchConfig, yolo,
+  backend, childSpawns, relation/anchor`) as well as placement; an inherited
+  default edited between preview and apply → `E_DECISION_STALE`. No backend
+  (Herdr) is started before the decision fence. The home is reserved with an
+  **exclusive** non-recursive `mkdir` right after the check: two concurrent
+  applies of one decision produce exactly one home; the loser refuses
+  `E_PLACEMENT_TAKEN` having touched nothing.
+- **`spawn-idempotency-2`**: `spawn --expect-decision <rev> --idempotency-key
+  <key>` records both in the new home. A **same-key retry replays** the
+  recorded receipt (found by key, never by name — the planned name may have
+  been auto-suffixed past it), runs **before** any placement/branch/base check
+  (so a spawn that created its explicit branch still replays), and re-saves no
+  wake. Same key + different decision → `E_IDEMPOTENCY_CONFLICT`. A home whose
+  spawn did not finish (crash between metadata and launch) → `E_SPAWN_INCOMPLETE`,
+  never a replayed success. The wake outcome is recorded and returned on replay
+  (`wake {requested, saved, error}`; `saved:null` = not recorded).
+- Decision-bound receipts echo the **full** bound decision; the kernel's own
+  post-spawn writes (completion marker, wake record) re-stamp the retirement
+  baseline so a fresh keyed home retires clean.
+- Every one of these came from the Desktop engineer's pre-wiring reads of the
+  merged producer, several proved in an inert VM; each is a new advertised name
+  because a strengthened guarantee must be distinguishable from the installed
+  CLI that lacks it.
+
+## Desktop
+
+- **Review spawn → Confirm spawn**: the spawn modal prepares a server-owned,
+  immutable intent (soul, root, choices, task, wake, the kernel's decision) and
+  applies only by reference; the idempotency key is minted at the first
+  confirmation and kept for that intent's retries. A lost response shows
+  **unknown** with an explicit *Check result* (a same-key kernel replay), never
+  a second spawn or a guessed terminal. Stale/conflict refusals require a fresh
+  review and a new confirmation. `E_SPAWN_INCOMPLETE` points at the session
+  surface; an unrecorded wake outcome says so ("check Schedules"). A raw local
+  spawn request on a fully capable CLI is refused (`E_PLAN_REQUIRED`); older or
+  remote CLIs keep ordinary spawn with the new choices unavailable. No
+  persistent task journal: after a Desktop restart a submitted intent is
+  unavailable/unknown and mints nothing.
+
+## Upgrade
+
+`npm i -g @awebai/oats@0.24.10`, then `oats doctor`.

package/lib/core.mjs

@@ -5925,6 +5925,25 @@ export function spawnInstance(root, agent, o = {}) {
   if (!instance.startsWith(agent.name)) instance = `${agent.name}-${slug(instance)}`;
   instance = slug(instance);
 
+  // K6e: key recovery FIRST — before any placement, branch, base, preflight or
+  // backend work — so a retry of a spawn that already created its explicit
+  // branch (or whose base moved) still reaches its own receipt.
+  if (o.idempotencyKey !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(String(o.idempotencyKey))) throw oatsError("E_BAD_ARGS", "--idempotency-key must be 1-128 chars of [A-Za-z0-9._:-]");
+  if (o.expectDecision !== undefined && o.idempotencyKey !== undefined) {
+    const instancesDir = join(agent._dir, "instances");
+    const prior = (existsSync(instancesDir) ? readdirSync(instancesDir) : []).filter((n) => !n.startsWith("."))
+      .map((n) => { try { return JSON.parse(readFileSync(join(instancesDir, n, "instance.json"), "utf8")); } catch { return null; } })
+      .find((m) => m && m.spawnIdempotencyKey === o.idempotencyKey);
+    if (prior) {
+      if (prior.decision?.revision !== o.expectDecision) throw Object.assign(oatsError("E_IDEMPOTENCY_CONFLICT", `idempotency key ${o.idempotencyKey} was used for a different decision (${prior.decision?.revision ?? "unrecorded"}); a key binds one confirmed decision`), { instance: prior.instance, home: prior.home });
+      // Completion custody: the home exists from the first metadata write, but
+      // the launch/lineage/events that make it a finished spawn may not have
+      // happened (crash in the interval). Say which, never replay a half-spawn.
+      if (prior.spawnCompleted !== true) throw Object.assign(oatsError("E_SPAWN_INCOMPLETE", `${prior.instance} was created for this key but its spawn did not complete (launch or lineage unfinished); inspect it with oats session inspect --home ${prior.home} — do not spawn again`), { instance: prior.instance, home: prior.home, launched: prior.launched === true ? "unknown" : false });
+      return { ...prior, replayed: true, launch: undefined, command: undefined, wake: prior.wake ?? { requested: null, saved: null, error: null } };
+    }
+  }
+
   // Forward-only lineage: EXPLICIT only. Relations (child|sibling|parent|unrelated)
   // anchor the new instance to an EXISTING instance (o.relativeTo). o.parent
   // (CLI --parent) is sugar for relation=child. Parsed and resolved BEFORE any
@@ -6254,10 +6273,10 @@ export function spawnInstance(root, agent, o = {}) {
   // spawn hooks run, which happens after the home exists.
   if ((launchConfig?.args || []).length && applicableRequirements(runtime, resolvedCfg.capabilities).length) throw oatsError("E_LAUNCH_PROBE_UNSUPPORTED", `${requirementsWithArgsMessage(runtime, resolvedCfg.capabilities, launchConfig)}; nothing was created`);
   const runtimePackages = verifyRuntimePackages(runtime, resolvedCfg, repoAbs, { ...(launchConfig?.executable ? { bin } : {}), env: launchEffectiveEnv({ base: process.env, configEnv: launchConfig?.env || {} }) });
-  if (launch && o.preview !== true && !which(backend)) throw new Error(`${backend} not installed${backend === "tmux" ? " (brew install tmux)" : " (https://herdr.dev)"}`);
-  // Preview never starts a backend daemon: it reports reachability as observed
-  // (binary present?) and leaves the socket alone.
-  const herdrBase = launch && backend === "herdr" && o.preview !== true ? ensureHerdr({ binary: which("herdr"), socket: o.herdrSocket }) : undefined;
+  // Backend presence/startup (ensureHerdr) happens AFTER the decision fence
+  // and the exclusive placement reservation below — a stale or losing apply
+  // must not start a daemon. Preview never starts one either.
+  let herdrBase;
   if (o.preview === true) { preflight = { status: previewPreflightBudget?.exhausted ? "timeout" : "complete", budgetMs: preflightBudgetMs, elapsedMs: Date.now() - preflightStarted }; previewPreflightBudget = null; }
   const task = o.task ?? (o.taskFile ? readFileSync(o.taskFile, "utf8") : "");
 
@@ -6279,9 +6298,17 @@ export function spawnInstance(root, agent, o = {}) {
     if (baseOid === undefined) throw oatsError("E_BASE_UNKNOWN", `base ${JSON.stringify(baseRef)} does not resolve to a commit in ${repoAbs}`);
     plannedBase = { ref: baseRef, oid: baseOid };
   }
+  // The decision a confirmation binds: placement AND what would actually
+  // launch (inherited defaults re-resolved at apply must not drift silently).
+  const buildDecision = () => {
+    const d = { instance, home, branch: plannedBranch, base: plannedBase,
+      effective: { repo: repoAbs, work, runtime, model: model || null, launchConfig: launchConfig?.name ?? null, yolo: yolo ?? null, backend, // backend regardless of --no-launch: the decision is what WOULD launch
+        childSpawns: ownChildPolicy.allowed, relation: relation ? { kind: relation, anchor: { instance: relativeTo ?? null, agentsRoot: anchorHome ? dirname(dirname(dirname(anchorHome))) : null } } : null } };
+    d.revision = createHash("sha256").update(canonicalJson(d)).digest("hex").slice(0, 24);
+    return d;
+  };
   if (o.preview === true) {
-    const decision = { instance, home, branch: plannedBranch, base: plannedBase };
-    decision.revision = createHash("sha256").update(canonicalJson(decision)).digest("hex").slice(0, 24);
+    const decision = buildDecision();
     return {
       spawnPreviewApi: 2, preview: true, agent: agent.name, kind: agent.kind || "persistent", instance, home, repo: repoAbs, work,
       subject: o.subject ?? { soul: agent.name, agentsRoot: root, context: null },
@@ -6299,11 +6326,22 @@ export function spawnInstance(root, agent, o = {}) {
     // oid, recomputed here under the same placement path. Any drift is a typed
     // refusal carrying the fresh decision — nothing is created, nothing is
     // auto-suffixed or silently re-based.
-    const fresh = { instance, home, branch: plannedBranch, base: plannedBase };
-    fresh.revision = createHash("sha256").update(canonicalJson(fresh)).digest("hex").slice(0, 24);
+    const fresh = buildDecision();
     if (fresh.revision !== o.expectDecision) throw Object.assign(oatsError("E_DECISION_STALE", `the previewed decision changed (${o.expectDecision} → ${fresh.revision}): ${fresh.instance}${plannedBase ? ` from ${plannedBase.ref}@${plannedBase.oid.slice(0, 12)}` : ""}; preview again`), { decision: fresh });
   }
-  mkdirSync(home, { recursive: true });
+  // Exclusive placement reservation: the parent may be created, the home
+  // itself never with `recursive` — EEXIST means another spawn (a concurrent
+  // apply of the same decision, or anything else) got here first, and this one
+  // has touched nothing.
+  mkdirSync(dirname(home), { recursive: true });
+  try { mkdirSync(home); }
+  catch (e) {
+    if (e?.code === "EEXIST") throw Object.assign(oatsError("E_PLACEMENT_TAKEN", `${instance} already exists at ${home} (a concurrent spawn won the placement); nothing was created by this call`), { instance, home });
+    throw e;
+  }
+  // Backend startup only now — the decision is bound and the placement is ours.
+  if (launch && !which(backend)) { try { rmdirSync(home); } catch { /* keep whatever is there */ } throw new Error(`${backend} not installed${backend === "tmux" ? " (brew install tmux)" : " (https://herdr.dev)"}`); }
+  herdrBase = launch && backend === "herdr" ? ensureHerdr({ binary: which("herdr"), socket: o.herdrSocket }) : undefined;
   // TOCTOU: the placement checks above ran BEFORE composition and the runtime
   // package preflight, both of which shell out — a window in which anything able
   // to write in the agent directory can swap `instances/` for a link elsewhere,
@@ -6723,6 +6761,12 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       relativeTo: relation ? relativeTo : undefined,
       spawnOrigin: relation || (parentInstance && parentInstance !== instance) ? "instance" : "operator",
       policy: { childSpawns: ownChildPolicy },
+      // K6c: a decision-bound spawn records what bound it, so a retry with the
+      // same key replays this receipt instead of spawning again.
+      // The FULL bound decision (placement + effective), exactly as the fence
+      // compared it — a receipt echoes what it was bound to, not a subset.
+      ...(o.expectDecision !== undefined ? { decision: buildDecision() } : {}),
+      ...(o.idempotencyKey !== undefined ? { spawnIdempotencyKey: String(o.idempotencyKey), spawnCompleted: false } : {}),
       capabilityMeta: Object.keys(hookRes.meta).length ? hookRes.meta : undefined,
       layers: Object.keys(resolvedCfg.provenance).length ? resolvedCfg.provenance : undefined,
       capabilities: resolvedCfg.capabilities.map((cap) => ({
@@ -6851,7 +6895,13 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
 
     appendEvent(home, { kind: "spawned", data: { agent: agent.name, work, branch: branch ?? null, runtime, model: model || null, parentInstance: meta.parentInstance ?? null, relation: relation ?? null, launched: launch } });
     if (launch) appendEvent(home, { kind: "launched", data: { runtime, backend, launchConfig: launchConfig?.name ?? null } });
-    return { ...meta, 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 };
+    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
+    }
+    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) {
     const note = compensateSpawn();
     error.message += note;
@@ -7285,6 +7335,18 @@ 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;
+}
 function writeRetirementBaseline(home, work, mode, workMode, capabilities, runtime, { exclusive = false, incarnationId, executionBinding } = {}) {
   if (mode === "directory") assertDirectoryRoots(home);
   const isWorktree = mode === "worktree";

package/package.json

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