@botbuddy/cli 1.60.2 → 1.60.4

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.60.2",
-  "source_commit": "6c687a8220e66196ede9b560405ff1493d0752f0",
-  "source_sha256": "2bb86426999a110ead51a17d7ab60b5cc816901b9cbd3c4426b6d02e75ab6288",
+  "release_version": "1.60.4",
+  "source_commit": "06faf46d8438c66ae116ce47eb5f343dfaca0c73",
+  "source_sha256": "9c1d721c1f0cfe90208bbc0960675053901326b324c7014c730769247d9d8c1c",
   "target": "darwin-arm64",
-  "sha256": "5a197ab76ecd57a479f26d364ad06b1f226a45ac6642a7f034ab725c432940e7"
+  "sha256": "ea3ec61a04791ef355abd7bb04e01ff0895f2603e57d9ef6e4a33614a140b12a"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.60.2",
-  "source_commit": "6c687a8220e66196ede9b560405ff1493d0752f0",
-  "source_sha256": "2bb86426999a110ead51a17d7ab60b5cc816901b9cbd3c4426b6d02e75ab6288",
+  "release_version": "1.60.4",
+  "source_commit": "06faf46d8438c66ae116ce47eb5f343dfaca0c73",
+  "source_sha256": "9c1d721c1f0cfe90208bbc0960675053901326b324c7014c730769247d9d8c1c",
   "target": "linux-x64",
-  "sha256": "f3c2ae3f7dd8c80ff439817d25e0577f236d532dafbc6714402945a84abce354"
+  "sha256": "ebe08409a8d9ea7a7292af476ea9d3d0acf91b8b09834b12e38a6833c0bf2ac5"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.60.2",
-  "source_commit": "6c687a8220e66196ede9b560405ff1493d0752f0",
-  "source_sha256": "2bb86426999a110ead51a17d7ab60b5cc816901b9cbd3c4426b6d02e75ab6288",
+  "release_version": "1.60.4",
+  "source_commit": "06faf46d8438c66ae116ce47eb5f343dfaca0c73",
+  "source_sha256": "9c1d721c1f0cfe90208bbc0960675053901326b324c7014c730769247d9d8c1c",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "5a197ab76ecd57a479f26d364ad06b1f226a45ac6642a7f034ab725c432940e7",
+      "sha256": "ea3ec61a04791ef355abd7bb04e01ff0895f2603e57d9ef6e4a33614a140b12a",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "f3c2ae3f7dd8c80ff439817d25e0577f236d532dafbc6714402945a84abce354",
+      "sha256": "ebe08409a8d9ea7a7292af476ea9d3d0acf91b8b09834b12e38a6833c0bf2ac5",
       "mode": "0755"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.60.2",
+  "version": "1.60.4",
   "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

