@botbuddy/cli 1.59.4 → 1.59.6

package/package.json

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

package/src/commands.mjs

@@ -212,6 +212,8 @@ ${bold("MCP CONFIG KEY")}
 ${bold("TOOLS")}
   help --tools               List every BotBuddy tool
   help <tool>                Show one tool's arguments
+  help test                  Safe test-lane launch and recovery guidance
+  help symptom <name>        Diagnose a known block without source-diving
   call <tool> [--key value]  Invoke any tool
   call <tool> --json '{...}' Invoke with a JSON arguments object
   call <tool> --pin <slug>   Pin the connection tenant (a user token needs one;
@@ -362,6 +364,11 @@ async function cmdCall(args) {
 }
 
 async function cmdToolHelp(args) {
+  const local = recoveryHelp(args);
+  if (local) {
+    console.log(local);
+    return;
+  }
   // `help --tools` (or `help --all`) lists the catalog; `help <tool>` details one.
   const tool = args[0].startsWith("-") ? null : args[0];
   const res = await fetch(discoveryUrlFor(SERVER_URL, tool));
@@ -373,6 +380,80 @@ async function cmdToolHelp(args) {
   console.log(formatDiscovery(await res.json(), { tool }));
 }
 
+// Keep the most common lifecycle recoveries local: an agent must be able to
+// discover the safe next action even when the MCP discovery endpoint is down.
+// This deliberately names only stable, already-shipped commands. New lifecycle
+// commands belong in their owning feature ticket before they are documented here.
+export function recoveryHelp(args) {
+  const topic = args.map((arg) => String(arg).trim().toLowerCase()).filter(Boolean).join(" ");
+  if (topic === "test") return `${bold("bb help test")} — launch tests without losing their evidence
+
+${bold("SAFE DEFAULT")}
+  1. Run ${cyan("bb doctor --json")} from the target worktree.
+  2. Run the repository's configured test command without manually copying a
+     session ID or session token unless the harness explicitly requires it.
+  3. Keep the command's original result and receipt path. Do not start a second
+     full suite merely because telemetry is missing.
+
+${bold("WHEN TEST TELEMETRY IS UNAVAILABLE")}
+  Run ${cyan("bb help symptom telemetry-unavailable")}. A null test-run ID means
+  there is no semantic test-run wait to arm; it is not a passing result.
+
+${bold("WAITING")}
+  Use ${cyan("bb wait 'test-run:id=<id>' --heartbeat")} only when the launch output
+  contains a real test-run ID. Do not replace a missing lifecycle signal with a
+  timer or status-polling loop.`;
+
+  if (topic === "symptom" || topic === "symptoms") return `${bold("bb help symptom <name>")} — supported recovery topics
+
+  ${cyan("telemetry-unavailable")}  A test launch has no test-run ID or wait command.
+  ${cyan("command-run-stuck")}     A local command receipt and remote lifecycle disagree.
+
+Choose the symptom printed by the command. If neither applies, preserve the
+original command result and receipt, then report the exact error and command ID.`;
+
+  if (topic === "symptom telemetry-unavailable") return `${bold("Symptom: telemetry unavailable")}
+
+${bold("Meaning")}
+The workload may have started, but BotBuddy did not create a test-run record.
+There is no ${cyan("test-run:id")} wait to arm and silence is never a green result.
+
+${bold("Safe recovery")}
+  1. Do not launch another full suite yet.
+  2. Preserve the original ${cyan("command_run_id")} and receipt path from its output.
+  3. Read the terminal receipt when the original runner returns. A receipt with a
+     terminal status is evidence of that workload's result.
+  4. If the receipt is not terminal, keep the original runner result pending;
+     do not poll it or use a timer as a completion signal.
+  5. After a terminal receipt, fix the launch/authentication cause and rerun the
+     smallest affected scope once, with an explicit rerun reason when supported.
+
+${bold("Escalation payload")}
+Include CLI version, exact command (with secrets removed), command-run ID,
+receipt status/exit code, and whether a test-run ID was created.`;
+
+  if (topic === "symptom command-run-stuck") return `${bold("Symptom: command run appears stuck")}
+
+${bold("Meaning")}
+A remote lifecycle record can lag or fail to receive a terminal callback. It
+does not prove that the workload is still running.
+
+${bold("Safe recovery")}
+  1. Preserve the command-run ID and the original result.
+  2. Prefer the owning runner's local terminal receipt for the workload verdict.
+  3. If the receipt is terminal, do not cancel or duplicate the command solely
+     because remote state remains ${cyan("registered")} or ${cyan("running")}.
+  4. If the receipt is absent/non-terminal, retain the original runner result;
+     do not poll or infer completion from elapsed time.
+  5. Report the receipt and remote discrepancy as telemetry evidence.
+
+${bold("Boundary")}
+Command-run status is agent-owned. A different agent may be denied access; that
+denial is not evidence that the run is missing or terminal.`;
+
+  return null;
+}
+
 // BOT-1566 C1: a tenant slug as the server accepts it on `?tenant=` — lowercase
 // alphanumerics and hyphens, 2–63 chars, not starting with a hyphen.
 export const TENANT_SLUG_RE = /^[a-z0-9][a-z0-9-]{1,62}$/;

package/src/stack.mjs

@@ -64,7 +64,16 @@ export const STACK_SCHEMA_VERSION = 1;
  */
 export const CALLBACK_PORT_UNSUPPORTED_REMOTE = "CALLBACK_PORT_UNSUPPORTED_REMOTE";
 export const DEFAULT_RECEIPT_MAX_BYTES = 10240;
-export const DEFAULT_TIMEOUT_SEC = 3600;
+/**
+ * BOT-2400: a capacity park waits for days, not an hour. A full host costs a wait, never a
+ * failed run plus a token-expensive re-arm; and when even this deadline passes the lease keeps
+ * its queue place (PARK_DEADLINE) instead of being released.
+ */
+export const DEFAULT_TIMEOUT_SEC = 72 * 3600;
+/** BOT-2400: the typed code on a park that reached its deadline with the lease still queued and held. */
+export const PARK_DEADLINE = "PARK_DEADLINE";
+/** A park ended but the owner hold could not be confirmed; the lease is never cancelled. */
+export const PARK_HOLD_UNCONFIRMED = "PARK_HOLD_UNCONFIRMED";
 /**
  * BOT-2154: how long `stack up --local-exec` lets `supabase start` run before it gives up and
  * releases the lease itself (`--provision-timeout` overrides). Deliberately below the server's
@@ -74,7 +83,10 @@ export const DEFAULT_TIMEOUT_SEC = 3600;
 export const LOCAL_EXEC_PROVISION_TIMEOUT_SEC = 900;
 /** BOT-2230: the bounds the control plane enforces on an owner place hold (hold_stack_lease_place). */
 export const HOLD_ON_TIMEOUT_MIN_SEC = 60;
-export const HOLD_ON_TIMEOUT_MAX_SEC = 14400;
+/** BOT-2400: raised from 4 h to 72 h (hold_stack_lease_place_for_agent enforces the same bound). */
+export const HOLD_ON_TIMEOUT_MAX_SEC = 72 * 3600;
+/** The bound a pre-BOT-2400 control plane enforces; a refused longer hold is retried at it. */
+export const LEGACY_HOLD_MAX_SEC = 14400;
 /** How often a run renews its stack directory's retention while it still exists
  * (BOT-1798): frequent enough to cover the pre-child queue/provision waits. */
 const RETENTION_REFRESH_MS = 5 * 60 * 1000;
@@ -99,6 +111,7 @@ ${bold("USAGE")}
   botbuddy stack status <lease_id>   Show a lease's state + connection
   botbuddy stack touch  <lease_id>   Bump the idle clock (and report measured use) so the reaper doesn't stop it
   botbuddy stack done   <lease_id>   Release (done): idle the stack for re-adoption (--reap tears it down)
+  botbuddy stack cancel <lease_id>   Give a queued lease's place up (= done --reap; BOT-2400)
   botbuddy stack run [options] -- <executable> [args...]
                                       Own one Helper-backed test/fix batch end-to-end
 
@@ -117,11 +130,17 @@ ${bold("up OPTIONS")}
                          or use 'stack run', which materializes one for you.
   --purpose <text>       Free-text purpose recorded on the lease.
   --idle-ttl <seconds>   Idle seconds before the reaper STOPS an unused stack (default 1800).
-  --timeout <seconds>    Max seconds to park for capacity before giving up (default ${DEFAULT_TIMEOUT_SEC}).
+  --timeout <seconds>    Seconds to park for capacity (default ${DEFAULT_TIMEOUT_SEC} = 72 h, BOT-2400). At the
+                         deadline the lease is NOT released: it keeps its queue place (owner hold) and the
+                         exit-2 receipt says code PARK_DEADLINE, state queued, queue_hold — re-run the same
+                         command to resume it; \`stack cancel <lease_id>\` gives it up.
+                         If the hold cannot be confirmed, PARK_HOLD_UNCONFIRMED keeps ownership and
+                         omits unverified state; inspect \`stack status <lease_id>\` before resuming.
   --no-wait              If the host is full, print the queue position and exit (don't park).
   --hold-on-timeout <seconds>
                          BOT-2230: when the --timeout park runs out with the lease still queued,
-                         keep its queue place for <seconds> (60–14400) instead of losing it: the
+                         keep its queue place for <seconds> (60–259200; default since BOT-2400: 259200)
+                         instead of losing it: the
                          lease stays queued but is not dispatched, and re-running the same
                          \`stack up\` (same agent + slot) before then re-attaches to it. The exit-2
                          receipt carries queue_hold {held, until, queue_position}; \`stack done
@@ -173,6 +192,10 @@ ${bold("run OPTIONS")}
                          leases that. The identity is STABLE per worktree+slot (BOT-1803), so
                          the next run maps to the same directory, project and ports. "." is REFUSED — the worktree root is the shared
                          canonical project and the Helper would start/clobber it.
+  --timeout <seconds>    Same 72 h park as up (BOT-2400): at the deadline the queued lease keeps its
+                         place (exit 2, code PARK_DEADLINE) and re-running the same \`stack run\`
+                         re-attaches to it. A slot whose previous lease of yours is still reaping is
+                         waited out until reaped, then requested again (no exit 5).
   --provision-timeout N  Seconds to wait for a physical Helper provision (default: --timeout).
   --reap-timeout N       Seconds to wait for signed physical reap proof (default: 300); also bounds
                          the wait for an idle lease being re-provisioned/preempted to reach reaped.
@@ -216,7 +239,8 @@ ${bold("GLOBAL")}
   --receipt-max-bytes N  Receipt size cap (default ${DEFAULT_RECEIPT_MAX_BYTES}).
 
 ${bold("EXIT CODES")}
-  0 ok/held (or queued+--no-wait)   2 park timed out            3 not authenticated
+  0 ok/held (or queued+--no-wait)   2 park deadline (PARK_DEADLINE: still queued, place kept)
+  3 not authenticated
   4 invalid arguments               5 backend/coordination      6 lease failed/reaped
   7 internal error                  8 cleanup/reap proof failed
 
@@ -322,7 +346,11 @@ export function deriveSlot({ slot, repo, ticket } = {}, env = process.env) {
  */
 export function parseStackArgs(argv) {
   const errors = [];
-  const [command, ...rawRest] = argv;
+  const [rawCommand, ...rawRest] = argv;
+  // BOT-2400: `stack cancel <lease_id>` is the explicit give-up for a queued lease (its place
+  // is otherwise kept): exactly `stack done <lease_id> --reap`.
+  const cancel = rawCommand === "cancel";
+  const command = cancel ? "done" : rawCommand;
   const divider = rawRest.indexOf("--");
   const rest = divider === -1 ? rawRest : rawRest.slice(0, divider);
   const childArgv = divider === -1 ? [] : rawRest.slice(divider + 1);
@@ -339,7 +367,7 @@ export function parseStackArgs(argv) {
     bundleInclude: [],
     disposition: "destroy", json: false, receiptMaxBytes: DEFAULT_RECEIPT_MAX_BYTES,
     // BOT-1803: eager release (reap) instead of the default idle release (done/run).
-    reap: false,
+    reap: cancel,
   };
   const positionals = [];
   const need = (name, v) => {
@@ -575,7 +603,15 @@ export async function holdQueuePlace(call, leaseId, holdSecs) {
   let res;
   try { res = await call("hold_stack_lease_place", { lease_id: leaseId, hold_secs: holdSecs }); }
   catch (err) { return { held: false, code: null, error: String(err?.message ?? err) }; }
-  const d = res?.data;
+  let d = res?.data;
+  // BOT-2400: a control plane that predates the 72 h bound refuses a longer hold; keep the
+  // place for the longest hold it accepts rather than losing it.
+  if (d?.code === "INVALID_HOLD_SECS" && holdSecs > LEGACY_HOLD_MAX_SEC) {
+    try { res = await call("hold_stack_lease_place", { lease_id: leaseId, hold_secs: LEGACY_HOLD_MAX_SEC }); }
+    catch (err) { return { held: false, code: null, error: String(err?.message ?? err) }; }
+    d = res?.data;
+    holdSecs = LEGACY_HOLD_MAX_SEC;
+  }
   if (res?.ok && d?.success) {
     return { held: true, until: d.queue_hold_until ?? null, queue_position: d.queue_position ?? null, hold_secs: d.hold_secs ?? holdSecs };
   }
@@ -1188,7 +1224,9 @@ const BOTBUDDY_BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "bin",
 
 /** argv for the park: this CLI's own `bb wait` on the server's condition, bounded by --timeout. */
 export function capacityWaitArgv(condition, timeoutSec) {
-  return [process.execPath, BOTBUDDY_BIN, "wait", condition, "--timeout", String(timeoutSec)];
+  // BOT-2400: the caller chose this bound with --wait-capacity, so it may be under the floor.
+  return [process.execPath, BOTBUDDY_BIN, "wait", condition, "--timeout", String(timeoutSec),
+    "--allow-short-timeout", "bb stack --wait-capacity park"];
 }
 
 /**
@@ -2441,10 +2479,12 @@ export async function cmdUp(opts, {
       try { const read = await call("get_stack_lease", { lease_id: leaseId }); if (read?.ok && read.data?.success && read.data.ledger) ledger = read.data.ledger; } catch { /* keep the request-time ledger */ }
       for (const line of describeUnitLedger(ledger)) process.stderr.write(`stack: ${line}\n`);
       // BOT-2230: keep the queue place for the owner's next attempt instead of losing it.
-      const queueHold = opts.holdOnTimeout ? await holdQueuePlace(call, leaseId, opts.holdOnTimeout) : null;
-      if (queueHold?.held) {
-        process.stderr.write(`stack: lease ${leaseId} keeps queue place ${queueHold.queue_position ?? "?"} until ${queueHold.until} — re-run the same \`stack up\` before then to re-attach (\`stack done ${leaseId}\` gives it up)\n`);
-      } else if (queueHold) {
+      // BOT-2400: by default (`--hold-on-timeout` only shortens it): a park deadline never
+      // gives the place up — only `stack cancel` / `stack done` or the owner's death does.
+      const queueHold = await holdQueuePlace(call, leaseId, opts.holdOnTimeout ?? HOLD_ON_TIMEOUT_MAX_SEC);
+      if (queueHold.held) {
+        process.stderr.write(`stack: lease ${leaseId} keeps queue place ${queueHold.queue_position ?? "?"} until ${queueHold.until} — re-run the same \`stack up\` before then to re-attach (\`stack cancel ${leaseId}\` gives it up)\n`);
+      } else {
         process.stderr.write(`${yellow("⚠")} stack: lease ${leaseId} could not keep its queue place (${queueHold.code ?? "error"}: ${queueHold.error})\n`);
       }
       // BOT-2237: a park that ended inside an unrecovered platform incident never observed admission.
@@ -2452,7 +2492,11 @@ export async function cmdUp(opts, {
       const why = blind
         ? `parked ${opts.timeout}s inside a platform incident (${parked.incident.reason} since ${parked.incident.first_at}), so its admission was never observed`
         : `parked ${opts.timeout}s without capacity`;
-      return emitResult(buildReceipt({ command: "up", outcome: "timeout", ...(blind ? { code: parked.incident.reason } : {}), lease_id: leaseId, state: "queued", slot, error: why, ...(ledger ? { unit_ledger: ledger } : {}), ...(queueHold ? { queue_hold: queueHold } : {}) }), opts, EXIT.TIMEOUT);
+      // BOT-2400: a held place is PARK_DEADLINE; the BOT-2237 incident code still wins when the
+      // park never observed admission (the place is held either way — see queue_hold).
+      const code = blind ? parked.incident.reason : (queueHold.held ? PARK_DEADLINE : PARK_HOLD_UNCONFIRMED);
+      const detail = queueHold.held ? why : `${why}; queue hold unconfirmed; the lease was not cancelled — inspect \`bb stack status ${leaseId}\` before resuming or explicitly cancelling it`;
+      return emitResult(buildReceipt({ command: "up", outcome: "timeout", code, lease_id: leaseId, ...(queueHold.held ? { state: "queued" } : {}), slot, error: detail, ...(ledger ? { unit_ledger: ledger } : {}), queue_hold: queueHold }), opts, EXIT.TIMEOUT);
     }
     if (parked.auth) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: "unauthorized on wait stream" }), opts, EXIT.AUTH);
     if (parked.error) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: parked.error }), opts, EXIT.BACKEND);
