@botbuddy/cli 1.59.0 → 1.59.3

package/package.json

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

package/src/stack.mjs

@@ -134,6 +134,8 @@ ${bold("up OPTIONS")}
                          deadline (exit 2) and a failed wait (its own exit code) never retry.
   --local-exec           FALLBACK (no Helper): run 'supabase start' in an ISOLATED --stack-path
                          stack and self-activate. Refused at the worktree root (shared stack).
+  --keep-volumes         LOCAL-EXEC only: preserve a reaped stack's volumes; refuses when the
+                         latest signed Helper receipt requires a one-time recovery stop.
   --provision-timeout N  LOCAL-EXEC: seconds 'supabase start' may run (default ${LOCAL_EXEC_PROVISION_TIMEOUT_SEC}). On
                          timeout up runs 'stack done --local-exec' itself and exits 6 with
                          park_reason provision_timeout (BOT-2154). The server also fails a local-exec
@@ -328,7 +330,7 @@ export function parseStackArgs(argv) {
     slot: null, host: null, repo: null, ticket: null, ticketUrl: null,
     prId: null, prUrl: null, purpose: null, idleTtl: null, stackPath: ".", stackPathExplicit: false,
     timeout: DEFAULT_TIMEOUT_SEC, provisionTimeout: null, reapTimeout: 300, hardTtl: null,
-    connectionFile: null, noWait: false, claimOnly: false, localExec: false, waitCapacity: null, holdOnTimeout: null,
+    connectionFile: null, noWait: false, claimOnly: false, localExec: false, keepVolumes: false, waitCapacity: null, holdOnTimeout: null,
     dockerContext: null, dockerEndpoint: null,
     // BOT-2142: execution placement (null = command default), remote-lease callback + bundle cap.
     execution: null, remote: false, localOnly: false, callbackPort: null, bundleMaxBytes: null,
@@ -453,6 +455,7 @@ export function parseStackArgs(argv) {
       case "--no-wait": opts.noWait = true; break;
       case "--claim-only": opts.claimOnly = true; break;
       case "--local-exec": opts.localExec = true; break;
+      case "--keep-volumes": opts.keepVolumes = true; break;
       case "--docker-context": if (need(a, rest[i + 1])) opts.dockerContext = rest[++i]; break;
       case "--docker-endpoint": if (need(a, rest[i + 1])) opts.dockerEndpoint = rest[++i]; break;
       case "--stop": opts.disposition = "stop"; break;
@@ -520,6 +523,9 @@ export function parseStackArgs(argv) {
   if (opts.claimOnly && (command !== "up" || !opts.localExec)) {
     errors.push("--claim-only is valid only with `stack up --local-exec`");
   }
+  if (opts.keepVolumes && (command !== "up" || !opts.localExec)) {
+    errors.push("--keep-volumes is valid only with `stack up --local-exec`");
+  }
   if ((opts.dockerContext || opts.dockerEndpoint) && !(["up", "done"].includes(command) && opts.localExec)) {
     errors.push("--docker-context and --docker-endpoint are valid only with `stack up --local-exec` or `stack done --local-exec`");
   }
@@ -1397,13 +1403,13 @@ export async function waitForLease(leaseId, isDone, isFailed, { timeoutSec, auth
         try { sig = JSON.parse(f.data); } catch { continue; }
         if (sig.signal_type !== "stack_lease" || sig.subject_key !== `lease:${leaseId}`) continue;
         const st = sig.payload?.state ?? null;
-        if (isFailed(st)) {
+        if (isFailed(st, sig.payload)) {
           // BOT-2013: carry the server's reap_reason so the receipt says WHY the lease is gone.
           const reapReason = typeof sig.payload?.reap_reason === "string" ? sig.payload.reap_reason : null;
           decided = { reason: "failed", result: { failed: true, state: st, ...(reapReason ? { reap_reason: reapReason } : {}) }, status: "error" };
           break frameLoop;
         }
-        if (isDone(st)) { 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 }, status: "matched" }; break frameLoop; }
       }
     }
   } catch (err) {
@@ -1603,8 +1609,8 @@ export async function parkOnLease(leaseId, isDone, isFailed, {
       // Codex #1168 P1: an authenticated read of the lease proves the outage is over, so a later,
       // independent rotation starts a fresh auth budget instead of inheriting this one.
       if (state != null) recovered();
-      if (state != null && isFailed(state)) return done({ failed: true, state, ...(read?.reap_reason ? { reap_reason: read.reap_reason } : {}) });
-      if (state != null && isDone(state)) return done({ woke: true, state });
+      if (state != null && isFailed(state, read)) return done({ failed: true, state, ...(read?.reap_reason ? { reap_reason: read.reap_reason } : {}) });
+      if (state != null && isDone(state, read)) return done({ woke: true, state });
     }
   }
 }
@@ -2097,6 +2103,60 @@ export function localTeardown(stackDir, dockerTarget, disposition, spawn = spawn
   return labelScopedTeardown(projectId, disposition, spawn, dockerEnv, log);
 }
 
+/** BOT-2398: a prior signed `volumes_reusable=false` receipt permits one exact,
+ * bounded Supabase recovery stop before a local-exec start. This deliberately
+ * has no label-scoped fallback: the signed Helper receipt authorizes only this
+ * Supabase project on this pinned daemon, and any uncertainty leaves the lease
+ * fenced without starting. */
+export async function localVolumeRecoveryStop(opts, execution, dockerTarget, {
+  targetCheck = runLocalExecTargetCheck,
+  spawn = spawnSync,
+  readProjectId = projectIdUnder,
+  acquireLock = acquireStackLock,
+  lockHeld = false,
+  env = process.env,
+} = {}) {
+  if (!opts?.localExec || !ADMITTED_DOCKER_VALIDATIONS.has(dockerTarget?.validation) ||
+      !dockerTarget?.resolved_endpoint || !dockerTarget?.server_id) return false;
+  const stackDir = stackDirFor(execution);
+  const projectId = readProjectId(stackDir);
+  if (typeof projectId !== "string" || !/^[a-z0-9][a-z0-9_-]{0,62}$/.test(projectId)) return false;
+  let lock;
+  if (!lockHeld) {
+    try { lock = await acquireLock(lockPathForProject(projectId), { timeoutMs: 0 }); }
+    catch { return false; }
+  }
+  try {
+    const currentTarget = async () => {
+      const checked = await targetCheck(opts);
+      return checked?.exitCode === 0 ? dockerTargetFromPreflight(checked.receipt) : null;
+    };
+    const before = await currentTarget();
+    if (!dockerTargetsMatch(dockerTarget, before)) return false;
+    const dockerEnv = dockerEnvForTarget(dockerTarget, env);
+    const stop = spawn("supabase", ["stop", "--workdir", stackDir, "--no-backup"], {
+      encoding: "utf8", env: dockerEnv, timeout: 120_000, killSignal: "SIGTERM",
+      stdio: ["ignore", "pipe", "pipe"], maxBuffer: 1024 * 1024,
+    });
+    if (stop?.error || stop?.status !== 0) return false;
+    const after = await currentTarget();
+    if (!dockerTargetsMatch(dockerTarget, after)) return false;
+    const listProjectResources = (args) => spawn("docker", args, {
+      encoding: "utf8", env: dockerEnv, timeout: 30_000, killSignal: "SIGTERM",
+      stdio: ["ignore", "pipe", "pipe"], maxBuffer: 1024 * 1024,
+    });
+    const containers = listProjectResources(["ps", "-aq", "--filter", `label=com.supabase.cli.project=${projectId}`]);
+    if (containers?.error || containers?.status !== 0 || String(containers.stdout || "").trim()) return false;
+    const volumes = listProjectResources(["volume", "ls", "-q", "--filter", `label=com.supabase.cli.project=${projectId}`]);
+    if (volumes?.error || volumes?.status !== 0 || String(volumes.stdout || "").trim()) return false;
+    const networks = listProjectResources(["network", "ls", "-q", "--filter", `label=com.supabase.cli.project=${projectId}`]);
+    if (networks?.error || networks?.status !== 0 || String(networks.stdout || "").trim()) return false;
+    return true;
+  } finally {
+    lock?.release?.();
+  }
+}
+
 /** BOT-2001: remove exactly one Supabase project's containers, network and (for `destroy`)
  * volumes by the CLI's project label; true iff a re-list finds NONE of the resource classes
  * this disposition removes (Codex #1012: a busy volume or network fails closed too). */
@@ -2147,9 +2207,17 @@ export async function cmdUp(opts, {
   callTool = callToolJson,
   authProvider = stackAuthHeader,
   localProvisionFn = localProvision,
+  // BOT-2398: exactly one fixed `supabase stop --no-backup` against the
+  // validated stack directory/engine, only when a signed prior reap requires it.
+  // Keep the fourth argument: the caller holds the project lock across this
+  // stop and the immediately following start, so the recovery primitive must
+  // not try to acquire the same lock recursively.
+  recoveryStopFn = localVolumeRecoveryStop,
   // BOT-2154: the self-release after a timed-out local start (`stack done --local-exec`).
   localDoneFn = null,
   waitFn = waitForLease,
+  // BOT-2398 focused seam; production uses the existing lease SSE park below.
+  waitHandoffFn = null,
   emitResult = emit,
   machineUuidFn = machineUuid,
   assertIsolated = validateLocalExecTarget,
@@ -2460,10 +2528,181 @@ export async function cmdUp(opts, {
       const reservedProjectId = projectIdUnder(stackDirFor(execution));
       const reservedConnection = connectionWithDockerTarget(
         reservedProjectId ? { project_id: reservedProjectId } : {}, localDockerTarget);
-      const reserved = await call("reserve_stack_lease", {
-        lease_id: leaseId,
-        connection: reservedConnection,
-      });
+      let volumeRecoveryRequired = false;
+      let provisionReserved = false;
+      if (d.volume_recovery_protocol === 1) {
+        const priorRead = await call("get_stack_lease", { lease_id: leaseId });
+        const current = priorRead?.ok && priorRead.data?.success ? priorRead.data : null;
+        const exactCurrentContext = current && current.state === "provisioning" &&
+          current.host_key === d.host_key && current.slot === slot &&
+          current.worktree_root === execution.worktreeRoot && current.stack_path === execution.stackPath &&
+          current.execution_mode === "local_exec";
+        if (!exactCurrentContext) {
+          const cancelled = await call("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+          const leaseCancellation = cancelled.ok && cancelled.data?.success
+            ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+            : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+          return emitResult(buildReceipt({
+            command: "up", outcome: "refused", code: "VOLUME_RECOVERY_CONTEXT_UNVERIFIED", lease_id: leaseId, slot,
+            error: "could not verify the exact local-exec host/slot/worktree before checking volume-recovery state",
+            lease_cancellation: leaseCancellation,
+          }), opts, EXIT.LEASE_FAILED);
+        }
+        const hasPriorSource = Object.prototype.hasOwnProperty.call(current, "prior_volume_source_lease_id");
+        const hasPriorDecision = Object.prototype.hasOwnProperty.call(current, "prior_volumes_reusable");
+        const priorSource = current.prior_volume_source_lease_id;
+        if (!hasPriorSource || !hasPriorDecision ||
+            (priorSource !== null && (typeof priorSource !== "string" || !priorSource.trim()))) {
+          const cancelled = await call("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+          const leaseCancellation = cancelled.ok && cancelled.data?.success
+            ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+            : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+          return emitResult(buildReceipt({
+            command: "up", outcome: "refused", code: "VOLUME_RECOVERY_HISTORY_UNVERIFIED", lease_id: leaseId, slot,
+            error: "the server omitted or malformed prior local-exec history; no recovery or start was attempted",
+            lease_cancellation: leaseCancellation,
+          }), opts, EXIT.LEASE_FAILED);
+        }
+        const reuseState = current.prior_volumes_reusable;
+        if (reuseState !== undefined && reuseState !== null && typeof reuseState !== "boolean") {
+          const cancelled = await call("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+          const leaseCancellation = cancelled.ok && cancelled.data?.success
+            ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+            : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+          return emitResult(buildReceipt({
+            command: "up", outcome: "refused", code: "VOLUME_RECOVERY_STATE_INVALID", lease_id: leaseId, slot,
+            error: "the server returned an invalid prior volume-reuse state; no recovery or start was attempted",
+            lease_cancellation: leaseCancellation,
+          }), opts, EXIT.LEASE_FAILED);
+        }
+        if (priorSource !== null && reuseState !== true && reuseState !== false) {
+          // The Helper handoff is bound to the already-reserved ordinary
+          // provision job. Reserve it before enqueueing the distinct control
+          // action; neither job may race the local start.
+          const handoffReservation = await call("reserve_stack_lease", {
+            lease_id: leaseId, connection: reservedConnection,
+          });
+          if (!handoffReservation.ok || handoffReservation.data?.success !== true) {
+            return emitResult(buildReceipt({ command: "up", outcome: "error", code: "PREDECESSOR_HANDOFF_RESERVATION_FAILED",
+              lease_id: leaseId, slot, error: "the local provision job could not be reserved before requesting the Helper fence handoff; local start was not attempted" }),
+              opts, EXIT.LEASE_FAILED);
+          }
+          provisionReserved = true;
+          const requestedHandoff = await call("request_stack_lease_predecessor_handoff", { lease_id: leaseId });
+          if (!requestedHandoff.ok || requestedHandoff.data?.success !== true ||
+              requestedHandoff.data?.handoff_required !== true ||
+              typeof requestedHandoff.data?.handoff_job_id !== "string" ||
+              !requestedHandoff.data.handoff_job_id.trim()) {
+            const cancelled = requestedHandoff.ok && requestedHandoff.data?.success === true &&
+                requestedHandoff.data?.handoff_required === false
+              ? await call("cancel_unclaimed_stack_lease", { lease_id: leaseId }) : null;
+            const leaseCancellation = cancelled
+              ? (cancelled.ok && cancelled.data?.success
+                ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+                : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" })
+              : null;
+            return emitResult(buildReceipt({
+              command: "up", outcome: "refused", code: "PREDECESSOR_HANDOFF_UNAVAILABLE", lease_id: leaseId, slot,
+              error: "the owner-authenticated Helper could not prove an accepted exact schema-1 predecessor handoff; refusing recovery stop and local start",
+              ...(leaseCancellation ? { lease_cancellation: leaseCancellation } : {}),
+            }), opts, EXIT.LEASE_FAILED);
+          }
+          const handoffJobID = requestedHandoff.data.handoff_job_id;
+          const isAcceptedHandoff = (value) => value?.state === "provisioning" &&
+            value?.predecessor_handoff_job_id === handoffJobID &&
+            value?.predecessor_handoff_status === "completed" &&
+            value?.predecessor_handoff_outcome === "succeeded";
+          const isFailedHandoff = (value) => value?.state === "provisioning" &&
+            value?.predecessor_handoff_job_id === handoffJobID &&
+            ["failed", "stale"].includes(value?.predecessor_handoff_status);
+          let handoffState = await call("get_stack_lease", { lease_id: leaseId });
+          if (!handoffState.ok || handoffState.data?.success !== true ||
+              (handoffState.data.predecessor_handoff_job_id != null &&
+                handoffState.data.predecessor_handoff_job_id !== handoffJobID)) {
+            return emitResult(buildReceipt({ command: "up", outcome: "error", code: "PREDECESSOR_HANDOFF_STATE_UNVERIFIED",
+              lease_id: leaseId, slot, error: "the exact Helper handoff job status could not be verified; local start was not attempted" }),
+              opts, EXIT.LEASE_FAILED);
+          }
+          if (!isAcceptedHandoff(handoffState.data) && !isFailedHandoff(handoffState.data)) {
+            const waited = waitHandoffFn
+              ? await waitHandoffFn(leaseId, handoffJobID)
+              : await resilientWait(
+                (leaseState, payload) => leaseState === "provisioning" &&
+                  payload?.predecessor_handoff_job_id === handoffJobID &&
+                  payload?.predecessor_handoff_status === "completed" &&
+                  payload?.predecessor_handoff_outcome === "succeeded",
+                (leaseState, payload) => leaseState === "reap_failed" ||
+                  (leaseState === "provisioning" && payload?.predecessor_handoff_job_id === handoffJobID &&
+                    ["failed", "stale"].includes(payload?.predecessor_handoff_status)),
+              );
+            if (!waited?.woke) {
+              return emitResult(buildReceipt({ command: "up", outcome: waited?.timeout ? "timeout" : "error",
+                code: waited?.timeout ? "PREDECESSOR_HANDOFF_TIMEOUT" : "PREDECESSOR_HANDOFF_FAILED",
+                lease_id: leaseId, slot, error: "the Helper predecessor handoff did not reach accepted success; recovery stop and local start were not attempted" }),
+                opts, waited?.timeout ? EXIT.TIMEOUT : EXIT.LEASE_FAILED);
+            }
+            handoffState = await call("get_stack_lease", { lease_id: leaseId });
+          }
+          if (!handoffState.ok || !isAcceptedHandoff(handoffState.data)) {
+            return emitResult(buildReceipt({ command: "up", outcome: "error", code: "PREDECESSOR_HANDOFF_FAILED",
+              lease_id: leaseId, slot, error: "the exact Helper handoff has no accepted successful terminal receipt; recovery stop and local start were not attempted" }),
+              opts, EXIT.LEASE_FAILED);
+          }
+          // The signed Helper acknowledgement rebinds exact local custody,
+          // but schema 1 did not record whether old volumes were reusable. A
+          // recovery stop would be destructive, so honour --keep-volumes before
+          // it can be attempted.
+          if (opts.keepVolumes) {
+            const cancelled = await call("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+            const leaseCancellation = cancelled.ok && cancelled.data?.success
+              ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+              : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+            return emitResult(buildReceipt({
+              command: "up", outcome: "refused", code: "VOLUME_RECOVERY_REQUIRED", lease_id: leaseId, slot,
+              error: "the accepted predecessor handoff has no reusable-volume decision; --keep-volumes prevents the required recovery stop",
+              lease_cancellation: leaseCancellation,
+            }), opts, EXIT.LEASE_FAILED);
+          }
+          // Run the established bounded no-backup stop under the project lock
+          // before starting this exact successor.
+          volumeRecoveryRequired = true;
+        }
+        if (reuseState === false || reuseState === true) {
+          const priorProject = current.prior_project_id;
+          const priorTarget = current.prior_docker_target;
+          const exactPriorTarget = priorSource !== null && priorProject === reservedProjectId &&
+            dockerTargetsMatch(priorTarget, localDockerTarget);
+          if (!exactPriorTarget) {
+            const cancelled = await call("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+            const leaseCancellation = cancelled.ok && cancelled.data?.success
+              ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+              : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+            return emitResult(buildReceipt({
+              command: "up", outcome: "refused", code: "VOLUME_RECOVERY_TARGET_MISMATCH", lease_id: leaseId, slot,
+              error: "the prior signed non-reusable-volume receipt is for a different or incomplete Docker target/project; refusing to start",
+              lease_cancellation: leaseCancellation,
+            }), opts, EXIT.LEASE_FAILED);
+          }
+          if (reuseState === false && opts.keepVolumes) {
+            const cancelled = await call("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+            const leaseCancellation = cancelled.ok && cancelled.data?.success
+              ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+              : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+            return emitResult(buildReceipt({
+              command: "up", outcome: "refused", code: "VOLUME_RECOVERY_REQUIRED", lease_id: leaseId, slot,
+              error: "the exact prior Helper receipt marked volumes non-reusable; --keep-volumes prevents the required recovery stop",
+              lease_cancellation: leaseCancellation,
+            }), opts, EXIT.LEASE_FAILED);
+          }
+          volumeRecoveryRequired = reuseState === false;
+        }
+      }
+      const reserved = provisionReserved
+        ? { ok: true, data: { success: true, reserved: true } }
+        : await call("reserve_stack_lease", {
+          lease_id: leaseId,
+          connection: reservedConnection,
+        });
       if (!reserved.ok || !reserved.data?.success) {
         // A Helper can win the reservation race by taking the queued provision
         // job between `request_stack_lease` and `reserve_stack_lease`. That is NOT
@@ -2505,10 +2744,46 @@ export async function cmdUp(opts, {
           }), opts, EXIT.LEASE_FAILED);
         }
       } else {
+        let recoveryLock = null;
+        if (volumeRecoveryRequired) {
+          if (opts.keepVolumes) {
+            const cancelled = await call("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+            return emitResult(buildReceipt({
+              command: "up", outcome: "refused", code: "VOLUME_RECOVERY_REQUIRED", lease_id: leaseId, slot,
+              error: "the exact predecessor handoff requires a recovery stop; --keep-volumes prevents the required recovery",
+              lease_cancellation: cancelled.ok && cancelled.data?.success
+                ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+                : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" },
+            }), opts, EXIT.LEASE_FAILED);
+          }
+          if (typeof reservedProjectId !== "string" || !/^[a-z0-9][a-z0-9_-]{0,62}$/.test(reservedProjectId)) {
+            return emitResult(buildReceipt({
+              command: "up", outcome: "error", code: "VOLUME_RECOVERY_PROJECT_UNVERIFIED", lease_id: leaseId, slot,
+              error: "the isolated stack project id is unavailable; the recovery stop and supabase start were not attempted",
+            }), opts, EXIT.LEASE_FAILED);
+          }
+          try { recoveryLock = await acquireStackLock(lockPathForProject(reservedProjectId), { timeoutMs: 0 }); }
+          catch {
+            return emitResult(buildReceipt({
+              command: "up", outcome: "error", code: "VOLUME_RECOVERY_PROJECT_BUSY", lease_id: leaseId, slot,
+              error: "the isolated stack project lock is held; the recovery stop and supabase start were not attempted",
+            }), opts, EXIT.LEASE_FAILED);
+          }
+          let recovered = false;
+          try { recovered = await recoveryStopFn(opts, execution, localDockerTarget, { lockHeld: true }) === true; } catch { recovered = false; }
+          if (!recovered) {
+            recoveryLock.release();
+            return emitResult(buildReceipt({
+              command: "up", outcome: "error", code: "VOLUME_RECOVERY_STOP_FAILED", lease_id: leaseId, slot,
+              error: "the exact bounded `supabase stop --no-backup` recovery failed; the reserved lease remains fenced and `supabase start` was not attempted",
+            }), opts, EXIT.LEASE_FAILED);
+          }
+        }
         let conn;
         try {
           conn = connectionWithDockerTarget(localProvisionFn(opts, localDockerTarget, execution), localDockerTarget);
         } catch (e) {
+          recoveryLock?.release();
           if (e?.code === "PROVISION_TIMEOUT") {
             // BOT-2154: a bounded start that ran out of time. Release the lease ourselves —
             // `stack done --local-exec` stops whatever the start left behind and reaps the lease
@@ -2533,6 +2808,7 @@ export async function cmdUp(opts, {
           // review); do NOT cancel.
           return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: e.message }), opts, EXIT.LEASE_FAILED);
         }
+        recoveryLock?.release();
         const act = await call("activate_stack_lease", { lease_id: leaseId, connection: conn });
         if (!act.ok || !act.data?.success) {
           return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: act.error || act.data?.code || "activate failed" }), opts, EXIT.BACKEND);
@@ -2691,6 +2967,8 @@ export async function cmdDone(leaseId, opts, {
   if (!auth) return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
   const call = rpc.call;
   let dockerTarget = null;
+  let expectedDockerTarget = null;
+  let provisionedProjectId = null;
   let legacyTargetProof = null;
   let teardownDir = process.cwd();
   let leaseBefore = null;
@@ -2751,6 +3029,7 @@ export async function cmdDone(leaseId, opts, {
     // old lease would still finalize. Refuse on project drift (the provisioned project_id is
     // persisted on the lease connection at `up`).
     const provisionedProject = current.data.connection?.project_id;
+    provisionedProjectId = provisionedProject ?? null;
     if (provisionedProject) {
       const currentProject = projectIdUnder(teardownDir);
       if (currentProject && currentProject !== provisionedProject) {
@@ -2763,6 +3042,7 @@ export async function cmdDone(leaseId, opts, {
       }
     }
     const expected = current.data.connection?.botbuddy_docker_target;
+    expectedDockerTarget = expected ?? null;
     // BOT-1711 (Codex R13 P1): a modern-target lease that lacks a persisted provisioned
     // project_id was NOT provisioned by BOT-1711+ local-exec (e.g. a pre-1.32 lease that
     // recorded a non-root stack_path but actually started the worktree ROOT). Its recorded
@@ -2877,7 +3157,17 @@ export async function cmdDone(leaseId, opts, {
         error: "local `supabase stop` failed — NOT finalizing; the slot stays fenced. Tear the stack down and re-run `stack done --local-exec`, or let the reaper reconcile.",
       }), opts, EXIT.LEASE_FAILED);
     }
-    const fin = await call("finalize_stack_lease", { lease_id: leaseId });
+    // BOT-2398: a successful owner-local teardown is itself an authenticated
+    // custody receipt. Carry the exact provisioned project, Docker daemon, and
+    // disposition so the server can persist a reusable decision without waiting
+    // for a Helper reap receipt that will never exist on this path.
+    const localExecCompletion = opts.localExec && expectedDockerTarget && provisionedProjectId
+      ? { project_id: provisionedProjectId, docker_target: dockerTarget, disposition }
+      : undefined;
+    const fin = await call("finalize_stack_lease", {
+      lease_id: leaseId,
+      ...(localExecCompletion ? { local_exec_completion: localExecCompletion } : {}),
+    });
     if (fin.ok && fin.data?.success) state = fin.data.state;
     else process.stderr.write(`${yellow("⚠")} stack: finalize failed (${fin.error || fin.data?.code}); the reaper will reconcile.\n`);
   }

package/src/wait-core.mjs

@@ -676,9 +676,12 @@ export function parseSseFrames(buffer) {
 }
 
 // ---------------------------------------------------------------------------
-// Cursor — the spine `seq` is a non-negative integer; reject garbage loudly.
+// Cursor — replay uses JavaScript Numbers at the relay boundary, so only exact
+// non-negative safe integers can be replayed without changing the requested floor.
 // ---------------------------------------------------------------------------
 
+const MAX_SAFE_SIGNAL_SEQUENCE = BigInt(Number.MAX_SAFE_INTEGER);
+
 /**
  * @param {string|null|undefined} raw
  * @returns {{kind: "absent"} | {kind: "ok", value: string} | {kind: "invalid", raw: string}}
@@ -688,7 +691,9 @@ export function normalizeSince(raw) {
   const t = String(raw).trim();
   if (t === "") return { kind: "absent" };
   if (!/^\d+$/.test(t)) return { kind: "invalid", raw };
-  return { kind: "ok", value: String(BigInt(t)) };
+  const value = BigInt(t);
+  if (value > MAX_SAFE_SIGNAL_SEQUENCE) return { kind: "invalid", raw };
+  return { kind: "ok", value: String(value) };
 }
 
 // ---------------------------------------------------------------------------

package/src/wait.mjs

@@ -153,7 +153,7 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
 OPTIONS
   --any                 wake on the first matching condition (default; only mode in v1)
   --timeout <seconds>   max wait (default 7200; hard cap 28800). Timeout is exit 2, not an error.
-  --since <seq>         resume from a prior receipt's next_cursor (replay what you missed)
+  --since <seq>         resume from a prior receipt's next_cursor (0..9007199254740991; replay what you missed)
   --receipt-max-bytes <n>   cap the receipt (512..65536; default 10240; payloads truncate to pointers)
   --heartbeat           keep this agent session alive while waiting (so it is not reaped)
   --url <base>          relay base URL (default $BOTBUDDY_RELAY_URL or https://api.bot-buddy.ai/functions/v1)
@@ -216,6 +216,7 @@ function parseArgv(argv) {
     mode: "any",
     timeout: 7200,
     since: null,
+    sinceProvided: false,
     receiptMaxBytes: 10240,
     heartbeat: false,
     url: process.env.BOTBUDDY_RELAY_URL || "https://api.bot-buddy.ai/functions/v1",
@@ -248,7 +249,7 @@ function parseArgv(argv) {
     else if (a === "--heartbeat") opts.heartbeat = true;
     else if (a === "--timeout") opts.timeout = Number(optionValue());
     else if (a === "--deadline-at") opts.deadlineAt = optionValue(); // internal recovery argv; never shown as public API
-    else if (a === "--since") opts.since = optionValue();
+    else if (a === "--since") { opts.sinceProvided = true; opts.since = optionValue(); }
     else if (a === "--receipt-max-bytes") opts.receiptMaxBytes = Number(optionValue());
     else if (a === "--url") opts.url = optionValue();
     // BOT-1574: --token and --profile are RETIRED. A wait authenticates from
@@ -1572,6 +1573,19 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
     process.exit(EXIT.INVALID);
   }
 
+  // BOT-2453: an explicit replay cursor is a request to replay, never permission
+  // to silently fall back to live-only. Validate it before creating a recoverable
+  // checkpoint, resolving credentials, registering a wait, or opening SSE.
+  if (opts.sinceProvided) {
+    const since = normalizeSince(opts.since);
+    if (since.kind !== "ok") {
+      process.stderr.write("bb-wait: --since must be a non-negative signal sequence <= 9007199254740991\n");
+      emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_since", cursor: opts.since });
+      process.exit(EXIT.INVALID);
+    }
+    opts.since = since.value;
+  }
+
   const { conditions, errors } = parseConditions(opts.conditions);
   if (errors.length > 0) {
     for (const e of errors) process.stderr.write(`bb-wait: invalid condition '${e.spec}': ${e.message}\n`);