@awebai/oats 0.24.8 → 0.24.10

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/docs/release-notes/v0.24.9.md

@@ -0,0 +1,67 @@
+# OATS v0.24.9 — readiness pins, side-effect-free spawn preview (API 2), process-group safety, Desktop Readiness view
+
+Kernel/Pi/Desktop **0.24.9**. Tag `v0.24.9` → 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
+
+- **Spawn preview API 2** (feature `spawn-preview-2`, `spawnPreviewApi: 2`).
+  API 1 previews **wrote before they returned** — a refused child spawn appended
+  an event to the parent, a Herdr backend could be started, an unknown soul
+  could be imported from an importable def — and nothing bound a later spawn to
+  the previewed decision. API 2: a preview touches nothing, success or refusal
+  (proven by a byte-identical deployment tree); `spawn --agents-root <abs>`
+  binds the exact root with no fallback and the preview echoes `subject` as
+  given; `decision {instance, home, branch, base, revision}` + `spawn
+  --expect-decision <rev>` refuses **`E_DECISION_STALE`** with the fresh
+  decision on any drift (no auto-suffix, no silent re-base, nothing created);
+  every native probe shares one bounded preflight budget and is process-group
+  killed on timeout (`preflight {status, budgetMs, elapsedMs}`). **Gate on API
+  2 — API 1 is the pre-fix marker.**
+- **Readiness pins** (`oats readiness`): `configured` is *effective* activation
+  (a capability declared for the soul but disabled is a fail that says so);
+  data-only capabilities (skills/inject, no commands/hooks/env) report trust
+  **not-applicable** — the inspect row carries `health.executableSurface`;
+  every item is typed (`capability {id, level, scope}`, `origin {kind,
+  target}`) and `summary.byCapability[]` regroups the same items with
+  `ownReady` vs `ready` (never ready under a `summary.subjectBlockers[]` item
+  such as unknown membership); `subject.selector` echoes the arguments as given,
+  byte-exact; an unreadable member document is `unknown`, not not-applicable;
+  `readiness --home <captured>` refuses `E_UNSUPPORTED_MODE`; `--agents-root`
+  documented. **Signature verification** (feature `readiness-verify`) is
+  bounded custody: one budget per read, process-group kill, cleanup on
+  SIGINT/SIGTERM/SIGHUP, `GIT_CONFIG_GLOBAL=/dev/null`, https/ssh only, a closed
+  `signature.failure.code` — never stderr.
+- **Process-group safety (high).** Bounded-custody code killed a child's
+  process group on timeout with `process.kill(-child.pid)`; a **failed** spawn
+  (binary missing → `ENOENT`) reports `pid: 0`, and `kill(-0)` signals the
+  caller's own process group — `oats readiness --verify-signatures` without
+  `git` would have SIGKILLed the operator's shell/tmux/Desktop backend. One
+  guarded helper now refuses non-positive PIDs at every kill site.
+- **OKF 2.1.3** mirrored and pinned in the official catalog: per-cause `check`
+  reasons, a named remedy when a soul has no `okf.json` (was a raw ENOENT from
+  the required spawn hook), retired drained sources switch their `okf-<id>` job
+  off.
+
+## Desktop
+
+- **Readiness** (frame 09/04): Workspace header entry and first-run
+  invitation; the quartet from `oats readiness` with items, remedies (display
+  only), *View policy*, *Skip for now* (presentation only). Verify signatures
+  and Enrol are shown unavailable with the exact reason until their contracts
+  land. Effective-readiness section per scope on the Capabilities view.
+- **Normalized route classification**: one classifier decides every specialized
+  IPC route from the normalized pathname — dot-segment, percent-encoded,
+  backslash, tab and CRLF aliases can no longer skip a route's frame/epoch
+  guard.
+- Spawn modal: kernel **preview** (API 2) for the instance name, home, worktree,
+  branch and resolved base — *Suggest* asks the kernel for its default
+  candidate; preview-only choices block legacy submission rather than being
+  dropped. Apply companion, attach-knowledge, auto-PR and branch enumeration are
+  named follow-ups, not parity-done.
+
+## Upgrade
+
+`npm i -g @awebai/oats@0.24.9`, then `oats doctor`. Desktops on an older CLI
+show the new controls as unavailable until the CLI advertises them.