@@ -3391,7 +3435,12 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     touch: (leaseId, usage) => rpc.call("touch_stack_lease", { lease_id: leaseId, ...(usage ? { usage } : {}) }),
     // BOT-1803: `{ idle: true }` idles an ACTIVE lease instead of reaping it.
     release: (leaseId, signal, { idle = false } = {}) => rpc.call("release_stack_lease", { lease_id: leaseId, disposition: "destroy", ...(idle ? { idle: true } : {}) }, { signal }),
+    // BOT-2400: keep a queued lease's place when the park deadline passes.
+    hold: (leaseId, holdSecs) => holdQueuePlace((name, args) => rpc.call(name, args), leaseId, holdSecs),
   };
+  // An injected api double without `hold` keeps the pre-BOT-2400 release unless the test also
+  // injected the tool transport (never a real network call from a test).
+  const holdPlace = api.hold ?? (adapters.callTool ? (leaseId, holdSecs) => holdQueuePlace((name, args) => rpc.call(name, args), leaseId, holdSecs) : null);
   const measureUsage = adapters.measureUsage ?? measureStackUsage;
   const machineUuidFn = adapters.machineUuidFn ?? machineUuid;
   const wait = adapters.wait ?? ((leaseId, done, failed, options) => waitForLease(leaseId, done, failed, options));
