@botbuddy/cli 1.46.1 → 1.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.46.1",
+  "version": "1.47.0",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/stack-isolation.mjs

@@ -20,7 +20,7 @@
 // Supply Guard's `scripts/local-supabase-isolated.sh`, ported here because the
 // published CLI cannot import repo scripts and stays Node-stdlib only.
 import { createHash, randomUUID } from "node:crypto";
-import { cpSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
 import { lockPathForProject, projectIdFromConfig } from "./stack-file-lock.mjs";
@@ -72,6 +72,11 @@ export function defaultPortRegistryDir() {
 const LEASED_STACK_RETENTION_GRACE_MS = 30 * 60 * 1000;
 /** The idle TTL a lease gets when the caller names none (`bb stack up --idle-ttl`). */
 const DEFAULT_IDLE_TTL_SECS = 1800;
+/** BOT-1803: how long an IDLE lease's stack directory and port block stay reserved
+ * after its run ended. The stack is still running (the lease is `active` + idle), so
+ * another worktree must not take its ports; the next run on the same slot re-adopts it
+ * and renews the claim. Far above any idle TTL, below "forever". */
+export const LEASED_STACK_IDLE_RETENTION_SECS = 24 * 60 * 60;
 
 
 // TOML decimal integers may carry a leading sign (`+56321`); radix forms may not.
@@ -251,7 +256,12 @@ function identityTag(ticket, slot) {
  * and the file lock then reads as reclaimable — so the refresh could swap the
  * `supabase/functions` tree under a batch that was still running. A run's lease
  * is released with `destroy`, so a stable identity bought no volume reuse anyway.
- * Omit `nonce` for a deterministic per-slot identity (tests, diagnostics).
+ * Omit `nonce` for a deterministic per-slot identity — since BOT-1803 that is what
+ * `bb stack run` uses: a run's lease goes IDLE (still running) instead of being reaped,
+ * and the next run on the same worktree+slot re-adopts that exact stack, which needs
+ * the same directory, project id and ports. Concurrent runs on one slot are still
+ * refused by the per-project lock, and the server refuses a second LIVE lease on the
+ * slot; a nonce remains for tests.
  */
 export function leasedStackIdentity({ worktreeRoot, slot, ticket, nonce } = {}) {
   // JSON-encode the parts so no path/slot/nonce combination can alias another
@@ -626,6 +636,9 @@ function collectFinishedStacks(stacksDir, { keep, ticket, slot, readdir, remove,
       // and fall back to the conservative default age.
       const retainUntil = Number.isFinite(marker?.retain_until) ? marker.retain_until : null;
       if (retainUntil === null && !isOwnStackFamily(entry, { ticket, slot, marker })) continue;
+      // BOT-1803: an IDLE lease's stack is still running from this directory — never collect it
+      // on a deadline (a run on its slot re-adopts or re-provisions it).
+      if (marker?.idle_retained === true) continue;
       if (now() < (retainUntil ?? stat(join(stacksDir, entry)).mtimeMs + LEASED_STACK_GC_MIN_AGE_MS)) continue;
       if (stackDirIsClaimed(entry, { read, alive, host, marker })) continue;
       remove(join(stacksDir, entry), { recursive: true, force: true });
@@ -646,15 +659,19 @@ function collectFinishedStacks(stacksDir, { keep, ticket, slot, readdir, remove,
  * Returns false (never throws) when there is no marker to refresh — an explicitly
  * prepared `--stack-path` is the caller's to manage, not ours to annotate.
  */
-export function refreshLeasedStackRetention(stackDir, { idleTtlSecs, now = Date.now, read = readFileSync, write = writeFileSync, rename = renameSync, portRegistryDir = null } = {}) {
+export function refreshLeasedStackRetention(stackDir, { idleTtlSecs, idleRetained = false, now = Date.now, read = readFileSync, write = writeFileSync, rename = renameSync, portRegistryDir = null } = {}) {
   const marker = readStackMarker(stackDir, read);
   if (!marker) return false;
   const ttlMs = Math.max(0, Number.isFinite(idleTtlSecs) ? idleTtlSecs : DEFAULT_IDLE_TTL_SECS) * 1000;
   const at = now();
+  // BOT-1803: `idle_retained` marks a stack whose lease went idle (still running, kept
+  // for re-adoption); a renewal from a live batch clears it.
+  const { idle_retained: _wasIdle, released: _wasReleased, ...base } = marker;
   const renewed = JSON.stringify({
-    ...marker,
+    ...base,
     last_seen_at: at,
     retain_until: at + Math.max(LEASED_STACK_GC_MIN_AGE_MS, ttlMs + LEASED_STACK_RETENTION_GRACE_MS),
+    ...(idleRetained ? { idle_retained: true } : {}),
   });
   try {
     atomicWrite(join(stackDir, LEASED_STACK_MARKER), renewed, { write, rename });
@@ -684,6 +701,34 @@ export function refreshLeasedStackRetention(stackDir, { idleTtlSecs, now = Date.
   return true;
 }
 
+/**
+ * BOT-1803 (Codex #1160 P1): may `stack run` re-materialize the STABLE per-slot stack
+ * directory? Only when no batch can still be using it: no marker yet, a lease that went idle
+ * cleanly (`idle_retained`), or a batch whose reap was proven (`released`). Any other marker
+ * may belong to a batch whose owner process died while its detached child and containers
+ * still run — re-copying `supabase/` under those bind mounts is exactly what the
+ * per-invocation identity (BOT-1798) prevented, so such a run gets a fresh identity instead.
+ */
+export function stableRunStackReusable(worktreeRoot, dirName, { read = readFileSync } = {}) {
+  if (typeof dirName !== "string" || !dirName) return true;
+  const marker = readStackMarker(join(worktreeRoot, LEASED_STACKS_DIR, dirName), read);
+  if (!marker) return true;
+  return marker.idle_retained === true || marker.released === true;
+}
+
+/** BOT-1803: record a PROVEN reap on the stack's marker, so the next run may reuse the directory. */
+export function markLeasedStackReleased(stackDir, { read = readFileSync, write = writeFileSync, rename = renameSync } = {}) {
+  const marker = readStackMarker(stackDir, read);
+  if (!marker) return false;
+  const { idle_retained: _idle, ...base } = marker;
+  try {
+    atomicWrite(join(stackDir, LEASED_STACK_MARKER), JSON.stringify({ ...base, released: true }), { write, rename });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /** This stack's ownership/retention marker, or null when it has none. */
 function readStackMarker(stackDir, read) {
   try {
@@ -702,7 +747,7 @@ function readStackMarker(stackDir, read) {
  * them and the second Helper fails on a bind error after provisioning starts.
  * A block counts as taken while its stack is retained or its lock owner is alive.
  */
-function occupiedPortBlocks(registryDir, { keep, readdir, read, now, alive, host, stale = null }) {
+function occupiedPortBlocks(registryDir, { keep, readdir, read, now, alive, host, stale = null, exists = existsSync }) {
   const taken = new Map(); // portBase -> { projectId, createdAt }
   let entries;
   try { entries = readdir(registryDir); } catch { return taken; }
@@ -712,7 +757,12 @@ function occupiedPortBlocks(registryDir, { keep, readdir, read, now, alive, host
     try { claim = JSON.parse(read(join(registryDir, entry), "utf8")); } catch { continue; }
     const portBase = Number(claim?.port_base);
     if (!Number.isInteger(portBase)) continue;
-    const retained = Number.isFinite(claim.retain_until) && now() < claim.retain_until;
+    // BOT-1803: an IDLE lease's stack keeps running with no process renewing its claim, and
+    // the lease has no time ceiling — so its claim stands while its stack directory exists
+    // (until a run on the same slot re-adopts or re-provisions it, or the worktree is gone),
+    // never on a fixed deadline.
+    const retained = (Number.isFinite(claim.retain_until) && now() < claim.retain_until)
+      || (claim.idle_retained === true && typeof claim.stack_dir === "string" && exists(claim.stack_dir));
     const ownerAlive = Number.isInteger(claim.owner_pid) && claim.owner_pid > 0
       && (!claim.host || claim.host === host()) && alive(claim.owner_pid);
     if (!retained && !ownerAlive) {
@@ -923,7 +973,7 @@ export function reservePortBlocks(ports, { registryDir = defaultPortRegistryDir(
 
   mkdir(registryDir, { recursive: true });
   const claimed = [];
-  const record = (block, at = now(), ttlSecs = owner?.idleTtlSecs) => JSON.stringify({
+  const record = (block, at = now(), ttlSecs = owner?.idleTtlSecs, idleRetained = false) => JSON.stringify({
     schema: 1,
     project_id: owner?.projectId ?? null,
     invocation_token: invocationToken,
@@ -935,6 +985,7 @@ export function reservePortBlocks(ports, { registryDir = defaultPortRegistryDir(
     retain_until: at + Math.max(LEASED_STACK_GC_MIN_AGE_MS, (Number(ttlSecs) || DEFAULT_IDLE_TTL_SECS) * 1000 + LEASED_STACK_RETENTION_GRACE_MS),
     owner_pid: process.pid,
     host: host(),
+    ...(idleRetained ? { idle_retained: true } : {}),
   });
   try {
     withAllocationLock(registryDir, { writeExclusive, read, remove, now, alive, host, sleep }, () => {
@@ -959,7 +1010,11 @@ export function reservePortBlocks(ports, { registryDir = defaultPortRegistryDir(
           // Only THIS invocation's own reservation is not a peer.
           let existing = null;
           try { existing = JSON.parse(read(portClaimPath(registryDir, block), "utf8")); } catch { /* unreadable */ }
-          if (existing && existing.invocation_token === invocationToken) write(portClaimPath(registryDir, block), record(block));
+          // BOT-1803: a claim kept for an IDLE lease of this same prepared project is the
+          // stack this run is about to re-adopt (or re-provision) on the same slot — the
+          // project lock already serializes runs of one project, so take it over.
+          const idleOwnProject = existing?.idle_retained === true && owner?.projectId != null && existing.project_id === owner.projectId;
+          if (existing && (existing.invocation_token === invocationToken || idleOwnProject)) write(portClaimPath(registryDir, block), record(block));
           else {
             const busy = new Error(`refusing to lease this stack: port block ${block} was claimed by another run.`);
             busy.code = "stack_ports_busy";
@@ -981,13 +1036,13 @@ export function reservePortBlocks(ports, { registryDir = defaultPortRegistryDir(
     /** Keep the reservation alive while the batch runs (Codex #928 R21): a
      * prepared `--stack-path` has no directory marker, so nothing else renews it,
      * and an aged-out claim could be reclaimed under a still-live stack. */
-    renew: ({ idleTtlSecs, now: at = now } = {}) => {
+    renew: ({ idleTtlSecs, idleRetained = false, now: at = now } = {}) => {
       let renewed = false;
       for (const block of claimed) {
         try {
           const current = JSON.parse(read(portClaimPath(registryDir, block), "utf8"));
           if (current?.invocation_token !== invocationToken) continue;
-          write(portClaimPath(registryDir, block), record(block, at(), idleTtlSecs ?? owner?.idleTtlSecs));
+          write(portClaimPath(registryDir, block), record(block, at(), idleTtlSecs ?? owner?.idleTtlSecs, idleRetained));
           renewed = true;
         } catch { /* advisory: never fence a healthy batch */ }
       }
@@ -1356,8 +1411,14 @@ export function materializeRunStackDir(cwd, { slot, ticket, nonce, idleTtlSecs }
   // allocation lock (Codex #928 R16): the scan only REPORTS stale reservations, and
   // reclaiming one plus taking the block happen as one serialized step, so a
   // slower peer can never delete the winner's fresh claim.
+  // BOT-1803: a stable (nonce-less) identity re-materializes the SAME stack each run, so
+  // it keeps the block it already holds (an idle lease's stack is still bound to it, and
+  // the deterministic stack digest covers the remapped ports) instead of drifting back to
+  // the hash-preferred block whenever that one has freed up.
+  const previous = dirExisted ? readStackMarker(stackDir, read) : null;
+  const previousBlock = previous?.project_id === identity.projectId && Number.isInteger(previous?.port_base) ? previous.port_base : null;
   const portBase = withAllocationLock(registryDir, { writeExclusive, read, remove, now, alive, host, sleep }, () => {
-    let preferred = identity.portBase;
+    let preferred = previousBlock ?? identity.portBase;
     for (let attempt = 0; attempt < LEASED_PORT_SLOTS; attempt++) {
       const stale = new Set();
       const taken = occupiedPortBlocks(registryDir, { keep: identity.projectId, readdir, read, now, alive, host, stale });

package/src/stack-usage.mjs

@@ -0,0 +1,111 @@
+// BOT-1803 (AC-12) — the client-side USE signal for a leased stack.
+//
+// The server judges a lease idle only from observations. For a CO-LOCATED stack
+// (execution_mode `local` / `local_exec`) the coding machine can read the stack's
+// own Postgres: `docker exec supabase_db_<project_id> psql … pg_stat_activity` says
+// whether any client is connected and working right now, and when a client last
+// changed state. `bb stack touch` and `bb stack run`'s heartbeat send that as
+// `usage: { client_connections, last_client_query_at }`.
+//
+// Fail toward "no observation": a remote lease, an unusable project id, a Docker/psql
+// failure or a slow answer (> USAGE_TIMEOUT_MS) yields `null`, and the caller then
+// sends NO `usage` at all — the server never judges a lease idle from an observation
+// that did not happen. Nothing here reads or prints a secret: the query runs as the
+// container's local `postgres` role over its Unix socket.
+//
+// Dependency-free (Node stdlib only), like the rest of the published CLI.
+import { execFile } from "child_process";
+
+/** How long one measurement may take before it counts as no observation. */
+export const USAGE_TIMEOUT_MS = 5_000;
+
+/** Supabase's own service roles: their connections are the platform, not a client. */
+export const SUPABASE_INTERNAL_ROLES = Object.freeze([
+  "supabase_admin", "supabase_auth_admin", "supabase_storage_admin", "supabase_realtime_admin",
+  "supabase_replication_admin", "supabase_functions_admin", "supabase_read_only_user", "pgbouncer", "authenticator",
+]);
+
+const ROLE_LIST = SUPABASE_INTERNAL_ROLES.map((r) => `'${r}'`).join(", ");
+
+/**
+ * Two values, `|`-separated (psql -tA):
+ *   1. client_connections — client backends doing work now (state <> 'idle'), excluding
+ *      this probe and every internal role except `authenticator`: a PostgREST request in
+ *      flight is use now (Codex #1160 P1); its pooled sessions sitting idle are not.
+ *   2. last_client_query_at — the latest state change of any client backend, counting
+ *      `authenticator` (PostgREST traffic IS use), ISO-8601 UTC; empty when none.
+ */
+export const USAGE_SQL =
+  "SELECT " +
+  "(SELECT count(*) FROM pg_stat_activity WHERE backend_type = 'client backend' AND pid <> pg_backend_pid() " +
+  `AND (coalesce(usename, '') NOT IN (${ROLE_LIST}) OR usename = 'authenticator') AND state <> 'idle'), ` +
+  "(SELECT to_char(max(state_change) AT TIME ZONE 'UTC', 'YYYY-MM-DD\"T\"HH24:MI:SS.US\"Z\"') FROM pg_stat_activity " +
+  "WHERE backend_type = 'client backend' AND pid <> pg_backend_pid() " +
+  `AND (coalesce(usename, '') NOT IN (${ROLE_LIST}) OR usename = 'authenticator'))`;
+
+const CO_LOCATED_MODES = new Set(["local", "local_exec"]);
+// `supabase_db_<id>` is named after the Supabase project id; refuse anything else
+// rather than build a container name (an argv element) out of it.
+const PROJECT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$/;
+
+/** The Docker CLI selector for the engine running the stack ([] = the CLI's current context). */
+export function dockerSelectorArgs(target) {
+  if (typeof target?.context === "string" && target.context) return ["--context", target.context];
+  const endpoint = target?.resolved_endpoint ?? target?.endpoint;
+  if (typeof endpoint === "string" && endpoint) return ["-H", endpoint];
+  return [];
+}
+
+/** The full `docker` argv for one measurement of `projectId`'s database. */
+export function usageDockerArgs(projectId, target = null) {
+  return [...dockerSelectorArgs(target), "exec", `supabase_db_${projectId}`, "psql", "-U", "postgres", "-d", "postgres", "-tAc", USAGE_SQL];
+}
+
+/** Parse psql's `-tA` answer (`<count>|<iso or empty>`); null when it is not that shape. */
+export function parseUsageOutput(text) {
+  const line = String(text ?? "").split(/\r?\n/).map((l) => l.trim()).find((l) => l.length > 0);
+  if (!line) return null;
+  const parts = line.split("|");
+  if (parts.length !== 2) return null;
+  const [countRaw, atRaw] = parts.map((p) => p.trim());
+  if (!/^\d+$/.test(countRaw)) return null;
+  if (atRaw && Number.isNaN(Date.parse(atRaw))) return null;
+  return { client_connections: Number(countRaw), last_client_query_at: atRaw || null };
+}
+
+/** Default runner: `docker <args>` with a hard timeout; never a shell. */
+export function runDockerUsage(args, { timeoutMs = USAGE_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- fixed executable, validated argv, no shell.
+    execFile("docker", args, { timeout: timeoutMs, killSignal: "SIGKILL", maxBuffer: 64 * 1024, windowsHide: true }, (error, stdout) => {
+      resolve({ code: error ? (typeof error.code === "number" ? error.code : 1) : 0, stdout: String(stdout ?? ""), timedOut: Boolean(error?.killed) });
+    });
+  });
+}
+
+/**
+ * Measure a lease's client use. `lease` is a `get_stack_lease` answer (or the same shape):
+ * `{ execution_mode, connection: { project_id, botbuddy_docker_target? } }`.
+ * Returns `{ client_connections, last_client_query_at }`, or null for no observation.
+ * Never throws.
+ */
+export async function measureStackUsage(lease, { run = runDockerUsage, timeoutMs = USAGE_TIMEOUT_MS } = {}) {
+  let timer = null;
+  try {
+    if (!CO_LOCATED_MODES.has(lease?.execution_mode)) return null;
+    const projectId = lease?.connection?.project_id;
+    if (typeof projectId !== "string" || !PROJECT_ID_RE.test(projectId)) return null;
+    const args = usageDockerArgs(projectId, lease.connection.botbuddy_docker_target ?? null);
+    // Not unref'd: the timer is the only thing that settles a hung measurement, and it is
+    // cleared in `finally` the moment the answer lands (an unref'd timer let the event loop end
+    // with the race still pending on Linux CI).
+    const timeout = new Promise((resolve) => { timer = setTimeout(() => resolve(null), timeoutMs); });
+    const answer = await Promise.race([Promise.resolve().then(() => run(args, { timeoutMs })), timeout]);
+    if (!answer || answer.code !== 0 || answer.timedOut) return null;
+    return parseUsageOutput(answer.stdout);
+  } catch {
+    return null;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}

package/src/stack.mjs

@@ -6,10 +6,16 @@
 //                                  saturated; return an ACTIVE lease receipt.
 //   botbuddy stack status <id>   → the lease's current state + connection.
 //   botbuddy stack touch  <id>   → bump the idle clock (before a long silent step).
-//   botbuddy stack done   <id>   → release (`done`): reap the stack.
+//   botbuddy stack done   <id>   → release (`done`): idle the stack (BOT-1803; --reap tears it down).
 //
 // The canonical batch flow is:  stack up  →  test → break → fix → test  →  stack done.
 //
+// BOT-1803 (JIT idle leases): a finished batch's lease goes IDLE instead of being reaped —
+// still `active`, stack running, capacity still held — so the next batch on the same
+// worktree+slot re-adopts it with no provision. The control plane preempts an idle lease
+// only when a queued lease needs the capacity (volumes kept), and re-provisions it when the
+// stack's content digest changed.
+//
 // Design contract (matches bb-wait):
 //   * Dependency-free (Node stdlib only) so an explicit `npm exec --package` invocation cold-starts fast.
 //   * Exactly ONE single-line JSON receipt to stdout; all diagnostics go to stderr.
@@ -36,7 +42,8 @@ import { AGENT_KEY_RE, readAgentSessionTokenEnv } from "./agent-key.mjs";
 import { resolveAgentSessionCredential, selfHealAgentSession } from "./agent-session.mjs";
 import { runDockerCommand, runDockerWorkflow, ADMITTED_DOCKER_VALIDATIONS } from "./docker-hygiene.mjs";
 import { acquireStackLock, lockPathForProject, projectIdFromConfig } from "./stack-file-lock.mjs";
-import { assertLeasedStackIsolated, leasedStackIdentity, materializeRunStackDir, portMapInConfig, refreshLeasedStackRetention, releaseLeasedStackClaim, reservePortBlocks } from "./stack-isolation.mjs";
+import { LEASED_STACK_IDLE_RETENTION_SECS, assertLeasedStackIsolated, markLeasedStackReleased, stableRunStackReusable, leasedStackIdentity, materializeRunStackDir, portMapInConfig, refreshLeasedStackRetention, releaseLeasedStackClaim, reservePortBlocks } from "./stack-isolation.mjs";
+import { measureStackUsage } from "./stack-usage.mjs";
 import { machineUuid } from "./machine-id.mjs";
 import { DEFAULT_BUNDLE_MAX_BYTES, buildStackBundle, uploadStackBundle, validateBundleIncludePath } from "./stack-bundle.mjs";
 import { assertSshTarget, establishSshTunnel } from "./stack-tunnel.mjs";
@@ -87,8 +94,8 @@ export const STACK_HELP = `${bold("botbuddy stack")} — one command for a batch
 ${bold("USAGE")}
   botbuddy stack up [options]        Request a lease; park if the host is full; hold it active
   botbuddy stack status <lease_id>   Show a lease's state + connection
-  botbuddy stack touch  <lease_id>   Bump the idle clock so the reaper doesn't stop it
-  botbuddy stack done   <lease_id>   Release (done): tear the stack down
+  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 run [options] -- <executable> [args...]
                                       Own one Helper-backed test/fix batch end-to-end
 
@@ -138,8 +145,14 @@ ${bold("up OPTIONS")}
                          SSH forwards; --remote is refused here — use \`stack run --remote\`.
 
 ${bold("done OPTIONS")}
-  --stop                 Keep volumes (cheap re-provision next batch). Default: destroy.
+  (default)              BOT-1803: an ACTIVE lease goes IDLE — the stack keeps running and its
+                         capacity stays held, so the next \`stack run\`/\`stack up\` on this slot re-adopts
+                         it without provisioning. Receipt outcome "idle" + idle_since, idle_reason.
+                         A queued/provisioning/reaping/reaped lease is released exactly as --reap.
+  --reap                 Release eagerly: reap (tear down) the stack now, as before BOT-1803.
+  --stop                 With --reap: keep volumes (cheap re-provision next batch). Default: destroy.
   --local-exec           FALLBACK (no Helper): run 'supabase stop' locally and self-finalize.
+                         Implies --reap (a local-exec stack is never left idle).
   --docker-context <name> Explicit Docker context used by the matching local-exec up
                          (OrbStack or Docker Desktop; must match the engine that provisioned the lease).
   --docker-endpoint <uri> Explicit Docker endpoint instead of --docker-context.
@@ -152,10 +165,16 @@ ${bold("run OPTIONS")}
   --stack-path <relative> Optional PREPARED isolated stack dir. Omit it (the norm): run
                          materializes .botbuddy/stacks/<project_id>/ from this worktree's
                          supabase/ tree with a distinct project_id + remapped ports and
-                         leases that. "." is REFUSED — the worktree root is the shared
+                         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.
   --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).
+  --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.
+  --reap                 Reap the stack when the child ends (as before BOT-1803). Default: the lease
+                         goes IDLE (no reap wait; receipt cleanup {idle, idle_since}) and the stack
+                         directory + port block stay reserved (24 h, renewed on re-adoption).
+                         Interrupts, --hard-ttl, a fenced heartbeat or a lost tunnel always reap.
   --connection-file P    Optional empty file path for the mode-0600 connection JSON.
   --hard-ttl N           Bound the child runtime; timeout requests normal cleanup.
   --local-exec           Rejected: stack run never starts Docker directly.
@@ -196,6 +215,21 @@ ${bold("EXIT CODES")}
   4 invalid arguments               5 backend/coordination      6 lease failed/reaped
   7 internal error                  8 cleanup/reap proof failed
 
+${bold("IDLE LEASES")} (BOT-1803)
+  stack run sends stack_digest (the deterministic sha256 of the materialised stack bundle, also
+  with --local-only; omitted when it cannot be built) and the control plane answers with one of:
+    reused_idle      the slot's idle lease is re-adopted: no provision; receipt reused "idle"
+    IDLE_LEASE_REPROVISIONING / LEASE_PREEMPTED
+                     the idle lease is being reaped (content changed / capacity reclaimed): run
+                     waits for it to reach reaped (--reap-timeout), re-sends the same request
+                     once, and the receipt says reprovisioned "digest_mismatch" | "preempted";
+                     no reap in time → exit 6
+    4 STACK_EXECUTION_MODE_MISMATCH  the idle lease is in another mode/host (it stays idle)
+  While the child runs (and on \`stack touch\`) a co-located lease's measured use is sent as
+  usage {client_connections, last_client_query_at} (docker exec … psql pg_stat_activity, 5 s cap;
+  no usage at all when it cannot be read). A lease preempted under a running child ends it:
+  exit 6, code LEASE_PREEMPTED, volumes_kept true; \`stack touch\` exits 6 with outcome "preempted".
+
 ${bold("REMOTE LEASES")} (BOT-2142, stack run)
   The receipt carries execution_mode (local|remote), execution_host_key, requester_host,
   transport (none|ssh-forward), and for a remote lease forwards [{name, remote, local}] + bundle.
@@ -295,6 +329,8 @@ export function parseStackArgs(argv) {
     // default exclusions (`--bundle-include`, repeatable).
     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,
   };
   const positionals = [];
   const need = (name, v) => {
@@ -413,6 +449,7 @@ export function parseStackArgs(argv) {
       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;
+      case "--reap": opts.reap = true; break;
       case "--destroy": opts.disposition = "destroy"; break;
       case "--json": opts.json = true; break;
       default:
@@ -462,6 +499,9 @@ export function parseStackArgs(argv) {
       "worktree root's default (shared canonical) project. Point --stack-path at a slot-derived stack directory with its " +
       "own supabase/config.toml (distinct project_id + remapped ports).");
   }
+  if (opts.reap && !["done", "run"].includes(command)) {
+    errors.push("--reap is valid only with `stack done` or `stack run`");
+  }
   if (opts.waitCapacity != null && !["up", "run"].includes(command)) {
     errors.push("--wait-capacity is valid only with `stack up` or `stack run`");
   }
@@ -642,15 +682,17 @@ export function resolveStackPath(cwd = process.cwd(), stackPath = ".") {
  *
  * Fail closed: whatever produced the path, a `run` lease at `"."` is refused.
  *
- * Each invocation gets its OWN stack directory and project id (BOT-1798, Codex
- * #928 R3/R5): a second `run` on the same worktree+slot must never delete and
- * recopy the `supabase/functions` tree a live batch's edge runtime is
- * bind-mounting — and that batch stays live even when its OWNER process is gone
- * (the child is detached, and the containers and server lease survive to the idle
- * TTL), so no liveness check on this side could make a shared directory safe. The
- * per-project lock is still taken and held for the whole batch, so the directory
- * is visibly claimed while it is in use; a run's lease is released with `destroy`,
- * so nothing is lost by not reusing the previous invocation's volume.
+ * BOT-1803: the identity is STABLE per (worktree, slot) — no per-invocation nonce —
+ * because a finished run's lease now goes IDLE with its stack still running, and the
+ * next run on the slot re-adopts that exact stack (same directory, project id and
+ * ports, so the deterministic stack digest is comparable across runs). Concurrency is
+ * unchanged: the per-project lock is held for the whole batch, so a second concurrent
+ * run on the same slot is refused (stack_slot_busy), and the server refuses a second
+ * LIVE lease on the slot. (BOT-1798's per-invocation identity, Codex #928 R3/R5,
+ * guarded a batch whose OWNER process died while its detached child still ran; a run
+ * re-materializing over such a batch is the residual risk of the stable identity, and
+ * the server's live-lease refusal then stops it before any Helper acts.)
+ * `opts.stackNonce` still forces a distinct identity (tests).
  */
 async function claimProjectLock(projectId, lock, subject) {
   try {
@@ -665,7 +707,7 @@ async function claimProjectLock(projectId, lock, subject) {
   }
 }
 
-export async function resolveRunExecution(cwd, opts, { materialize = materializeRunStackDir, lock = acquireStackLock, identity = leasedStackIdentity, reserveBlocks = reservePortBlocks, releaseClaim = releaseLeasedStackClaim, portRegistryDir = null } = {}) {
+export async function resolveRunExecution(cwd, opts, { materialize = materializeRunStackDir, lock = acquireStackLock, identity = leasedStackIdentity, reserveBlocks = reservePortBlocks, releaseClaim = releaseLeasedStackClaim, stableReusable = stableRunStackReusable, markReleased = markLeasedStackReleased, portRegistryDir = null } = {}) {
   const refuseRoot = (execution) => {
     if (execution.stackPath === ".") {
       throw new Error(
@@ -728,8 +770,12 @@ export async function resolveRunExecution(cwd, opts, { materialize = materialize
     };
   }
   const worktreeRoot = realpathSync(cwd);
-  // One nonce per invocation, shared by the identity and the materialization below.
-  const nonce = opts.stackNonce ?? randomUUID();
+  // BOT-1803: a stable per-(worktree, slot) identity unless a test pins a nonce — and only
+  // when no batch can still be using that directory (Codex #1160 P1): a marker left by a
+  // batch that neither went idle nor proved its reap may belong to a live detached child,
+  // so this run takes a fresh per-invocation identity instead (BOT-1798's protection).
+  const stableDir = identity({ worktreeRoot, slot: opts.slot, ticket: opts.ticket, nonce: null }).dirName;
+  const nonce = opts.stackNonce ?? (stableReusable(worktreeRoot, stableDir) ? null : randomUUID());
   const { projectId } = identity({ worktreeRoot, slot: opts.slot, ticket: opts.ticket, nonce });
   const held = await claimProjectLock(projectId, lock, `this batch's isolated stack (${projectId})`);
   try {
@@ -751,6 +797,8 @@ export async function resolveRunExecution(cwd, opts, { materialize = materialize
       release: ({ reaped = false } = {}) => {
         if (reaped) {
           try { releaseClaim(stackDirFor(execution), portRegistryDir ? { registryDir: portRegistryDir } : undefined); } catch { /* advisory */ }
+          // BOT-1803: the stack is provably gone, so the next run may reuse this directory.
+          try { markReleased(stackDirFor(execution)); } catch { /* advisory */ }
         }
         held.release();
       },
@@ -2421,6 +2469,8 @@ export async function cmdUp(opts, {
     command: "up", outcome: "active", lease_id: leaseId, state: "active",
     host_key: g.host_key, slot: g.slot, connection: g.connection,
     idle_ttl_secs: g.idle_ttl_secs, resource_name: g.resource_name,
+    // BOT-1803: the slot's IDLE lease was re-adopted (already running; nothing provisioned).
+    ...(d.reused_idle === true ? { reused: "idle" } : {}),
     ...(localPreflight ? { preflight: localPreflight } : {}),
   }), opts, EXIT.OK);
 }
@@ -2453,16 +2503,55 @@ export async function cmdStatus(leaseId, opts, {
     ...(g.reap_requested_at ? { reap_requested_at: g.reap_requested_at } : {}),
     ...(g.reap_failed_at ? { reap_failed: true, reap_failed_at: g.reap_failed_at } : {}),
     ...(g.state === "reaping" && g.error ? { error: g.error } : {}),
+    // BOT-1803: an idle lease is `active` with idle_since; display_state says "idle".
+    ...idleStatusFields(g),
   }), opts, EXIT.OK);
 }
 
-async function cmdTouch(leaseId, opts, { rpc = retryingStackCall() } = {}) {
+/** BOT-1803: the idle/use fields a get_stack_lease answer carries (absent on older servers). */
+function idleStatusFields(g) {
+  const out = {};
+  for (const key of ["display_state", "idle", "idle_since", "idle_reason", "last_observed_use_at", "usage_observed_at", "usage_observed_source", "reap_reason", "preempted_for_lease_id"]) {
+    if (g?.[key] !== undefined && g?.[key] !== null) out[key] = g[key];
+  }
+  return out;
+}
+
+/** BOT-1803: is a touch/get answer the control plane's "this lease was preempted"? */
+export function isPreemptedAnswer(d) {
+  return d?.code === "LEASE_PREEMPTED" || (d?.success === false && d?.reap_reason === "preempted");
+}
+
+/**
+ * BOT-1803: `stack touch` bumps the idle clock and, for a co-located lease, reports the
+ * measured client use (AC-12). Reading the lease first (for its project + Docker target)
+ * is best-effort: without it the touch simply carries no usage. A preempted lease is a
+ * typed receipt and exit 6 — the keeper exit Supply Guard's heartbeat daemon sees (AC-11).
+ */
+export async function cmdTouch(leaseId, opts, { rpc = retryingStackCall(), emitResult = emit, measureUsage = measureStackUsage } = {}) {
   const auth = await rpc.init();
-  if (!auth) return emit(buildReceipt({ command: "touch", outcome: "error", lease_id: leaseId, error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
-  const r = await rpc.call("touch_stack_lease", { lease_id: leaseId });
-  if (!r.ok) return emit(buildReceipt({ command: "touch", outcome: "error", lease_id: leaseId, error: r.error }), opts, r.auth ? EXIT.AUTH : EXIT.BACKEND);
-  if (!r.data.success) return emit(buildReceipt({ command: "touch", outcome: "error", lease_id: leaseId, code: r.data.code, error: r.data.code }), opts, EXIT.BACKEND);
-  return emit(buildReceipt({ command: "touch", outcome: "touched", lease_id: leaseId, last_used_at: r.data.last_used_at }), opts, EXIT.OK);
+  if (!auth) return emitResult(buildReceipt({ command: "touch", outcome: "error", lease_id: leaseId, error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
+  let usage = null;
+  try {
+    const got = await rpc.call("get_stack_lease", { lease_id: leaseId });
+    if (got?.ok && got.data?.success && got.data.state === "active") usage = await measureUsage(got.data);
+  } catch { usage = null; }
+  const r = await rpc.call("touch_stack_lease", { lease_id: leaseId, ...(usage ? { usage } : {}) });
+  if (!r.ok) return emitResult(buildReceipt({ command: "touch", outcome: "error", lease_id: leaseId, error: r.error }), opts, r.auth ? EXIT.AUTH : EXIT.BACKEND);
+  if (isPreemptedAnswer(r.data)) {
+    return emitResult(buildReceipt({
+      command: "touch", outcome: "preempted", code: "LEASE_PREEMPTED", lease_id: leaseId, volumes_kept: true,
+      state: r.data.state ?? null, reap_reason: r.data.reap_reason ?? "preempted",
+      error: "the lease was preempted (its idle capacity went to a queued lease); the stack was stopped with its volumes kept — request a new lease",
+    }), opts, EXIT.LEASE_FAILED);
+  }
+  if (!r.data.success) return emitResult(buildReceipt({ command: "touch", outcome: "error", lease_id: leaseId, code: r.data.code, error: r.data.code }), opts, EXIT.BACKEND);
+  return emitResult(buildReceipt({
+    command: "touch", outcome: "touched", lease_id: leaseId, last_used_at: r.data.last_used_at,
+    ...(r.data.idle !== undefined ? { idle: r.data.idle } : {}),
+    ...(r.data.idle_since !== undefined ? { idle_since: r.data.idle_since } : {}),
+    usage_recorded: r.data.usage_recorded === true,
+  }), opts, EXIT.OK);
 }
 
 export async function cmdDone(leaseId, opts, {
@@ -2607,9 +2696,21 @@ export async function cmdDone(leaseId, opts, {
     }
   }
 
-  const r = await call("release_stack_lease", { lease_id: leaseId, disposition: opts.disposition });
+  // BOT-1803: the default `done` idles an ACTIVE lease (stack kept running for the next
+  // batch on this slot). `--reap` is today's eager release, and `--local-exec` implies it:
+  // its self-teardown below (and every hermetic lane / Supply Guard stop) needs the reap.
+  const idleRelease = !opts.reap && !opts.localExec;
+  const r = await call("release_stack_lease", { lease_id: leaseId, disposition: opts.disposition, ...(idleRelease ? { idle: true } : {}) });
   if (!r.ok) return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, error: r.error }), opts, r.auth ? EXIT.AUTH : EXIT.BACKEND);
   if (!r.data.success) return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, code: r.data.code, error: r.data.code }), opts, EXIT.BACKEND);
+  if (idleRelease && r.data.idle === true) {
+    return emitResult(buildReceipt({
+      command: "done", outcome: "idle", lease_id: leaseId, state: r.data.state ?? "active",
+      idle: true, idle_since: r.data.idle_since ?? null, idle_reason: r.data.idle_reason ?? null,
+      ...(r.data.noop === true ? { noop: true } : {}),
+    }), opts, EXIT.OK);
+  }
+  // Any other answer (the lease was not active) is exactly today's release.
   let state = r.data.state;
   // BOT-1887 (Codex #972 P1): a lease that is ALREADY reaping (an idle reap that
   // established `stop`, or a retried `destroy`) keeps its in-flight teardown contract —
@@ -2686,6 +2787,8 @@ export async function cmdDone(leaseId, opts, {
 }
 
 const SIGNAL_EXIT = Object.freeze({ SIGINT: 130, SIGTERM: 143, SIGHUP: 129 });
+/** BOT-1803: request answers meaning "this slot's idle lease is being reaped; re-request once it is". */
+const IDLE_REPROVISION_REASONS = Object.freeze({ IDLE_LEASE_REPROVISIONING: "digest_mismatch", LEASE_PREEMPTED: "preempted" });
 
 function safeConnectionPath(requested, leaseId) {
   if (requested) {
@@ -2823,10 +2926,12 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
   // BOT-2099 (Codex #1057 R4): a platform blip recorded by ANY lease wait stays on EVERY
   // terminal result (interrupted, unreadable, thrown, …), not only the paths that remember it.
   // BOT-2142: where the lease ran (and how it was reached) is on every terminal result too.
-  const incidentBox = { incident: null, execution: null };
+  // BOT-1803: whether this run re-adopted / re-provisioned an idle lease, and its stack digest.
+  const incidentBox = { incident: null, execution: null, idleLease: null };
   const result = await runStackLifecycleOnce(opts, childArgv, adapters, incidentBox);
   const withIncident = incidentBox.incident && !result?.incident ? { ...result, incident: incidentBox.incident } : result;
-  return incidentBox.execution && !withIncident?.execution ? { ...withIncident, execution: incidentBox.execution } : withIncident;
+  const withExecution = incidentBox.execution && !withIncident?.execution ? { ...withIncident, execution: incidentBox.execution } : withIncident;
+  return incidentBox.idleLease && !withExecution?.idleLease ? { ...withExecution, idleLease: incidentBox.idleLease } : withExecution;
 }
 
 async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
@@ -2851,9 +2956,12 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   const api = adapters.api ?? {
     request: (args) => rpc.call("request_stack_lease", args),
     get: (leaseId) => rpc.call("get_stack_lease", { lease_id: leaseId }),
-    touch: (leaseId) => rpc.call("touch_stack_lease", { lease_id: leaseId }),
-    release: (leaseId, signal) => rpc.call("release_stack_lease", { lease_id: leaseId, disposition: "destroy" }, { signal }),
+    // BOT-1803: a heartbeat carries the measured client use when there is one.
+    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 }),
   };
+  const measureUsage = adapters.measureUsage ?? measureStackUsage;
   const machineUuidFn = adapters.machineUuidFn ?? machineUuid;
   const wait = adapters.wait ?? ((leaseId, done, failed, options) => waitForLease(leaseId, done, failed, options));
   // BOT-2099: the queue park and the provision wait survive auth/availability blips.
@@ -2918,6 +3026,14 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   let tunnelLost = null;
   const placement = { mode: null, hostKey: null, requesterHost: null, transport: "none", forwards: null, bundle: null, placementReason: null, considered: null };
   incidentBox.execution = placement;
+  // BOT-1803: idle-lease bookkeeping for the receipt.
+  const idleLease = { reused: null, reprovisioned: null, previousLeaseId: null, stackDigest: null };
+  incidentBox.idleLease = idleLease;
+  // BOT-1803: set when this run's port block must stay reserved although nothing of ours
+  // was provisioned (the slot's idle/live stack in THIS directory is still bound to it).
+  let retainBlock = false;
+  // BOT-1803: a heartbeat touch found the lease preempted under the running child.
+  let preempted = null;
   const closeTunnel = async () => {
     if (!tunnel) return;
     const open = tunnel;
@@ -2925,7 +3041,10 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     try { await open.close(); } catch { /* best effort: the process is gone either way */ }
   };
 
-  const requestCleanup = () => {
+  // BOT-1803: `idle` (only the normal end of a run) asks the server to idle the ACTIVE lease
+  // — no reap job, no signed-reap wait. Any answer that is not an idle one (the lease was
+  // not active) continues into today's signed-reap wait unchanged.
+  const requestCleanup = ({ idle = false } = {}) => {
     // A signal can arrive while the lease-request RPC is in flight. There is
     // nothing to release yet, so do not cache this no-op; once the RPC returns
     // the interruption branch must perform the real signed cleanup.
@@ -2937,13 +3056,16 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     const cleanupTimer = clock.setTimeout(() => cleanupAbort.abort("reap-timeout"), opts.reapTimeout * 1000);
     let release;
     try {
-      release = await api.release(leaseId, cleanupAbort.signal);
+      release = idle ? await api.release(leaseId, cleanupAbort.signal, { idle: true }) : await api.release(leaseId, cleanupAbort.signal);
     } finally {
       clock.clearTimeout(cleanupTimer);
     }
     if (!release?.ok || !release?.data?.success) {
       return cleanupResult = { ok: false, error: release?.error || release?.data?.code || "release failed" };
     }
+    if (idle && release.data.idle === true) {
+      return cleanupResult = { ok: true, idle: true, state: release.data.state ?? "active", idle_since: release.data.idle_since ?? null, idle_reason: release.data.idle_reason ?? null };
+    }
     if (release.data.state === "reaped") return cleanupResult = { ok: true, state: "reaped" };
     // BOT-1822 (Codex P2 round 2, extended round 3): `reap_failed` is synthetic
     // (never a real DB state), so a Helper's failed receipt landing in the split
@@ -3062,18 +3184,34 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     let executionRequest = opts.execution ?? "auto";
     let bundle = null;
     const bundleInclude = opts.bundleInclude ?? [];
+    const buildRunBundle = ({ digestOnly = false } = {}) => {
+      // BOT-2162: ship the worktree's BOT-2107 readiness declaration with the stack, so the
+      // serving Helper runs the canonical bind-RPC probe for a remote lease too.
+      const declaration = join(execution.worktreeRoot, ".botbuddy", "config.json");
+      let hasDeclaration = false;
+      try { hasDeclaration = existsSync(declaration) && lstatSync(declaration).isFile(); } catch { hasDeclaration = false; }
+      return buildBundle(stackDirFor(execution), {
+        // A digest that ships nothing has no upload cap (the archive is only hashed).
+        maxBytes: digestOnly ? Number.MAX_SAFE_INTEGER : (opts.bundleMaxBytes ?? DEFAULT_BUNDLE_MAX_BYTES),
+        ...(digestOnly ? { rawLimitBytes: Number.MAX_SAFE_INTEGER } : {}),
+        ...(hasDeclaration ? { extraFiles: [{ rel: ".botbuddy/config.json", abs: declaration }] } : {}),
+        ...(bundleInclude.length ? { include: bundleInclude } : {}),
+      });
+    };
+    // BOT-1803: the stack digest — the deterministic bundle sha256 of the materialised stack —
+    // goes on EVERY request so the control plane re-adopts this slot's idle lease only when
+    // its content is unchanged. --local-only ships nothing, so there it is computed for the
+    // digest alone (no upload cap). Fail closed (Codex #1160 P1): every run request says
+    // `require_stack_digest`, so when no digest could be computed the control plane re-provisions
+    // an idle lease instead of handing back a stack whose content it cannot prove current.
+    let stackDigest = null;
+    let digestError = null;
+    if (executionRequest === "local") {
+      try { stackDigest = buildRunBundle({ digestOnly: true })?.sha256 ?? null; } catch (error) { digestError = error; }
+    }
     if (executionRequest !== "local") {
       try {
-        // BOT-2162: ship the worktree's BOT-2107 readiness declaration with the stack, so the
-        // serving Helper runs the canonical bind-RPC probe for a remote lease too.
-        const declaration = join(execution.worktreeRoot, ".botbuddy", "config.json");
-        let hasDeclaration = false;
-        try { hasDeclaration = existsSync(declaration) && lstatSync(declaration).isFile(); } catch { hasDeclaration = false; }
-        bundle = buildBundle(stackDirFor(execution), {
-          maxBytes: opts.bundleMaxBytes ?? DEFAULT_BUNDLE_MAX_BYTES,
-          ...(hasDeclaration ? { extraFiles: [{ rel: ".botbuddy/config.json", abs: declaration }] } : {}),
-          ...(bundleInclude.length ? { include: bundleInclude } : {}),
-        });
+        bundle = buildRunBundle();
         for (const entry of bundle.included ?? []) {
           stderrLine(`stack: the bundle includes ${entry.path} (sha256 ${entry.sha256.slice(0, 12)}…; keys: ${entry.keys.join(", ") || "none"})`);
         }
@@ -3092,6 +3230,17 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         stderrLine(`${yellow("⚠")} stack: could not build the remote-lease bundle (${message}); requesting a co-located lease (execution local) instead.`);
       }
     }
+    if (!stackDigest && !bundle?.sha256 && !digestError) {
+      // `auto` fell back to local above because its (capped) bundle failed: hash it uncapped.
+      try { stackDigest = buildRunBundle({ digestOnly: true })?.sha256 ?? null; } catch (error) { digestError = error; }
+    }
+    stackDigest = stackDigest ?? bundle?.sha256 ?? null;
+    if (typeof stackDigest !== "string" || !/^[0-9a-f]{64}$/.test(stackDigest)) stackDigest = null;
+    if (!stackDigest) {
+      stderrLine(`${yellow("⚠")} stack: could not compute the stack digest (${String(digestError?.message ?? digestError ?? "no digest")}); ` +
+        "an idle stack on this slot will be re-provisioned rather than reused.");
+    }
+    idleLease.stackDigest = stackDigest;
     const leaseArgs = {
       slot, host_key: opts.host || undefined, repo: opts.repo, ticket_id: opts.ticket,
       ticket_url: opts.ticketUrl || undefined, pr_id: opts.prId || undefined, pr_url: opts.prUrl || undefined,
@@ -3100,6 +3249,9 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       machine_uuid: hardwareUuid,
       execution: executionRequest,
       ...(bundle ? { bundle_sha256: bundle.sha256 } : {}),
+      ...(stackDigest ? { stack_digest: stackDigest } : {}),
+      // BOT-1803 (Codex #1160 P1): a run never re-adopts an idle stack it cannot prove current.
+      require_stack_digest: true,
       // BOT-2269: what the bundle carries beyond the defaults (paths, sha256, key NAMES).
       ...(bundle?.included?.length ? { bundle_included: bundle.included } : {}),
       ...(opts.callbackPort != null ? { callback_port: opts.callbackPort } : {}),
@@ -3108,61 +3260,111 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     // FIRST auth rejection among any of request/get/touch/release.
     // BOT-2024: a stale-capacity refusal prints phase-aware guidance; with the opt-in
     // --wait-capacity a TRANSIENT one parks on the server's capacity wait and re-admits once.
-    activeWaitAbort = new AbortController();
-    const admission = await requestWithCapacityWait(() => api.request(leaseArgs), opts, {
-      waitCapacity: adapters.waitCapacity ?? defaultWaitCapacity, log: stderrLine, signal: activeWaitAbort.signal,
-    });
-    activeWaitAbort = null;
-    const request = admission.req;
-    // Interrupted DURING the capacity park: the refused request created no lease, so
-    // there is nothing to release. (A signal during a request that DID admit falls
-    // through to the existing post-lease interruption branch, which cleans up.)
-    if (admission.interrupted) {
-      return { exitCode: SIGNAL_EXIT[receivedSignal] ?? EXIT.INTERNAL, outcome: "interrupted", code: request?.data?.code, ...capacityStaleReceiptFields(request?.data) };
-    }
-    if (admission.capacityTimeout) {
-      return {
-        exitCode: EXIT.TIMEOUT, outcome: "timeout", code: request.data.code, ...capacityStaleReceiptFields(request.data),
-        wait_exit_code: EXIT.TIMEOUT, wait_receipt: admission.waitReceipt,
-        error: `capacity did not recover within --wait-capacity ${opts.waitCapacity}s (${request.data.code})`,
-      };
-    }
-    if (admission.waitFailed) {
-      return {
-        exitCode: admission.waitFailed.exitCode, outcome: "error", code: request.data.code, ...capacityStaleReceiptFields(request.data),
-        wait_exit_code: admission.waitFailed.exitCode, wait_receipt: admission.waitFailed.receipt,
-        error: `--wait-capacity: bb wait exited ${admission.waitFailed.exitCode} (${admission.waitFailed.detail})`,
-      };
-    }
-    if (!request?.ok) {
-      // Codex #928 R23 (P2): `status: null` (callToolJson's fetch-threw branch) means
-      // NO response was ever received — the request may have reached the backend and
-      // created a lease we simply never heard back about, so a Helper could already be
-      // provisioning it. Any OTHER failure carries a real HTTP status: the backend was
-      // reached and definitely refused (or errored) before creating anything of ours.
-      // Only the definite case is safe to treat as unprovisioned and free the port
-      // claim immediately below; an ambiguous transport failure retains it instead — it
-      // still expires on its own TTL if nothing was actually provisioned.
-      if (request?.status == null) leaseProvisioned = true;
-      return { exitCode: request?.auth ? EXIT.AUTH : EXIT.BACKEND, outcome: "error", error: request?.error || "lease request failed" };
+    // BOT-1803: an idle lease on this slot that the control plane is re-provisioning (its
+    // stack digest changed) or that lost a race to a preemption answers with the OLD lease
+    // 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;
+    for (let attempt = 0; ; attempt++) {
+      activeWaitAbort = new AbortController();
+      const admission = await requestWithCapacityWait(() => api.request(leaseArgs), opts, {
+        waitCapacity: adapters.waitCapacity ?? defaultWaitCapacity, log: stderrLine, signal: activeWaitAbort.signal,
+      });
+      activeWaitAbort = null;
+      request = admission.req;
+
+      // Interrupted DURING the capacity park: the refused request created no lease, so
+      // there is nothing to release. (A signal during a request that DID admit falls
+      // through to the existing post-lease interruption branch, which cleans up.)
+      if (admission.interrupted) {
+        return { exitCode: SIGNAL_EXIT[receivedSignal] ?? EXIT.INTERNAL, outcome: "interrupted", code: request?.data?.code, ...capacityStaleReceiptFields(request?.data) };
+      }
+      if (admission.capacityTimeout) {
+        return {
+          exitCode: EXIT.TIMEOUT, outcome: "timeout", code: request.data.code, ...capacityStaleReceiptFields(request.data),
+          wait_exit_code: EXIT.TIMEOUT, wait_receipt: admission.waitReceipt,
+          error: `capacity did not recover within --wait-capacity ${opts.waitCapacity}s (${request.data.code})`,
+        };
+      }
+      if (admission.waitFailed) {
+        return {
+          exitCode: admission.waitFailed.exitCode, outcome: "error", code: request.data.code, ...capacityStaleReceiptFields(request.data),
+          wait_exit_code: admission.waitFailed.exitCode, wait_receipt: admission.waitFailed.receipt,
+          error: `--wait-capacity: bb wait exited ${admission.waitFailed.exitCode} (${admission.waitFailed.detail})`,
+        };
+      }
+      if (!request?.ok) {
+        // Codex #928 R23 (P2): `status: null` (callToolJson's fetch-threw branch) means
+        // NO response was ever received — the request may have reached the backend and
+        // created a lease we simply never heard back about, so a Helper could already be
+        // provisioning it. Any OTHER failure carries a real HTTP status: the backend was
+        // reached and definitely refused (or errored) before creating anything of ours.
+        // Only the definite case is safe to treat as unprovisioned and free the port
+        // claim immediately below; an ambiguous transport failure retains it instead — it
+        // still expires on its own TTL if nothing was actually provisioned.
+        if (request?.status == null) leaseProvisioned = true;
+        return { exitCode: request?.auth ? EXIT.AUTH : EXIT.BACKEND, outcome: "error", error: request?.error || "lease request failed" };
+      }
+      const why = attempt === 0 && request.data?.success === false && request.data?.lease_id ? IDLE_REPROVISION_REASONS[request.data.code] : null;
+      if (!why) break;
+      const previous = request.data.lease_id;
+      idleLease.previousLeaseId = previous;
+      stderrLine(`stack: this slot's idle lease ${previous} is being ${why === "preempted" ? "preempted" : "re-provisioned (the stack content changed)"} — waiting for it to reach reaped, then requesting again`);
+      activeWaitAbort = new AbortController();
+      const gone = await resilientWait(previous, (st) => st === "reaped", (st) => st === "reap_failed", { timeoutSec: opts.reapTimeout, auth: rpc.auth, signal: activeWaitAbort.signal });
+      activeWaitAbort = null;
+      if (gone?.interrupted || receivedSignal) {
+        return { exitCode: SIGNAL_EXIT[receivedSignal] ?? EXIT.INTERNAL, outcome: "interrupted", code: request.data.code };
+      }
+      let reaped = Boolean(gone?.woke) && gone.state === "reaped";
+      if (!reaped && !gone?.failed) {
+        // The same missed-wake recheck as the provision and reap waits (BOT-1822/1827).
+        const read = await readLeaseQuietly(previous);
+        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: EXIT.LEASE_FAILED, outcome: "error", code: request.data.code,
+          error: `this slot's idle lease ${previous} did not reach reaped ${gone?.failed ? "(its reap failed)" : `within ${opts.reapTimeout}s`} ` +
+            `after ${why}; no new lease was requested — check \`bb stack status ${previous}\` and re-run once it is reaped`,
+          ...(parkIncident ? { incident: parkIncident } : {}),
+        };
+      }
+      idleLease.reprovisioned = why;
     }
     if (!request.data?.success) {
       const hint = worktreeRegistrationHint(request.data?.code, rpc.auth)
         ?? stackPathRootRefusalNotice(request.data?.code, request.data?.message)
         ?? remoteRefusalNotice(request.data?.code);
       if (hint) stderrLine(hint);
+      // BOT-1803: the slot's idle lease stays idle (another mode/host); keep its block.
+      if (request.data?.code === "STACK_EXECUTION_MODE_MISMATCH" && request.data?.lease_id) retainBlock = true;
       return {
         exitCode: leaseRefusalExit(request.data?.code), outcome: "error", code: request.data?.code,
         ...capacityStaleReceiptFields(request.data), error: leaseRefusalError(request.data),
       };
     }
     leaseId = request.data.lease_id;
-    if (request.data.reused) {
+    // BOT-1803: `reused_idle` — the slot's IDLE lease was re-adopted: it is active with its
+    // 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) {
+      // With a stable identity a live lease in THIS stack directory is bound to our block.
+      if (request.data.stack_path != null && request.data.stack_path === execution.stackPath &&
+          (request.data.worktree_root == null || request.data.worktree_root === execution.worktreeRoot)) retainBlock = true;
       return { exitCode: EXIT.BACKEND, outcome: "error", leaseId, error: "a live lease already exists for this agent and stack slot; wait for that batch to finish instead of sharing its stack" };
     }
 
     leaseProvisioned = true; // from here a Helper may act on this lease
     let state = request.data.state;
+    if (reusedIdle) {
+      idleLease.reused = "idle";
+      state = "active";
+      stderrLine(`stack: re-adopted idle lease ${leaseId}${request.data.host_key ? ` on ${request.data.host_key}` : ""} — the stack is already running; nothing to provision`);
+    }
     // BOT-2142: where the server placed the lease. A server that predates BOT-2145
     // sends no execution_mode, and its lease is co-located.
     const remoteLease = request.data.execution_mode === "remote";
@@ -3192,6 +3394,8 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
           return { exitCode: EXIT.BACKEND, outcome: "error", code: error.code ?? "REMOTE_UNREACHABLE", leaseId, error: error.message, cleanup };
         }
       }
+      // BOT-1803: a re-adopted idle remote stack is already running there; nothing to upload.
+      if (!reusedIdle) {
       if (!bundle || !request.data.bundle_upload_url) {
         const cleanup = await requestCleanup();
         return {
@@ -3217,6 +3421,7 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       placement.bundle = { sha256: bundle.sha256, bytes: bundle.size };
       if (bundle.included?.length) placement.bundleIncluded = bundle.included;
       stderrLine(`stack: lease ${leaseId} is remote on ${placement.hostKey ?? "?"} — uploaded the ${bundle.size}-byte stack bundle (sha256 ${bundle.sha256.slice(0, 12)}…)`);
+      }
     } else if (bundle && state === "queued" && request.data.bundle_upload_url) {
       // BOT-2207: the lease queued HERE but may still move: every minute the control plane
       // re-offers it to the owner's other hosts, and it can only move with its bundle in
@@ -3389,9 +3594,23 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     // last activity, not its creation, so a batch that outlives the default window
     // and then loses its owner process is never collected while it is still running.
     keepAlive();
+    // BOT-1803 (AC-12): a co-located lease's heartbeat carries the measured client use; a
+    // remote one (or an unreadable measurement) sends no usage at all.
+    const usageLease = { ...current.data, execution_mode: current.data.execution_mode ?? (servedRemote ? "remote" : "local") };
     heartbeat = clock.setInterval(async () => {
       if (fencing || childResult) return;
-      const touched = await api.touch(leaseId);
+      let usage = null;
+      if (!servedRemote) { try { usage = await measureUsage(usageLease); } catch { usage = null; } }
+      if (fencing || childResult) return;
+      const touched = usage ? await api.touch(leaseId, usage) : await api.touch(leaseId);
+      if (touched?.ok && isPreemptedAnswer(touched.data)) {
+        // BOT-1803 (AC-11): the control plane reclaimed this lease's capacity. Stop the
+        // child and end typed — never the generic lost-lease wording.
+        preempted = { state: touched.data.state ?? "reaping", reap_reason: touched.data.reap_reason ?? "preempted" };
+        fencing = true;
+        stopChild("SIGTERM", EXIT.LEASE_FAILED);
+        return;
+      }
       if (!touched?.ok || !touched?.data?.success) {
         fencing = true;
         stopChild("SIGTERM", EXIT.LEASE_FAILED);
@@ -3407,10 +3626,29 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     if (retention) { clock.clearInterval(retention); retention = null; }
     if (hardTimer) clock.clearTimeout(hardTimer);
     await closeTunnel();
-    const cleanup = await requestCleanup();
+    // BOT-1803: a run that ended on its own (the child exited, success or not) leaves its
+    // lease IDLE for the next run on this slot — no reap wait. `--reap`, a signal, the
+    // hard TTL, a fenced/preempted heartbeat and a lost tunnel keep the eager signed reap.
+    const idleOnEnd = !opts.reap && !receivedSignal && !fencing && !tunnelLost && forcedStopCode == null;
+    const cleanup = await requestCleanup({ idle: idleOnEnd });
+    if (cleanup?.idle) {
+      // The stack is still running: keep its directory and host port block reserved well
+      // past any idle TTL so no other worktree takes them; the next run renews the claim.
+      try { refreshRetention(stackDirFor(execution), { idleTtlSecs: LEASED_STACK_IDLE_RETENTION_SECS, idleRetained: true }); } catch { /* advisory */ }
+      try { execution.renew?.({ idleTtlSecs: LEASED_STACK_IDLE_RETENTION_SECS, idleRetained: true }); } catch { /* advisory */ }
+      stderrLine(`stack: lease ${leaseId} is idle${cleanup.idle_since ? ` since ${cleanup.idle_since}` : ""} — its stack keeps running for the next run on this slot (\`bb stack done ${leaseId} --reap\` tears it down)`);
+    }
     if (tunnelLost && !receivedSignal) {
       return tunnelLostResult(tunnelLost, { leaseId, cleanup, childExitCode: childResult.code, fenced: fencing, ...(parkIncident ? { incident: parkIncident } : {}) });
     }
+    if (preempted && !receivedSignal) {
+      return {
+        exitCode: EXIT.LEASE_FAILED, outcome: "failed", code: "LEASE_PREEMPTED", volumesKept: true, leaseId, childExitCode: childResult.code, cleanup, fenced: true,
+        error: `lease ${leaseId} was preempted while the child ran (its capacity went to a queued lease); the child was stopped and the stack ` +
+          "stopped with its volumes kept — re-run the batch to get a new lease",
+        ...(parkIncident ? { incident: parkIncident } : {}),
+      };
+    }
     const exitCode = receivedSignal ? SIGNAL_EXIT[receivedSignal] : forcedStopCode ?? (childResult.code !== 0 ? childResult.code : !cleanup.ok ? EXIT.CLEANUP_FAILED : 0);
     return { exitCode, outcome: exitCode === 0 ? "completed" : "failed", leaseId, childExitCode: childResult.code, cleanup, fenced: fencing, ...(parkIncident ? { incident: parkIncident } : {}) };
   } catch (error) {
@@ -3436,8 +3674,10 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     // A request the backend refused, or one that only re-attached to somebody
     // else's live lease, provisioned nothing of ours — its block must go back at
     // once, or repeated refusals would exhaust the host (Codex #928 R21 P2).
-    const provenReap = !leaseProvisioned
-      || (cleanupResult?.ok === true && (cleanupResult.state === "reaped" || cleanupResult.state == null));
+    // BOT-1803: an IDLE lease (cleanupResult.state "active") is not a reap — its stack still
+    // runs, so its block stays reserved; so does one this run must not free (retainBlock).
+    const provenReap = !retainBlock && (!leaseProvisioned
+      || (cleanupResult?.ok === true && (cleanupResult.state === "reaped" || cleanupResult.state == null)));
     execution?.release?.({ reaped: provenReap });
     for (const [signal, handler] of signalHandlers) signals.off?.(signal, handler);
   }
@@ -3452,7 +3692,14 @@ export function runReceiptFields(result) {
     // BOT-2024: a stale-capacity refusal carries its phase + armable wait on the receipt.
     ...capacityStaleReceiptFields(result),
     ...(result.wait_exit_code != null ? { wait_exit_code: result.wait_exit_code, wait_receipt: result.wait_receipt ?? null } : {}),
-    child_exit_code: result.childExitCode ?? null, cleanup: result.cleanup?.ok ?? null,
+    child_exit_code: result.childExitCode ?? null,
+    // BOT-1803: an idle release is `cleanup: { idle: true, idle_since }` (nothing was reaped).
+    cleanup: result.cleanup?.idle ? { idle: true, idle_since: result.cleanup.idle_since ?? null } : result.cleanup?.ok ?? null,
+    ...(result.volumesKept ? { volumes_kept: true } : {}),
+    ...(result.idleLease?.reused ? { reused: result.idleLease.reused } : {}),
+    ...(result.idleLease?.reprovisioned ? { reprovisioned: result.idleLease.reprovisioned } : {}),
+    ...(result.idleLease?.previousLeaseId ? { previous_lease_id: result.idleLease.previousLeaseId } : {}),
+    ...(result.idleLease?.stackDigest ? { stack_digest: result.idleLease.stackDigest } : {}),
     ...(result.parkReason ? { park_reason: result.parkReason } : {}),
     // BOT-2142: where the lease ran and how the child reached it.
     execution_mode: result.execution?.mode ?? null,