@botbuddy/cli 1.43.0 → 1.44.0

package/package.json

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

package/src/stack-bundle.mjs

@@ -50,6 +50,170 @@ export function isExcludedBundlePath(relPath) {
   return SECRET_DOTENV.test(name);
 }
 
+// ── BOT-2269: --bundle-include (exact paths) + the content guard ─────────────
+
+const NO_OPT_IN = new Set();
+/** An opted-in file is config, not data: anything bigger is refused before it is read. */
+export const BUNDLE_INCLUDE_MAX_BYTES = 1024 * 1024;
+const GLOB_CHARS = /[*?[\]{}]/;
+
+/**
+ * Validate one `--bundle-include` path: an EXACT stack-relative POSIX path to a file — no
+ * glob characters, no `..`/`.`/empty segments, not absolute, no backslashes, and never a path
+ * the bundle always drops whatever the caller asks (node_modules, Supabase CLI scratch, the
+ * retention marker). Returns the path unchanged; throws BUNDLE_INCLUDE_INVALID.
+ */
+export function validateBundleIncludePath(rel) {
+  const path = typeof rel === "string" ? rel : "";
+  const refuse = (why) => bundleError("BUNDLE_INCLUDE_INVALID", `--bundle-include ${JSON.stringify(path)}: ${why}`);
+  if (!path) throw refuse("needs an exact stack-relative file path (e.g. supabase/functions/.env)");
+  if (GLOB_CHARS.test(path)) throw refuse("globs are not accepted; name each file exactly");
+  if (path.includes("\\")) throw refuse("use forward slashes");
+  if (path.startsWith("/")) throw refuse("must be relative to the stack directory, not absolute");
+  const parts = path.split("/");
+  if (parts.some((p) => p === "" || p === "." || p === "..")) throw refuse("must not contain '..', '.' or empty segments, or end in '/'");
+  if (parts.some((p) => EXCLUDED_NAMES.has(p)) || (parts.length === 1 && EXCLUDED_ROOT_FILES.has(path))) {
+    throw refuse("is inside a path the bundle never ships (node_modules, supabase/.temp|.branches, .bb-stack.json)");
+  }
+  return path;
+}
+
+const DEMO_SUPABASE_SECRET = "sb_secret_N7UND0UgjKTVK-Uodkm0Hg_xSvEMPvz"; // the Supabase CLI's fixed local default
+const LIVE_KEY_SHAPES = [
+  { what: "a live Stripe secret key (sk_live_…)", re: /(?<![A-Za-z0-9])sk_live_[A-Za-z0-9]{8,}/ },
+  { what: "a live Stripe restricted key (rk_live_…)", re: /(?<![A-Za-z0-9])rk_live_[A-Za-z0-9]{8,}/ },
+  // Both documented Resend forms: re_<id>_<secret> and the single-segment re_<secret> (Codex #1125 P1).
+  // Short mock values (re_test_mock) stay below the 16-character floor.
+  { what: "a Resend API key (re_…)", re: /(?<![A-Za-z0-9_])re_[A-Za-z0-9_-]{16,}/ },
+  // Stripe webhook signing secrets look the same in test and live mode; mocks stay short
+  // (whsec_local_mock), a real one is whsec_ + 32 characters (Codex #1125 P1).
+  { what: "a Stripe webhook signing secret (whsec_…)", re: /(?<![A-Za-z0-9_])whsec_[A-Za-z0-9]{24,}/ },
+  { what: "a GitHub token (gh?_…)", re: /(?<![A-Za-z0-9_])gh[pousr]_[A-Za-z0-9]{30,}/ },
+  { what: "a GitHub fine-grained token (github_pat_…)", re: /(?<![A-Za-z0-9_])github_pat_[A-Za-z0-9_]{20,}/ },
+  { what: "an AWS access key id (AKIA…/ASIA…)", re: /(?<![A-Z0-9])(?:AKIA|ASIA)[0-9A-Z]{16}(?![0-9A-Z])/ },
+  { what: "a PEM private key block", re: /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----/ },
+  { what: "a Supabase secret key (sb_secret_…)", re: /(?<![A-Za-z0-9_])sb_secret_[A-Za-z0-9_-]{16,}/g, allow: (m) => m === DEMO_SUPABASE_SECRET },
+];
+const JWT_RE = /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*/g;
+const LOCAL_JWT_REFS = new Set(["local", "demo", "supabase-demo"]);
+
+function jwtPayload(token) {
+  try { return JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString("utf8")); } catch { return null; }
+}
+
+/** Why `value` (under `key`) is a live credential, or null. Never returns any part of the value. */
+function liveCredentialShape(key, value) {
+  for (const shape of LIVE_KEY_SHAPES) {
+    if (shape.allow) {
+      for (const m of value.matchAll(shape.re)) if (!shape.allow(m[0])) return shape.what;
+    } else if (shape.re.test(value)) return shape.what;
+  }
+  const serviceRoleKey = /SERVICE_ROLE_KEY$/i.test(key ?? "");
+  for (const [token] of value.matchAll(JWT_RE)) {
+    const claims = jwtPayload(token);
+    if (!claims || typeof claims !== "object") {
+      if (serviceRoleKey) return "a JWT that cannot be decoded (a service-role key must be the Supabase demo key)";
+      continue;
+    }
+    if (typeof claims.ref === "string" && !LOCAL_JWT_REFS.has(claims.ref)) return "a JWT for a hosted Supabase project (it carries a project ref)";
+    const demo = claims.iss === "supabase-demo";
+    if ((serviceRoleKey || claims.role === "service_role") && !demo) return "a service-role JWT that is not the Supabase demo key";
+  }
+  return null;
+}
+
+/** An unescaped closing quote of each dotenv quoting style. */
+const CLOSING_QUOTE = { '"': /(?<!\\)"/, "'": /(?<!\\)'/, "`": /(?<!\\)`/ };
+
+/** Parse dotenv text into [{ key, value, line }] (quotes, `export`, comments, multi-line quoted values). */
+function parseDotenv(text) {
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.-]*)\s*=\s?(.*)$/.exec(lines[i]);
+    if (!match) continue;
+    const [, key, rest] = match;
+    const start = i;
+    let value = rest.trim();
+    const quote = value[0];
+    if (quote === '"' || quote === "'" || quote === "`") {
+      let body = value.slice(1);
+      // A quoted value may span lines (a PEM block); consume until the closing quote.
+      const closing = CLOSING_QUOTE[quote];
+      while (!closing.test(body) && i + 1 < lines.length) body += `\n${lines[++i]}`;
+      const close = body.search(closing);
+      value = close === -1 ? body : body.slice(0, close);
+    } else {
+      value = value.replace(/\s+#.*$/, "");
+    }
+    out.push({ key, value, line: start + 1, endLine: i + 1 });
+  }
+  return out;
+}
+
+const isDotenvName = (rel) => /^\.env/.test(rel.split("/").pop()) || /\.env$/.test(rel);
+
+/**
+ * BOT-2269 content guard for one opted-in file. Refuses (BUNDLE_SECRET_ENV) when any value
+ * matches a live-credential shape, naming the KEY (or the line) and the shape — never the
+ * value. Every raw line is scanned as well (inline comments, lines the parser cannot
+ * attribute), so formatting is not a way around it. Returns { keys } (dotenv key names, file order, deduplicated).
+ */
+export function scanBundleIncludeEnv(rel, text) {
+  const refuse = (where, what) => bundleError("BUNDLE_SECRET_ENV",
+    `refusing to ship ${rel} in the stack bundle: ${where} looks like ${what}. Remove real provider credentials ` +
+      "from the opted-in file (a remote lease ships it to another host); mock values, the Supabase demo keys and " +
+      "loopback URLs are fine.");
+  const entries = isDotenvName(rel) ? parseDotenv(text) : [];
+  const keyOfLine = new Map();
+  for (const { key, value, line, endLine } of entries) {
+    for (let n = line; n <= endLine; n++) keyOfLine.set(n, key);
+    const what = liveCredentialShape(key, value);
+    if (what) throw refuse(key, what);
+  }
+  // Every RAW line is scanned too, not only the parsed values: an inline comment after a
+  // valid assignment (`MODE=mock # old KEY=sk_live_…`) never reaches a parsed value but
+  // still ships (Codex #1125 P1), and a line the parser cannot attribute ships as well.
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const what = liveCredentialShape(null, lines[i]);
+    if (what) throw refuse(keyOfLine.has(i + 1) ? `${keyOfLine.get(i + 1)} (line ${i + 1})` : `line ${i + 1}`, what);
+  }
+  // A PEM block split across unattributed lines is caught by its BEGIN line above.
+  return { keys: [...new Set(entries.map((e) => e.key))] };
+}
+
+/**
+ * Resolve and guard every `--bundle-include` path against the materialised stack root:
+ * syntax (validateBundleIncludePath), existence (BUNDLE_INCLUDE_MISSING), the existing symlink
+ * rules (the path, and every link on the way, must resolve inside the stack —
+ * BUNDLE_UNSAFE_LINK), a regular file (BUNDLE_INCLUDE_NOT_A_FILE) of at most
+ * BUNDLE_INCLUDE_MAX_BYTES, and the content guard. Returns [{ path, sha256, keys }] sorted.
+ */
+export function resolveBundleIncludes(root, include = [], { readFile = readFileSync } = {}) {
+  const paths = [...new Set((include ?? []).map(validateBundleIncludePath))].sort();
+  return paths.map((path) => {
+    const abs = join(root, path);
+    try { lstatSync(abs); } catch {
+      throw bundleError("BUNDLE_INCLUDE_MISSING", `refusing --bundle-include ${path}: it does not exist in the materialised stack (${root})`);
+    }
+    let real;
+    try { real = realpathSync(abs); } catch { throw bundleError("BUNDLE_UNSAFE_LINK", `refusing --bundle-include ${path}: it is a dangling symlink`); }
+    const inside = relative(root, real);
+    if (inside === "" || inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside)) {
+      throw bundleError("BUNDLE_UNSAFE_LINK", `refusing --bundle-include ${path}: it resolves outside the stack directory (${real})`);
+    }
+    const info = statSync(real);
+    if (!info.isFile()) throw bundleError("BUNDLE_INCLUDE_NOT_A_FILE", `refusing --bundle-include ${path}: it is not a regular file`);
+    if (info.size > BUNDLE_INCLUDE_MAX_BYTES) {
+      throw bundleError("BUNDLE_INCLUDE_TOO_LARGE", `refusing --bundle-include ${path}: ${info.size} bytes is over the ${BUNDLE_INCLUDE_MAX_BYTES}-byte cap for an opted-in file`);
+    }
+    const body = readFile(abs);
+    const { keys } = scanBundleIncludeEnv(path, body.toString("utf8"));
+    return { path, sha256: createHash("sha256").update(body).digest("hex"), keys };
+  });
+}
+
 // ── ustar writer ─────────────────────────────────────────────────────────────
 
 const BLOCK = 512;