@@ -3404,9 +3453,9 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   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.
-  const authUnavailableResult = (waited, phase, cleanup) => ({
-    exitCode: EXIT.AUTH, outcome: "error", code: PARK_INCIDENT_REASONS.AUTH, leaseId: leaseId ?? null, cleanup,
-    error: `${waited.error} while the lease was ${phase}; its server state is unknown to this run — inspect it with \`bb stack status ${leaseId}\` after \`bb doctor --fix\``,
+  const authUnavailableResult = (waited, phase, cleanup, waitedLeaseId = leaseId) => ({
+    exitCode: 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 } : {}),
   });
   const resilientWait = async (leaseIdArg, done, failed, options) => {
@@ -3716,6 +3765,7 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     // id: wait for it to reach `reaped`, then send the SAME request once more (it then
     // provisions a fresh lease for the slot).
     let request;
+    let idleRetried = false;
     for (let attempt = 0; ; attempt++) {
       activeWaitAbort = new AbortController();
       const admission = await requestWithCapacityWait(() => api.request(leaseArgs), opts, {
@@ -3756,6 +3806,44 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         if (request?.status == null) leaseProvisioned = true;
         return { exitCode: request?.auth ? EXIT.AUTH : EXIT.BACKEND, outcome: "error", error: request?.error || "lease request failed" };
       }
+      // BOT-2400 (item 6): this agent's OWN previous lease on the slot is still `reaping` (a
+      // provision rollback, an idle reap, the previous batch's teardown). It is not somebody's
+      // live batch: park until it is reaped, then send the same request again.
+      const ownReaping = request.data?.success === true && request.data.reused === true &&
+        request.data.state === "reaping" && request.data.lease_id ? request.data.lease_id : null;
+      if (ownReaping && attempt < 3) {
+        stderrLine(`stack: this slot's previous lease ${ownReaping} is still reaping — waiting for it to reach reaped, then requesting again`);
+        activeWaitAbort = new AbortController();
+        const gone = await resilientWait(ownReaping, (st) => st === "reaped", (st) => st === "reap_failed", { timeoutSec: opts.timeout, auth: rpc.auth, signal: activeWaitAbort.signal });
+        activeWaitAbort = null;
+        if (gone?.interrupted || receivedSignal) {
+          // The previous lease's containers may still own these ports until its reap is proven.
+          retainBlock = true;
+          return { exitCode: SIGNAL_EXIT[receivedSignal] ?? EXIT.INTERNAL, outcome: "interrupted", leaseId: ownReaping };
+        }
+        if (gone?.authUnavailable) {
+          // The old lease can still own this stack's ports. Preserve the definitive credential
+          // terminal instead of misclassifying it as a reap timeout, and do not request another lease.
+          retainBlock = true;
+          return authUnavailableResult(gone, "reaping", undefined, ownReaping);
+        }
+        let reaped = Boolean(gone?.woke) && gone.state === "reaped";
+        if (!reaped && !gone?.failed) {
+          const read = await readLeaseQuietly(ownReaping);
+          reaped = Boolean(read?.ok && read.data?.success && read.data.state === "reaped");
+        }
+        if (!reaped) {
+          // Its containers may still hold this stack's ports.
+          retainBlock = true;
+          return {
+            exitCode: gone?.failed ? EXIT.LEASE_FAILED : EXIT.TIMEOUT, outcome: gone?.failed ? "error" : "timeout", leaseId: ownReaping,
+            error: `this slot's previous lease ${ownReaping} did not reach reaped ${gone?.failed ? "(its reap failed)" : `within ${opts.timeout}s`}; ` +
+              `no new lease was requested — check \`bb stack status ${ownReaping}\``,
+            ...(parkIncident ? { incident: parkIncident } : {}),
+          };
+        }
+        continue;
+      }
       let why = attempt === 0 && request.data?.success === false && request.data?.lease_id ? IDLE_REPROVISION_REASONS[request.data.code] : null;
       // BOT-2403: a re-adopted idle stack is handed over only when its edge runtime still sees
       // the functions (the gate restarts the runtime once). Still broken → reap it and send the
@@ -3780,6 +3868,7 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         }
       }
       if (!why) break;
+      idleRetried = true;
       const previous = request.data.lease_id;
       idleLease.previousLeaseId = previous;
       const becoming = why === "preempted" ? "preempted"
@@ -3833,7 +3922,15 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     // stored connection and nothing is provisioned, so the run goes straight on to the
     // post-activation flow. Any other reuse is somebody's LIVE batch, refused as before.
     const reusedIdle = request.data.reused === true && request.data.reused_idle === true;
-    if (request.data.reused && !reusedIdle) {
+    // BOT-2400 (item 1): this agent's own QUEUED lease for the slot — the place a previous run
+    // kept at its park deadline. This run holds the stack directory's project lock, and the
+    // control plane bound the lease to this same worktree + stack path (it refuses another), so
+    // no live run can be parked on it: re-attach and keep parking at the same place.
+    const reusedQueued = request.data.reused === true && !reusedIdle && request.data.state === "queued";
+    if (reusedQueued) {
+      stderrLine(`stack: re-attached to this slot's queued lease ${leaseId} — it kept its queue place${request.data.queue_position != null ? ` (position ${request.data.queue_position})` : ""}`);
+    }
+    if (request.data.reused && !reusedIdle && !reusedQueued) {
       // 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;
@@ -3877,7 +3974,18 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         }
       }
       // BOT-1803: a re-adopted idle remote stack is already running there; nothing to upload.
-      if (!reusedIdle) {
+      // BOT-2400: a queued lease can also be re-attached after PARK_DEADLINE. The server omits
+      // its one-shot URL once the stored bundle exists, so matching its returned path + digest is
+      // the positive proof that this run must retain the queue place and proceed without a PUT.
+      const reusedQueuedBundle = reusedQueued && bundle &&
+        !request.data.bundle_upload_url &&
+        typeof request.data.bundle_path === "string" && request.data.bundle_path.length > 0 &&
+        request.data.bundle_sha256 === bundle.sha256;
+      if (reusedQueuedBundle) {
+        placement.bundle = { sha256: bundle.sha256, bytes: bundle.size };
+        if (bundle.included?.length) placement.bundleIncluded = bundle.included;
+        stderrLine(`stack: re-attached remote lease ${leaseId} already has the matching stack bundle; keeping its queue place without uploading again`);
+      } else if (!reusedIdle) {
       if (!bundle || !request.data.bundle_upload_url) {
         const cleanup = await requestCleanup();
         return {
@@ -3961,16 +4069,47 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         const final = await readLeaseQuietly(leaseId);
         const ledger = final?.ok && final.data?.success ? final.data.ledger ?? null : null;
         for (const line of describeUnitLedger(ledger)) stderrLine(`stack: ${line}`);
-        const cleanup = await requestCleanup();
         // BOT-2237: a park that ended inside an unrecovered platform incident never observed the
         // lease's admission, so it must not claim the host had no capacity.
-        if (parkIncident && !parkIncident.recovered) {
+        const blind = parkIncident && !parkIncident.recovered;
+        const why = blind
+          ? `lease ${leaseId} parked ${opts.timeout}s inside a platform incident (${parkIncident.reason} since ${parkIncident.first_at}), so its admission was never observed`
+          : `parked ${opts.timeout}s without capacity`;
+        // BOT-2400 (item 1): the park deadline never gives the queue place up. Hold the lease
+        // for the owner's next run (which re-attaches to it) and exit PARK_DEADLINE; only
+        // `stack cancel` / `stack done` or the owner's death releases it.
+        const queueHold = holdPlace ? await holdPlace(leaseId, HOLD_ON_TIMEOUT_MAX_SEC) : null;
+        if (queueHold) {
+          // A refused/lost hold reply is not an owner cancellation: it may have
+          // committed before the reply was lost, or the queued lease may have
+          // just been granted. Preserve both lease and conservative port claim.
+          retainBlock = true;
+          const retainSecs = queueHold.held ? queueHold.hold_secs ?? HOLD_ON_TIMEOUT_MAX_SEC : HOLD_ON_TIMEOUT_MAX_SEC;
+          try { refreshRetention(stackDirFor(execution), { idleTtlSecs: retainSecs, idleRetained: true }); } catch { /* advisory */ }
+          try { execution.renew?.({ idleTtlSecs: retainSecs, idleRetained: true }); } catch { /* advisory */ }
+        }
+        if (queueHold?.held) {
+          stderrLine(`stack: lease ${leaseId} keeps queue place ${queueHold.queue_position ?? "?"} until ${queueHold.until ?? "?"} — re-run the same \`stack run\` to resume it (\`bb stack cancel ${leaseId}\` gives it up)`);
           return {
-            exitCode: EXIT.TIMEOUT, outcome: "timeout", code: parkIncident.reason, leaseId, cleanup, ...incident, ...(ledger ? { ledger } : {}),
-            error: `lease ${leaseId} parked ${opts.timeout}s inside a platform incident (${parkIncident.reason} since ${parkIncident.first_at}), so its admission was never observed`,
+            exitCode: EXIT.TIMEOUT, outcome: "timeout", code: blind ? parkIncident.reason : PARK_DEADLINE, leaseId, state: "queued", queueHold,
+            error: `${why}; lease ${leaseId} is still queued and keeps its place — re-run the same command to resume it`,
+            ...incident, ...(ledger ? { ledger } : {}),
           };
         }
-        return { exitCode: EXIT.TIMEOUT, outcome: "timeout", leaseId, error: `parked ${opts.timeout}s without capacity`, cleanup, ...incident, ...(ledger ? { ledger } : {}), ...(parkReason ? { parkReason } : {}) };
+        if (queueHold) {
+          stderrLine(`${yellow("⚠")} stack: lease ${leaseId} queue hold unconfirmed (${queueHold.code ?? "error"}: ${queueHold.error}); the lease was not cancelled — inspect \`bb stack status ${leaseId}\``);
+          return {
+            exitCode: EXIT.TIMEOUT, outcome: "timeout", code: blind ? parkIncident.reason : PARK_HOLD_UNCONFIRMED,
+            leaseId, queueHold,
+            error: `${why}; queue hold unconfirmed; the lease was not cancelled — inspect \`bb stack status ${leaseId}\` before resuming or explicitly cancelling it`,
+            ...incident, ...(ledger ? { ledger } : {}), ...(parkReason ? { parkReason } : {}),
+          };
+        }
+        const cleanup = await requestCleanup();
+        return {
+          exitCode: EXIT.TIMEOUT, outcome: "timeout", ...(blind ? { code: parkIncident.reason } : {}), leaseId, error: why, cleanup,
+          ...incident, ...(ledger ? { ledger } : {}), ...(queueHold ? { queueHold } : {}), ...(parkReason ? { parkReason } : {}),
+        };
       }
       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 }; }
@@ -4267,6 +4406,9 @@ export function runReceiptFields(result) {
     // incident (reason, window, attempts, recovered) — never as the lease's outcome.
     ...(result.incident ? { platform_incident: result.incident } : {}),
     ...(result.ledger ? { unit_ledger: result.ledger } : {}),
+    // BOT-2400: a PARK_DEADLINE run names the lease's state (still queued) and the place it holds.
+    ...(result.state ? { state: result.state } : {}),
+    ...(result.queueHold ? { queue_hold: result.queueHold } : {}),
     // BOT-2237: whether this run handed its host port block back, or kept it and why.
     ...(result.portBlock ? { port_block: result.portBlock } : {}),
   };

package/src/test-lane.mjs

@@ -176,18 +176,29 @@ export async function launchTestLane(argv, {
     return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", errors }) };
   }
   let managedCredential = null;
-  if (!opts.sessionId && !opts.sessionToken) {
-    // Test doubles intentionally do not self-mint. The shipped command does,
-    // using exactly the same cache/re-adoption resolver as `bb wait` and `run`.
+  // A session id names a session but is not an API credential. Resolve the
+  // worktree's token even when the caller supplied --session-id, so the
+  // create/update calls are authenticated and the launched lane has a durable
+  // test-run to wait on. Without this, an otherwise valid explicit id could
+  // launch a real test with test_run_id:null and no supported wait condition.
+  //
+  // Test doubles that provide only a synthetic session id retain the old
+  // no-network seam. Production, and every caller that supplies a resolver,
+  // must resolve the token or fail before launching an untrackable run.
+  const mustResolveCredential = !opts.sessionToken
+    && (!opts.sessionId || !!resolveCredential || call === callToolJson);
+  if (mustResolveCredential) {
     if (!resolveCredential && call !== callToolJson) {
       process.stderr.write("botbuddy test: --session-id is required (or set BOTBUDDY_AGENT_SESSION_TOKEN)\n");
       return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", errors: ["--session-id is required"] }) };
     }
     try {
-      const credential = await (resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd });
+      const credential = await (resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd, sessionId: opts.sessionId });
       managedCredential = credential;
       opts.sessionToken = credential.token;
-      opts.sessionId = credential.sessionId ?? null;
+      // --session-id is a deliberate caller choice. The resolved token proves
+      // authority; it must not silently replace the session the caller named.
+      opts.sessionId ??= credential.sessionId ?? null;
     } catch (error) {
       const code = error?.code ?? "agent_session_unavailable";
       process.stderr.write(`botbuddy test: ${error?.message ?? code}\n`);

package/src/wait-core.mjs

@@ -44,11 +44,15 @@ const LEASE_UUID_SPELLING = /^(?:\{(?=.*\}$)|(?!.*\}$))((?:[0-9a-f]{4}-?){7}[0-9
 
 // BOT-2013: stack_lease frame states that mean the lease is gone, not granted.
 export const LEASE_LOST_STATES = Object.freeze(new Set(["reaping", "reaped", "reap_failed"]));
+// BOT-2400: the lease states a `lease:id=…,state=<s>` wait may target.
+export const LEASE_WAIT_STATES = Object.freeze(["provisioning", "active", "reaped"]);
 
 /** The lease-lost detail for a matched lease frame, or null when the frame is a grant. */
 export function leaseLostDetail(signal, condition) {
   if (condition?.type !== "lease" || signal?.signal_type !== "stack_lease") return null;
   const leaseState = signal.payload?.state;
+  // BOT-2400: the state a `state=` wait asked for is its match, never a loss.
+  if (condition.params?.state != null && leaseState === condition.params.state) return null;
   if (!LEASE_LOST_STATES.has(leaseState)) return null;
   return {
     lease_id: signal.payload?.lease_id ?? condition.params?.id ?? null,
@@ -205,7 +209,15 @@ const VALIDATORS = {
     const m = LEASE_UUID_SPELLING.exec(raw);
     const hex = m ? m[1].replace(/-/g, "") : null;
     const id = hex ? `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}` : raw;
-    return { id };
+    // BOT-2400 (folds BOT-1938): `state=` waits for that exact lease state, level-triggered by
+    // the register-time snapshot. `state=reaped` is the reap wait: a `reaping` lease keeps
+    // waiting instead of ending lease_lost, and an already-reaped lease matches at once.
+    if (p.state === undefined) return { id };
+    const state = String(p.state).trim().toLowerCase();
+    if (!LEASE_WAIT_STATES.includes(state)) {
+      throw new Error(`lease state must be one of ${LEASE_WAIT_STATES.join(", ")}`);
+    }
+    return { id, state };
   },
   // BOT-2330: terminal state for one owner/session-bound managed allocation.
   // Both fences are required so a stale wait cannot observe a later reuse.
@@ -241,9 +253,9 @@ const VALIDATORS = {
   // slots. Capacity is host-shared (no tenant), so `policy` is recorded for intent
   // but matching is by free-slot threshold + optional host pin. `slots>=N` parses
   // as the bare key `slots>` (parseParams splits on the first '='); `min_slots=N`
-  // is an alias. `stale_grace` bounds the wait: with no host beacon in the schema,
-  // if the threshold isn't reached within the grace the wait exits
-  // capacity_source_stale (degraded) rather than hanging forever.
+  // is an alias. `stale_grace` is still parsed for older automation, but since BOT-2400 a
+  // stale capacity source never ends the wait: it is reported as degraded and the wait
+  // keeps parking to its --timeout.
   capacity(p) {
     if (!p.policy) throw new Error("capacity needs policy=<name>");
     const rawMin = p["slots>"] ?? p.min_slots ?? p.slots;
@@ -825,6 +837,10 @@ export function truncateReceipt(receipt, maxBytes = 10240) {
       state: leaseLostState ?? { truncated: true },
       truncated: true,
       ...(clone.client ? { client: clone.client } : {}),
+      ...(clone.degraded?.includes("capacity_source_sustained") ? {
+        degraded: ["capacity_source_stale", "capacity_source_sustained"],
+        stale_since: clone.stale_since ?? null,
+      } : {}),
     };
     for (const key of ["next_cursor", "wait_session_id"]) {
       if (clone[key] == null) continue;
@@ -840,6 +856,10 @@ export function truncateReceipt(receipt, maxBytes = 10240) {
       error: typeof clone.error === "string" ? clone.error.slice(0, 48) : "receipt_truncated",
       truncated: true,
       ...(clone.client ? { client: clone.client } : {}),
+      ...(clone.degraded?.includes("capacity_source_sustained") ? {
+        degraded: ["capacity_source_stale", "capacity_source_sustained"],
+        stale_since: clone.stale_since ?? null,
+      } : {}),
     };
     // BOT-1590: the recovery hint is the whole point of an error receipt, so keep
     // it (trimmed to whatever still fits the cap) rather than dropping it — a
@@ -1038,7 +1058,17 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
       // BOT-1220: recipient-scoped stack-lease transition (queued→provisioning, or
       // →active). The relay only delivers it to the lease's owning agent, so any
       // stack_lease frame for this lease id is ours to wake on.
-      return signal.signal_type === "stack_lease" && signal.subject_key === `lease:${params.id}`;
+      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.
+      if (params.state != null) {
+        const leaseState = signal.payload?.state;
+        if (leaseState === params.state) return true;
+        if (params.state === "reaped") return leaseState === "reap_failed";
+        return LEASE_LOST_STATES.has(leaseState);
+      }
+      return true;
     case "managed-allocation": {
       const p = signal.payload;
       return signal.signal_type === "managed_allocation" && signal.subject_key === `allocation:${params.id}` &&
@@ -1358,6 +1388,7 @@ export async function runWaitLoop({
   backoff = (attempt) => nextBackoff(attempt),
   sleep = null,
   onFrame = null,
+  onCapacitySourceSustained = null,
   startedAt: originalStartedAt = null,
   // BOT-1259: the wait session's server-resolved tenant (from the register echo). A
   // tenanted spine signal only matches a session resolved to that tenant; `null` (the
@@ -1381,19 +1412,8 @@ export async function runWaitLoop({
   // On an expired recovery, replay only durable rows created before this original
   // deadline; the caller supplies a short transport grace via deadlineMs.
   replayOnlyThroughMs = null,
-  // BOT-1148: after a beacon-driven source_stale:true transition on a HOST-PINNED
-  // capacity wait, wait this long for a recovery (source_stale:false) before exiting
-  // capacity_source_stale. Absorbs threshold flap on the client (the server latch is
-  // the primary hysteresis); 0 = exit immediately on the stale signal. Injectable so
-  // a clock-controlled test can drive it. Not a grammar surface (no new condition name).
-  //
-  // Default MUST exceed the beacon evaluator's worst-case cadence (Codex P2). Before
-  // BOT-2024 the recovery transition was emitted only by the `* * * * *` (60s)
-  // eval_container_beacon_staleness cron, so a host that resumed polling right after a
-  // stale emission had its recovery frame arrive up to ~60s later. Since BOT-2024 the
-  // beacon itself (claim_container_job / attested registerHost) emits the recovery, so
-  // the frame now lands on the Helper's next beacon; 90s still covers one ~45-60s
-  // Helper beacon interval plus margin, and an older server's cron-only recovery.
+  // BOT-1148's beacon-stale confirm window. BOT-2400 (item 8): a stale capacity source no
+  // longer ends a wait, so this is accepted only for callers that still pass it (no effect).
   beaconConfirmMs = 90_000,
   // BOT-1837: the arm-time notice (if any) to carry into a TIMEOUT receipt's
   // `error`, so the receipt itself says what CI was already doing when this wait
@@ -1427,6 +1447,8 @@ export async function runWaitLoop({
   const pendingReplayBeaconFrames = [];
   let pendingReplaySupersession = null;
   const degraded = [];
+  const sustainedHosts = new Map();
+  const sustainedNotices = new Map();
   // BOT-2351: `reconnects` counts every stream rotation for the receipt (an operator
   // still sees churn); `failures` counts CONSECUTIVE failed connects — a connect that
   // threw, or a stream that ended before delivering a single frame — and is reset by any
@@ -1457,11 +1479,9 @@ export async function runWaitLoop({
   };
 
   const finalize = async (outcome, extra = {}) => {
-    // A terminal receipt supersedes any pending alarm/confirm window — cancel their timers so
-    // none outlives the wait and holds the event loop open (Codex round-40 P2). clearStale
-    // ConfirmTimer is defined further down but only reached at runtime, after setup completes.
+    // A terminal receipt supersedes any pending alarm — cancel their timers so none outlives
+    // the wait and holds the event loop open (Codex round-40 P2).
     clearPendingAlarmTimers();
-    clearStaleConfirmTimer?.();
     // BOT-1147 (Codex P2): re-check Linear feed freshness before EVERY terminal receipt
     // (timeout, capacity-stale, signal match, error) via this single finalization path —
     // not just the alarm path — so a mixed wait (e.g. `linear` + `pr-review`) that
@@ -1485,6 +1505,12 @@ export async function runWaitLoop({
       error: extra.error ?? null,
       reacquireLock: extra.reacquireLock ?? null,
     });
+    // Keep the server's oldest outstanding outage clock on every terminal path.
+    if (sustainedHosts.size > 0) {
+      receipt.stale_since = [...sustainedHosts.values()]
+        .filter((value) => typeof value === "string" && Number.isFinite(Date.parse(value)))
+        .sort((a, b) => Date.parse(a) - Date.parse(b))[0] ?? null;
+    }
     return { receipt: truncateReceipt(receipt, receiptMaxBytes), exitCode: extra.exitCode };
   };
 
@@ -1529,20 +1555,13 @@ export async function runWaitLoop({
     .filter((a) => Number.isFinite(a.atMs))
     .map((a) => ({ ...a, kind: "match" }));
   if (deadlineMs != null) alarms.push({ kind: "timeout", atMs: deadlineMs });
-  // BOT-1065: a capacity condition degrades to a BOUNDED stale exit rather than
-  // hanging. There is no host self-report beacon in the schema (capacity is derived
-  // from permits), so we cannot observe silent helper death directly; the grace
-  // window is the truthful bound — if the requested free-slot threshold isn't
-  // reached within it, the wait exits with a capacity_source_stale error receipt
-  // (degraded) on an EXISTING exit code (5), never a new numeric code (AC 3).
-  for (const c of conditions) {
-    if (c.type === "capacity" && c.params.staleGraceSec != null) {
-      const staleAtMs = Number.isFinite(c.params.staleDeadlineMs)
-        ? c.params.staleDeadlineMs
-        : now() + c.params.staleGraceSec * 1000;
-      alarms.push({ kind: "stale", conditionId: c.id, atMs: staleAtMs });
-    }
-  }
+  // BOT-1065 bounded a capacity wait with a terminal `stale_grace` alarm (exit 5
+  // capacity_source_stale). BOT-2400 (item 8): a stale capacity source HOLDS the wait
+  // instead of ending it, so the grace no longer arms a terminal alarm: the wait keeps parking to its own --timeout and
+  // re-evaluates when the beacon returns (the beacon-stale path below folds the degraded
+  // marker). A Helper worker that is briefly down (ENT-5492, 2026-10-14 22:32→22:47Z) must
+  // cost a longer wait, never a failed wait plus a token-expensive re-arm. `stale_grace=` is
+  // still accepted (and recorded on a checkpoint) for older automation.
   const earliest = alarms.length ? alarms.reduce((m, a) => (a.atMs < m.atMs ? a : m)) : null;
   // A recovered wait may have alarms that were already due at its original
   // deadline. Do not put those into the initial race: the durable replay must
@@ -1560,12 +1579,6 @@ export async function runWaitLoop({
     // finalization path), so every terminal receipt gets it — not just the alarm path.
     if (!alarm) return null;
     if (alarm.kind === "timeout") return finalize("timeout", { exitCode: EXIT.TIMEOUT, error: timeoutError ?? null });
-    if (alarm.kind === "stale") {
-      // Capacity source didn't deliver within the grace: degrade truthfully and
-      // exit with an error receipt (not a silent hang, not a plain timeout).
-      if (!degraded.includes("capacity_source_stale")) degraded.push("capacity_source_stale");
-      return finalize("error", { exitCode: EXIT.BACKEND, error: "capacity_source_stale" });
-    }
     const condition = conditions.find((c) => c.id === alarm.conditionId);
     return finalize("matched", {
       exitCode: EXIT.MATCHED,
@@ -1640,84 +1653,59 @@ export async function runWaitLoop({
     }
   };
 
-  // BOT-1148: server-side, beacon-driven capacity staleness. On a container_capacity
-  // frame carrying source_stale:true whose host matches a HOST-PINNED capacity wait,
-  // fold capacity_source_stale and — unless a recovery (source_stale:false) arrives
-  // within beaconConfirmMs — exit 5 fast (server-driven) instead of grinding the full
-  // client stale_grace backstop. Un-pinned capacity waits ignore a single host's
-  // beacon signal: another live host may still serve them (AC-4), so they keep only
-  // the grace backstop. A recovery clears the marker and lets the wait continue
-  // without re-registration (AC-3), and may itself grant if it carries free_slots.
+  // BOT-1148: server-side, beacon-driven capacity staleness. A container_capacity frame
+  // carrying source_stale:true whose host matches a HOST-PINNED capacity wait folds
+  // capacity_source_stale into `degraded`; a recovery (source_stale:false, or any normal
+  // capacity frame — BOT-2100) clears it and may itself grant. BOT-2400 (item 8): the stale
+  // state is degraded, never terminal — the BOT-1148 confirm-window fast-fail (exit 5) is
+  // gone, so the wait stays armed and re-evaluates when the beacon returns. Un-pinned
+  // capacity waits ignore a single host's beacon (another live host may serve them, AC-4).
   const hostPinnedCapacity = conditions.filter((c) => c.type === "capacity" && c.params.host != null);
-  // PER-HOST stale-confirm state (Codex P2): keyed by the pinned host_key. A recovery
-  // from host B must never cancel host A's pending confirm — with a single shared timer,
-  // an --any wait pinned to multiple hosts would miss A's fast-fail when B recovers.
-  const staleConfirm = new Map();  // hostKey -> atMs the confirm window elapses
-  let staleConfirmPromise = null;  // races the EARLIEST pending confirm across hosts
-  let staleConfirmTimer = null;    // handle for that race's real timer, so it can be cancelled
-  // Cancel any pending confirm timer. The race timer is a REAL setTimeout (not the injected
-  // `sleep`) precisely so it is cancellable: re-arming, a host recovery, or a terminal
-  // finalize supersedes the pending confirm, and an ORPHANED confirm timer would otherwise
-  // keep the process (and the checked-in `pnpm test:bb-wait` lane) alive for the full
-  // beaconConfirmMs window — the parent suite ran ~6.5s, this leak made it ~92s (Codex
-  // round-40 P2). Same "real timer, tracked so it can be cleared" discipline as the alarm
-  // timers above.
-  const clearStaleConfirmTimer = () => {
-    if (staleConfirmTimer != null) { clearTimeout(staleConfirmTimer); staleConfirmTimer = null; }
-  };
+  // PER-HOST stale state (Codex P2): host B's recovery never clears host A's marker.
+  const staleHosts = new Set();
   const beaconHostKey = (signal) => {
     const match = hostPinnedCapacity.find(
       (c) => c.params.host === signal.subject_key || c.params.host === signal.payload?.host_key,
     );
     return match ? match.params.host : null;
   };
-  const armStaleConfirmRace = () => {
-    clearStaleConfirmTimer(); // supersede any prior pending confirm — never leak its timer
-    if (staleConfirm.size === 0) { staleConfirmPromise = null; return; }
-    const soonest = Math.min(...staleConfirm.values());
-    staleConfirmPromise = new Promise((resolve) => {
-      staleConfirmTimer = setTimeout(() => {
-        staleConfirmTimer = null;
-        resolve({ __staleConfirm: true });
-      }, Math.max(0, soonest - now()));
-    });
-  };
-  // Returns "continue" (skip this frame), "fallthrough" (let matchFrame see it), or
-  // "exit" (terminate immediately on a stale signal when beaconConfirmMs<=0).
+  // The frame always goes on to matchFrame afterwards: a raw
+  // `event:type=container_capacity,subject=<host>` escape-hatch condition must still observe
+  // beacon-stale transitions (Codex round-23/24 P2), and the `capacity` matcher refuses to
+  // grant on a source_stale frame, so a stale frame is never a false grant.
   const applyBeaconStale = (signal) => {
-    const stale = signal.payload.source_stale === true;
+    if (signalTenantBlocked(signal, sessionTenant)) return;
     const hostKey = beaconHostKey(signal);
-    // Not a host this wait pins a `capacity` condition to (un-pinned / other host):
-    // fall through to matchFrame instead of swallowing the frame. A raw
-    // `event:type=container_capacity,subject=<host>` escape-hatch condition must be
-    // able to observe beacon-stale transitions (Codex round-23 P2); the `capacity`
-    // matcher already refuses to grant on a source_stale frame, so no false grant.
-    if (hostKey == null) return "fallthrough";
-    if (stale) {
-      if (!degraded.includes("capacity_source_stale")) degraded.push("capacity_source_stale");
-      if (beaconConfirmMs <= 0) return "exit";
-      if (!staleConfirm.has(hostKey)) {
-        staleConfirm.set(hostKey, now() + beaconConfirmMs);
-        armStaleConfirmRace();
+    if (hostKey == null) return;
+    if (signal.payload.source_stale === true) {
+      staleHosts.add(hostKey);
+      noteDegraded("capacity_source_stale");
+      if (signal.payload.phase === "sustained") {
+        const since = typeof signal.payload.stale_since === "string" &&
+          Number.isFinite(Date.parse(signal.payload.stale_since)) ? signal.payload.stale_since : null;
+        sustainedHosts.set(hostKey, since);
+        noteDegraded("capacity_source_sustained");
+        if (!sustainedNotices.has(hostKey) || sustainedNotices.get(hostKey) !== since) {
+          sustainedNotices.set(hostKey, since);
+          onCapacitySourceSustained?.({ host_key: hostKey, stale_since: since });
+        }
+      } else if (signal.payload.phase === "transient") {
+        sustainedHosts.delete(hostKey);
       }
-      // Arm the confirm race, but DON'T consume the frame — fall through to matchFrame
-      // (Codex round-23/24 P2). A wait that pins a `capacity` condition to this host AND
-      // carries a raw `event:type=container_capacity,subject=<same-host>` must still let
-      // the raw condition wake on the transition. The `capacity` matcher refuses to
-      // grant on a source_stale frame (never a false grant), and a host-pinned-only wait
-      // simply finds no match here and keeps waiting on the confirm race as before.
-      return "fallthrough";
+    } else {
+      staleHosts.delete(hostKey);
+      sustainedHosts.delete(hostKey);
+      sustainedNotices.delete(hostKey);
     }
-    // Recovery for THIS host only: drop its confirm; keep the marker while any OTHER
-    // pinned host is still pending-stale. Fall through so a recovery carrying
-    // free_slots >= minSlots can grant normally.
-    staleConfirm.delete(hostKey);
-    if (staleConfirm.size === 0) {
-      const i = degraded.indexOf("capacity_source_stale");
-      if (i !== -1) degraded.splice(i, 1);
+    for (const [marker, active] of [
+      ["capacity_source_stale", staleHosts.size > 0],
+      ["capacity_source_sustained", sustainedHosts.size > 0],
+    ]) {
+      if (!active) {
+        const i = degraded.indexOf(marker);
+        if (i !== -1) degraded.splice(i, 1);
+      }
     }
-    armStaleConfirmRace();
-    return "fallthrough";
   };
 
   while (true) {
@@ -1776,7 +1764,6 @@ export async function runWaitLoop({
         ));
       }
       const racers = [deadlinePromise, pendingNext];
-      if (staleConfirmPromise) racers.push(staleConfirmPromise);
       if (preDeadlineProbePromise && !preDeadlineProbeDone) racers.push(preDeadlineProbePromise);
       const raced = await Promise.race(racers);
 
@@ -1800,24 +1787,6 @@ export async function runWaitLoop({
         await probeFeedLag();
         continue;
       }
-      // BOT-1148: the beacon-stale confirm window elapsed. If still stale (no recovery
-      // cleared it), exit fast on the existing code 5; otherwise drop the settled
-      // confirm promise and keep waiting — pendingNext stays in flight, re-raced next
-      // iteration, so no frame is dropped.
-      if (raced && raced.__staleConfirm) {
-        // Any pinned host whose confirm window elapsed while STILL stale → fast-fail.
-        // A recovery from a different host already removed its own entry, so it can't
-        // suppress this one (Codex P2, per-host).
-        const anyDue = [...staleConfirm.values()].some((atMs) => now() >= atMs);
-        if (anyDue) {
-          if (!degraded.includes("capacity_source_stale")) degraded.push("capacity_source_stale");
-          return finalize("error", { exitCode: EXIT.BACKEND, error: "capacity_source_stale" });
-        }
-        // A settled promise whose host recovered before firing: re-arm for the next
-        // pending host (if any) and keep waiting — pendingNext stays in flight.
-        armStaleConfirmRace();
-        continue;
-      }
       // raced settled from pendingNext (a frame result) — consume it before the next read.
       pendingNext = null;
       const { value: frame, done } = raced;
@@ -1895,7 +1864,6 @@ export async function runWaitLoop({
       if (frame.event === "replay_complete") {
         replayPending = false;
         replayFrontier = cursor;
-        let pendingBeaconExit = null;
         // A replay terminal is a point-in-time receipt. Beacon state after an
         // earlier match/supersession cannot affect that receipt.
         let terminalSeq = [
@@ -1909,13 +1877,7 @@ export async function runWaitLoop({
           // They are only transport catch-up, never evidence for the terminal
           // receipt, so they must not alter stale confirmation state either.
           if (!pendingBeaconFrame.beforeReplayDeadline) continue;
-          const disposition = applyBeaconStale(pendingBeaconFrame.signal);
-          if (disposition === "exit") {
-            pendingBeaconExit = pendingBeaconFrame;
-            terminalSeq = pendingBeaconFrame.seqKey;
-            break;
-          }
-          if (disposition !== "fallthrough" || !pendingBeaconFrame.beforeReplayDeadline) continue;
+          applyBeaconStale(pendingBeaconFrame.signal);
           if (signalTenantBlocked(pendingBeaconFrame.signal, sessionTenant)) continue;
           const matched = matchFrame(pendingBeaconFrame.frame, conditions, waitSessionId, sessionTenant);
           if (!matched) continue;
@@ -1938,7 +1900,6 @@ export async function runWaitLoop({
         const replayCandidate = [
           pendingMatch && { kind: "match", ...pendingMatch },
           pendingReplaySupersession && { kind: "superseded", ...pendingReplaySupersession },
-          pendingBeaconExit && { kind: "beacon_stale", ...pendingBeaconExit },
         ].filter(Boolean).sort((a, b) => BigInt(a.seqKey) < BigInt(b.seqKey) ? -1 : BigInt(a.seqKey) > BigInt(b.seqKey) ? 1 : 0)[0] ?? null;
         if (replayCandidate) {
           const candidateAtMs = Date.parse(replayCandidate.signal.created_at);
@@ -1946,9 +1907,6 @@ export async function runWaitLoop({
             return fireAlarm(restoredAlarm);
           }
           if (replayCandidate.kind === "superseded") return finalizeSuperseded(replayCandidate.signal);
-          if (replayCandidate.kind === "beacon_stale") {
-            return finalize("error", { exitCode: EXIT.BACKEND, error: "capacity_source_stale" });
-          }
           const terminal = await finalizeMatch(replayCandidate.entry, replayCandidate.signal);
           if (onFrame) {
             await onFrame(replayCandidate.signal, {
@@ -2026,15 +1984,8 @@ export async function runWaitLoop({
           pendingReplayBeaconFrames.push({ frame, signal, seqKey, beforeReplayDeadline });
           continue;
         }
-        const disposition = applyBeaconStale(signal);
-        if (disposition === "exit") {
-          return finalize("error", { exitCode: EXIT.BACKEND, error: "capacity_source_stale" });
-        }
-        if (disposition === "continue") {
-          await checkpointNonterminalFrame();
-          continue;
-        }
-        // "fallthrough": let matchFrame see the frame — a recovery may grant via
+        applyBeaconStale(signal);
+        // Let matchFrame see the frame — a recovery may grant via
         // free_slots, and a raw `event` condition may match a stale frame (the
         // `capacity` matcher itself never grants on source_stale).
       }

package/src/wait.mjs

@@ -107,6 +107,10 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       becoming active — the zero-poll wake for a parked
                                       \`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).
   guidance:request=<post_id>          a command-post guidance request being answered
                                       (scoped to the asking agent; fetch the body with
                                       get_guidance_response)
@@ -123,8 +127,9 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
   capacity:policy=<p>,slots>=<N>[,host=<h>][,stale_grace=<sec>]
                                       a managed-container host reaching >= N free slots.
                                       Host-shared; a silently-dead host is detected server-side
-                                      (capacity_source_stale) via a host beacon — the client
-                                      grace (default 900s) is a backstop, no longer the only guard.
+                                      (capacity_source_stale) via a host beacon. BOT-2400: a stale
+                                      source is DEGRADED, never terminal — the wait stays armed and
+                                      re-evaluates when the beacon returns (stale_grace is ignored).
                                       Grants are RANKED (BOT-1577): when several waiters
                                       contend, a freed slot is handed to the highest-scored
                                       one and its receipt carries grant:{position,tier,score};
@@ -152,7 +157,13 @@ 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.
+  --timeout <seconds>   safety cap (default 86400 = 24 h; hard cap 259200 = 72 h). Timeout is exit 2,
+                        not an error. The timeout is a SAFETY CAP measured in hours or days, never a
+                        polling interval: every re-arm wakes you and re-reads your whole context. A
+                        cap under 7200 s on a non-timer wait exits 4 timeout_too_short (BOT-2400).
+  --allow-short-timeout <reason>
+                        accept a cap under 7200 s (a CI job budget, a probe); the reason is recorded
+                        on the wait. Automation may set $BOTBUDDY_WAIT_SHORT_TIMEOUT_REASON instead.
   --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)
@@ -194,27 +205,55 @@ OUTPUT
 
 EXAMPLES
   # wait for a Playwright lane to free up, then acquire it yourself
-  botbuddy wait 'lock:subtype=playwright_lane,host=Jonos-MBP' --timeout 1800
+  botbuddy wait 'lock:subtype=playwright_lane,host=Jonos-MBP'
 
   # queue for a specific lane and be HANDED it when it frees (no acquire race):
   #   acquire_lock (gets queued) → bb-wait claim=true → wake already holding lane 3
-  botbuddy wait 'lock:subtype=playwright_lane,host=Jonos-MBP,slot=3,claim=true' --timeout 1800 --heartbeat
+  botbuddy wait 'lock:subtype=playwright_lane,host=Jonos-MBP,slot=3,claim=true' --heartbeat
 
   # wait for a chat reply on any channel, or 20 minutes, whichever first
   botbuddy wait --any 'chat:channel=*' 'timer:duration=1200' --heartbeat
 
   # after pushing review fixes, wait for the next review comment or a state change
   botbuddy wait --any 'pr-review:repo=bot-buddy/botbuddy-webapp,pr=425' \\
-                'pr-state:repo=bot-buddy/botbuddy-webapp,pr=425' --timeout 3600
+                'pr-state:repo=bot-buddy/botbuddy-webapp,pr=425'
 
 ${SETUP_BLOCK}
 `;
 
+// BOT-2400: a wait's timeout is a SAFETY CAP measured in hours or days, never a polling
+// interval. Each re-arm wakes the agent and re-reads its whole context (ENT-4850 §18: 15
+// wakes ≈ 50M tokens), so the default is a day, the cap three days, and a cap under two hours
+// on a non-timer wait is refused unless the caller says why (--allow-short-timeout).
+export const DEFAULT_WAIT_TIMEOUT_SEC = 24 * 3600;
+export const MAX_WAIT_TIMEOUT_SEC = 72 * 3600;
+export const MIN_WAIT_TIMEOUT_SEC = 2 * 3600;
+const SHORT_TIMEOUT_REASON_ENV = "BOTBUDDY_WAIT_SHORT_TIMEOUT_REASON";
+const SHORT_TIMEOUT_REASON_MAX = 300;
+
+/**
+ * BOT-2400: the short-timeout gate. Returns null when the wait may arm, else the refusal.
+ * `timer:`-only waits are exempt (the timer IS the wake); a resume keeps its saved deadline.
+ */
+export function shortTimeoutRefusal({ timeoutSec, conditions, reason, resuming = false }) {
+  if (resuming || !(timeoutSec < MIN_WAIT_TIMEOUT_SEC)) return null;
+  if (conditions.every((condition) => condition.type === "timer")) return null;
+  if (typeof reason === "string" && reason.trim()) return null;
+  return {
+    error: "timeout_too_short",
+    minimum_timeout_seconds: MIN_WAIT_TIMEOUT_SEC,
+    recovery: `a wait's --timeout is a safety cap in hours or days, never a polling interval: omit it (default ${DEFAULT_WAIT_TIMEOUT_SEC} s) or pass at least ${MIN_WAIT_TIMEOUT_SEC} s. ` +
+      `A caller that genuinely needs a short cap (a CI job budget, a probe) passes --allow-short-timeout "<reason>" (or ${SHORT_TIMEOUT_REASON_ENV}); the reason is recorded on the wait.`,
+  };
+}
+
 function parseArgv(argv) {
   const opts = {
     conditions: [],
     mode: "any",
-    timeout: 7200,
+    timeout: DEFAULT_WAIT_TIMEOUT_SEC,
+    // BOT-2400: why this wait needs a cap under MIN_WAIT_TIMEOUT_SEC (recorded on the wait).
+    shortTimeoutReason: process.env[SHORT_TIMEOUT_REASON_ENV] || null,
     since: null,
     sinceProvided: false,
     receiptMaxBytes: 10240,
@@ -248,6 +287,7 @@ function parseArgv(argv) {
     else if (a === "--any") opts.mode = "any";
     else if (a === "--heartbeat") opts.heartbeat = true;
     else if (a === "--timeout") opts.timeout = Number(optionValue());
+    else if (a === "--allow-short-timeout") opts.shortTimeoutReason = optionValue();
     else if (a === "--deadline-at") opts.deadlineAt = optionValue(); // internal recovery argv; never shown as public API
     else if (a === "--since") { opts.sinceProvided = true; opts.since = optionValue(); }
     else if (a === "--receipt-max-bytes") opts.receiptMaxBytes = Number(optionValue());
@@ -317,6 +357,8 @@ async function registerWait(opts, conditions, deadlineIso) {
     // wait will NOT replay itself.
     since: String(opts.since ?? -1),
     ...(opts.localWaitId ? { local_wait_id: opts.localWaitId } : {}),
+    // BOT-2400: a cap under the floor was asked for on purpose; the relay records why.
+    ...(opts.shortTimeoutReasonApplied ? { short_timeout_reason: opts.shortTimeoutReasonApplied } : {}),
     ...(opts.expectedAgentId ? {
       expected_agent_id: opts.expectedAgentId,
       expected_tenant_id: opts.expectedTenantId ?? null,
@@ -525,6 +567,10 @@ async function registerWait(opts, conditions, deadlineIso) {
     // pr-review/pr-state target. Report-only — surfaced on stderr so a silent
     // edge-triggered park isn't mistaken for "no review yet".
     prReviewSnapshot: Array.isArray(body.pr_review_snapshot) ? body.pr_review_snapshot : null,
+    // BOT-2400: how often this session already armed this exact condition set (24 h), and
+    // the relay's warning once that reaches 3.
+    rearmCount: Number.isInteger(body.rearm_count) ? body.rearm_count : null,
+    rearmWarning: typeof body.rearm_warning === "string" ? body.rearm_warning : null,
     // BOT-1837: what CI had already done on the branch at arm time. An ABSENT
     // arm_context (a pre-BOT-1837 relay, or a condition that isn't scope=next
     // with a branch) and an explicit `latest_run: null` both collapse to null —
@@ -1613,7 +1659,19 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
     });
     process.exit(EXIT.INVALID);
   }
-  const timeoutSec = Math.min(opts.timeout, 28800); // 8h hard cap (session-budget gate)
+  // BOT-2400: refuse a short cap before anything is armed (exit 4, names the floor).
+  const shortRefusal = shortTimeoutRefusal({
+    timeoutSec: opts.timeout, conditions, reason: opts.shortTimeoutReason, resuming: Boolean(opts.resumeLocalWait),
+  });
+  if (shortRefusal) {
+    process.stderr.write(`bb-wait: --timeout ${opts.timeout} is under the ${MIN_WAIT_TIMEOUT_SEC} s floor — ${shortRefusal.recovery}\n`);
+    emitReceipt({ schema_version: 1, outcome: "error", ...shortRefusal });
+    process.exit(EXIT.INVALID);
+  }
+  if (opts.timeout < MIN_WAIT_TIMEOUT_SEC && !conditions.every((condition) => condition.type === "timer") && !opts.resumeLocalWait) {
+    opts.shortTimeoutReasonApplied = String(opts.shortTimeoutReason).trim().slice(0, SHORT_TIMEOUT_REASON_MAX);
+  }
+  const timeoutSec = Math.min(opts.timeout, MAX_WAIT_TIMEOUT_SEC); // BOT-2400: 72 h hard cap
   const deadlineMs = opts.deadlineAt == null ? Date.now() + timeoutSec * 1000 : Date.parse(opts.deadlineAt);
   if (!Number.isFinite(deadlineMs)) {
     emitReceipt({ schema_version: 1, outcome: "error", error: "wait_checkpoint_invalid" });
@@ -1635,8 +1693,8 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       const createdMs = Date.parse(checkpoint.created_at);
       const savedDeadlineMs = Date.parse(checkpoint.deadline_at);
       if (opts.deadlineAt !== checkpoint.deadline_at || !Number.isFinite(createdMs) ||
-          !Number.isFinite(savedDeadlineMs) || savedDeadlineMs > createdMs + 28_800_000) {
-        throw new WaitCheckpointError("wait_checkpoint_invalid", "saved wait deadline exceeds its original eight-hour cap");
+          !Number.isFinite(savedDeadlineMs) || savedDeadlineMs > createdMs + MAX_WAIT_TIMEOUT_SEC * 1000) {
+        throw new WaitCheckpointError("wait_checkpoint_invalid", "saved wait deadline exceeds its original 72-hour cap");
       }
       const expectedSpecs = resumedSpecs(checkpoint);
       if (expectedSpecs.length !== opts.conditions.length ||
@@ -1897,6 +1955,8 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       for (const line of formatPrReviewSnapshotWarnings(reg.prReviewSnapshot)) {
         process.stderr.write(`bb-wait: ${line}\n`);
       }
+      // BOT-2400: re-arming the same wait again and again burns tokens on every wake.
+      if (reg.rearmWarning) process.stderr.write(`bb-wait: ${reg.rearmWarning}\n`);
       // BOT-1837: one line naming the branch's latest run at arm time. Report-only
       // (arming before dispatch is the correct flow), and carried into a timeout
       // receipt below so the receipt explains the silence too.
@@ -2161,6 +2221,9 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       // BOT-1837: a timeout receipt carries the arm-time CI notice, so a caller
       // reading only the receipt learns the run it meant had already finished.
       timeoutError: ciArmNotice,
+      onCapacitySourceSustained: ({ host_key, stale_since }) => {
+        process.stderr.write(`bb-wait: BLOCKED capacity_source_sustained on ${host_key}, stale_since=${stale_since ?? "unknown"}; ask for a Helper check/restart (launchctl print user/$UID/com.botbuddy.helper.worker). The wait remains armed.\n`);
+      },
       // BOT-1259: fail-closed tenant scope for the central guard, plus a debug sink
       // (opt-in via BB_WAIT_DEBUG) that surfaces each fail-closed drop without turning
       // it into an error.