@botbuddy/cli 1.53.1 → 1.55.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.53.1",
-  "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
+  "version": "1.55.0",
+  "description": "BotBuddy \u2014 Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {
     "bb": "./bin/botbuddy.mjs",

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, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, 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";
@@ -1108,7 +1108,7 @@ function selectPortBase(preferred, taken) {
  * (BOT-1798, Codex #928 R4 P1). The refresh prunes and copies BEFORE
  * `resolveStackPath` could notice an escape, so a stale or hostile symlink at
  * `.botbuddy/`, `.botbuddy/stacks/`, `<project_id>/` or its `supabase/` would
- * make `prune()` delete data OUTSIDE the worktree. Every existing component of
+ * make the refresh's deletions remove data OUTSIDE the worktree. Every existing component of
  * the path must therefore resolve to itself; the first one that does not is
  * fatal, and a component that does not exist yet ends the walk (nothing below it
  * can exist either). `worktreeRoot` is already canonical (realpath of the cwd).
@@ -1137,12 +1137,76 @@ function assertCanonicalTarget(worktreeRoot, relPath, realpath) {
  * worktree cannot linger in the leased stack (and be applied by `supabase start`).
  * The stack's own CLI scratch state (SKIP_ENTRIES) is left alone. A not-yet-created
  * directory is simply nothing to prune. */
-function prune(stackSupabaseDir, { readdir, remove }) {
-  let entries;
-  try { entries = readdir(stackSupabaseDir); } catch { return; }
-  for (const entry of entries) {
-    if (SKIP_ENTRIES.has(entry)) continue;
-    remove(join(stackSupabaseDir, entry), { recursive: true, force: true });
+// BOT-2403 — the stack is refreshed IN PLACE. The edge runtime bind-mounts
+// `<stack>/supabase/functions` (a directory) and each BOT-1828 escaping import (single
+// files), and a bind mount pins the inode it resolved at container start. The old
+// prune-then-cpSync refresh removed and recreated every one of them on each run (also a
+// refused or queued one, which materializes before its lease request), so a live or idle
+// stack's runtime was left holding deleted directories: 0 functions, every function 503
+// BOOT_ERROR after re-adoption. Here an existing directory is kept and recursed into, an
+// unchanged file is not touched, a changed file is rewritten in place (copyFileSync keeps
+// the inode; cpSync onto an existing file does not), and only entries the source no longer
+// has — or whose type changed — are removed (rsync --delete semantics, as before).
+
+/** True when two regular files have identical bytes. */
+function sameFileContent(a, b, { read, lstat }) {
+  try {
+    if (lstat(a).size !== lstat(b).size) return false;
+    return Buffer.compare(read(a), read(b)) === 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Bring one source entry to `dest` in place; `copy` only ever creates what is missing. */
+function syncEntryInPlace(source, dest, ops) {
+  const { lstat, readlink, remove, copy, copyFile } = ops;
+  const src = lstat(source);
+  let existing = null;
+  try { existing = lstat(dest); } catch { /* missing */ }
+  if (src.isDirectory()) {
+    if (existing?.isDirectory()) return syncTreeInPlace(source, dest, ops);
+    if (existing) remove(dest, { recursive: true, force: true });
+    copy(source, dest, { recursive: true, force: true, verbatimSymlinks: true, filter: (path) => !SKIP_ENTRIES.has(basename(path)) });
+    return;
+  }
+  if (src.isSymbolicLink()) {
+    if (existing?.isSymbolicLink() && readlink(dest) === readlink(source)) return;
+    if (existing) remove(dest, { recursive: true, force: true });
+    copy(source, dest, { force: true, verbatimSymlinks: true });
+    return;
+  }
+  if (existing?.isFile()) {
+    if (!sameFileContent(source, dest, ops)) copyFile(source, dest);
+    return;
+  }
+  if (existing) remove(dest, { recursive: true, force: true });
+  copy(source, dest, { force: true });
+}
+
+/**
+ * Make `dest` mirror `source` without replacing anything that already matches. `keep`
+ * names top-level `dest` entries that are not the source's to manage (the Supabase CLI's
+ * scratch state, the rewritten config.toml); `SKIP_ENTRIES` are never copied.
+ */
+function syncTreeInPlace(source, dest, ops, { keep = new Set() } = {}) {
+  const { readdir, remove, mkdir } = ops;
+  mkdir(dest, { recursive: true });
+  const wanted = new Set(readdir(source).filter((entry) => !SKIP_ENTRIES.has(entry) && !keep.has(entry)));
+  for (const entry of readdir(dest)) {
+    if (keep.has(entry) || wanted.has(entry)) continue;
+    remove(join(dest, entry), { recursive: true, force: true });
+  }
+  for (const entry of wanted) syncEntryInPlace(join(source, entry), join(dest, entry), ops);
+}
+
+/** The inode of the stack's functions directory, or null when it has none. */
+function functionsInode(stackDir, lstat) {
+  try {
+    const st = lstat(join(stackDir, "supabase", "functions"));
+    return st.isDirectory() ? Number(st.ino) : null;
+  } catch {
+    return null;
   }
 }
 
@@ -1247,7 +1311,7 @@ function listMatchingFiles(dir, { exts = [], names = [] }, { readdir, stat }) {
  * file that does not exist, naming the importing file and the specifier. Returns the
  * sorted list of worktree-relative paths copied (possibly empty).
  */
-function copyEscapingImports(worktreeRoot, stackDir, { read, mkdir, copy, readdir, stat, realpath }) {
+function copyEscapingImports(worktreeRoot, stackDir, { read, mkdir, copy, readdir, stat, realpath, sync = null }) {
   const functionsDir = join(worktreeRoot, "supabase", "functions");
   const visited = new Set(); // worktree-relative paths already queued or copied
   const queue = [];
@@ -1333,7 +1397,10 @@ function copyEscapingImports(worktreeRoot, stackDir, { read, mkdir, copy, readdi
     // whose text to scan for further imports.
     let isDir = false;
     try { isDir = stat(item.absPath).isDirectory(); } catch { /* copy() will report it */ }
-    copy(item.absPath, dest, isDir ? { recursive: true, force: true } : { force: true });
+    // BOT-2403: each copied file is a single-file bind mount of a running edge runtime, so
+    // it is refreshed in place (same inode), never replaced.
+    if (sync) syncEntryInPlace(item.absPath, dest, sync);
+    else copy(item.absPath, dest, isDir ? { recursive: true, force: true } : { force: true });
     extraFiles.push(item.relPath);
     if (!isDir && ESCAPING_IMPORT_SCAN_EXTENSIONS.some((ext) => item.relPath.endsWith(ext))) {
       scanForImports(item.absPath, item.relPath);
@@ -1354,9 +1421,11 @@ function copyEscapingImports(worktreeRoot, stackDir, { read, mkdir, copy, readdi
  * symlink that resolves on the host does not resolve inside Docker (the same
  * reason Supply Guard's isolated-stack script materializes function sources).
  * Copying every run also keeps the leased stack in step with the worktree — and
- * the copy is a REPLACE (rsync --delete semantics, like the hermetic lane), so a
+ * the copy mirrors the worktree (rsync --delete semantics, like the hermetic lane), so a
  * migration or function deleted in the worktree is not resurrected by the leased
- * stack. Only the Supabase CLI's own scratch state survives the refresh.
+ * stack. Only the Supabase CLI's own scratch state survives the refresh. BOT-2403: the
+ * refresh is IN PLACE — a running (or idle) stack's edge runtime bind-mounts the
+ * functions directory and the escaping-import files, so they are never replaced.
  */
 export function materializeRunStackDir(cwd, { slot, ticket, nonce, idleTtlSecs } = {}, io = {}) {
   const read = io.readFile ?? readFileSync;
@@ -1369,6 +1438,14 @@ export function materializeRunStackDir(cwd, { slot, ticket, nonce, idleTtlSecs }
   const now = io.now ?? Date.now;
   const rename = io.rename ?? renameSync;
   const resolveRoot = io.realpath ?? realpathSync;
+  const lstat = io.lstat ?? lstatSync;
+  const warn = io.warn ?? (() => {});
+  // BOT-2403: the in-place refresh's file operations (`copy` only creates what is missing).
+  const sync = {
+    read, mkdir, remove, copy, readdir, lstat,
+    readlink: io.readlink ?? readlinkSync,
+    copyFile: io.copyFile ?? copyFileSync,
+  };
 
   const worktreeRoot = resolveRoot(cwd);
   const sourceDir = join(worktreeRoot, "supabase");
@@ -1412,7 +1489,7 @@ export function materializeRunStackDir(cwd, { slot, ticket, nonce, idleTtlSecs }
   // stable per-slot one, so the project id is exactly as specific (and keeps a
   // refresh idempotent).
   const invocationToken = nonce ? String(nonce) : identity.projectId;
-  const marker = (portBase, extraFiles = []) => JSON.stringify({
+  const marker = (portBase, extraFiles = [], functionsIno = null) => JSON.stringify({
     schema: 1,
     project_id: identity.projectId,
     invocation_token: invocationToken,
@@ -1428,6 +1505,9 @@ export function materializeRunStackDir(cwd, { slot, ticket, nonce, idleTtlSecs }
     // outside supabase/ — recorded so an operator can see why this stack dir has
     // (e.g.) a src/ directory, instead of guessing at a `supabase start` failure.
     extra_files: extraFiles,
+    // BOT-2403: the functions directory a running edge runtime bind-mounts; a later run
+    // warns when another writer replaced it (the container would keep the old one).
+    functions_inode: functionsIno,
   });
   const registryDir = io.portRegistryDir ?? defaultPortRegistryDir();
   const writeExclusive = io.writeExclusive ?? ((path, data) => writeFileSync(path, data, { flag: "wx" }));
@@ -1490,29 +1570,35 @@ export function materializeRunStackDir(cwd, { slot, ticket, nonce, idleTtlSecs }
     const { text } = rewriteLeasedStackConfig(rootConfig, { projectId: identity.projectId, portBase });
     assertLeasedStackIsolated(rootConfig, text);
 
-    prune(join(stackDir, "supabase"), { readdir, remove });
-    copy(sourceDir, join(stackDir, "supabase"), {
-      recursive: true,
-      force: true,
-      // BOT-2142: keep relative symlinks relative (cpSync's default rewrites them to
-      // absolute links INTO the source worktree, which a remote bundle must refuse —
-      // Supply Guard's supabase/CLAUDE.md -> AGENTS.md).
-      verbatimSymlinks: true,
-      filter: (source) => !SKIP_ENTRIES.has(basename(source)),
-    });
-    write(join(stackDir, "supabase", "config.toml"), text);
+    // BOT-2403: a replaced functions directory strands a running edge runtime's bind mount.
+    // This refresh never replaces it; another writer may have, so say so once.
+    const recordedIno = previous?.project_id === identity.projectId && Number.isInteger(previous?.functions_inode) ? previous.functions_inode : null;
+    const currentIno = functionsInode(stackDir, lstat);
+    if (recordedIno !== null && currentIno !== null && currentIno !== recordedIno) {
+      warn(`stack: warning: ${stackPath}/supabase/functions was replaced since this stack was materialized (inode ${recordedIno} → ${currentIno}); ` +
+        "a running edge runtime still sees the old directory. Update a leased stack directory in place — never rm + recreate it.");
+    }
+
+    // BOT-2142: symlinks stay verbatim (relative), never rewritten to absolute links INTO
+    // the source worktree, which a remote bundle must refuse (Supply Guard's
+    // supabase/CLAUDE.md -> AGENTS.md).
+    syncTreeInPlace(sourceDir, join(stackDir, "supabase"), sync, { keep: new Set([...SKIP_ENTRIES, "config.toml"]) });
+    let currentConfig = null;
+    try { currentConfig = read(join(stackDir, "supabase", "config.toml"), "utf8"); } catch { /* first materialization */ }
+    if (currentConfig !== text) write(join(stackDir, "supabase", "config.toml"), text);
 
     // BOT-1828: bring along any file an edge function imports OUTSIDE supabase/
     // (Supply Guard's admin-api-keys/index.ts pulls in ../../../src/lib/…) —
     // `supabase start` resolves function imports when it starts the edge runtime, so
     // without this the Helper fails deep inside `supabase start` with a raw ENOENT.
-    const extraFiles = copyEscapingImports(worktreeRoot, stackDir, { read, mkdir, copy, readdir, stat, realpath: resolveRoot });
+    const extraFiles = copyEscapingImports(worktreeRoot, stackDir, { read, mkdir, copy, readdir, stat, realpath: resolveRoot, sync });
 
   // Re-state the claim after the copy: the marker records who owns this directory,
   // which port block it holds, and how long a later run must keep it (Codex #928
   // R7/R12). It lives beside `supabase/`, which the refresh replaces wholesale.
-    atomicWrite(join(stackDir, LEASED_STACK_MARKER), marker(portBase, extraFiles), { write, rename });
-    atomicWrite(portClaimPath(registryDir, portBase), marker(portBase, extraFiles), { write, rename });
+    const functionsIno = functionsInode(stackDir, lstat);
+    atomicWrite(join(stackDir, LEASED_STACK_MARKER), marker(portBase, extraFiles, functionsIno), { write, rename });
+    atomicWrite(portClaimPath(registryDir, portBase), marker(portBase, extraFiles, functionsIno), { write, rename });
     return stackPath;
   } catch (error) {
     try { remove(portClaimPath(registryDir, portBase), { force: true }); } catch { /* best effort */ }

package/src/stack-mount-health.mjs

@@ -0,0 +1,94 @@
+// BOT-2403 — a re-adopted idle stack is never handed over with a stale functions mount.
+//
+// The edge runtime (`supabase_edge_runtime_<project>`) bind-mounts the stack's
+// `supabase/functions` DIRECTORY. A bind mount pins the directory it resolved at
+// container start: if that directory is later removed and recreated (a new inode — what
+// `bb stack run`'s materializer did before BOT-2403, and what any rm + recreate writer
+// does), the container keeps the deleted directory and lists 0 entries, so every function
+// answers 503 BOOT_ERROR while the host directory looks complete. Re-adoption proves the
+// files' CONTENT (the stack digest), not that the running container still sees them.
+//
+// So before a re-adopted CO-LOCATED stack is reported ready, `bb stack run` checks the
+// mount from inside the container. Empty while the host directory is not → restart the
+// edge runtime once (a restart resolves the bind source again) → still empty → the caller
+// re-provisions. A remote lease is skipped: re-adoption uploads no bundle, so the Helper's
+// copy of the stack directory is never rewritten under a running container. A stack with
+// no functions, or with no edge runtime container (`No such container`), is skipped too; any
+// other inspection failure fails closed.
+//
+// Dependency-free (Node stdlib only); docker is run with a fixed argv, never a shell.
+import { execFile } from "node:child_process";
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { dockerSelectorArgs } from "./stack-usage.mjs";
+
+export const MOUNT_CHECK_TIMEOUT_MS = 10_000;
+export const RUNTIME_RESTART_TIMEOUT_MS = 60_000;
+const CO_LOCATED_MODES = new Set(["local", "local_exec"]);
+const PROJECT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$/;
+
+/** Default runner: `docker <args>` with a hard timeout; never a shell. */
+export function runDocker(args, { timeoutMs = MOUNT_CHECK_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: 4 * 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => {
+      resolve({ code: error ? (typeof error.code === "number" ? error.code : 1) : 0, stdout: String(stdout ?? ""), stderr: String(stderr ?? ""), timedOut: Boolean(error?.killed) });
+    });
+  });
+}
+
+/** The container path the functions directory is mounted at, or null (from `docker inspect … .Mounts`). */
+export function functionsMountDestination(mountsJson, hostFunctionsDir) {
+  let mounts;
+  try { mounts = JSON.parse(String(mountsJson ?? "").trim()); } catch { return null; }
+  if (!Array.isArray(mounts)) return null;
+  const mount = mounts.find((m) => m?.Type === "bind" && m?.Source === hostFunctionsDir);
+  return typeof mount?.Destination === "string" && mount.Destination ? mount.Destination : null;
+}
+
+/**
+ * Check (and once repair) the functions mount of a re-adopted idle lease.
+ * `lease` is the re-adoption answer: `{ execution_mode, connection: { project_id, botbuddy_docker_target? } }`.
+ * Returns `{ ok: true, skipped? , restarted? }` or `{ ok: false, restarted, reason }`. Never throws.
+ */
+export async function checkReadoptedStackMounts(lease, stackDir, { run = runDocker, listHost = (dir) => readdirSync(dir), log = () => {} } = {}) {
+  if (!CO_LOCATED_MODES.has(lease?.execution_mode)) return { ok: true, skipped: "remote" };
+  const projectId = lease?.connection?.project_id;
+  if (typeof projectId !== "string" || !PROJECT_ID_RE.test(projectId)) return { ok: true, skipped: "no_project_id" };
+  if (typeof stackDir !== "string" || !stackDir) return { ok: true, skipped: "no_stack_dir" };
+  const hostFunctions = join(stackDir, "supabase", "functions");
+  let hostEntries;
+  try { hostEntries = listHost(hostFunctions); } catch { return { ok: true, skipped: "no_functions" }; }
+  if (!Array.isArray(hostEntries) || hostEntries.length === 0) return { ok: true, skipped: "no_functions" };
+
+  const docker = dockerSelectorArgs(lease.connection.botbuddy_docker_target ?? null);
+  const container = `supabase_edge_runtime_${projectId}`;
+  const inspect = await run([...docker, "container", "inspect", "--format", "{{json .Mounts}}", container]);
+  if (inspect.code !== 0) {
+    // Only a definitively absent runtime (edge_runtime disabled) is skipped. Any other
+    // failure — daemon/context down, permissions, a timeout — fails closed (Codex #1191 P2):
+    // the caller re-provisions rather than hand over a stack nobody could check.
+    // Real counterpart (Docker Desktop, 2026-10-16): "Error response from daemon: No such container: <name>".
+    if (!inspect.timedOut && /No such (container|object)/i.test(inspect.stderr ?? "")) return { ok: true, skipped: "no_edge_runtime" };
+    return { ok: false, restarted: false, reason: `could not inspect ${container} (exit ${inspect.code}${inspect.timedOut ? ", timed out" : ""})` };
+  }
+  const destination = functionsMountDestination(inspect.stdout, hostFunctions);
+  if (!destination) return { ok: false, restarted: false, reason: `${container} does not bind-mount ${hostFunctions}` };
+
+  const mountedEntries = async () => {
+    const answer = await run([...docker, "exec", container, "ls", "-A", destination]);
+    if (answer.code !== 0) return null;
+    return answer.stdout.split(/\r?\n/).filter((line) => line.length > 0).length;
+  };
+  const first = await mountedEntries();
+  if (first) return { ok: true, restarted: false };
+
+  log(`stack: the re-adopted stack's edge runtime sees ${first === null ? "no readable" : "an empty"} functions mount (${hostEntries.length} entries on the host) — restarting ${container} once`);
+  const restart = await run([...docker, "restart", container], { timeoutMs: RUNTIME_RESTART_TIMEOUT_MS });
+  if (restart.code !== 0) {
+    return { ok: false, restarted: false, reason: `docker restart ${container} failed (exit ${restart.code}${restart.timedOut ? ", timed out" : ""})` };
+  }
+  const second = await mountedEntries();
+  if (second) return { ok: true, restarted: true };
+  return { ok: false, restarted: true, reason: `${container} still sees ${second === null ? "no readable" : "an empty"} functions mount after a restart` };
+}

package/src/stack-usage.mjs

@@ -27,10 +27,29 @@ export const SUPABASE_INTERNAL_ROLES = Object.freeze([
 
 const ROLE_LIST = SUPABASE_INTERNAL_ROLES.map((r) => `'${r}'`).join(", ");
 
+/**
+ * BOT-2402: Supabase's own internal database. Logflare (`supabase_analytics_<project>`)
+ * writes its log tables there as `postgres` every ~10 s, so on a stack with analytics
+ * enabled every observation looked like fresh client use. Nothing a client does to the
+ * project happens there; the Helper census excludes it too (helper 0.2.39).
+ */
+export const SUPABASE_INTERNAL_DATABASE = "_supabase";
+
+/**
+ * BOT-2402: a pg_cron job run is a libpq connection the scheduler opens to its own server
+ * (unix socket or loopback) as the job owner, usually `postgres`, every minute. It is the
+ * stack's own schedule, not a client (the Helper census rule, BOT-2219). A backend that only
+ * borrows the name from another address is still a client.
+ */
+const NOT_CRON_RUN = "NOT (coalesce(application_name, '') = 'pg_cron' AND (client_addr IS NULL OR host(client_addr) IN ('127.0.0.1', '::1')))";
+const NOT_PLATFORM = `datname IS DISTINCT FROM '${SUPABASE_INTERNAL_DATABASE}' AND ${NOT_CRON_RUN}`;
+
 /**
  * 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
+ *      this probe, anything on the internal `_supabase` database, pg_cron's own job runs
+ *      (BOT-2402) 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.
@@ -38,9 +57,11 @@ const ROLE_LIST = SUPABASE_INTERNAL_ROLES.map((r) => `'${r}'`).join(", ");
 export const USAGE_SQL =
   "SELECT " +
   "(SELECT count(*) FROM pg_stat_activity WHERE backend_type = 'client backend' AND pid <> pg_backend_pid() " +
+  `AND ${NOT_PLATFORM} ` +
   `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 ${NOT_PLATFORM} ` +
   `AND (coalesce(usename, '') NOT IN (${ROLE_LIST}) OR usename = 'authenticator'))`;
 
 const CO_LOCATED_MODES = new Set(["local", "local_exec"]);

package/src/stack.mjs

@@ -44,6 +44,7 @@ import { runDockerCommand, runDockerWorkflow, ADMITTED_DOCKER_VALIDATIONS } from
 import { acquireStackLock, lockPathForProject, projectIdFromConfig } from "./stack-file-lock.mjs";
 import { LEASED_STACK_IDLE_RETENTION_SECS, assertLeasedStackIsolated, leasedStackClaimHeld, markLeasedStackReleased, stableRunStackReusable, leasedStackIdentity, materializeRunStackDir, portMapInConfig, refreshLeasedStackRetention, releaseLeasedStackClaim, reservePortBlocks } from "./stack-isolation.mjs";
 import { measureStackUsage } from "./stack-usage.mjs";
+import { checkReadoptedStackMounts } from "./stack-mount-health.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";
@@ -218,7 +219,11 @@ ${bold("EXIT CODES")}
 ${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"
+    reused_idle      the slot's idle lease is re-adopted: no provision; receipt reused "idle".
+                     A co-located one is handed over only when its edge runtime still sees the
+                     functions (BOT-2403): an empty mount restarts the runtime once; still empty →
+                     the lease is reaped and the request re-sent once (reprovisioned
+                     "unhealthy_mount"); receipt readopt_health {ok, restarted|skipped, reason}
     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
@@ -586,6 +591,7 @@ const CONSIDERED_VERDICT_TEXT = {
   HOST_CAPACITY_WAIT: () => "Docker pressure full",
   HOST_CAPACITY_BUDGET_FULL: () => "slot budget full",
   HOST_CAPACITY_INVENTORY_UNKNOWN: () => "unknown Docker resources in its census",
+  HOST_PRESSURE: () => "host under pressure",
   TENANT_RESERVATION_FULL: () => "tenant reservation full",
   SLOT_HELD: () => "this slot is already leased there",
   HOST_HELPER_OUTDATED: () => "Helper predates remote leases (protocol < 4)",
@@ -605,6 +611,33 @@ export function describeConsidered(considered) {
     });
 }
 
+/**
+ * BOT-1630: the typed park reason of a queued lease, or null. The server holds a host under
+ * pressure (`docker info` failing, low memory, engine footprint) with verdict HOST_PRESSURE, and
+ * a Helper that hits it mid-provision defers the lease back to the queue with that reason.
+ */
+export function queuedParkReason(d) {
+  if (!d || typeof d !== "object") return null;
+  const ledger = d.ledger && typeof d.ledger === "object" ? d.ledger : null;
+  if (ledger?.verdict === "HOST_PRESSURE" || ledger?.capacity?.code === "HOST_PRESSURE") return "host_pressure";
+  const here = Array.isArray(d.considered) ? d.considered.find((c) => c?.host_key === d.host_key) : null;
+  if (here?.verdict_code === "HOST_PRESSURE") return "host_pressure";
+  if (d.provision_defer_reason === "HOST_PRESSURE") return "host_pressure";
+  return null;
+}
+
+/** BOT-1630: "docker_unresponsive (docker_command_failed:docker info:-2; clears …)" per binding dimension. */
+export function describePressure(d) {
+  const reasons = d?.ledger?.capacity?.pressure?.reasons;
+  if (!Array.isArray(reasons) || reasons.length === 0) return null;
+  return reasons.filter((r) => r && typeof r.dimension === "string").map((r) => {
+    const parts = [];
+    if (r.observed != null) parts.push(r.limit != null ? `${r.observed} vs limit ${r.limit}` : String(r.observed));
+    if (typeof r.clears_at === "string") parts.push(`clears ${r.clears_at}`);
+    return parts.length ? `${r.dimension} (${parts.join("; ")})` : r.dimension;
+  }).join(", ") || null;
+}
+
 export function describeUnitLedger(ledger) {
   if (!ledger || typeof ledger !== "object") return [];
   const cap = ledger.capacity ?? {};
@@ -707,7 +740,7 @@ async function claimProjectLock(projectId, lock, subject) {
   }
 }
 
-export async function resolveRunExecution(cwd, opts, { materialize = materializeRunStackDir, lock = acquireStackLock, identity = leasedStackIdentity, reserveBlocks = reservePortBlocks, releaseClaim = releaseLeasedStackClaim, claimHeld = leasedStackClaimHeld, stableReusable = stableRunStackReusable, markReleased = markLeasedStackReleased, portRegistryDir = null } = {}) {
+export async function resolveRunExecution(cwd, opts, { materialize = materializeRunStackDir, lock = acquireStackLock, identity = leasedStackIdentity, reserveBlocks = reservePortBlocks, releaseClaim = releaseLeasedStackClaim, claimHeld = leasedStackClaimHeld, stableReusable = stableRunStackReusable, markReleased = markLeasedStackReleased, portRegistryDir = null, warn = (line) => process.stderr.write(`${line}\n`) } = {}) {
   const refuseRoot = (execution) => {
     if (execution.stackPath === ".") {
       throw new Error(
@@ -785,7 +818,8 @@ export async function resolveRunExecution(cwd, opts, { materialize = materialize
     const execution = refuseRoot(resolveStackPath(cwd, materialize(
       cwd,
       { slot: opts.slot, repo: opts.repo, ticket: opts.ticket, nonce, idleTtlSecs: opts.idleTtl ?? undefined },
-      portRegistryDir ? { portRegistryDir } : {},
+      // BOT-2403: a functions directory another writer replaced under this stack is reported.
+      { ...(portRegistryDir ? { portRegistryDir } : {}), warn },
     )));
     return {
       ...execution,
@@ -2865,6 +2899,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" });
+// BOT-2403: the re-adopted idle stack failed the functions-mount gate and was reaped.
+const READOPT_UNHEALTHY_REASON = "unhealthy_mount";
 
 function safeConnectionPath(requested, leaseId) {
   if (requested) {
@@ -3093,6 +3129,8 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   // stack directory; the default is the real materializing resolver.
   const resolveExecution = adapters.resolveExecution ?? ((runOpts) => resolveRunExecution(process.cwd(), runOpts));
   const refreshRetention = adapters.refreshRetention ?? refreshLeasedStackRetention;
+  // BOT-2403: a re-adopted co-located idle stack must see its functions before it is handed over.
+  const readoptHealth = adapters.readoptHealth ?? ((lease, stackDir) => checkReadoptedStackMounts(lease, stackDir, { log: stderrLine }));
   // BOT-2142: remote-lease seams (bundle build/upload, SSH forwards). Production uses the
   // real builders; the fake-ssh tests swap only the ssh binary (BOTBUDDY_STACK_SSH_BIN works too).
   const buildBundle = adapters.buildBundle ?? buildStackBundle;
@@ -3124,7 +3162,7 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   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 };
+  const idleLease = { reused: null, reprovisioned: null, previousLeaseId: null, stackDigest: null, readoptHealth: 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).
@@ -3407,16 +3445,43 @@ 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" };
       }
-      const why = attempt === 0 && request.data?.success === false && request.data?.lease_id ? IDLE_REPROVISION_REASONS[request.data.code] : null;
+      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
+      // same request once more, exactly like a digest re-provision.
+      if (!why && attempt === 0 && request.data?.success === true && request.data.reused === true && request.data.reused_idle === true) {
+        let health;
+        try { health = await readoptHealth(request.data, stackDirFor(execution)); } catch (error) { health = { ok: false, reason: String(error?.message ?? error) }; }
+        idleLease.readoptHealth = health;
+        if (!health?.ok) {
+          const broken = request.data.lease_id;
+          stderrLine(`stack: re-adopted idle lease ${broken} is not healthy (${health?.reason ?? "unknown"}) — reaping it and provisioning a fresh stack`);
+          const released = await api.release(broken);
+          if (!released?.ok || released.data?.success === false) {
+            retainBlock = true;
+            return {
+              exitCode: EXIT.LEASE_FAILED, outcome: "error", code: "READOPT_UNHEALTHY", leaseId: broken,
+              error: `re-adopted idle lease ${broken} is not healthy (${health?.reason ?? "unknown"}) and its reap could not be requested ` +
+                `(${released?.data?.code ?? released?.error ?? "release failed"}); run \`bb stack done ${broken} --reap\` and re-run`,
+            };
+          }
+          why = READOPT_UNHEALTHY_REASON;
+        }
+      }
       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`);
+      const becoming = why === "preempted" ? "preempted"
+        : why === READOPT_UNHEALTHY_REASON ? "reaped (its edge runtime lost the functions mount)" : "re-provisioned (the stack content changed)";
+      stderrLine(`stack: this slot's idle lease ${previous} is being ${becoming} — 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 };
+        // Codex #1191 P2: the old lease's reap is not proven, so its containers may still hold
+        // this stack's ports — keep the block (never double-booked by the next run).
+        retainBlock = true;
+        return { exitCode: SIGNAL_EXIT[receivedSignal] ?? EXIT.INTERNAL, outcome: "interrupted", code: request.data.code ?? "READOPT_UNHEALTHY" };
       }
       let reaped = Boolean(gone?.woke) && gone.state === "reaped";
       if (!reaped && !gone?.failed) {
@@ -3428,7 +3493,7 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         // Its containers may still hold this stack's ports.
         retainBlock = true;
         return {
-          exitCode: EXIT.LEASE_FAILED, outcome: "error", code: request.data.code,
+          exitCode: EXIT.LEASE_FAILED, outcome: "error", code: request.data.code ?? "READOPT_UNHEALTHY",
           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 } : {}),
@@ -3547,16 +3612,28 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       const cleanup = await requestCleanup();
       return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup };
     }
+    // BOT-1630: ONE park budget (--timeout) across every park. A Helper that finds the host under
+    // pressure mid-provision defers the lease back to `queued` (its place kept); run then parks
+    // again against the same deadline instead of timing out on the provision clock.
+    const parkDeadlineMs = (adapters.now ?? Date.now)() + opts.timeout * 1000;
+    let parkView = request.data;
+    let parkReason = null;
+    for (;;) {
     if (state === "queued") {
       // BOT-2019: say where the lease sits (server dispatch rank, or why it has none) before parking.
-      stderrLine(`stack: lease ${leaseId} queued — ${describeQueuePosition(request.data)}`);
-      for (const line of describeUnitLedger(request.data.ledger)) stderrLine(`stack: ${line}`);
-      for (const line of describeConsidered(request.data.considered)) stderrLine(`stack: ${line}`);
+      stderrLine(`stack: lease ${leaseId} queued — ${describeQueuePosition(parkView)}`);
+      for (const line of describeUnitLedger(parkView.ledger)) stderrLine(`stack: ${line}`);
+      for (const line of describeConsidered(parkView.considered)) stderrLine(`stack: ${line}`);
+      parkReason = queuedParkReason(parkView) ?? parkReason;
+      if (parkReason === "host_pressure") {
+        const why = describePressure(parkView);
+        stderrLine(`stack: parked — park_reason host_pressure${why ? `: ${why}` : ""}; the lease keeps its queue place and starts when the host's pressure clears`);
+      }
       activeWaitAbort = new AbortController();
       // BOT-2013: every reap state (reaping / reaped / reap_failed) means the queued lease is lost.
       // BOT-2099: an auth/availability blip is retried inside the park until its deadline;
       // it never releases a queued lease or becomes the lease's outcome.
-      const parked = await resilientWait(leaseId, (s) => s !== "queued" && s != null, isReaped, { timeoutSec: opts.timeout, auth: rpc.auth, signal: activeWaitAbort.signal });
+      const parked = await resilientWait(leaseId, (s) => s !== "queued" && s != null, isReaped, { timeoutSec: opts.timeout, deadlineMs: parkDeadlineMs, auth: rpc.auth, signal: activeWaitAbort.signal });
       activeWaitAbort = null;
       const incident = parkIncident ? { incident: parkIncident } : {};
       if (parked?.interrupted || receivedSignal) { const cleanup = await requestCleanup(); return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup, ...incident }; }
@@ -3578,7 +3655,7 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
             error: `lease ${leaseId} parked ${opts.timeout}s inside a platform incident (${parkIncident.reason} since ${parkIncident.first_at}), so its admission was never observed`,
           };
         }
-        return { exitCode: EXIT.TIMEOUT, outcome: "timeout", leaseId, error: `parked ${opts.timeout}s without capacity`, cleanup, ...incident, ...(ledger ? { ledger } : {}) };
+        return { exitCode: EXIT.TIMEOUT, outcome: "timeout", leaseId, error: `parked ${opts.timeout}s without capacity`, cleanup, ...incident, ...(ledger ? { ledger } : {}), ...(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 }; }
@@ -3593,17 +3670,33 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       // provisionTimeout before the belt-and-braces recheck below ever notices
       // the lease is no longer provisioning. isReaped (== "reaping" || "reaped")
       // already covers both; cmdUp's equivalent waits use it for this reason.
-      const active = await resilientWait(leaseId, (s) => s === "active", isReaped, { timeoutSec: provisionTimeout, auth: rpc.auth, signal: activeWaitAbort.signal });
+      // BOT-1630: `queued` also ends this wait — a deferred provision (HOST_PRESSURE, capacity).
+      const active = await resilientWait(leaseId, (s) => s === "active" || s === "queued", isReaped, { timeoutSec: provisionTimeout, auth: rpc.auth, signal: activeWaitAbort.signal });
       activeWaitAbort = null;
       if (active?.interrupted || receivedSignal) { const cleanup = await requestCleanup(); return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup }; }
       if (active?.authUnavailable) { const cleanup = await requestCleanup(); return authUnavailableResult(active, "provisioning", cleanup); }
+      if (active?.state === "queued" && !active.timeout && !active.failed && !active.error && !active.auth) {
+        const read = await readLeaseQuietly(leaseId);
+        parkView = read?.ok && read.data?.success ? read.data : { host_key: placement.hostKey };
+        const why = parkView.provision_defer_reason ?? "host capacity";
+        stderrLine(`stack: lease ${leaseId} was deferred back to the queue while provisioning (${why}) — its place is kept; parking again`);
+        state = "queued";
+        continue;
+      }
       if (active?.timeout) {
         // BOT-1822 belt-and-braces: the zero-poll wait can still miss a live
         // `stack_lease` signal (an older server before this fix, a relay hiccup,
         // BOT-1816's class of dropped wakes) even though the lease genuinely went
-        // active. One direct read before declaring a timeout tells that apart from
-        // a lease that truly never provisioned, instead of reaping a healthy stack.
+        // active or was deferred back to queued. One direct read before declaring
+        // a timeout avoids reaping a healthy stack or destroying a kept queue place.
         const recheck = await api.get(leaseId);
+        if (recheck?.ok && recheck.data?.success && recheck.data.state === "queued") {
+          parkView = recheck.data;
+          const why = parkView.provision_defer_reason ?? "host capacity";
+          stderrLine(`stack: lease ${leaseId} was deferred back to the queue while provisioning (${why}) — its place is kept; parking again`);
+          state = "queued";
+          continue;
+        }
         if (!(recheck?.ok && recheck.data?.success && recheck.data.state === "active")) {
           const cleanup = await requestCleanup();
           return { exitCode: EXIT.TIMEOUT, outcome: "timeout", leaseId, error: `physical provision did not reach active in ${provisionTimeout}s`, cleanup, ...(parkIncident ? { incident: parkIncident } : {}) };
@@ -3621,6 +3714,8 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         return { exitCode: active?.auth ? EXIT.AUTH : EXIT.LEASE_FAILED, outcome: "error", leaseId, error: active?.error || `lease ${active?.state ?? "failed"} before reaching active${why}`, cleanup, ...(parkIncident ? { incident: parkIncident } : {}) };
       }
     }
+    break;
+    }
     const current = await api.get(leaseId);
     if (!current?.ok || !current.data?.success || current.data.state !== "active" || !current.data.connection || typeof current.data.connection !== "object") {
       const cleanup = await requestCleanup();
@@ -3834,6 +3929,7 @@ export function runReceiptFields(result) {
     ...(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.idleLease?.readoptHealth ? { readopt_health: result.idleLease.readoptHealth } : {}),
     ...(result.parkReason ? { park_reason: result.parkReason } : {}),
     // BOT-2142: where the lease ran and how the child reached it.
     execution_mode: result.execution?.mode ?? null,