@botbuddy/cli 1.60.1 → 1.60.3

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.60.1",
-  "source_commit": "ac9d46a93d57bb9d5af94cba238532767c1f19cc",
-  "source_sha256": "667acf404a591bd0e09357645192040cba7a0b2085f33d89be6a4bbc84a6dd53",
+  "release_version": "1.60.3",
+  "source_commit": "ce15cf76534b99c30468bdd541f2ab8e9340ee08",
+  "source_sha256": "962d9cae75ce935da9306a538440ccb1448270ea80b9c0d4ba76be0c3c3a6707",
   "target": "darwin-arm64",
-  "sha256": "9dd4af84ad4131cf69c94bbed69f3c51087ca8ac4d742df6e9367faadbeddb97"
+  "sha256": "989d317d944147c7ec86dc894c74b6a462e95fa85ee709e3e0c562783e231668"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.60.1",
-  "source_commit": "ac9d46a93d57bb9d5af94cba238532767c1f19cc",
-  "source_sha256": "667acf404a591bd0e09357645192040cba7a0b2085f33d89be6a4bbc84a6dd53",
+  "release_version": "1.60.3",
+  "source_commit": "ce15cf76534b99c30468bdd541f2ab8e9340ee08",
+  "source_sha256": "962d9cae75ce935da9306a538440ccb1448270ea80b9c0d4ba76be0c3c3a6707",
   "target": "linux-x64",
-  "sha256": "61db8eb2108fcf9407460e96f487316728e262927241b5ee672ffca3443a11d3"
+  "sha256": "90a9017148902699e54e26fddb940abc87d22ca96c3f415a75d4d172614dd281"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.60.1",
-  "source_commit": "ac9d46a93d57bb9d5af94cba238532767c1f19cc",
-  "source_sha256": "667acf404a591bd0e09357645192040cba7a0b2085f33d89be6a4bbc84a6dd53",
+  "release_version": "1.60.3",
+  "source_commit": "ce15cf76534b99c30468bdd541f2ab8e9340ee08",
+  "source_sha256": "962d9cae75ce935da9306a538440ccb1448270ea80b9c0d4ba76be0c3c3a6707",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "9dd4af84ad4131cf69c94bbed69f3c51087ca8ac4d742df6e9367faadbeddb97",
+      "sha256": "989d317d944147c7ec86dc894c74b6a462e95fa85ee709e3e0c562783e231668",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "61db8eb2108fcf9407460e96f487316728e262927241b5ee672ffca3443a11d3",
+      "sha256": "90a9017148902699e54e26fddb940abc87d22ca96c3f415a75d4d172614dd281",
       "mode": "0755"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.60.1",
+  "version": "1.60.3",
   "description": "BotBuddy \u2014 Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/stack-isolation.mjs