package/docs/workspace-adoption.md

@@ -107,7 +107,10 @@ onboarding and legacy roster/knowledge cutover remain separate.
   production store or grants are supplied. An acceptance fixture is parent-owned
   and cannot be counted as production knowledge adoption.
 - Current authored expert editions require knowledge **oats.okf@2.1.2** and
-  messaging **oats.aweb@1.11.2** (both OATS >=0.24.4), not optional defaults. These published revisions
+  messaging **oats.aweb@1.11.2** (both OATS >=0.24.4), not optional defaults.
+  The official catalog now offers **oats.okf 2.1.3** (per-cause `check` reasons,
+  a named remedy for a soul without `okf.json`, retired sources switch their
+  job off); editions move to it when their owner re-reviews them. These published revisions
   are **not proof that their combined bindings/runtime profile is ready**. The provider
   owner supplies that evidence and any subsequently reviewed compatible revision.
   Do not replace either requirement with none or erase a read edge to launch.

package/docs/workspaces.md

@@ -71,7 +71,7 @@ name: domain-expert
 requires:
   knowledge:
     capability: oats.okf
-    source: git:github.com/awebai/oats-okf@v2.1.2#oats-package
+    source: git:github.com/awebai/oats-okf@v2.1.3#oats-package
 ```
 
 This illustrates software selection, not complete OKF provisioning: the chosen capability also needs its own valid knowledge declaration, bindings and accepted base.

package/lib/core.mjs

@@ -26,7 +26,7 @@
  *   work (worktree|checkout|attached|workspace|directory), runtime (pi|claude|codex), model (pi model pattern, optional)
  *   (attached as soul default is for service agents — spawn must supply workDir)
  */
-import { execFileSync, execSync, spawn as spawnProcess } from "node:child_process";
+import { execFileSync, execSync, spawn as spawnProcess, spawnSync } from "node:child_process";
 import {
   chmodSync, closeSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, writeFileSync,
 } from "node:fs";
@@ -41,6 +41,7 @@ import { capturedPiSessionDirectory, requireCapturedPiRecordSupport, inspectCapt
 import { attachSessionTarget } from "./session-viewer.mjs";
 import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
 import { appendEvent } from "./instance-events.mjs";
+import { killGroup } from "./process-group.mjs";
 import { ensureHerdr, allocateHerdr, launchHerdr, inspectHerdr, stopHerdr, validHerdrTarget, herdrSnapshot, herdrCommand } from "./herdr.mjs";
 
 import { oatsError } from "./errors.mjs";
@@ -129,6 +130,30 @@ function legacyOperationalSkills(soulDir) {
 // ---------- shell helpers ----------
 function sh(cmdline) { return execSync(cmdline, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim(); }
 function shTry(cmdline) { try { return sh(cmdline); } catch { return undefined; } }
+/** A native PROBE (a runtime binary asked about its catalogue or packages) under
+ *  a preview: bounded by what is left of the shared preflight budget, run in its
+ *  own process group and group-killed on timeout. Cheap lookups (`command -v`)
+ *  are not probes and never draw from the budget. Outside a preview: shTry. */
+function probeTry(cmdline) {
+  if (!previewPreflightBudget) return shTry(cmdline);
+  const left = previewPreflightBudget.deadline - Date.now();
+  if (left <= 0) { previewPreflightBudget.exhausted = true; return undefined; }
+  const r = spawnSync("/bin/sh", ["-c", cmdline], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: left, killSignal: "SIGKILL", detached: true, env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "/bin/false" } });
+  if (r.error || r.signal) { killGroup(r); if (r.error?.code === "ETIMEDOUT" || r.signal === "SIGKILL") previewPreflightBudget.exhausted = true; return undefined; }
+  return r.status === 0 ? String(r.stdout).trim() : undefined;
+}
+let previewPreflightBudget = null;
+/** execFileSync for a native probe: under a preview budget, the timeout is what
+ *  is left of it and the child is group-killed; otherwise the caller's timeout. */
+function probeExecFile(file, args, options = {}) {
+  if (!previewPreflightBudget) return execFileSync(file, args, options);
+  const left = previewPreflightBudget.deadline - Date.now();
+  if (left <= 0) { previewPreflightBudget.exhausted = true; throw Object.assign(new Error("preflight budget exhausted"), { code: "E_PREFLIGHT_BUDGET" }); }
+  const r = spawnSync(file, args, { ...options, timeout: Math.min(left, options.timeout ?? left), killSignal: "SIGKILL", detached: true });
+  if (r.error || r.signal) { killGroup(r); if (r.error?.code === "ETIMEDOUT" || r.signal === "SIGKILL") previewPreflightBudget.exhausted = true; throw r.error || Object.assign(new Error("probe killed"), { code: "E_PREFLIGHT_BUDGET" }); }
+  if (r.status !== 0) throw Object.assign(new Error(`probe exited ${r.status}`), { status: r.status, stdout: r.stdout });
+  return r.stdout;
+}
 function shIn(cwd, cmdline, timeout = 45000) {
   return execSync(cmdline, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout }).trim();
 }
@@ -4327,7 +4352,7 @@ export const RUNTIME_PACKAGE_MANAGERS = {
       try {
         // The SELECTED executable answers (a wrapper or another binary), with
         // pi's own controlled list subcommand only: never a launch argument.
-        const out = execFileSync(opts.bin || "pi", ["list", "--no-approve"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 30000 });
+        const out = probeExecFile(opts.bin || "pi", ["list", "--no-approve"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 30000 });
         const rows = [];
         // pi dims the path with chalk; strip any escapes before matching.
         const lines = out.replace(/\u001b\[[0-9;]*m/g, "").split("\n");
@@ -4418,7 +4443,7 @@ export const RUNTIME_PACKAGE_MANAGERS = {
     list: (env = process.env, opts = {}) => {
       let out;
       try {
-        out = execFileSync(RUNTIME_PACKAGE_MANAGERS.claude.bin(opts), ["plugin", "list", "--json"],
+        out = probeExecFile(RUNTIME_PACKAGE_MANAGERS.claude.bin(opts), ["plugin", "list", "--json"],
           { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 60000, env });
       } catch { return []; }
       let rows;
@@ -5422,7 +5447,7 @@ export function resolveModelPreference(model, runtime = "pi") {
     const [provider, ...rest] = bare.split("/");
     const id = rest.join("/");
     if (!id) return pref; // bare pattern (no provider) — let pi resolve it
-    const out = shTry(`pi --list-models ${shq(id)} 2>/dev/null`) || "";
+    const out = probeTry(`pi --list-models ${shq(id)} 2>/dev/null`) || "";
     const found = out.split("\n").some((line) => {
       const cols = line.trim().split(/\s+/);
       return cols[0] === provider && cols[1] === id;
@@ -5865,7 +5890,14 @@ export function spawnInstance(root, agent, o = {}) {
   if (!repoAbs) throw new Error(`agent "${agent.name}" has no repo configured — pass one`);
   // Launch selection: a named configuration (explicit, or the soul's
   // launch-config default), or none; the runtime and model follow from it.
-  const launchSelection = resolveLaunchSelection({ launchConfigs: launchConfigsOf(configChain(repoAbs)), agent, selection: { launchConfig: o.launchConfig, runtime: o.runtime, model: o.model } });
+  // K6b: a preview's native probes (model catalogue, runtime packages) share
+  // ONE budget from here to the return; each probe is group-killed on timeout.
+  const preflightStarted = Date.now(), preflightBudgetMs = o.preview === true ? (Number(process.env.OATS_PREVIEW_PREFLIGHT_BUDGET_MS) || 20000) : undefined;
+  let preflight = { status: "complete", budgetMs: preflightBudgetMs ?? null };
+  if (o.preview === true) previewPreflightBudget = { deadline: preflightStarted + preflightBudgetMs };
+  let launchSelection;
+  try { launchSelection = resolveLaunchSelection({ launchConfigs: launchConfigsOf(configChain(repoAbs)), agent, selection: { launchConfig: o.launchConfig, runtime: o.runtime, model: o.model } }); }
+  catch (e) { previewPreflightBudget = null; throw e; }
   const launchConfig = launchSelection.config;
   const runtime = launchSelection.runtime;
   const model = launchSelection.model;
@@ -5893,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
@@ -6100,7 +6151,9 @@ export function spawnInstance(root, agent, o = {}) {
     const parentMeta = parentHome && existsSync(join(parentHome, "instance.json")) ? JSON.parse(readFileSync(join(parentHome, "instance.json"), "utf8")) : anchorMeta;
     const policy = childPolicyOf(parentMeta);
     if (policy.allowed === false) {
-      if (parentHome) appendEvent(parentHome, { kind: "child-spawn-refused", data: { child: instance, agent: agent.name, policy } });
+      // A preview touches nothing — not even the parent's event log; the
+      // typed refusal IS the preview's answer.
+      if (parentHome && o.preview !== true) appendEvent(parentHome, { kind: "child-spawn-refused", data: { child: instance, agent: agent.name, policy } });
       throw Object.assign(oatsError("E_CHILD_SPAWNS_DISABLED", `${parentInstance} does not allow child spawns (policy origin: ${policy.origin?.kind ?? "recorded"}${policy.origin?.detail ? ` — ${policy.origin.detail}` : ""}); nothing was spawned. Spawn without a parent relation, or respawn the parent with --allow-child-spawns.`),
         { parent: parentInstance, policy });
     }
@@ -6220,8 +6273,11 @@ 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 && !which(backend)) throw new Error(`${backend} not installed${backend === "tmux" ? " (brew install tmux)" : " (https://herdr.dev)"}`);
-  const herdrBase = launch && backend === "herdr" ? 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") : "");
 
   if (existsSync(directoryRollbackPath(homeReal))) throw oatsError("E_WORK_INSPECTION_FAILED", `directory cleanup is still owed for ${home}; restore and retire the retained home before reusing its name`);
@@ -6242,9 +6298,22 @@ 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 = buildDecision();
     return {
-      spawnPreviewApi: 1, preview: true, agent: agent.name, kind: agent.kind || "persistent", instance, home, repo: repoAbs, work,
+      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 },
+      decision, preflight,
+      backendStatus: launch ? { name: backend, installed: !!which(backend), started: false } : null,
       runtime, model: model || null, modelSource: launchSelection.modelSource ?? null, launchConfig: launchConfig?.name ?? null, yolo, backend,
       branch: plannedBranch, base: plannedBase, worktree: work === "worktree" ? join(home, "work") : null,
       relation: relation || null, parentInstance: parentInstance && parentInstance !== instance ? parentInstance : null,
@@ -6252,7 +6321,27 @@ export function spawnInstance(root, agent, o = {}) {
       skills: expectedResources.filter((r) => r.type === "skill-tree").flatMap((r) => r.entries || []), task: task || null,
     };
   }
-  mkdirSync(home, { recursive: true });
+  if (o.expectDecision !== undefined) {
+    // A confirmed preview binds THIS apply: same name, home, branch and base
+    // 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 = 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 });
+  }
+  // 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,
@@ -6672,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) => ({
@@ -6800,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;
@@ -7234,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/lib/process-group.mjs

@@ -0,0 +1,12 @@
+/** Kill a detached child's whole process group (e.g. git + its remote helper /
+ *  ssh, or a runtime probe + what it forked). ONLY for a child that was actually
+ *  spawned: a failed spawn (ENOENT) reports `pid: 0`, and `process.kill(-0)` /
+ *  `process.kill(0)` address the CALLER's own process group — the operator's
+ *  shell, tmux session or Desktop backend. Returns whether anything was signalled. */
+export function killGroup(child, signal = "SIGKILL") {
+  const pid = child?.pid;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try { process.kill(-pid, signal); } catch { /* already gone */ }
+  try { process.kill(pid, signal); } catch { /* already gone */ }
+  return true;
+}