@@ -134,13 +134,13 @@ export function buildStackRunOutcomePayload({ fields = {}, exitCode, runId = ran
  * credential the lease calls used); without one there is nothing to authenticate
  * with and nothing is sent. Never throws; resolves within `timeoutMs`.
  */
-export async function reportStackRunOutcome({ fields, exitCode, opts, env = process.env, durationMs = null, channel, timeoutMs = STACK_RUN_OUTCOME_TIMEOUT_MS }) {
+export async function reportStackRunOutcome({ fields, exitCode, runId, opts, env = process.env, durationMs = null, channel, timeoutMs = STACK_RUN_OUTCOME_TIMEOUT_MS }) {
   // Test suites opt out so a spawned real CLI never records a fixture run.
   if (env?.[STACK_RUN_OUTCOME_OPT_OUT_ENV] === "off") return { sent: false, reason: "disabled" };
   if (!channel?.auth || typeof channel.callTool !== "function") return { sent: false, reason: "no_credential" };
   let payload;
   try {
-    payload = buildStackRunOutcomePayload({ fields, exitCode, opts, env, durationMs });
+    payload = buildStackRunOutcomePayload({ fields, exitCode, runId, opts, env, durationMs });
   } catch {
     return { sent: false, reason: "payload_error" };
   }

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.
@@ -186,6 +188,8 @@ ${bold("done OPTIONS")}
 ${bold("run OPTIONS")}
   --repo <repo>          Required approved repository name.
   --ticket <BOT-123>     Required ticket for the batch.
+  --run-id <UUID>        Optional caller-chosen run identity. Choose it before dispatch to arm
+                         bb wait 'stack-run:id=<UUID>'; the completion signal carries this run's exit code.
   --stack-path <relative> Optional PREPARED isolated stack dir. Omit it (the norm): run
                          materializes .botbuddy/stacks/<project_id>/ from this worktree's
                          supabase/ tree with a distinct project_id + remapped ports and
@@ -356,7 +360,7 @@ export function parseStackArgs(argv) {
   const childArgv = divider === -1 ? [] : rawRest.slice(divider + 1);
   const opts = {
     slot: null, host: null, repo: null, ticket: null, ticketUrl: null,
-    prId: null, prUrl: null, purpose: null, idleTtl: null, stackPath: ".", stackPathExplicit: false,
+    prId: null, prUrl: null, purpose: null, runId: null, idleTtl: null, stackPath: ".", stackPathExplicit: false,
     timeout: DEFAULT_TIMEOUT_SEC, provisionTimeout: null, reapTimeout: 300, hardTtl: null,
     connectionFile: null, noWait: false, claimOnly: false, localExec: false, keepVolumes: false, waitCapacity: null, holdOnTimeout: null,
     dockerContext: null, dockerEndpoint: null,
@@ -388,6 +392,7 @@ export function parseStackArgs(argv) {
       case "--pr": if (need(a, rest[i + 1])) opts.prId = rest[++i]; break;
       case "--pr-url": if (need(a, rest[i + 1])) opts.prUrl = rest[++i]; break;
       case "--purpose": if (need(a, rest[i + 1])) opts.purpose = rest[++i]; break;
+      case "--run-id": if (need(a, rest[i + 1])) opts.runId = rest[++i]; break;
       case "--stack-path": if (need(a, rest[i + 1])) { opts.stackPath = rest[++i]; opts.stackPathExplicit = true; } break;
       case "--idle-ttl": {
         if (need(a, rest[i + 1])) {
@@ -488,6 +493,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:
@@ -515,6 +521,15 @@ export function parseStackArgs(argv) {
   } else if (opts.bundleInclude.length && opts.localOnly) {
     errors.push("--bundle-include ships files in the remote-lease bundle, and --local-only builds no bundle; drop one of them");
   }
+  if (opts.runId != null) {
+    if (command !== "run") {
+      errors.push("--run-id is valid only with `stack run`");
+    } else if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(String(opts.runId))) {
+      errors.push("--run-id must be a canonical UUID");
+    } else {
+      opts.runId = String(opts.runId).toLowerCase();
+    }
+  }
   opts.bundleInclude = [...new Set(opts.bundleInclude)];
   opts.execution = opts.remote ? "remote" : opts.localOnly ? "local" : null;
   if (typeof opts.stackPath !== "string" || !opts.stackPath.trim() || opts.stackPath.startsWith("/") ||
@@ -537,6 +552,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`");
   }
@@ -844,6 +860,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;
@@ -871,6 +888,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).
@@ -1456,7 +1474,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) {
@@ -3011,6 +3029,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
@@ -3243,10 +3264,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 });
@@ -3968,6 +4044,7 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     }
 
     leaseProvisioned = true; // from here a Helper may act on this lease
+    execution.bindLease?.(leaseId);
     let state = request.data.state;
     if (reusedIdle) {
       idleLease.reused = "idle";
@@ -4408,7 +4485,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}` }
@@ -4481,12 +4558,16 @@ export function runReceiptFields(result) {
 export async function cmdRun(opts, childArgv, {
   lifecycle = runStackLifecycle, report = reportStackRunOutcome, now = Date.now, env = process.env,
 } = {}) {
+  // A caller that needs a wait selects this immutable UUID before dispatch.
+  // Ordinary foreground runs still receive a unique telemetry id, but it is not
+  // retrospectively advertised as an armable completion contract.
+  const runId = opts.runId ?? randomUUID();
   const startedAt = now();
   const result = await lifecycle(opts, childArgv);
   const fields = runReceiptFields(result);
   const code = emit(buildReceipt(fields), opts, result.exitCode);
   try {
-    await report({ fields: stackRunOutcomeFields(result), exitCode: code, opts, env, durationMs: now() - startedAt, channel: result?.[OUTCOME_CHANNEL] ?? null });
+    await report({ fields: stackRunOutcomeFields(result), exitCode: code, runId, opts, env, durationMs: now() - startedAt, channel: result?.[OUTCOME_CHANNEL] ?? null });
   } catch { /* best-effort: the receipt and exit code are already final */ }
   return code;
 }
@@ -4535,7 +4616,7 @@ export async function cmdStack(argv, { report = reportStackRunOutcome, outcomeCh
     const code = emit(buildReceipt(fields), opts, EXIT.INVALID);
     // BOT-2467: a refused `stack run` is recorded as an `invocation` outcome (no lease).
     if (command === "run") {
-      try { await report({ fields, exitCode: code, opts, env: process.env, durationMs: 0, channel: await outcomeChannel(argv) }); } catch { /* best-effort */ }
+      try { await report({ fields, exitCode: code, runId: opts.runId ?? undefined, opts, env: process.env, durationMs: 0, channel: await outcomeChannel(argv) }); } catch { /* best-effort */ }
     }
     process.exitCode = code;
     return code;

package/src/wait-core.mjs

@@ -85,9 +85,9 @@ export const WAIT_SUPERSEDED_SIGNAL_TYPE = "wait_superseded";
 const HOST_APPROVAL_HOST_KEY_RE = /^bbh-[0-9a-f]{24}$/;
 
 // The USER-ARMABLE spine signal_type allowlist, for the `event:` escape hatch. The full
-// public.agent_signal_type enum is these PLUS the control types above
-// (WAIT_SUPERSEDED_SIGNAL_TYPE) — control types are intentionally excluded here so they
-// can't be armed on.
+// public.agent_signal_type enum also has control-only and dedicated-grammar types (for
+// example `wait_superseded` and BOT-2629's `stack_run`); they are intentionally excluded
+// here so raw event conditions cannot bypass their narrower matching contracts.
 export const SIGNAL_TYPES = Object.freeze([
   "ci_run",
   "pr_review",
@@ -110,6 +110,7 @@ export const SIGNAL_TYPES = Object.freeze([
 ]);
 
 const LOCK_SUBTYPES = Object.freeze(["playwright_lane", "vite_port", "backend_port", "supabase_local"]);
+const CANONICAL_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
 // ---------------------------------------------------------------------------
 // Condition grammar: `TYPE:key=val,key=val`
@@ -194,6 +195,16 @@ const VALIDATORS = {
     if (!p.id) throw new Error("test-run needs id=<run_id>");
     return { runId: String(p.id) };
   },
+  // BOT-2629: this is deliberately a dedicated condition rather than a raw
+  // event escape hatch. The UUID is chosen before dispatch and the exact subject
+  // prevents another run on the same idle/re-adopted lease waking this waiter.
+  "stack-run": (p) => {
+    const unexpected = Object.keys(p).filter((key) => key !== "id");
+    if (unexpected.length) throw new Error(`stack-run does not accept ${unexpected.join(", ")}`);
+    const id = String(p.id ?? "").trim().toLowerCase();
+    if (!CANONICAL_UUID_RE.test(id)) throw new Error("stack-run needs id=<canonical run UUID>");
+    return { id };
+  },
   // BOT-1063 — guidance: park on a command-post guidance RESPONSE to a request
   // this agent raised (pairs with request_guidance). The signal is
   // recipient-scoped to the requester and keyed by the request id.
@@ -1112,6 +1123,9 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
         prReviewFiltersMatch(signal, params);
     case "test-run":
       return signal.signal_type === "test_run" && signal.subject_key === `run:${params.runId}`;
+    case "stack-run":
+      return signal.signal_type === "stack_run" && signal.subject_key === `stack-run:${params.id}` &&
+        signal.payload?.run_id === params.id && Number.isInteger(signal.payload?.exit_code);
     case "guidance":
       return signal.signal_type === "guidance_response" && signal.subject_key === params.request;
     case "lease":