@@ -115,12 +279,14 @@ function toPosix(rel) {
  * host's Docker bind mounts cannot follow a link anyway); one resolving outside
  * it is refused, so a bundle can never carry a file from elsewhere on this machine.
  */
-function collect(root, rootReal, relDir, out, excluded, seenDirs = new Set([rootReal])) {
+function collect(root, rootReal, relDir, out, excluded, seenDirs = new Set([rootReal]), optIn = NO_OPT_IN) {
   const absDir = relDir ? join(root, relDir) : root;
   const names = readdirSync(absDir).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
   for (const name of names) {
     const rel = relDir ? `${relDir}/${name}` : name;
-    if (isExcludedBundlePath(rel)) { excluded.push(rel); continue; }
+    // BOT-2269: an exact --bundle-include path overrides the exclusion for that path only.
+    const optedIn = optIn.has(rel);
+    if (!optedIn && isExcludedBundlePath(rel)) { excluded.push(rel); continue; }
     const abs = join(root, rel);
     let info = lstatSync(abs);
     if (info.isSymbolicLink()) {
@@ -132,7 +298,8 @@ function collect(root, rootReal, relDir, out, excluded, seenDirs = new Set([root
       }
       // Codex #1077 P1: the exclusion rules apply to what a link POINTS AT too, or an
       // innocently named link (config-link -> .env) would ship an excluded secret.
-      if (isExcludedBundlePath(toPosix(inside))) { excluded.push(rel); continue; }
+      // An opted-in path names its own content (the guard scanned it), whatever it points at.
+      if (!optedIn && isExcludedBundlePath(toPosix(inside))) { excluded.push(rel); continue; }
       info = statSync(abs);
     }
     if (info.isDirectory()) {
@@ -141,7 +308,7 @@ function collect(root, rootReal, relDir, out, excluded, seenDirs = new Set([root
       const real = realpathSync(abs);
       if (seenDirs.has(real)) throw bundleError("BUNDLE_UNSAFE_LINK", `refusing to bundle ${rel}: it is a symlink to a directory already in the bundle (a cycle or duplicate)`);
       out.push({ rel: `${rel}/`, type: "dir" });
-      collect(root, rootReal, rel, out, excluded, new Set([...seenDirs, real]));
+      collect(root, rootReal, rel, out, excluded, new Set([...seenDirs, real]), optIn);
     } else if (info.isFile()) {
       out.push({ rel, type: "file", abs, size: info.size, executable: (info.mode & 0o111) !== 0 });
     }
@@ -161,16 +328,32 @@ function collect(root, rootReal, relDir, out, excluded, seenDirs = new Set([root
  * canonical bind-RPC readiness probe as a local one. Each must be a regular file (not a
  * symlink) with a safe relative name; one the stack dir already carries is not duplicated.
  */
-export function buildStackBundle(stackDir, { maxBytes = DEFAULT_BUNDLE_MAX_BYTES, rawLimitBytes = null, readFile = readFileSync, extraFiles = [] } = {}) {
+/**
+ * BOT-2269: `include` ([stack-relative paths], `bb stack run --bundle-include`) ships exactly
+ * those files even when the default rules exclude them (`SECRET_DOTENV`), after
+ * `resolveBundleIncludes` has validated each path and passed its content guard. The result's
+ * `included` lists [{ path, sha256, keys }] (key NAMES only). With no includes the archive is
+ * byte-identical to the pre-BOT-2269 bundle.
+ */
+export function buildStackBundle(stackDir, { maxBytes = DEFAULT_BUNDLE_MAX_BYTES, rawLimitBytes = null, readFile = readFileSync, extraFiles = [], include = [] } = {}) {
   const root = realpathSync(stackDir);
   try {
     if (!statSync(join(root, "supabase", "config.toml")).isFile()) throw new Error("not a file");
   } catch {
     throw bundleError("BUNDLE_NOT_A_STACK", `refusing to bundle ${root}: it has no supabase/config.toml, so it is not a materialised stack directory`);
   }
+  const included = resolveBundleIncludes(root, include, { readFile });
+  const optIn = included.length ? new Set(included.map((e) => e.path)) : NO_OPT_IN;
   const entries = [];
   const excluded = [];
-  collect(root, root, "", entries, excluded);
+  collect(root, root, "", entries, excluded, new Set([root]), optIn);
+  for (const { path } of included) {
+    // Reachable only through a path the walk does not enter (e.g. a directory link whose
+    // target is excluded): refuse rather than report a file that did not ship.
+    if (!entries.some((e) => e.rel === path)) {
+      throw bundleError("BUNDLE_INCLUDE_EXCLUDED", `refusing --bundle-include ${path}: the bundle walk never reaches it (it sits behind an excluded directory or link)`);
+    }
+  }
   const present = new Set(entries.map((e) => e.rel));
   const extras = [];
   for (const { rel, abs } of extraFiles) {
@@ -207,6 +390,13 @@ export function buildStackBundle(stackDir, { maxBytes = DEFAULT_BUNDLE_MAX_BYTES
         // huge file is a BUNDLE_TOO_LARGE error, never an out-of-memory kill.
         if (raw + entry.size > rawLimit) throw tooLarge(`more than ${rawLimit} bytes before compression (at ${entry.rel}, ${entry.size} bytes)`);
         const body = readFile(entry.abs);
+        if (optIn.has(entry.rel)) {
+          // The bytes that ship must be the bytes the guard scanned.
+          const scanned = included.find((e) => e.path === entry.rel);
+          if (createHash("sha256").update(body).digest("hex") !== scanned.sha256) {
+            throw bundleError("BUNDLE_INCLUDE_CHANGED", `refusing --bundle-include ${entry.rel}: it changed while the bundle was being built; re-run`);
+          }
+        }
         files += 1;
         return entryBlocks(toPosix(entry.rel), { size: body.length, mode: entry.executable ? 0o755 : 0o644, type: "0" }, body);
       })();
@@ -217,7 +407,7 @@ export function buildStackBundle(stackDir, { maxBytes = DEFAULT_BUNDLE_MAX_BYTES
   const bytes = gzipSync(Buffer.concat(chunks), { level: 9 });
   bytes[9] = 3; // gzip OS byte: "Unix" on every platform, so the digest is portable
   if (bytes.length > maxBytes) throw tooLarge(`${bytes.length} bytes compressed`);
-  return { bytes, sha256: createHash("sha256").update(bytes).digest("hex"), size: bytes.length, files, excluded };
+  return { bytes, sha256: createHash("sha256").update(bytes).digest("hex"), size: bytes.length, files, excluded, included };
 }
 
 /** Entry names in archive order (PAX long names resolved). For tests and diagnostics. */

package/src/stack.mjs

@@ -39,7 +39,7 @@ import { runDockerCommand, runDockerWorkflow, ADMITTED_DOCKER_VALIDATIONS } from
 import { acquireStackLock, lockPathForProject, projectIdFromConfig } from "./stack-file-lock.mjs";
 import { assertLeasedStackIsolated, leasedStackIdentity, materializeRunStackDir, portMapInConfig, refreshLeasedStackRetention, releaseLeasedStackClaim, reservePortBlocks } from "./stack-isolation.mjs";
 import { machineUuid } from "./machine-id.mjs";
-import { DEFAULT_BUNDLE_MAX_BYTES, buildStackBundle, uploadStackBundle } from "./stack-bundle.mjs";
+import { DEFAULT_BUNDLE_MAX_BYTES, buildStackBundle, uploadStackBundle, validateBundleIncludePath } from "./stack-bundle.mjs";
 import { assertSshTarget, establishSshTunnel } from "./stack-tunnel.mjs";
 import { ENGINE_PUBLISHES_BEYOND_LOOPBACK, engineSocketIsLocal, formatPublishIp, isLoopbackIp, publishIpFix, resolvePublishIp } from "./docker-publish-ip.mjs";
 import { bold, dim, yellow } from "./utils.mjs";
@@ -60,6 +60,13 @@ const CALLBACK_PORT_REMOTE_REFUSAL =
   "(pre-forward GatewayPorts probe). Use --local-only for a run that needs a callback port.";
 export const DEFAULT_RECEIPT_MAX_BYTES = 10240;
 export const DEFAULT_TIMEOUT_SEC = 3600;
+/**
+ * BOT-2154: how long `stack up --local-exec` lets `supabase start` run before it gives up and
+ * releases the lease itself (`--provision-timeout` overrides). Deliberately below the server's
+ * 1200 s `local_exec_provision_ttl_secs` backstop, so the CLI's own clean `stack done` wins the
+ * race against the reaper.
+ */
+export const LOCAL_EXEC_PROVISION_TIMEOUT_SEC = 900;
 /** BOT-2230: the bounds the control plane enforces on an owner place hold (hold_stack_lease_place). */
 export const HOLD_ON_TIMEOUT_MIN_SEC = 60;
 export const HOLD_ON_TIMEOUT_MAX_SEC = 14400;
@@ -122,6 +129,10 @@ ${bold("up OPTIONS")}
                          deadline (exit 2) and a failed wait (its own exit code) never retry.
   --local-exec           FALLBACK (no Helper): run 'supabase start' in an ISOLATED --stack-path
                          stack and self-activate. Refused at the worktree root (shared stack).
+  --provision-timeout N  LOCAL-EXEC: seconds 'supabase start' may run (default ${LOCAL_EXEC_PROVISION_TIMEOUT_SEC}). On
+                         timeout up runs 'stack done --local-exec' itself and exits 6 with
+                         park_reason provision_timeout (BOT-2154). The server also fails a local-exec
+                         lease still provisioning after local_exec_provision_ttl_secs (default 1200).
                          Refused (exit 4, ENGINE_PUBLISHES_BEYOND_LOOPBACK) when the Docker
                          engine would publish the stack's ports beyond loopback (BOT-2146).
   --docker-context <name> Explicit Docker context for the mandatory local preflight
@@ -170,6 +181,15 @@ ${bold("run OPTIONS")}
   --bundle-max-mb N      Remote-lease bundle size cap in MB (default 50, compressed). The bundle
                          excludes .bb-stack.json, node_modules, supabase/.temp|.branches and
                          untracked-secret dotenv files (.env, .env.local, .env.*.local).
+  --bundle-include <path> Ship this EXACT stack-relative file in the bundle even though the
+                         defaults exclude it (repeatable), e.g. supabase/functions/.env so a remote
+                         stack starts with the same functions env as a local one. No globs, no '..';
+                         the file must exist in the materialised stack and pass the content guard:
+                         a value shaped like a live credential (sk_live_/rk_live_, Resend re_, whsec_,
+                         ghp_/github_pat_, AKIA/ASIA, a PEM private key, sb_secret_, a JWT with a
+                         hosted project ref, a non-demo service-role JWT) refuses the run before any
+                         lease exists (exit 4 BUNDLE_SECRET_ENV, naming the KEY, never the value).
+                         The receipt and the lease carry bundle_included [{path, sha256, keys}].
 
 ${bold("GLOBAL")}
   --json                 Pretty-print the receipt (default is one compact JSON line).
@@ -201,6 +221,9 @@ ${bold("REMOTE LEASES")} (BOT-2142, stack run)
   5 CALLBACK_NOT_LOOPBACK (reserved for BOT-2184) the host's -R listener is not loopback-only
                           (sshd GatewayPorts yes) or could not be checked with lsof
   4 BUNDLE_TOO_LARGE      --remote and the bundle is over --bundle-max-mb
+  4 BUNDLE_SECRET_ENV     a --bundle-include file holds a live-credential-shaped value (names the key)
+  4 BUNDLE_INCLUDE_*      a --bundle-include path is missing, not a file, too large, or excluded
+                          (BUNDLE_UNSAFE_LINK: it resolves outside the stack); no lease is created
   4 CALLBACK_PORT_UNSUPPORTED_REMOTE  --callback-port on a remote lease (refused until BOT-2184;
                           under auto the remote lease is released first)
   6 TUNNEL_LOST           the forward exited mid-child: the child is stopped, the lease released,
@@ -269,6 +292,9 @@ export function parseStackArgs(argv) {
     dockerContext: null, dockerEndpoint: null,
     // BOT-2142: execution placement (null = command default), remote-lease callback + bundle cap.
     execution: null, remote: false, localOnly: false, callbackPort: null, bundleMaxBytes: null,
+    // BOT-2269: exact stack-relative files shipped in the remote-lease bundle despite the
+    // default exclusions (`--bundle-include`, repeatable).
+    bundleInclude: [],
     disposition: "destroy", json: false, receiptMaxBytes: DEFAULT_RECEIPT_MAX_BYTES,
   };
   const positionals = [];
@@ -358,6 +384,13 @@ export function parseStackArgs(argv) {
         }
         break;
       }
+      case "--bundle-include": {
+        if (need(a, rest[i + 1])) {
+          const path = rest[++i];
+          try { opts.bundleInclude.push(validateBundleIncludePath(path)); } catch (error) { errors.push(error.message); }
+        }
+        break;
+      }
       case "--bundle-max-mb": {
         if (need(a, rest[i + 1])) {
           const n = Number(rest[++i]);
@@ -405,6 +438,12 @@ export function parseStackArgs(argv) {
   } else if (opts.remote && opts.callbackPort != null) {
     errors.push(CALLBACK_PORT_REMOTE_REFUSAL);
   }
+  if (opts.bundleInclude.length && command !== "run") {
+    errors.push("--bundle-include is valid only with `stack run` (only run builds a remote-lease bundle)");
+  } else if (opts.bundleInclude.length && opts.localOnly) {
+    errors.push("--bundle-include ships files in the remote-lease bundle, and --local-only builds no bundle; drop one of them");
+  }
+  opts.bundleInclude = [...new Set(opts.bundleInclude)];
   opts.execution = opts.remote ? "remote" : opts.localOnly ? "local" : null;
   if (typeof opts.stackPath !== "string" || !opts.stackPath.trim() || opts.stackPath.startsWith("/") ||
       opts.stackPath.split("/").some((part) => part === "..")) {
@@ -1851,7 +1890,16 @@ export function localProvision(opts, dockerTarget, execution, spawn = spawnSync,
   const url = resolveIsolatedStackApiUrl(stackDir, env);
   const spawnEnv = { ...dockerEnvForTarget(dockerTarget, env), VITE_SUPABASE_URL: url };
   process.stderr.write(`${yellow("⚠ LOCAL-EXEC FALLBACK")} — no BotBuddy Helper; running ${bold("supabase start")} in ${stackDir} (VITE_SUPABASE_URL=${url}).\n`);
-  const start = spawn("supabase", ["start", "--workdir", stackDir], { encoding: "utf8", env: spawnEnv });
+  // BOT-2154: never an unbounded start — a hung `supabase start` held the host slot for hours.
+  const timeoutSec = opts?.provisionTimeout ?? LOCAL_EXEC_PROVISION_TIMEOUT_SEC;
+  const start = spawn("supabase", ["start", "--workdir", stackDir], {
+    encoding: "utf8", env: spawnEnv, timeout: timeoutSec * 1000, killSignal: "SIGTERM",
+  });
+  if (start.error?.code === "ETIMEDOUT") {
+    const timedOut = new Error(`supabase start did not finish within ${timeoutSec}s (--provision-timeout); stopping it and releasing the lease`);
+    timedOut.code = "PROVISION_TIMEOUT";
+    throw timedOut;
+  }
   if (start.status !== 0) {
     throw new Error(`supabase start failed (${start.status}): ${(start.stderr || start.stdout || "").slice(0, 400)}`);
   }
@@ -1942,11 +1990,21 @@ function emit(receipt, opts, code) {
 
 // ── command orchestration ────────────────────────────────────────────────────
 
+/** BOT-2154: run `stack done` in-process and capture its receipt instead of printing it, so
+ * `stack up` still emits exactly one receipt. */
+async function runLocalDone(leaseId, opts, deps = {}) {
+  let receipt = null;
+  const exitCode = await cmdDone(leaseId, opts, { ...deps, emitResult: (r, _o, code) => { receipt = r; return code; } });
+  return { exitCode, receipt };
+}
+
 export async function cmdUp(opts, {
   runPreflight = runLocalExecPreflight,
   callTool = callToolJson,
   authProvider = stackAuthHeader,
   localProvisionFn = localProvision,
+  // BOT-2154: the self-release after a timed-out local start (`stack done --local-exec`).
+  localDoneFn = null,
   waitFn = waitForLease,
   emitResult = emit,
   machineUuidFn = machineUuid,
@@ -2278,6 +2336,21 @@ export async function cmdUp(opts, {
         try {
           conn = connectionWithDockerTarget(localProvisionFn(opts, localDockerTarget, execution), localDockerTarget);
         } catch (e) {
+          if (e?.code === "PROVISION_TIMEOUT") {
+            // BOT-2154: a bounded start that ran out of time. Release the lease ourselves —
+            // `stack done --local-exec` stops whatever the start left behind and reaps the lease
+            // — instead of leaving it provisioning for the server's backstop to find.
+            const done = await (localDoneFn ?? ((id, doneOpts) => runLocalDone(id, doneOpts, { callTool, authProvider })))(
+              leaseId, { ...opts, localExec: true, disposition: "destroy", json: false });
+            const doneReceipt = done?.receipt ?? {};
+            const cleaned = done?.exitCode === 0;
+            return emitResult(buildReceipt({
+              command: "up", outcome: "timeout", code: "PROVISION_TIMEOUT", park_reason: "provision_timeout",
+              lease_id: leaseId, slot, error: e.message, cleanup: cleaned,
+              done: { outcome: doneReceipt.outcome ?? null, state: doneReceipt.state ?? null, exit_code: done?.exitCode ?? null },
+              ...(cleaned ? {} : { cleanup_error: doneReceipt.error ?? `stack done --local-exec exited ${done?.exitCode}` }),
+            }), opts, EXIT.LEASE_FAILED);
+          }
           // Once the local provisioner has run, `supabase start` may have created
           // (or fully started) containers even on a nonzero exit or a status-parse
           // failure. Cancelling here would reap the lease and free the slot while
@@ -2978,6 +3051,7 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     // `--local-only` never ships anything.
     let executionRequest = opts.execution ?? "auto";
     let bundle = null;
+    const bundleInclude = opts.bundleInclude ?? [];
     if (executionRequest !== "local") {
       try {
         // BOT-2162: ship the worktree's BOT-2107 readiness declaration with the stack, so the
@@ -2988,10 +3062,17 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         bundle = buildBundle(stackDirFor(execution), {
           maxBytes: opts.bundleMaxBytes ?? DEFAULT_BUNDLE_MAX_BYTES,
           ...(hasDeclaration ? { extraFiles: [{ rel: ".botbuddy/config.json", abs: declaration }] } : {}),
+          ...(bundleInclude.length ? { include: bundleInclude } : {}),
         });
+        for (const entry of bundle.included ?? []) {
+          stderrLine(`stack: the bundle includes ${entry.path} (sha256 ${entry.sha256.slice(0, 12)}…; keys: ${entry.keys.join(", ") || "none"})`);
+        }
       } catch (error) {
         const message = String(error?.message ?? error);
-        if (executionRequest === "remote") {
+        // BOT-2269: the caller asked for these files to ship. A refused path or a live key is
+        // a hard refusal in every mode — quietly falling back to a co-located lease would
+        // hide it — and it happens before any lease exists.
+        if (executionRequest === "remote" || bundleInclude.length) {
           const fixable = typeof error?.code === "string" && error.code.startsWith("BUNDLE_");
           return { exitCode: fixable ? EXIT.INVALID : EXIT.INTERNAL, outcome: "error", code: error?.code ?? "BUNDLE_FAILED", error: message };
         }
@@ -3009,6 +3090,8 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       machine_uuid: hardwareUuid,
       execution: executionRequest,
       ...(bundle ? { bundle_sha256: bundle.sha256 } : {}),
+      // 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 } : {}),
     };
     // The retrying caller (api → rpc.call) transparently clears+self-heals+retries the
@@ -3128,6 +3211,7 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
         return { exitCode: EXIT.BACKEND, outcome: "error", code: "BUNDLE_UPLOAD_FAILED", leaseId, cleanup, error: uploaded?.error || "bundle upload failed" };
       }
       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
@@ -3142,6 +3226,7 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       }
       if (uploaded?.ok) {
         placement.bundle = { sha256: bundle.sha256, bytes: bundle.size };
+        if (bundle.included?.length) placement.bundleIncluded = bundle.included;
         stderrLine(`stack: lease ${leaseId} queued on ${placement.hostKey ?? "?"} — uploaded the ${bundle.size}-byte stack bundle so it can move to another owned host that admits first`);
       } else {
         stderrLine(`${yellow("⚠")} stack: could not upload the stack bundle (${uploaded?.error || "upload failed"}); lease ${leaseId} stays queued on ${placement.hostKey ?? "this host"} and cannot move to another host.`);
@@ -3358,9 +3443,9 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   }
 }
 
-async function cmdRun(opts, childArgv) {
-  const result = await runStackLifecycle(opts, childArgv);
-  return emit(buildReceipt({
+/** The `stack run` receipt fields for a lifecycle result (exported for the receipt tests). */
+export function runReceiptFields(result) {
+  return {
     // BOT-1797: carry the server's typed refusal code (e.g. stack_path_root_refused)
     // so automation can branch on it instead of matching the message text.
     command: "run", outcome: result.outcome, code: result.code ?? null, lease_id: result.leaseId ?? null,
@@ -3376,6 +3461,8 @@ async function cmdRun(opts, childArgv) {
     transport: result.execution?.transport ?? "none",
     ...(result.execution?.forwards ? { forwards: result.execution.forwards } : {}),
     ...(result.execution?.bundle ? { bundle: result.execution.bundle } : {}),
+    // BOT-2269: the opted-in files that shipped in that bundle — paths, sha256, key names.
+    ...(result.execution?.bundle && result.execution?.bundleIncluded ? { bundle_included: result.execution.bundleIncluded } : {}),
     // BOT-2207: why it ran where it did (e.g. moved_remote_on_requeue) and every host weighed.
     ...(result.execution?.placementReason ? { placement_reason: result.execution.placementReason } : {}),
     ...(result.execution?.considered ? { considered: result.execution.considered } : {}),
@@ -3384,7 +3471,12 @@ async function cmdRun(opts, childArgv) {
     // incident (reason, window, attempts, recovered) — never as the lease's outcome.
     ...(result.incident ? { platform_incident: result.incident } : {}),
     ...(result.ledger ? { unit_ledger: result.ledger } : {}),
-  }), opts, result.exitCode);
+  };
+}
+
+async function cmdRun(opts, childArgv) {
+  const result = await runStackLifecycle(opts, childArgv);
+  return emit(buildReceipt(runReceiptFields(result)), opts, result.exitCode);
 }
 
 /** Entry point wired from commands.mjs (`botbuddy stack ...`). Returns/sets the exit code. */