@@ -993,6 +993,7 @@ export function reservePortBlocks(ports, { registryDir = defaultPortRegistryDir(
 
   mkdir(registryDir, { recursive: true });
   const claimed = [];
+  let boundLeaseId = null;
   const record = (block, at = now(), ttlSecs = owner?.idleTtlSecs, idleRetained = false) => JSON.stringify({
     schema: 1,
     project_id: owner?.projectId ?? null,
@@ -1001,6 +1002,7 @@ export function reservePortBlocks(ports, { registryDir = defaultPortRegistryDir(
     slot: owner?.slot == null ? null : String(owner.slot),
     stack_dir: owner?.stackDir ?? null,
     port_base: block,
+    ...(boundLeaseId ? { lease_id: boundLeaseId } : {}),
     created_at: at,
     retain_until: at + Math.max(LEASED_STACK_GC_MIN_AGE_MS, (Number(ttlSecs) || DEFAULT_IDLE_TTL_SECS) * 1000 + LEASED_STACK_RETENTION_GRACE_MS),
     owner_pid: process.pid,
@@ -1053,6 +1055,10 @@ export function reservePortBlocks(ports, { registryDir = defaultPortRegistryDir(
   return {
     blocks: claimed,
     invocationToken,
+    bindLease: (leaseId) => {
+      bindLeasedStackClaim(owner.stackDir, leaseId, { registryDir, invocationToken });
+      boundLeaseId = leaseId;
+    },
     /** Keep the reservation alive while the batch runs (Codex #928 R21): a
      * prepared `--stack-path` has no directory marker, so nothing else renews it,
      * and an aged-out claim could be reclaimed under a still-live stack. */
@@ -1084,6 +1090,136 @@ export function reservePortBlocks(ports, { registryDir = defaultPortRegistryDir(
   };
 }
 
+/** Read-only candidate lookup; accepted server proof and exact identity checks still gate removal. */
+export function hasLocalLeaseClaim(leaseId, { cwd = process.cwd(), registryDir = defaultPortRegistryDir() } = {}) {
+  try {
+    const root = realpathSync(cwd);
+    return readdirSync(registryDir).filter((entry) => entry.endsWith(".json")).some((entry) => {
+      try {
+        const claim = JSON.parse(readFileSync(join(registryDir, entry), "utf8"));
+        const rel = typeof claim.stack_dir === "string" ? relative(root, claim.stack_dir) : "..";
+        return claim.lease_id === leaseId && claim.host === hostname() && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+      } catch { return false; }
+    });
+  } catch { return false; }
+}
+
+function claimInventory(registryDir) {
+  return readdirSync(registryDir).filter((name) => name.endsWith(".json")).map((name) => {
+    // Allocation counts every JSON claim. Never report absence after overlooking
+    // a retained record under an unexpected name.
+    if (!/^\d+\.json$/.test(name)) throw new Error("claim inventory contains an invalid file name");
+    const path = join(registryDir, name);
+    const claim = JSON.parse(readFileSync(path, "utf8"));
+    if (!claim || typeof claim !== "object" || !Number.isInteger(claim.port_base) || name !== `${claim.port_base}.json`) throw new Error("claim inventory is invalid");
+    return { path, claim };
+  });
+}
+
+/** Exact lease-bound metadata remains usable when its old stack directory is gone. */
+export function leasedClaimContext(stackPath, leaseId, { cwd = process.cwd(), registryDir = defaultPortRegistryDir() } = {}) {
+  try {
+    const root = realpathSync(cwd);
+    const claims = claimInventory(registryDir).filter(({ claim }) => {
+      if (claim.lease_id !== leaseId || claim.host !== hostname() || typeof claim.stack_dir !== "string" || !isAbsolute(claim.stack_dir)) return false;
+      const rel = relative(root, claim.stack_dir);
+      return rel === stackPath && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+    });
+    const first = claims[0]?.claim;
+    return first && typeof first.project_id === "string" && /^[A-Za-z0-9_-]+$/.test(first.project_id) &&
+      claims.every(({ claim }) => claim.project_id === first.project_id && claim.stack_dir === first.stack_dir)
+      ? { project: first.project_id, stackDir: first.stack_dir } : null;
+  } catch { return null; }
+}
+
+/** Bind an admitted lease to its exact invocation while the caller holds the project lock. */
+export function bindLeasedStackClaim(stackDir, leaseId, { registryDir = defaultPortRegistryDir(), invocationToken = null } = {}) {
+  const marker = readStackMarker(stackDir, readFileSync);
+  const token = invocationToken ?? marker?.invocation_token;
+  if (!token || !leaseId) throw new Error("local port claim has no invocation identity");
+  return mutateBoundClaims(stackDir, registryDir, (claims) => {
+    if (claims.some(({ claim }) => claim.invocation_token !== token)) throw new Error("local port claim was replaced");
+    for (const { path, claim } of claims) atomicWrite(path, JSON.stringify({ ...claim, lease_id: leaseId }), { write: writeFileSync, rename: renameSync });
+    // An authorized adoption (reservePortBlocks re-taking this project's idle reservation
+    // under a fresh invocation, Codex #1248 P2) leaves an older invocation's marker behind.
+    // The verified claims and both locks prove this invocation now owns the directory, so the
+    // marker follows them; a marker for another project or directory is never rewritten.
+    const project = claims[0]?.claim.project_id;
+    const adoptable = marker && (marker.invocation_token === token ||
+      ((marker.project_id == null || marker.project_id === project) && (marker.stack_dir == null || marker.stack_dir === stackDir)));
+    if (adoptable) atomicWrite(join(stackDir, LEASED_STACK_MARKER), JSON.stringify({ ...marker, invocation_token: token, lease_id: leaseId }), { write: writeFileSync, rename: renameSync });
+  });
+}
+
+/** Allocation and recovery serialize the inspect/delete against replacement claims. */
+function mutateBoundClaims(stackDir, registryDir, mutate) {
+  const config = readFileSync(join(stackDir, "supabase/config.toml"), "utf8");
+  const project = projectIdFromConfig(config);
+  const blocks = blocksForPorts([...portMapInConfig(config).values()]);
+  if (!project || !/^[A-Za-z0-9_-]+$/.test(project) || !blocks.length) throw new Error("local stack port identity is unavailable");
+  return withAllocationLock(registryDir, {
+    writeExclusive: (path, data) => writeFileSync(path, data, { flag: "wx" }), read: readFileSync,
+    remove: rmSync, now: Date.now, alive: pidIsAlive, host: hostname,
+  }, () => {
+    const claims = blocks.map((block) => {
+      const path = portClaimPath(registryDir, block);
+      const claim = JSON.parse(readFileSync(path, "utf8"));
+      if (claim.stack_dir !== stackDir || claim.project_id !== project || claim.host !== hostname() || claim.port_base !== block) {
+        throw new Error("local port claim identity does not match this stack");
+      }
+      return { path, claim };
+    });
+    return mutate(claims);
+  });
+}
+
+/** Physical proof alone cannot release a newer invocation's port reservation.
+ * The command also holds the project lock; legacy claims without a lease binding stay retained.
+ * This never deletes a container, volume, stack directory or another invocation's claim. */
+export function recoverLeasedStackClaim(stackDir, leaseId, proof, { registryDir = defaultPortRegistryDir() } = {}) {
+  if (proof?.lease_id !== leaseId || proof.state !== "reaped" || proof.cleanup_verified !== true ||
+      !["signed_reap", "never_provisioned", "local_exec_teardown", "pre_driver_absence"].includes(proof.cleanup_proof) ||
+      (proof.cleanup_proof === "signed_reap" && !proof.cleanup_receipt_id)) {
+    return { released: false, reason: "accepted cleanup proof is unavailable" };
+  }
+  try {
+    return withAllocationLock(registryDir, {
+      writeExclusive: (path, data) => writeFileSync(path, data, { flag: "wx" }), read: readFileSync,
+      remove: rmSync, now: Date.now, alive: pidIsAlive, host: hostname,
+    }, () => {
+      const claims = claimInventory(registryDir).filter(({ claim }) => claim.stack_dir === stackDir);
+      if (!claims.length) return { released: true, reason: "no local claim remains for this stack" };
+      const token = claims[0].claim.invocation_token;
+      const project = claims[0].claim.project_id;
+      if (typeof token !== "string" || !token || typeof project !== "string" || !/^[A-Za-z0-9_-]+$/.test(project) || claims.some(({ claim }) =>
+        claim.lease_id !== leaseId || claim.invocation_token !== token || claim.project_id !== project || claim.host !== hostname() ||
+        !Number.isInteger(claim.owner_pid) || claim.owner_pid <= 0 || pidIsAlive(claim.owner_pid))) {
+        return { released: false, reason: "local claim is live, replaced, or lacks this lease binding" };
+      }
+      // Strict read: only a genuinely absent marker (a prepared stack) skips the identity
+      // fence; an unreadable or corrupt one cannot verify the invocation, so keep the claim.
+      let marker = null;
+      try {
+        const raw = readFileSync(join(stackDir, LEASED_STACK_MARKER), "utf8");
+        marker = JSON.parse(raw);
+        if (!marker || typeof marker !== "object") throw new Error("invalid marker");
+      } catch (error) {
+        if (error?.code !== "ENOENT") return { released: false, reason: "stack marker is unreadable or corrupt; local claim retained" };
+        marker = null;
+      }
+      if (marker && (marker.invocation_token !== token || marker.lease_id !== leaseId || marker.project_id !== project)) {
+        return { released: false, reason: "stack marker was replaced" };
+      }
+      for (const { path } of claims) rmSync(path);
+      if (claims.some(({ path }) => existsSync(path))) return { released: false, reason: "local claim removal was not verified" };
+      if (marker) markLeasedStackReleased(stackDir);
+      return { released: true, cleanup_proof: proof.cleanup_proof, cleanup_receipt_id: proof.cleanup_receipt_id ?? null };
+    });
+  } catch (error) {
+    return { released: false, reason: `local claim retained: ${error.code ?? error.message}` };
+  }
+}
+
 /** The host-scoped reservation file for a block. */
 function portClaimPath(registryDir, portBase) {
   return join(registryDir, `${portBase}.json`);

package/src/stack-run-outcome.mjs

@@ -49,8 +49,8 @@ function boundedCode(value) {
 }
 
 /**
- * Classify one `bb stack run` terminal from its receipt fields (`runReceiptFields`
- * output, or the argument-error receipt) and its exit code. Pure.
+ * Classify one `bb stack run` terminal from its internal outcome fields
+ * (`stackRunOutcomeFields`, or the argument-error receipt) and exit code. Pure.
  *
  *   script      — the lease was active and the child's exit decided the result
  *                 (`--hard-ttl` stop → code HARD_TTL)
@@ -64,7 +64,9 @@ export function classifyStackRunOutcome(fields = {}, exitCode) {
   const outcome = typeof fields.outcome === "string" ? fields.outcome : null;
   if (outcome === "interrupted") return { category: "interrupted", code };
   if (code && PLATFORM_CODES.has(code)) return { category: "platform", code };
-  if (fields.fenced === true) return { category: "platform", code: code ?? "LEASE_LOST" };
+  // The stdout fence also covers unresolved cleanup. The lifecycle supplies its
+  // original lease-fence fact separately so coincident child exits cannot hide it.
+  if ((fields.lease_fenced ?? fields.fenced) === true) return { category: "platform", code: code ?? "LEASE_LOST" };
   if (outcome === "completed" && exitCode === 0) return { category: "script", code: null };
   if (outcome === "failed" && code == null && child != null) {
     if (SIGNAL_EXITS.has(exitCode)) return { category: "interrupted", code: null };

package/src/stack.mjs

@@ -43,7 +43,7 @@ import { AGENT_KEY_RE, readAgentSessionTokenEnv } from "./agent-key.mjs";
 import { resolveAgentSessionCredential, selfHealAgentSession } from "./agent-session.mjs";
 import { runDockerCommand, runDockerWorkflow, ADMITTED_DOCKER_VALIDATIONS } from "./docker-hygiene.mjs";
 import { acquireStackLock, lockPathForProject, projectIdFromConfig } from "./stack-file-lock.mjs";
-import { LEASED_STACK_IDLE_RETENTION_SECS, assertLeasedStackIsolated, leasedStackClaimHeld, markLeasedStackReleased, stableRunStackReusable, leasedStackIdentity, materializeRunStackDir, portMapInConfig, refreshLeasedStackRetention, releaseLeasedStackClaim, reservePortBlocks } from "./stack-isolation.mjs";
+import { LEASED_STACK_IDLE_RETENTION_SECS, bindLeasedStackClaim, recoverLeasedStackClaim, hasLocalLeaseClaim, leasedClaimContext, assertLeasedStackIsolated, leasedStackClaimHeld, markLeasedStackReleased, stableRunStackReusable, leasedStackIdentity, materializeRunStackDir, portMapInConfig, refreshLeasedStackRetention, releaseLeasedStackClaim, reservePortBlocks } from "./stack-isolation.mjs";
 import { measureStackUsage } from "./stack-usage.mjs";
 import { checkReadoptedStackMounts } from "./stack-mount-health.mjs";
 import { machineUuid } from "./machine-id.mjs";
@@ -173,6 +173,8 @@ ${bold("done OPTIONS")}
                          capacity stays held, so the next \`stack run\`/\`stack up\` on this slot re-adopts
                          it without provisioning. Receipt outcome "idle" + idle_since, idle_reason.
                          A queued/provisioning/reaping/reaped lease is released exactly as --reap.
+  --release-port-claim   With done --reap: explicitly reconcile a retained local port claim
+                         after accepted cleanup; unknown, live and replaced claims stay retained.
   --reap                 Release eagerly: reap (tear down) the stack now, as before BOT-1803.
   --stop                 With --reap: keep volumes (cheap re-provision next batch). Default: destroy.
   --local-exec           FALLBACK (no Helper): run 'supabase stop' locally and self-finalize.
@@ -488,6 +490,7 @@ export function parseStackArgs(argv) {
       case "--docker-endpoint": if (need(a, rest[i + 1])) opts.dockerEndpoint = rest[++i]; break;
       case "--stop": opts.disposition = "stop"; break;
       case "--reap": opts.reap = true; break;
+      case "--release-port-claim": opts.releasePortClaim = true; break;
       case "--destroy": opts.disposition = "destroy"; break;
       case "--json": opts.json = true; break;
       default:
@@ -537,6 +540,7 @@ export function parseStackArgs(argv) {
       "worktree root's default (shared canonical) project. Point --stack-path at a slot-derived stack directory with its " +
       "own supabase/config.toml (distinct project_id + remapped ports).");
   }
+  if (opts.releasePortClaim && (command !== "done" || !opts.reap || opts.localExec)) errors.push("--release-port-claim requires `stack done --reap` without --local-exec");
   if (opts.reap && !["done", "run"].includes(command)) {
     errors.push("--reap is valid only with `stack done` or `stack run`");
   }
@@ -728,6 +732,10 @@ export function truncateReceipt(receipt, maxBytes = DEFAULT_RECEIPT_MAX_BYTES) {
     schema_version: r.schema_version, command: r.command, outcome: r.outcome,
     lease_id: r.lease_id ?? null, state: r.state ?? null, exit_code: r.exit_code,
     error: r.error ?? null, truncated: true,
+    ...(r.cleanup !== undefined ? { cleanup: r.cleanup } : {}),
+    ...(r.fenced !== undefined ? { fenced: r.fenced } : {}),
+    ...(r.cleanup_code ? { cleanup_code: r.cleanup_code } : {}),
+    ...(r.cleanup_error ? { cleanup_error: String(r.cleanup_error).slice(0, 160) } : {}),
   };
 }
 
@@ -840,6 +848,7 @@ export async function resolveRunExecution(cwd, opts, { materialize = materialize
       // A prepared directory carries no retention marker, so its reservation is
       // renewed here on the batch's own beat (Codex #928 R21 P2).
       renew: (options) => ports.renew(options),
+      bindLease: (leaseId) => ports.bindLease(leaseId),
       // BOT-2237: returns the VERIFIED disposition the receipt reports.
       release: ({ reaped = false } = {}) => {
         let released = false;
@@ -867,6 +876,7 @@ export async function resolveRunExecution(cwd, opts, { materialize = materialize
     )));
     return {
       ...execution,
+      bindLease: (leaseId) => bindLeasedStackClaim(stackDirFor(execution), leaseId, portRegistryDir ? { registryDir: portRegistryDir } : undefined),
       // Release is called once the batch's signed reap is done, so hand the host
       // its port block back immediately rather than holding it for the retention
       // window this batch no longer needs (Codex #928 R19 P2).
@@ -1156,6 +1166,11 @@ export const REMOTE_REFUSAL_GUIDANCE = Object.freeze({
 
 /** The refusal text for a receipt: the server's message, else the CLI's guidance, else the code. */
 export function leaseRefusalError(data) {
+  if (data?.lease_id && ["STACK_CONTEXT_BIND_FAILED", "STACK_CONTEXT_ALREADY_BOUND"].includes(data?.code)) {
+    return `${data.message || data.code}; lease ${data.lease_id} is ${data.state ?? "unknown"}. ` +
+      `Inspect with \`bb stack status ${data.lease_id}\`; after the owning batch ends, release with \`bb stack done ${data.lease_id} --reap\`, ` +
+      `then wait with \`bb wait 'lease:id=${data.lease_id},state=reaped' --heartbeat\`.`;
+  }
   return data?.message || REMOTE_REFUSAL_GUIDANCE[data?.code] || data?.code || "lease request refused";
 }
 
@@ -1447,7 +1462,7 @@ export async function waitForLease(leaseId, isDone, isFailed, { timeoutSec, auth
           decided = { reason: "failed", result: { failed: true, state: st, ...(reapReason ? { reap_reason: reapReason } : {}) }, status: "error" };
           break frameLoop;
         }
-        if (isDone(st, sig.payload)) { decided = { reason: "matched", result: { woke: true, state: st }, status: "matched" }; break frameLoop; }
+        if (isDone(st, sig.payload)) { decided = { reason: "matched", result: { woke: true, state: st, ...(sig.payload?.cleanup_verified === true ? { cleanupEvidence: sig.payload } : {}) }, status: "matched" }; break frameLoop; }
       }
     }
   } catch (err) {
@@ -3002,6 +3017,9 @@ export async function cmdDone(leaseId, opts, {
   localTeardownFn = localTeardown,
   emitResult = emit,
   refreshAuth = refreshRejectedCacheAuth,
+  waitFn = waitForLease,
+  recoverClaim = recoverLocalLeaseClaim,
+  localClaimExists = hasLocalLeaseClaim,
 } = {}) {
   // BOT-1750 (Codex R10 P2): `done` must recover a server-rejected cached session on
   // its own — otherwise an active lease can't be released until the cache is manually
@@ -3234,10 +3252,65 @@ export async function cmdDone(leaseId, opts, {
         (retry.budget_reset === true ? " and the reap retry budget was reset" : ""),
     }
     : {};
-  return emitResult(buildReceipt({ command: "done", outcome: "released", lease_id: leaseId, state, disposition,
+  let portBlock = null;
+  if (opts.releasePortClaim || (opts.reap && !opts.localExec && localClaimExists(leaseId))) {
+    try {
+      const current = await call("get_stack_lease", { lease_id: leaseId });
+      if (!current.ok || !current.data?.success) {
+        portBlock = { released: false, reason: "owned lease context could not be read" };
+      } else {
+        const verified = await waitFn(leaseId,
+          (s, p) => s === "reaped" && p?.cleanup_verified === true,
+          // BOT-1948: an accepted failed reap, or a reaped snapshot the server marks as never
+          // provable (cleanup_verified strictly false), ends at once; a raw frame keeps waiting.
+          (s, p) => (s === "reap_failed" && p?.cleanup_verified === true) || (s === "reaped" && p?.cleanup_verified === false),
+          { timeoutSec: opts.reapTimeout ?? 300, auth: rpc.auth });
+        if (verified.woke && verified.cleanupEvidence) {
+          state = "reaped";
+          portBlock = await recoverClaim({ ...current.data, lease_id: leaseId }, verified.cleanupEvidence);
+        } else portBlock = { released: false, reason: "accepted cleanup proof is unavailable; local claim retained" };
+      }
+    } catch (error) {
+      portBlock = { released: false, reason: `local claim retained: ${error.code ?? error.message}` };
+    }
+  }
+  return emitResult(buildReceipt({ command: "done", outcome: portBlock?.released === false ? "error" : "released", lease_id: leaseId, state, disposition,
     ...retried,
+    ...(portBlock ? { port_block: portBlock } : {}),
     ...(helperTeardown ? { teardown: "helper" } : {}),
-    ...(legacyTargetProof ? { legacy_target_proof: legacyTargetProof } : {}) }), opts, EXIT.OK);
+    ...(legacyTargetProof ? { legacy_target_proof: legacyTargetProof } : {}) }), opts, portBlock?.released === false ? EXIT.CLEANUP_FAILED : EXIT.OK);
+}
+
+/** Recover only in the original worktree, with its project lock and an exact lease-bound claim. */
+export async function recoverLocalLeaseClaim(lease, proof, { cwd = process.cwd(), recover = recoverLeasedStackClaim, lock = acquireStackLock, claimContext = leasedClaimContext } = {}) {
+  let held;
+  try {
+    const root = realpathSync(cwd);
+    const path = lease.stack_path;
+    if (!lease.worktree_root || root !== realpathSync(lease.worktree_root) || typeof path !== "string" || !path || path === "." || isAbsolute(path) || path.split(/[\\/]/).includes("..")) {
+      return { released: false, reason: "run recovery from the lease's original worktree with its isolated path" };
+    }
+    const context = claimContext(path, lease.lease_id, { cwd });
+    let stackDir, project;
+    try {
+      stackDir = stackDirFor(resolveStackPath(cwd, path));
+      project = projectIdUnder(stackDir);
+    } catch (error) {
+      // No path is reconstructed from remote input. A removed directory needs
+      // an exact local lease/host/path binding; unknown or legacy claims stay kept.
+      if (error.code !== "ENOENT" || !context) throw error;
+      stackDir = context.stackDir;
+      project = context.project;
+    }
+    if (typeof project !== "string" || !/^[A-Za-z0-9_-]+$/.test(project) ||
+        (context && (project !== context.project || stackDir !== context.stackDir))) {
+      return { released: false, reason: "local stack project identity is unavailable or invalid" };
+    }
+    held = await lock(lockPathForProject(project), { timeoutMs: 0 });
+    return recover(stackDir, lease.lease_id, proof);
+  } catch (error) {
+    return { released: false, reason: `local claim retained: ${error.code ?? error.message}` };
+  } finally { held?.release(); }
 }
 
 const SIGNAL_EXIT = Object.freeze({ SIGINT: 130, SIGTERM: 143, SIGHUP: 129 });
@@ -3452,9 +3525,11 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   // BOT-2099: a best-effort diagnostic read (ledger, persisted Helper reason) never throws.
   const readLeaseQuietly = async (id) => { try { return await api.get?.(id) ?? null; } catch { return null; } };
   // BOT-2237: the typed end of a park that cannot re-authenticate — names the lease, never a
-  // capacity timeout. Exit AUTH: the caller's credential, not the lease, is what failed.
+  // capacity timeout. Keep AUTH after confirmed cleanup; unproven cleanup takes
+  // CLEANUP_FAILED while preserving the primary credential diagnostic.
   const authUnavailableResult = (waited, phase, cleanup, waitedLeaseId = leaseId) => ({
-    exitCode: EXIT.AUTH, outcome: "error", code: PARK_INCIDENT_REASONS.AUTH, leaseId: waitedLeaseId ?? null, cleanup,
+    exitCode: cleanup?.ok === false ? EXIT.CLEANUP_FAILED : EXIT.AUTH,
+    outcome: "error", code: PARK_INCIDENT_REASONS.AUTH, leaseId: waitedLeaseId ?? null, cleanup,
     error: `${waited.error} while the lease was ${phase}; its server state is unknown to this run — inspect it with \`bb stack status ${waitedLeaseId}\` after \`bb doctor --fix\``,
     ...(parkIncident ? { incident: parkIncident } : {}),
   });
@@ -3595,7 +3670,9 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     // state — instead of leaving this wait to park until --reap-timeout on a reap
     // that already failed. Report that specific outcome instead of the generic
     // "was not proven" timeout message.
-    // BOT-2099 (Codex #1057 R6): the signed-reap wait survives auth/availability blips too.
+    // Cleanup owns one immutable deadline. Its signed reap wait may recover from a
+    // transient relay/auth blip, but never repeats the release request. A persistent
+    // failure remains explicit receipt data below; it never fabricates a reap.
     const reaped = await resilientWait(leaseId, (state) => state === "reaped", (state) => state === "reap_failed", { timeoutSec: opts.reapTimeout, auth: rpc.auth });
     if (reaped?.woke || reaped?.state === "reaped") return cleanupResult = { ok: true, state: "reaped" };
     if (reaped?.failed) return cleanupResult = { ok: false, error: "the signed reap failed and the lease may still hold containers (fenced) — see stack hygiene" };
@@ -3612,12 +3689,21 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     if (recheck?.ok && recheck.data?.success && recheck.data.state === "reaped") return cleanupResult = { ok: true, state: "reaped" };
     const postCheck = durableReapFailure(recheck);
     if (postCheck) return cleanupResult = postCheck;
-    return cleanupResult = { ok: false, error: reaped?.timeout ? `signed reap did not arrive within ${opts.reapTimeout}s` : (reaped?.error || "signed reap was not proven") };
+    const persistentWaitFailure = reaped?.incident && reaped.incident.recovered === false
+      ? reaped.incident.last_error
+      : null;
+    return cleanupResult = {
+      ok: false,
+      error: persistentWaitFailure ?? (reaped?.timeout ? `signed reap did not arrive within ${opts.reapTimeout}s` : (reaped?.error || "signed reap was not proven")),
+    };
     })().catch((error) => {
-      // BOT-2237: a release/read whose session renewal THROWS (e.g. `session_mint_invalid`
-      // once the cache names another agent) is a failed cleanup of THIS lease — never an
-      // exception that escapes the lifecycle and loses the lease id from the receipt.
-      return cleanupResult = { ok: false, error: `cleanup could not run: ${error?.code ? `${error.code}: ` : ""}${error?.message ?? error}` };
+      // A release/read whose session renewal throws is a failed cleanup of THIS lease —
+      // never an exception that escapes the lifecycle and loses its recovery receipt.
+      return cleanupResult = {
+        ok: false,
+        code: error?.code ?? null,
+        error: String(error?.message ?? error),
+      };
     });
     return cleanupPromise;
   };
@@ -3906,11 +3992,14 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         ?? stackPathRootRefusalNotice(request.data?.code, request.data?.message)
         ?? remoteRefusalNotice(request.data?.code);
       if (hint) stderrLine(hint);
-      // BOT-1803: the slot's idle lease stays idle (another mode/host); keep its block.
-      if (request.data?.code === "STACK_EXECUTION_MODE_MISMATCH" && request.data?.lease_id) retainBlock = true;
+      // A refusal naming an admitted lease (including a failed context bind or
+      // an idle mode mismatch) is not proof that its ports are free. Keep the
+      // claim until owner-safe cleanup is verified; never reap a possibly live batch.
+      if (request.data?.lease_id) retainBlock = true;
       return {
         exitCode: leaseRefusalExit(request.data?.code), outcome: "error", code: request.data?.code,
         ...capacityStaleReceiptFields(request.data), error: leaseRefusalError(request.data),
+        ...(request.data.lease_id ? { leaseId: request.data.lease_id, state: request.data.state ?? null } : {}),
       };
     }
     leaseId = request.data.lease_id;
@@ -3934,10 +4023,16 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       // With a stable identity a live lease in THIS stack directory is bound to our block.
       if (request.data.stack_path != null && request.data.stack_path === execution.stackPath &&
           (request.data.worktree_root == null || request.data.worktree_root === execution.worktreeRoot)) retainBlock = true;
-      return { exitCode: EXIT.BACKEND, outcome: "error", leaseId, error: "a live lease already exists for this agent and stack slot; wait for that batch to finish instead of sharing its stack" };
+      const blockedState = request.data.state ?? "unknown";
+      const recovery = blockedState === "reaping"
+        ? `wait with \`bb wait 'lease:id=${leaseId},state=reaped' --heartbeat\``
+        : `inspect with \`bb stack status ${leaseId}\`; after the owning batch ends, release with \`bb stack done ${leaseId} --reap\`, then wait with \`bb wait 'lease:id=${leaseId},state=reaped' --heartbeat\``;
+      return { exitCode: EXIT.BACKEND, outcome: "error", leaseId, state: blockedState,
+        error: `live lease already exists for this agent and stack slot: ${leaseId} is ${blockedState}; ${recovery}` };
     }
 
     leaseProvisioned = true; // from here a Helper may act on this lease
+    execution.bindLease?.(leaseId);
     let state = request.data.state;
     if (reusedIdle) {
       idleLease.reused = "idle";
@@ -4112,7 +4207,13 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         };
       }
       if (parked?.failed) { const cleanup = await requestCleanup(); return { exitCode: EXIT.LEASE_FAILED, outcome: "error", leaseId, error: `lease was ${parked.state} while queued (reap_reason=${parked.reap_reason ?? "unknown"})`, cleanup, ...incident }; }
-      if (parked?.error || parked?.auth) { const cleanup = await requestCleanup(); return { exitCode: parked?.auth ? EXIT.AUTH : EXIT.LEASE_FAILED, outcome: "error", leaseId, error: parked?.error || "lease did not leave queue", cleanup, ...incident }; }
+      if (parked?.error || parked?.auth) {
+        const cleanup = await requestCleanup();
+        return {
+          exitCode: parked?.auth && cleanup?.ok === false ? EXIT.CLEANUP_FAILED : (parked?.auth ? EXIT.AUTH : EXIT.LEASE_FAILED),
+          outcome: "error", leaseId, error: parked?.error || "lease did not leave queue", cleanup, ...incident,
+        };
+      }
       state = parked.state;
     }
     if (state !== "active") {
@@ -4143,7 +4244,10 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         // BOT-1816's class of dropped wakes) even though the lease genuinely went
         // active or was deferred back to queued. One direct read before declaring
         // a timeout avoids reaping a healthy stack or destroying a kept queue place.
-        const recheck = await api.get(leaseId);
+        // Production adapters always expose `get`. Focused lifecycle adapters may
+        // intentionally model only admission and release; preserve their original
+        // terminal cleanup receipt rather than replacing it with a test-only TypeError.
+        const recheck = api.get ? await api.get(leaseId) : null;
         if (recheck?.ok && recheck.data?.success && recheck.data.state === "queued") {
           parkView = recheck.data;
           const why = parkView.provision_defer_reason ?? "host capacity";
@@ -4153,9 +4257,16 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         }
         if (!(recheck?.ok && recheck.data?.success && recheck.data.state === "active")) {
           const cleanup = await requestCleanup();
-          // BOT-2467: `timeoutPhase` is for the outcome record only (never on the receipt):
-          // an admitted lease whose stack never started is not a capacity shortage.
-          return { exitCode: EXIT.TIMEOUT, outcome: "timeout", timeoutPhase: "provision", leaseId, error: `physical provision did not reach active in ${provisionTimeout}s`, cleanup, ...(parkIncident ? { incident: parkIncident } : {}) };
+          const cleanupFailed = cleanup?.ok === false;
+          return {
+            exitCode: cleanupFailed ? EXIT.CLEANUP_FAILED : EXIT.TIMEOUT,
+            outcome: "timeout", timeoutPhase: "provision", leaseId,
+            // An unproven cleanup is more actionable than the generic timeout for an
+            // admitted lease, because recovery must preserve its fenced claim.
+            error: cleanupFailed ? cleanup.error : `physical provision did not reach active in ${provisionTimeout}s`,
+            cleanup, ...(parkIncident ? { incident: parkIncident } : {}),
+          };
+
         }
       }
       if (active?.failed || active?.error || active?.auth) {
@@ -4167,7 +4278,11 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
           if (read?.ok && read.data?.success && typeof read.data.error === "string" && read.data.error) why = ` — ${read.data.error}`;
         }
         const cleanup = await requestCleanup();
-        return { exitCode: active?.auth ? EXIT.AUTH : EXIT.LEASE_FAILED, outcome: "error", leaseId, error: active?.error || `lease ${active?.state ?? "failed"} before reaching active${why}`, cleanup, ...(parkIncident ? { incident: parkIncident } : {}) };
+        return {
+          exitCode: cleanup?.ok === false ? EXIT.CLEANUP_FAILED : (active?.auth ? EXIT.AUTH : EXIT.LEASE_FAILED),
+          outcome: "error", leaseId, state: active?.state ?? null, error: active?.error || `lease ${active?.state ?? "failed"} before reaching active${why}`, cleanup,
+          ...(parkIncident ? { incident: parkIncident } : {}),
+        };
       }
     }
     break;
@@ -4358,7 +4473,7 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
           ? `a lease on this stack slot may still hold its ports (idle, unreaped, or another live batch)${retained} so its stack is never double-booked`
           // BOT-2418: an idle release is a deliberate keep (BOT-1803), not an unproven reap.
           : cleanupResult?.ok === true && cleanupResult.idle === true
-            ? `the lease is idle and keeps its stack for the next run on this slot, so its claim stays reserved with it (\`bb stack done ${leaseId} --reap\` reaps the lease; it does not release this host's claim)`
+            ? `the lease is idle and keeps its stack for the next run on this slot, so its claim stays reserved with it (\`bb stack done ${leaseId} --reap\` reaps the lease and releases its exact lease-bound local claim after accepted cleanup)`
             : `reap not proven (${cleanupResult?.error ?? "no cleanup ran"})${retained} so a stack the Helper may still run is never double-booked` }
         : releaseError || disposition?.released === false
           ? { released: false, reason: `the reap was proven but the claim could not be removed (${releaseError?.message ?? "it is still on disk"})${retained}` }
@@ -4374,6 +4489,7 @@ export function runReceiptFields(result) {
     // BOT-1797: carry the server's typed refusal code (e.g. stack_path_root_refused)
     // so automation can branch on it instead of matching the message text.
     command: "run", outcome: result.outcome, code: result.code ?? null, lease_id: result.leaseId ?? null,
+    ...(result.state ? { state: result.state } : {}),
     // BOT-2468: the lease's /docker?lease= deeplink (null when the server sent none).
     web_url: result.webUrl ?? null,
     // BOT-2024: a stale-capacity refusal carries its phase + armable wait on the receipt.
@@ -4382,6 +4498,13 @@ export function runReceiptFields(result) {
     child_exit_code: result.childExitCode ?? null,
     // BOT-1803: an idle release is `cleanup: { idle: true, idle_since }` (nothing was reaped).
     cleanup: result.cleanup?.idle ? { idle: true, idle_since: result.cleanup.idle_since ?? null } : result.cleanup?.ok ?? null,
+    cleanup_code: result.cleanup?.code ?? null,
+    cleanup_error: result.cleanup?.ok === false ? result.cleanup.error ?? "cleanup was not proven" : null,
+    ...(result.leaseId && result.cleanup?.ok === false ? { recovery: {
+      status: `bb stack status ${result.leaseId}`,
+      wait: `bb wait 'lease:id=${result.leaseId},state=reaped' --heartbeat`,
+      release: `bb stack done ${result.leaseId} --reap`,
+    } } : {}),
     ...(result.volumesKept ? { volumes_kept: true } : {}),
     ...(result.idleLease?.reused ? { reused: result.idleLease.reused } : {}),
     ...(result.idleLease?.reprovisioned ? { reprovisioned: result.idleLease.reprovisioned } : {}),
@@ -4401,7 +4524,7 @@ export function runReceiptFields(result) {
     // BOT-2207: why it ran where it did (e.g. moved_remote_on_requeue) and every host weighed.
     ...(result.execution?.placementReason ? { placement_reason: result.execution.placementReason } : {}),
     ...(result.execution?.considered ? { considered: result.execution.considered } : {}),
-    fenced: result.fenced ?? false, error: result.error ?? result.cleanup?.error ?? null,
+    fenced: result.fenced === true || result.cleanup?.ok === false, error: result.error ?? result.cleanup?.error ?? null,
     // BOT-2099: a platform auth/availability blip during the park is reported as an
     // incident (reason, window, attempts, recovered) — never as the lease's outcome.
     ...(result.incident ? { platform_incident: result.incident } : {}),
@@ -4440,10 +4563,14 @@ export async function cmdRun(opts, childArgv, {
  */
 /**
  * BOT-2467: the fields the outcome classifier reads — the receipt's, plus facts the
- * receipt deliberately does not carry (which wait a timeout ended). Never emitted.
+ * receipt deliberately does not carry (which wait a timeout ended and the original
+ * lease fence). Never emitted.
  */
 export function stackRunOutcomeFields(result) {
-  return { ...runReceiptFields(result), ...(result?.timeoutPhase ? { timeout_phase: result.timeoutPhase } : {}) };
+  return {
+    ...runReceiptFields(result), lease_fenced: result?.fenced === true,
+    ...(result?.timeoutPhase ? { timeout_phase: result.timeoutPhase } : {}),
+  };
 }
 
 async function parseErrorOutcomeChannel(argv, { resolveCredential = resolveAgentSessionCredential, callTool = callToolJson } = {}) {

package/src/wait-core.mjs

@@ -35,6 +35,7 @@ export const EXIT = Object.freeze({
   // liveness reaper abandoned it, it was cancelled, or its row is gone. The relay
   // refuses the stream with a typed `wait_abandoned` error frame; re-arm from next_cursor.
   ABANDONED: 11,
+  LEASE_CLEANUP_FAILED: 12,
 });
 
 // BOT-2013: the uuid spellings Postgres accepts for a lease id (uuid_in), mirrored by the SQL
@@ -58,6 +59,7 @@ export function leaseLostDetail(signal, condition) {
     lease_id: signal.payload?.lease_id ?? condition.params?.id ?? null,
     lease_state: leaseState,
     reap_reason: typeof signal.payload?.reap_reason === "string" ? signal.payload.reap_reason : null,
+    ...(condition.params?.state === "active" && signal.payload?.error_class ? { error_class: signal.payload.error_class } : {}),
   };
 }
 
@@ -797,7 +799,15 @@ function compactLeaseLostState(state) {
   if (!state || typeof state !== "object") return null;
   const short = (v) => (typeof v === "string" ? v.slice(0, 64) : null);
   if (state.lease_id == null && state.reap_reason == null) return null;
-  return { lease_id: short(state.lease_id), lease_state: short(state.lease_state), reap_reason: short(state.reap_reason) };
+  return { lease_id: short(state.lease_id), lease_state: short(state.lease_state), reap_reason: short(state.reap_reason),
+    ...(state.cleanup_unverified === true ? { cleanup_unverified: true } : {}) };
+}
+
+function compactCleanupState(state) {
+  if (!state || !["signed_reap", "never_provisioned", "local_exec_teardown", "pre_driver_absence"].includes(state.cleanup_proof)) return null;
+  const short = (v) => typeof v === "string" ? v.slice(0, 64) : null;
+  return Object.fromEntries(["lease_id", "lease_state", "reap_disposition", "cleanup_proof", "cleanup_receipt_id"]
+    .filter((key) => state[key] != null).map((key) => [key, short(state[key])]));
 }
 
 /**
@@ -818,8 +828,9 @@ export function truncateReceipt(receipt, maxBytes = 10240) {
   // state is the whole point of that receipt (which lease, why) and is already three short
   // fields, so it is kept compact instead (BOT-2013, Codex #1017 P2).
   const leaseLostState = clone.outcome === "lease_lost" ? compactLeaseLostState(clone.state) : null;
+  const cleanupState = ["matched", "error"].includes(clone.outcome) ? compactCleanupState(clone.state) : null;
   if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes) {
-    clone.state = leaseLostState ?? { truncated: true };
+    clone.state = leaseLostState ?? cleanupState ?? { truncated: true };
   }
   // A matched signal's subject key can be caller-controlled through the raw
   // event escape hatch. Keep the durable sequence pointer, but not an
@@ -863,6 +874,19 @@ export function truncateReceipt(receipt, maxBytes = 10240) {
     delete clone.detail;
     clone.detail_truncated = true;
   }
+  if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && cleanupState) {
+    const base = {
+      schema_version: clone.schema_version, outcome: clone.outcome,
+      ...(clone.error ? { error: String(clone.error).slice(0, 48) } : {}),
+      state: cleanupState, truncated: true,
+    };
+    for (const key of ["client", "next_cursor", "wait_session_id"]) {
+      if (clone[key] == null) continue;
+      const candidate = { ...base, [key]: clone[key] };
+      if (Buffer.byteLength(JSON.stringify(candidate)) <= maxBytes) base[key] = clone[key];
+    }
+    return base;
+  }
   if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && clone.outcome === "lease_lost") {
     // BOT-2013: the bounded fallback keeps the lease-lost detail, then adds the resume
     // pointers only while they still fit.
@@ -1096,12 +1120,22 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
       // stack_lease frame for this lease id is ours to wake on.
       if (signal.signal_type !== "stack_lease" || signal.subject_key !== `lease:${params.id}`) return false;
       // BOT-2400: with `state=`, only that state matches — or a terminal loss on the way
-      // (reap_failed for a reap wait; any reap state while waiting for provisioning/active),
-      // which finalizeMatch reports as lease_lost. `reaping` en route to `reaped` keeps waiting.
+      // (any reap state while waiting for provisioning/active), which finalizeMatch reports
+      // as lease_lost. `reaping` en route to `reaped` keeps waiting.
       if (params.state != null) {
         const leaseState = signal.payload?.state;
+        if (params.state === "reaped") {
+          // BOT-1948: a raw `reaped` row is not cleanup proof. Only the server's verified
+          // evidence (an accepted signed reap receipt, or a verified never-provisioned no-op)
+          // ends the reap wait as matched/cleanup-failed. An unverified reap_failed is still
+          // terminal (BOT-2400 Codex #1194 P1) and ends lease_lost without claiming cleanup.
+          if (signal.payload?.cleanup_verified === true) return leaseState === "reaped" || leaseState === "reap_failed";
+          // The server marks a reaped registration snapshot it can never prove as
+          // explicitly unverified (strictly false; an absent field keeps waiting).
+          if (signal.payload?.cleanup_verified === false && leaseState === "reaped") return true;
+          return leaseState === "reap_failed";
+        }
         if (leaseState === params.state) return true;
-        if (params.state === "reaped") return leaseState === "reap_failed";
         return LEASE_LOST_STATES.has(leaseState);
       }
       return true;
@@ -1564,6 +1598,25 @@ export async function runWaitLoop({
   // provisioning against a dead lease.
   const finalizeMatch = async (entry, signal) => {
     const condition = conditions.find((c) => c.id === entry.condition_id);
+    if (condition?.type === "lease" && condition.params.state === "reaped" && signal.payload?.cleanup_verified === true) {
+      const p = signal.payload;
+      const failed = p.state === "reap_failed";
+      return finalize(failed ? "error" : "matched", {
+        exitCode: failed ? EXIT.LEASE_CLEANUP_FAILED : EXIT.MATCHED, matched: [entry],
+        state: { lease_id: condition.params.id, lease_state: p.state,
+          reap_disposition: p.reap_disposition ?? null, cleanup_proof: p.cleanup_proof ?? null,
+          cleanup_receipt_id: p.cleanup_receipt_id ?? null },
+        error: failed ? "lease_cleanup_failed" : null,
+      });
+    }
+    if (condition?.type === "lease" && condition.params.state === "reaped" && signal.payload?.cleanup_verified === false) {
+      const p = signal.payload;
+      return finalize("lease_lost", {
+        exitCode: EXIT.LEASE_LOST, matched: [entry], error: "lease_lost",
+        state: { lease_id: p.lease_id ?? condition.params.id, lease_state: p.state ?? null,
+          reap_reason: typeof p.reap_reason === "string" ? p.reap_reason : null, cleanup_unverified: true },
+      });
+    }
     const lost = leaseLostDetail(signal, condition);
     if (lost) {
       return finalize("lease_lost", { exitCode: EXIT.LEASE_LOST, matched: [entry], state: lost, error: "lease_lost" });

package/src/wait.mjs

@@ -108,9 +108,14 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       \`botbuddy stack up\` (recipient-scoped to the owner).
                                       Level-triggered: an already-granted lease wakes at once.
   lease:id=<lease_id>,state=<s>       BOT-2400: wait for that exact state (provisioning, active,
-                                      reaped). state=reaped is the reap wait: an already-reaped
-                                      lease matches at once and a reaping one keeps waiting
-                                      (only reap_failed ends it, exit 9).
+                                      reaped). provisioning/active end on lease loss (exit 9,
+                                      with the provisioning failure's reason and class).
+  lease:id=<lease_id>,state=reaped    proven cleanup of that owned lease (BOT-1948). Requires an
+                                      accepted successful reap receipt or a verified
+                                      never-provisioned no-op; preserves stop/destroy
+                                      disposition. An already-cleaned lease matches at once;
+                                      reaping keeps waiting. A verified failed reap exits 12;
+                                      an unverified gave-up reap exits 9 (lease_lost).
   guidance:request=<post_id>          a command-post guidance request being answered
                                       (scoped to the asking agent; fetch the body with
                                       get_guidance_response)
@@ -200,7 +205,8 @@ OUTPUT
                 · 11 abandoned (the server ended this wait while it
                 was parked — reaped after 180 s without a live stream,
                 or cancelled; receipt outcome abandoned +
-                state.status/reason — re-arm with --since <next_cursor>).
+                state.status/reason — re-arm with --since <next_cursor>)
+                · 12 named lease cleanup failed.
                 If the receipt has
                 reacquire_lock (claim=true), acquire_lock again FIRST and re-run
                 only on a queued/busy result (granted = you hold it — just resume);