@botbuddy/cli 1.40.13 → 1.41.0

package/package.json

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

package/src/stack-bundle.mjs

@@ -0,0 +1,296 @@
+// BOT-2142 — the remote-lease stack bundle.
+//
+// A remote lease (BOT-2145 `execution: "remote"|"auto"`) is provisioned on a host
+// that does not have this worktree, so `bb stack run` ships the materialised
+// isolated stack directory (`.botbuddy/stacks/<project_id>/`, BOT-1798) as one
+// gzip'd tar. The control plane pins it by digest (`bundle_sha256`, sent with the
+// lease request) and hands back a signed upload URL (`bundle_upload_url`); the
+// serving Helper downloads it and verifies the digest before provisioning
+// (BOT-2143).
+//
+// Determinism is the contract: the digest must be a pure function of the tree's
+// relative paths, contents and executable bits, so a retried request for the same
+// tree re-sends the same `bundle_sha256`. The archive is therefore written here
+// (ustar + PAX long names, sorted entries, mtime/uid/gid 0, modes normalised to
+// 0644/0755, gzip header OS byte fixed) rather than by the platform `tar`, whose
+// output differs between bsdtar and GNU tar and embeds mtimes and owners.
+//
+// Dependency-free (Node stdlib only), like the rest of `bb stack`.
+
+import { createHash } from "node:crypto";
+import { lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { gunzipSync, gzipSync } from "node:zlib";
+
+/** Default compressed-size cap (BOT-2142 §2): a real stack is a few MB. */
+export const DEFAULT_BUNDLE_MAX_BYTES = 50 * 1024 * 1024;
+
+/** Directory/file names never shipped, at any depth: dependency trees and the
+ * Supabase CLI's own scratch state (the serving host rebuilds both). */
+const EXCLUDED_NAMES = new Set(["node_modules", ".temp", ".branches"]);
+/** Root-only: the retention marker records local pids, hosts and paths (BOT-1798). */
+const EXCLUDED_ROOT_FILES = new Set([".bb-stack.json"]);
+/** Conventionally UNTRACKED dotenv files hold real provider secrets; committed
+ * ones (`.env.example`, `.env.test`, `.env.integration`, …) are test config and ship. */
+const SECRET_DOTENV = /^\.env(?:\.local|\..+\.local)?$/;
+
+function bundleError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/** True when a stack-relative POSIX path (file or directory) is never bundled. */
+export function isExcludedBundlePath(relPath) {
+  const parts = String(relPath).split("/").filter(Boolean);
+  if (parts.length === 0) return false;
+  const name = parts[parts.length - 1];
+  if (parts.length === 1 && EXCLUDED_ROOT_FILES.has(name)) return true;
+  if (parts.some((part) => EXCLUDED_NAMES.has(part))) return true;
+  return SECRET_DOTENV.test(name);
+}
+
+// ── ustar writer ─────────────────────────────────────────────────────────────
+
+const BLOCK = 512;
+
+function octal(value, width) {
+  // width includes the trailing NUL
+  return value.toString(8).padStart(width - 1, "0") + "\0";
+}
+
+function header(name, { size = 0, mode = 0o644, type = "0" } = {}) {
+  const block = Buffer.alloc(BLOCK, 0);
+  block.write(name, 0, 100, "utf8");
+  block.write(octal(mode, 8), 100, "ascii");
+  block.write(octal(0, 8), 108, "ascii"); // uid
+  block.write(octal(0, 8), 116, "ascii"); // gid
+  block.write(octal(size, 12), 124, "ascii");
+  block.write(octal(0, 12), 136, "ascii"); // mtime
+  block.write("        ", 148, "ascii"); // checksum placeholder
+  block.write(type, 156, "ascii");
+  block.write("ustar\0", 257, "ascii");
+  block.write("00", 263, "ascii");
+  let sum = 0;
+  for (const byte of block) sum += byte;
+  block.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148, "ascii");
+  return block;
+}
+
+function padding(size) {
+  const rest = size % BLOCK;
+  return rest === 0 ? Buffer.alloc(0) : Buffer.alloc(BLOCK - rest, 0);
+}
+
+/** One PAX `path=` record; its decimal length prefix counts itself. */
+function paxPathRecord(path) {
+  const body = ` path=${path}\n`;
+  let length = Buffer.byteLength(body) + 1;
+  while (String(length).length + Buffer.byteLength(body) !== length) length = String(length).length + Buffer.byteLength(body);
+  return Buffer.from(`${length}${body}`, "utf8");
+}
+
+function entryBlocks(name, opts, body = null) {
+  const blocks = [];
+  if (Buffer.byteLength(name) > 100) {
+    const pax = paxPathRecord(name);
+    blocks.push(header("PaxHeader/entry", { size: pax.length, type: "x" }), pax, padding(pax.length));
+  }
+  // An over-long name is carried by the PAX record; the ustar field keeps a
+  // deterministic truncated stand-in.
+  blocks.push(header(Buffer.from(name).subarray(0, 100).toString("utf8"), opts));
+  if (body) blocks.push(body, padding(body.length));
+  return blocks;
+}
+
+// ── tree walk ────────────────────────────────────────────────────────────────
+
+function toPosix(rel) {
+  return sep === "/" ? rel : rel.split(sep).join("/");
+}
+
+/**
+ * Collect the bundle's entries in byte-wise sorted order. A symlink that resolves
+ * INSIDE the stack directory is stored as the file/dir it points at (the serving
+ * 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])) {
+  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; }
+    const abs = join(root, rel);
+    let info = lstatSync(abs);
+    if (info.isSymbolicLink()) {
+      let target;
+      try { target = realpathSync(abs); } catch { throw bundleError("BUNDLE_UNSAFE_LINK", `refusing to bundle ${rel}: it is a dangling symlink`); }
+      const inside = relative(rootReal, target);
+      if (inside === "" || inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside)) {
+        throw bundleError("BUNDLE_UNSAFE_LINK", `refusing to bundle ${rel}: the symlink resolves outside the stack directory (${target})`);
+      }
+      // 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; }
+      info = statSync(abs);
+    }
+    if (info.isDirectory()) {
+      // A directory reached twice (a symlink to an ancestor or a sibling) would loop
+      // or duplicate the tree; refuse it rather than guess which copy is meant.
+      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]));
+    } else if (info.isFile()) {
+      out.push({ rel, type: "file", abs, size: info.size, executable: (info.mode & 0o111) !== 0 });
+    }
+    // sockets, fifos and devices are not stack inputs; skip them silently
+  }
+}
+
+/**
+ * Build the deterministic bundle of a materialised stack directory.
+ * @returns {{ bytes: Buffer, sha256: string, size: number, files: number, excluded: string[] }}
+ */
+/**
+ * `extraFiles` ([{ rel, abs }]) adds files from OUTSIDE the stack dir at a fixed relative
+ * path, ahead of the tree (deterministic). BOT-2162: the worktree's `.botbuddy/config.json`
+ * — the BOT-2107 readiness declaration the serving Helper reads at
+ * `<bundle root>/.botbuddy/config.json` — so a remote BotBuddy lease runs the same
+ * 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 = [] } = {}) {
+  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 entries = [];
+  const excluded = [];
+  collect(root, root, "", entries, excluded);
+  const present = new Set(entries.map((e) => e.rel));
+  const extras = [];
+  for (const { rel, abs } of extraFiles) {
+    const parts = String(rel).split("/");
+    if (!rel || rel.startsWith("/") || parts.some((p) => p === "" || p === "." || p === "..") || isExcludedBundlePath(rel)) {
+      throw bundleError("BUNDLE_UNSAFE_LINK", `refusing to add ${rel} to the bundle: it is not a safe relative path`);
+    }
+    if (present.has(rel)) continue;
+    const info = lstatSync(abs);
+    if (!info.isFile()) throw bundleError("BUNDLE_UNSAFE_LINK", `refusing to add ${rel} to the bundle: ${abs} is not a regular file`);
+    for (let i = 1; i < parts.length; i++) {
+      const dir = `${parts.slice(0, i).join("/")}/`;
+      if (!present.has(dir)) { present.add(dir); extras.push({ rel: dir, type: "dir" }); }
+    }
+    present.add(rel);
+    extras.push({ rel, type: "file", abs, size: info.size, executable: false });
+  }
+  entries.unshift(...extras);
+  // Raw bytes are bounded too, so a pathological tree fails fast instead of
+  // exhausting memory before the compressed cap can be checked.
+  const rawLimit = rawLimitBytes ?? Math.max(maxBytes * 16, 64 * 1024 * 1024);
+  const chunks = [];
+  let raw = 0;
+  let files = 0;
+  const tooLarge = (what) => bundleError("BUNDLE_TOO_LARGE",
+    `the stack bundle for ${root} is ${what}, over the ${maxBytes} byte cap. A materialised stack is normally a few MB: ` +
+      "look for a large file copied into supabase/ (dumps, fixtures, a stray node_modules is already excluded), " +
+      "or raise the cap with --bundle-max-mb <n>.");
+  for (const entry of entries) {
+    const blocks = entry.type === "dir"
+      ? entryBlocks(toPosix(entry.rel), { mode: 0o755, type: "5" })
+      : (() => {
+        // Codex #1077 P2: refuse from the stat size BEFORE allocating the file, so one
+        // 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);
+        files += 1;
+        return entryBlocks(toPosix(entry.rel), { size: body.length, mode: entry.executable ? 0o755 : 0o644, type: "0" }, body);
+      })();
+    for (const block of blocks) { raw += block.length; chunks.push(block); }
+    if (raw > rawLimit) throw tooLarge(`more than ${rawLimit} bytes before compression`);
+  }
+  chunks.push(Buffer.alloc(BLOCK * 2, 0)); // end-of-archive marker
+  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 };
+}
+
+/** Entry names in archive order (PAX long names resolved). For tests and diagnostics. */
+export function bundleEntryNames(tgz) {
+  const tar = gunzipSync(tgz);
+  const names = [];
+  let pending = null;
+  for (let offset = 0; offset + BLOCK <= tar.length;) {
+    const block = tar.subarray(offset, offset + BLOCK);
+    if (block.every((byte) => byte === 0)) break;
+    const size = parseInt(block.subarray(124, 135).toString("ascii"), 8) || 0;
+    const type = String.fromCharCode(block[156]);
+    const body = tar.subarray(offset + BLOCK, offset + BLOCK + size);
+    if (type === "x") {
+      const match = /\d+ path=([^\n]*)\n/.exec(body.toString("utf8"));
+      pending = match ? match[1] : null;
+    } else {
+      names.push(pending ?? block.subarray(0, 100).toString("utf8").replace(/\0.*$/s, ""));
+      pending = null;
+    }
+    offset += BLOCK + Math.ceil(size / BLOCK) * BLOCK;
+  }
+  return names;
+}
+
+// ── upload ───────────────────────────────────────────────────────────────────
+
+/** The signed upload URL must be https, or plain http only on loopback (a local
+ * control plane). Anything else is refused before a byte leaves this machine. */
+export function assertBundleUploadUrl(url) {
+  let parsed;
+  try { parsed = new URL(String(url ?? "")); } catch { parsed = null; }
+  const loopback = parsed && ["127.0.0.1", "localhost", "[::1]"].includes(parsed.hostname);
+  if (!parsed || !(parsed.protocol === "https:" || (parsed.protocol === "http:" && loopback))) {
+    throw bundleError("BUNDLE_UPLOAD_URL_INVALID", "the control plane returned an unusable bundle_upload_url (it must be https, or http on loopback)");
+  }
+  return parsed;
+}
+
+/** Redact a URL's query (the signed token) from any text we might print. */
+function redact(text, url) {
+  let out = String(text ?? "");
+  try {
+    const parsed = new URL(url);
+    if (parsed.search) out = out.split(parsed.search).join("?<redacted>");
+    for (const value of parsed.searchParams.values()) if (value) out = out.split(value).join("<redacted>");
+  } catch { /* nothing to redact */ }
+  return out;
+}
+
+/**
+ * PUT the bundle to the signed Storage upload URL (`stack-bundles/<tenant>/<lease>.tgz`).
+ * Never throws: returns { ok, status, error? }. The signed token never appears in the error.
+ */
+export async function uploadStackBundle(url, bundle, { fetchImpl = fetch, signal = undefined } = {}) {
+  try {
+    assertBundleUploadUrl(url);
+  } catch (error) {
+    return { ok: false, status: null, error: error.message };
+  }
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: "PUT",
+      headers: { "content-type": "application/gzip", "x-upsert": "false" },
+      body: bundle.bytes,
+      ...(signal ? { signal } : {}),
+    });
+  } catch (error) {
+    return { ok: false, status: null, error: `bundle upload failed: ${redact(error?.message ?? error, url)}` };
+  }
+  if (response?.ok) return { ok: true, status: response.status };
+  let detail = "";
+  try { detail = (await response.text()).slice(0, 200); } catch { /* no body */ }
+  return { ok: false, status: response?.status ?? null, error: `bundle upload was refused (HTTP ${response?.status ?? "?"})${detail ? `: ${redact(detail, url)}` : ""}` };
+}

package/src/stack-isolation.mjs

@@ -1408,6 +1408,10 @@ export function materializeRunStackDir(cwd, { slot, ticket, nonce, idleTtlSecs }
     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);

package/src/stack-tunnel.mjs

@@ -0,0 +1,322 @@
+// BOT-2142 — SSH port forwards for a remote stack lease.
+//
+// A remote lease (BOT-2145) is served by another host the caller's owner owns. Its
+// stack publishes on that host, and the control plane advertises ONLY loopback
+// ports plus the host's operator-set `ssh_target` (BOT-2146: a LAN address is
+// never returned). The caller reaches it the way the BOT-2021 spine proved: one
+// `ssh -N` carrying a `-L` per stack port (+29 ms per new connection), and — when
+// the caller runs a callback listener the stack's edge functions call through
+// `host.docker.internal` (Supply Guard's TLS probe / PDF worker on 4600) — a
+// reverse `-R <port>:127.0.0.1:<port>`.
+//
+// Contract:
+//   * every forward binds 127.0.0.1 on BOTH ends; nothing leaves loopback;
+//   * a free local port keeps the remote number, a busy one gets an ephemeral
+//     port (the remap table is returned and lands on the receipt);
+//   * `ExitOnForwardFailure=yes` makes a lost bind race a clean exit, retried on
+//     remapped ports; `BatchMode=yes` means ssh never prompts (no agent hang);
+//   * `ServerAlive*` turns a dead link (caller asleep, BOT-1980) into an exit the
+//     CLI sees as `tunnel_lost`, instead of a hang the child reads as product
+//     failures (BB hop 12 of the spine).
+//
+// Dependency-free (Node stdlib only).
+
+import { spawn, spawnSync } from "node:child_process";
+import { connect, createServer } from "node:net";
+
+export const SSH_FORWARD_OPTIONS = Object.freeze([
+  "-N", "-T",
+  "-o", "BatchMode=yes",
+  "-o", "ExitOnForwardFailure=yes",
+  "-o", "ServerAliveInterval=15",
+  "-o", "ServerAliveCountMax=3",
+  // A user's ControlMaster config would multiplex the forwards through a master
+  // this process does not own, so its exit could no longer mean "tunnel lost".
+  "-o", "ControlMaster=no",
+  "-o", "ControlPath=none",
+]);
+
+export const DEFAULT_TUNNEL_READY_MS = 20_000;
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
+
+function tunnelError(code, message, extra = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, extra);
+  return error;
+}
+
+/** An ssh destination we are willing to put on argv: an alias or [user@]host, or
+ * ssh://[user@]host[:port] — never something ssh could read as an option or a shell could
+ * split. A port is accepted ONLY in the ssh:// form: OpenSSH reads `mini:2222` as a host
+ * literally named "mini:2222" on port 22 (Codex #1077 P2). */
+const SSH_USER = "[A-Za-z0-9_][A-Za-z0-9._%+-]*";
+const SSH_HOST = "(?:[A-Za-z0-9_][A-Za-z0-9._%-]*|\\[[0-9A-Fa-f:.%a-z]+\\])";
+const SSH_TARGET_RE = new RegExp(`^(?:(?:${SSH_USER}@)?${SSH_HOST}|ssh://(?:${SSH_USER}@)?${SSH_HOST}(?::\\d{1,5})?)$`);
+
+/**
+ * The serving host's SSH destination, validated. Missing → REMOTE_UNREACHABLE with
+ * the operator instruction (the CLI cannot invent one; BOT-2142 edge case).
+ */
+export function assertSshTarget(target, hostKey = null) {
+  const host = hostKey ? `serving host ${hostKey}` : "the serving host";
+  if (target == null || target === "") {
+    throw tunnelError("REMOTE_UNREACHABLE",
+      `${host} has no ssh_target, so this machine cannot reach its stack. An operator must set the host's SSH destination ` +
+        "(container_hosts.ssh_target, e.g. the `ssh mini` alias this machine already trusts; BOT-2174) — or re-run with --local-only.");
+  }
+  if (typeof target !== "string" || !SSH_TARGET_RE.test(target)) {
+    throw tunnelError("REMOTE_UNREACHABLE", `${host} advertises an ssh_target that is not a plain ssh destination ([user@]host, or ` +
+      "ssh://[user@]host:port when it needs a port); refusing to pass it to ssh");
+  }
+  return target;
+}
+
+function validPort(value) {
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0 && n <= 65535 ? n : null;
+}
+
+function urlPort(url) {
+  if (typeof url !== "string") return null;
+  const match = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]*@)?(?:\[[^\]]+\]|[^:/?#]+):(\d+)/i.exec(url.trim());
+  return match ? validPort(match[1]) : null;
+}
+
+/** Every stack port the child may touch: api + db always, then `connection.ports[]`. */
+export function remotePortsFromConnection(connection) {
+  const ports = [];
+  const add = (name, raw) => {
+    const port = validPort(raw);
+    if (port == null) throw tunnelError("REMOTE_CONNECTION_INVALID", `the remote lease connection has an invalid port for ${name}: ${raw}`);
+    if (!ports.some((p) => p.port === port)) ports.push({ name, port });
+  };
+  const api = urlPort(connection?.api_url);
+  if (api == null) throw tunnelError("REMOTE_CONNECTION_INVALID", "the remote lease connection has no api_url with an explicit port");
+  add("api", api);
+  const db = validPort(connection?.db_port) ?? urlPort(connection?.db_url);
+  if (db != null) add("db", db);
+  for (const entry of Array.isArray(connection?.ports) ? connection.ports : []) {
+    add(String(entry?.name ?? "port"), entry?.port);
+  }
+  return ports;
+}
+
+/** True when 127.0.0.1:<port> can be bound right now. */
+export function isLocalPortFree(port) {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.once("error", () => resolve(false));
+    server.listen({ host: "127.0.0.1", port, exclusive: true }, () => server.close(() => resolve(true)));
+  });
+}
+
+/** An ephemeral port the kernel considers free on 127.0.0.1. */
+export function pickFreeLocalPort() {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen({ host: "127.0.0.1", port: 0, exclusive: true }, () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+/**
+ * Decide each forward's local port: the remote number when it is free (and not in
+ * `avoid`), otherwise a fresh ephemeral port. Returns the remap table.
+ */
+export async function planForwards(remotePorts, { isFree = isLocalPortFree, pickFree = pickFreeLocalPort, avoid = new Set() } = {}) {
+  const used = new Set();
+  const plan = [];
+  for (const { name, port } of remotePorts) {
+    let local = null;
+    if (!avoid.has(port) && !used.has(port) && await isFree(port)) local = port;
+    for (let tries = 0; local == null && tries < 20; tries++) {
+      const candidate = await pickFree();
+      if (!used.has(candidate) && !avoid.has(candidate)) local = candidate;
+    }
+    if (local == null) throw tunnelError("REMOTE_UNREACHABLE", `could not find a free local port to forward ${name} (${port})`);
+    used.add(local);
+    plan.push({ name, remote: port, local, remapped: local !== port });
+  }
+  return plan;
+}
+
+/** `ssh` argv (without the binary) for the planned forwards. */
+export function buildSshForwardArgv({ sshTarget, forwards, callbackPort = null }) {
+  const argv = [...SSH_FORWARD_OPTIONS];
+  for (const f of forwards) argv.push("-L", `127.0.0.1:${f.local}:127.0.0.1:${f.remote}`);
+  if (callbackPort != null) argv.push("-R", `${callbackPort}:127.0.0.1:${callbackPort}`);
+  argv.push("--", sshTarget);
+  return argv;
+}
+
+/**
+ * The connection the CHILD sees: every loopback URL/port the forwards cover is
+ * rewritten to its local port. project_id, keys and everything else are kept.
+ * The server's object is not mutated.
+ */
+export function rewriteConnectionForForwards(connection, forwards) {
+  const byRemote = new Map(forwards.map((f) => [f.remote, f.local]));
+  const rewriteUrl = (value) => value.replace(
+    /^([a-z][a-z0-9+.-]*:\/\/(?:[^@/]*@)?)(127\.0\.0\.1|localhost|\[::1\]):(\d+)/i,
+    (whole, prefix, _host, port) => (byRemote.has(Number(port)) ? `${prefix}127.0.0.1:${byRemote.get(Number(port))}` : whole),
+  );
+  const out = {};
+  for (const [key, value] of Object.entries(connection ?? {})) {
+    out[key] = typeof value === "string" ? rewriteUrl(value) : value;
+  }
+  const db = validPort(connection?.db_port);
+  if (db != null && byRemote.has(db)) out.db_port = byRemote.get(db);
+  out.ports = forwards.map((f) => ({ name: f.name, port: f.local, remote_port: f.remote }));
+  out.transport = "ssh-forward";
+  return out;
+}
+
+function probeConnect(port, timeoutMs = 500) {
+  return new Promise((resolve) => {
+    const socket = connect({ host: "127.0.0.1", port });
+    const done = (ok) => { socket.destroy(); resolve(ok); };
+    socket.setTimeout(timeoutMs, () => done(false));
+    socket.once("connect", () => done(true));
+    socket.once("error", () => done(false));
+  });
+}
+
+const BIND_RACE = /address already in use|cannot listen|could not request local forwarding/i;
+
+/**
+ * Spawn ONE ssh carrying every forward and resolve once each local listener accepts.
+ * Rejects (killing ssh) if ssh exits first or readiness times out.
+ */
+export async function openSshForwards({
+  sshBin = "ssh", argv, forwards, sshTarget, readyTimeoutMs = DEFAULT_TUNNEL_READY_MS,
+  spawnImpl = spawn, env = process.env, connectProbe = probeConnect, sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+}) {
+  // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- fixed ssh argv; target validated by assertSshTarget; no shell.
+  const child = spawnImpl(sshBin, argv, { stdio: ["ignore", "ignore", "pipe"], env });
+  let stderr = "";
+  child.stderr?.on("data", (chunk) => { stderr = (stderr + chunk.toString("utf8")).slice(-2048); });
+  let exited = null;
+  let closing = false;
+  const listeners = [];
+  const exitPromise = new Promise((resolve) => {
+    const finish = (code, signal) => {
+      if (exited) return;
+      exited = { code: code ?? null, signal: signal ?? null };
+      resolve(exited);
+      if (!closing) for (const fn of listeners) fn({ ...exited, stderr: stderr.trim() });
+    };
+    child.once("exit", finish);
+    child.once("error", (error) => { stderr += `\n${error.message}`; finish(null, null); });
+  });
+
+  const close = async () => {
+    if (exited) return exited;
+    closing = true;
+    try { child.kill("SIGTERM"); } catch { /* gone */ }
+    const timer = setTimeout(() => { try { child.kill("SIGKILL"); } catch { /* gone */ } }, 3_000);
+    timer.unref?.();
+    const result = await exitPromise;
+    clearTimeout(timer);
+    return result;
+  };
+
+  const deadline = Date.now() + readyTimeoutMs;
+  const pending = new Set(forwards.map((f) => f.local));
+  while (pending.size) {
+    if (exited) break;
+    for (const port of [...pending]) if (await connectProbe(port)) pending.delete(port);
+    if (!pending.size || exited) break;
+    if (Date.now() > deadline) break;
+    await sleep(100);
+  }
+  if (exited || pending.size) {
+    const timedOut = !exited;
+    await close();
+    const tail = stderr.trim();
+    throw tunnelError("REMOTE_UNREACHABLE",
+      `ssh ${sshTarget} could not open the stack forwards${timedOut ? ` within ${Math.round(readyTimeoutMs / 1000)}s` : ` (exit ${exited?.code ?? "?"})`}` +
+        `${tail ? `: ${tail}` : ""}. Check that \`ssh ${sshTarget}\` works non-interactively from this machine (BatchMode: a key, no password prompt).`,
+      { bindRace: BIND_RACE.test(tail), sshStderr: tail });
+  }
+  return {
+    pid: child.pid,
+    argv,
+    exited: exitPromise,
+    onExit: (fn) => { listeners.push(fn); if (exited && !closing) fn({ ...exited, stderr: stderr.trim() }); },
+    stderrTail: () => stderr.trim(),
+    close,
+  };
+}
+
+/**
+ * Codex #1077 P1: `-R` asks for a loopback listener on the host, but an sshd with
+ * `GatewayPorts yes` silently binds it on every interface, exposing this machine's
+ * callback service to the host's network. The CLI cannot read sshd_config, so after the
+ * forward is up it asks the host which address the listener really holds and refuses
+ * anything but loopback (fail closed: no lsof, no listener, unreadable → refused).
+ */
+export function verifyCallbackLoopback({ sshBin, sshTarget, port, env = process.env, run = spawnSync }) {
+  const fail = (why) => tunnelError("CALLBACK_NOT_LOOPBACK",
+    `the reverse forward for --callback-port ${port} on ${sshTarget} could not be proven loopback-only (${why}). ` +
+      "An sshd with GatewayPorts yes binds -R forwards on every interface; set GatewayPorts no (or clientspecified) on the host, " +
+      "or run without --callback-port.");
+  // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- fixed argv; target validated; integer port.
+  const r = run(sshBin, [
+    "-T", "-o", "BatchMode=yes", "-o", "ControlMaster=no", "-o", "ControlPath=none", "--", sshTarget,
+    `lsof -nP -iTCP:${Number(port)} -sTCP:LISTEN -Fn`,
+  ], { encoding: "utf8", env, timeout: 15_000 });
+  if (r.error || r.status !== 0) {
+    const tail = String(r.stderr || r.error?.message || "").trim().split("\n").slice(-1)[0];
+    // lsof exits 1 with no output when nothing listens.
+    if (r.status === 1 && !String(r.stdout || "").trim()) throw fail(`no listener on the host's port ${port}`);
+    throw fail(`could not run lsof on the host (exit ${r.status ?? "?"}${tail ? `: ${tail}` : ""})`);
+  }
+  const addresses = String(r.stdout || "").split("\n").filter((l) => l.startsWith("n")).map((l) => l.slice(1).trim());
+  if (!addresses.length) throw fail(`no listener on the host's port ${port}`);
+  const exposed = addresses.filter((a) => !(a.startsWith("127.") || a.startsWith("[::1]:") || a.startsWith("localhost:")));
+  if (exposed.length) throw fail(`the host listens on ${exposed.join(", ")}`);
+  return addresses;
+}
+
+/**
+ * Plan, spawn and verify the forwards for an ACTIVE remote lease.
+ * @returns {{ forwards, connection, argv, attempts, onExit, close, pid }}
+ */
+export async function establishSshTunnel({
+  connection, sshTarget, hostKey = null, callbackPort = null, sshBin = null, env = process.env,
+  attempts = 3, readyTimeoutMs = DEFAULT_TUNNEL_READY_MS, isFree = isLocalPortFree, pickFree = pickFreeLocalPort, spawnImpl = spawn,
+  runRemote = spawnSync,
+}) {
+  const target = assertSshTarget(sshTarget, hostKey);
+  const remotePorts = remotePortsFromConnection(connection);
+  const bin = sshBin || env.BOTBUDDY_STACK_SSH_BIN || "ssh";
+  let avoid = new Set();
+  let lastError = null;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const forwards = await planForwards(remotePorts, { isFree, pickFree, avoid });
+    const argv = buildSshForwardArgv({ sshTarget: target, forwards, callbackPort });
+    try {
+      const handle = await openSshForwards({ sshBin: bin, argv, forwards, sshTarget: target, readyTimeoutMs, spawnImpl, env });
+      if (callbackPort != null) {
+        try {
+          verifyCallbackLoopback({ sshBin: bin, sshTarget: target, port: callbackPort, env, run: runRemote });
+        } catch (error) {
+          await handle.close();
+          throw error;
+        }
+      }
+      return { ...handle, forwards, connection: rewriteConnectionForForwards(connection, forwards), attempts: attempt };
+    } catch (error) {
+      lastError = error;
+      // Only a lost local bind race is worth another try, on fresh ports; an auth or
+      // host failure would fail the same way again.
+      if (!error?.bindRace) throw error;
+      avoid = new Set([...avoid, ...forwards.map((f) => f.local), ...remotePorts.map((p) => p.port)]);
+    }
+  }
+  throw lastError;
+}

package/src/stack.mjs

@@ -23,7 +23,7 @@
 
 import { writeLaneStatus } from "./lane-status.mjs";
 import { spawn, spawnSync } from "child_process";
-import { readFileSync, realpathSync } from "fs";
+import { existsSync, lstatSync, readFileSync, realpathSync } from "fs";
 import { open, unlink, readFile } from "fs/promises";
 import { homedir, tmpdir } from "os";
 import { basename, dirname, join, relative, isAbsolute } from "path";
@@ -39,10 +39,25 @@ 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 { 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";
 
 export const STACK_SCHEMA_VERSION = 1;
+
+/**
+ * Codex #1077 P1: an sshd with `GatewayPorts yes` binds a `-R` forward on every interface,
+ * and the post-forward lsof check (`verifyCallbackLoopback`) runs only AFTER the listener
+ * exists — so the caller's callback service could be reachable from the host's network for
+ * a few seconds. Until a pre-forward probe lands (BOT-2184), a REMOTE lease refuses
+ * --callback-port outright (fail closed). Co-located leases are unaffected.
+ */
+export const CALLBACK_PORT_UNSUPPORTED_REMOTE = "CALLBACK_PORT_UNSUPPORTED_REMOTE";
+const CALLBACK_PORT_REMOTE_REFUSAL =
+  `${CALLBACK_PORT_UNSUPPORTED_REMOTE}: --callback-port is not supported on a remote lease yet — the -R listener ` +
+  "could be exposed on the serving host's network (sshd GatewayPorts yes) before it is checked. Tracked in BOT-2184 " +
+  "(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;
 /** How often a run renews its stack directory's retention while it still exists
@@ -102,6 +117,9 @@ ${bold("up OPTIONS")}
   --docker-context <name> Explicit Docker context for the mandatory local preflight
                          (an allowlisted engine: OrbStack or Docker Desktop, e.g. desktop-linux).
   --docker-endpoint <uri> Explicit Docker endpoint instead of --docker-context.
+  --local-only           Always the case for up: it asks for a co-located host (execution "local").
+                         up exits once the lease is active, so it cannot hold a remote lease's
+                         SSH forwards; --remote is refused here — use \`stack run --remote\`.
 
 ${bold("done OPTIONS")}
   --stop                 Keep volumes (cheap re-provision next batch). Default: destroy.
@@ -126,6 +144,22 @@ ${bold("run OPTIONS")}
   --hard-ttl N           Bound the child runtime; timeout requests normal cleanup.
   --local-exec           Rejected: stack run never starts Docker directly.
   --wait-capacity <dur>  Same as up: park a TRANSIENT stale-capacity refusal, then re-admit once.
+  --remote               Require a REMOTE lease (BOT-2142): another host this owner owns serves the
+                         stack. run uploads the materialised stack as a digest-pinned bundle, waits
+                         for active, forwards every stack port over one \`ssh -N -L\` to the host's
+                         ssh_target (transport ssh-forward), and gives the child a connection file
+                         on the LOCAL ports (same numbers when free, else remapped; see "forwards").
+  --local-only           Require a co-located host (execution "local"); no bundle is built.
+                         Default (neither flag): execution "auto" — co-located if it admits now,
+                         else a remote host with capacity; the bundle digest is sent up front.
+  --callback-port N      The caller runs a listener the stack calls back through
+                         host.docker.internal:N (e.g. 4600): sent as callback_port. Co-located
+                         leases only for now: a REMOTE lease refuses it (exit 4
+                         CALLBACK_PORT_UNSUPPORTED_REMOTE) until the pre-forward GatewayPorts
+                         probe lands (BOT-2184).
+  --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).
 
 ${bold("GLOBAL")}
   --json                 Pretty-print the receipt (default is one compact JSON line).
@@ -136,6 +170,28 @@ ${bold("EXIT CODES")}
   4 invalid arguments               5 backend/coordination      6 lease failed/reaped
   7 internal error                  8 cleanup/reap proof failed
 
+${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.
+  The child also gets BOTBUDDY_STACK_EXECUTION_MODE and BOTBUDDY_STACK_TRANSPORT.
+  5 REMOTE_UNREACHABLE    the host has no ssh_target (an operator must set it), or
+                          \`ssh <target>\` could not open the forwards (BatchMode: key auth only)
+  5 REMOTE_UNSUPPORTED    --remote, but the control plane placed the lease locally (pre-remote server)
+  5 HOST_NO_SSH_TARGET    the (pinned) remote host has no ssh_target — operator: set container_hosts.ssh_target
+  5 HOST_HELPER_OUTDATED  the (pinned) remote host's Helper predates protocol 4 — upgrade that Helper
+  5 NO_HELPER_HOST        no co-located host admits and no owned host qualifies as remote
+  4 STACK_EXECUTION_MODE_MISMATCH  the slot already holds a lease in another mode/host — stack done it first
+  (the four codes above create NO lease)
+  5 BUNDLE_UPLOAD_FAILED  the signed bundle upload failed (the lease is released first)
+  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 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,
+                          park_reason tunnel_lost (its failures were transport, not product)
+  Every remote failure after the lease exists still runs \`stack done\` and closes the forwards.
+
 ${bold("HOST_CAPACITY_SOURCE_STALE")} (BOT-2024)
   HOST_CAPACITY_SOURCE_STALE is a capacity flag, not a Helper diagnosis. Read \`phase\` on the
   receipt. transient → arm the printed \`bb wait 'capacity:…'\` and re-run once it fires
@@ -196,6 +252,8 @@ export function parseStackArgs(argv) {
     timeout: DEFAULT_TIMEOUT_SEC, provisionTimeout: null, reapTimeout: 300, hardTtl: null,
     connectionFile: null, noWait: false, claimOnly: false, localExec: false, waitCapacity: null,
     dockerContext: null, dockerEndpoint: null,
+    // BOT-2142: execution placement (null = command default), remote-lease callback + bundle cap.
+    execution: null, remote: false, localOnly: false, callbackPort: null, bundleMaxBytes: null,
     disposition: "destroy", json: false, receiptMaxBytes: DEFAULT_RECEIPT_MAX_BYTES,
   };
   const positionals = [];
@@ -275,6 +333,24 @@ export function parseStackArgs(argv) {
         }
         break;
       }
+      case "--remote": opts.remote = true; break;
+      case "--local-only": opts.localOnly = true; break;
+      case "--callback-port": {
+        if (need(a, rest[i + 1])) {
+          const n = Number(rest[++i]);
+          if (!Number.isInteger(n) || n <= 0 || n > 65535) errors.push("--callback-port must be an integer port (1-65535)");
+          else opts.callbackPort = n;
+        }
+        break;
+      }
+      case "--bundle-max-mb": {
+        if (need(a, rest[i + 1])) {
+          const n = Number(rest[++i]);
+          if (!Number.isInteger(n) || n <= 0 || n > 1024) errors.push("--bundle-max-mb must be an integer number of MB (1-1024)");
+          else opts.bundleMaxBytes = n * 1024 * 1024;
+        }
+        break;
+      }
       case "--no-wait": opts.noWait = true; break;
       case "--claim-only": opts.claimOnly = true; break;
       case "--local-exec": opts.localExec = true; break;
@@ -288,6 +364,24 @@ export function parseStackArgs(argv) {
         else positionals.push(a);
     }
   }
+  // BOT-2142: where the lease may be served. `run` defaults to the server's `auto`;
+  // `up` exits once the lease is active, so it can never hold a remote lease's SSH
+  // forwards and always asks for a co-located host.
+  if (opts.remote && opts.localOnly) errors.push("--remote and --local-only are mutually exclusive");
+  if (opts.remote && opts.localExec) {
+    errors.push("--remote cannot be combined with --local-exec: a local-exec stack is started on THIS machine");
+  }
+  if ((opts.remote || opts.localOnly) && !["up", "run"].includes(command)) {
+    errors.push("--remote and --local-only are valid only with `stack up` or `stack run`");
+  } else if (command === "up" && opts.remote) {
+    errors.push("stack up cannot hold a remote lease's SSH forwards (it exits once the lease is active); use `stack run --remote -- <command>`");
+  }
+  if ((opts.callbackPort != null || opts.bundleMaxBytes != null) && command !== "run") {
+    errors.push("--callback-port and --bundle-max-mb are valid only with `stack run`");
+  } else if (opts.remote && opts.callbackPort != null) {
+    errors.push(CALLBACK_PORT_REMOTE_REFUSAL);
+  }
+  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 === "..")) {
     errors.push("--stack-path must be a non-empty relative path without '..'");
@@ -787,9 +881,35 @@ export function leaseRefusalExit(code) {
   return code === STACK_PATH_ROOT_REFUSED_CODE || code === "STACK_EXECUTION_MODE_MISMATCH" ? EXIT.INVALID : EXIT.BACKEND;
 }
 
-/** The refusal text for a receipt: the server's message, else its code. */
+/**
+ * BOT-2142: the remote-lease host-selection refusals of BOT-2145 (#1087) arrive as a bare
+ * `{ success: false, code }`. Name each one with the fix, so an agent never has to guess
+ * what a code means. Every one of them created NO lease.
+ */
+export const REMOTE_REFUSAL_GUIDANCE = Object.freeze({
+  HOST_NO_SSH_TARGET: "the remote host has no ssh_target, so this machine cannot forward to its stack. An operator must set " +
+    "container_hosts.ssh_target for that host (e.g. the `ssh mini` alias this machine already trusts; BOT-2174). " +
+    "No lease was created; re-run with --local-only meanwhile.",
+  HOST_HELPER_OUTDATED: "the remote host's Helper is too old to serve a remote lease (it must speak protocol 4, which " +
+    "provisions from the uploaded bundle; BOT-2143). Upgrade the Helper on that host. No lease was created; re-run with --local-only meanwhile.",
+  NO_HELPER_HOST: "no host can serve this lease: no co-located Helper admits it and no other host you own qualifies as remote " +
+    "(an owned, device-consented, beacon-fresh Helper on protocol 4 with an operator-set ssh_target). No lease was created.",
+  HOST_NOT_OWNED: "the pinned host is not a device-consented Helper host your owner owns. No lease was created.",
+  HOST_STALE: "the pinned remote host's Helper beacon is stale. No lease was created; retry once it beacons, or drop --host.",
+  HOST_NOT_REMOTE: "--remote pinned this machine's own host; drop --host or --remote. No lease was created.",
+  BUNDLE_REQUIRED: "the server picked a remote host but this request carried no bundle digest. No lease was created; " +
+    "re-run (the bundle is built automatically unless it failed — see the warning above) or use --local-only.",
+});
+
+/** The refusal text for a receipt: the server's message, else the CLI's guidance, else the code. */
 export function leaseRefusalError(data) {
-  return data?.message || data?.code || "lease request refused";
+  return data?.message || REMOTE_REFUSAL_GUIDANCE[data?.code] || data?.code || "lease request refused";
+}
+
+/** One stderr line naming a remote-lease refusal (null for every other code). */
+export function remoteRefusalNotice(code) {
+  const guidance = REMOTE_REFUSAL_GUIDANCE[code];
+  return guidance ? `${yellow("⚠")} stack: ${code}: ${guidance}` : null;
 }
 
 // ── BOT-2024: phase-aware HOST_CAPACITY_SOURCE_STALE ─────────────────────────
@@ -1823,6 +1943,9 @@ export async function cmdUp(opts, {
     stack_path: execution.stackPath,
     worktree_root: execution.worktreeRoot,
     machine_uuid: hardwareUuid,
+    // BOT-2142: `up` returns once the lease is active and cannot keep SSH forwards
+    // open for a remote host, so it always asks for a co-located one (BOT-2145).
+    execution: "local",
     // BOT-1926: fence the provision job from the Helper server-side. Without it a
     // polling Helper wins the request→reserve race, provisions the stack itself and
     // records a targetless connection that `done --local-exec` cannot release.
@@ -2511,6 +2634,22 @@ export async function materializeLeasedTestConfig(worktreeRoot, leaseId, connect
   return { envFile, stackConfig, edgeMountRoot };
 }
 
+/**
+ * BOT-2142: the SSH forward to a remote lease's host exited while the child ran. The
+ * child was stopped (its failures would otherwise read as product failures, BOT-2021
+ * spine hop 12) and the lease released; the outcome is a lost lease, exit 6, with
+ * the BOT-1754-style `park_reason`.
+ */
+function tunnelLostResult(lost, { leaseId, cleanup, childExitCode, ...rest }) {
+  const how = lost.signal ? `signal ${lost.signal}` : `exit ${lost.code ?? "?"}`;
+  return {
+    exitCode: EXIT.LEASE_FAILED, outcome: "failed", code: "TUNNEL_LOST", parkReason: "tunnel_lost", leaseId, childExitCode, cleanup,
+    error: `the SSH forward to ${lost.target ?? "the serving host"} ended (${how}) while the child was running, so the child was stopped and the lease released` +
+      `${lost.stderr ? ` — ssh: ${lost.stderr.split("\n").slice(-2).join(" ")}` : ""}. Re-run the batch; if it repeats, check the link to the host.`,
+    ...rest,
+  };
+}
+
 /**
  * The command-owned lifecycle. The optional adapters are intentionally narrow so
  * its queue, heartbeat, process-group, and cleanup contract is spawn-testable
@@ -2519,9 +2658,11 @@ export async function materializeLeasedTestConfig(worktreeRoot, leaseId, connect
 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.
-  const incidentBox = { incident: null };
+  // BOT-2142: where the lease ran (and how it was reached) is on every terminal result too.
+  const incidentBox = { incident: null, execution: null };
   const result = await runStackLifecycleOnce(opts, childArgv, adapters, incidentBox);
-  return incidentBox.incident && !result?.incident ? { ...result, incident: incidentBox.incident } : result;
+  const withIncident = incidentBox.incident && !result?.incident ? { ...result, incident: incidentBox.incident } : result;
+  return incidentBox.execution && !withIncident?.execution ? { ...withIncident, execution: incidentBox.execution } : withIncident;
 }
 
 async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
@@ -2583,6 +2724,11 @@ 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-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;
+  const uploadBundle = adapters.uploadBundle ?? uploadStackBundle;
+  const openTunnel = adapters.openTunnel ?? ((args) => establishSshTunnel(args));
   const clock = adapters.clock ?? { setInterval, clearInterval, setTimeout, clearTimeout };
   const signals = adapters.signals ?? process;
   const provisionTimeout = opts.provisionTimeout ?? opts.timeout;
@@ -2603,6 +2749,17 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   let forcedStopCode = null;
   let fencing = false;
   let activeWaitAbort = null;
+  // BOT-2142: the remote lease's forwards, and whether they died under a running child.
+  let tunnel = null;
+  let tunnelLost = null;
+  const placement = { mode: null, hostKey: null, requesterHost: null, transport: "none", forwards: null, bundle: null };
+  incidentBox.execution = placement;
+  const closeTunnel = async () => {
+    if (!tunnel) return;
+    const open = tunnel;
+    tunnel = null;
+    try { await open.close(); } catch { /* best effort: the process is gone either way */ }
+  };
 
   const requestCleanup = () => {
     // A signal can arrive while the lease-request RPC is in flight. There is
@@ -2734,12 +2891,44 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     keepAlive();
     retention = clock.setInterval(keepAlive, RETENTION_REFRESH_MS);
     retention?.unref?.();
+    // BOT-2142: `auto` (the default) may be served by another host this owner owns, and
+    // the client cannot know which one the server picks, so the bundle digest goes up
+    // front for both `auto` and `remote` (BOT-2145 refuses a remote pick without it).
+    // `--local-only` never ships anything.
+    let executionRequest = opts.execution ?? "auto";
+    let bundle = null;
+    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 }] } : {}),
+        });
+      } catch (error) {
+        const message = String(error?.message ?? error);
+        if (executionRequest === "remote") {
+          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 };
+        }
+        // Codex #1077 P2: without a digest, `auto` could still pick a remote host and be
+        // refused BUNDLE_REQUIRED instead of queueing here, so ask for this machine.
+        executionRequest = "local";
+        stderrLine(`${yellow("⚠")} stack: could not build the remote-lease bundle (${message}); requesting a co-located lease (execution local) instead.`);
+      }
+    }
     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,
       purpose: opts.purpose || "stack run", idle_ttl_secs: opts.idleTtl ?? undefined,
       stack_path: execution.stackPath, worktree_root: execution.worktreeRoot,
       machine_uuid: hardwareUuid,
+      execution: executionRequest,
+      ...(bundle ? { bundle_sha256: bundle.sha256 } : {}),
+      ...(opts.callbackPort != null ? { callback_port: opts.callbackPort } : {}),
     };
     // The retrying caller (api → rpc.call) transparently clears+self-heals+retries the
     // FIRST auth rejection among any of request/get/touch/release.
@@ -2785,7 +2974,8 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     }
     if (!request.data?.success) {
       const hint = worktreeRegistrationHint(request.data?.code, rpc.auth)
-        ?? stackPathRootRefusalNotice(request.data?.code, request.data?.message);
+        ?? stackPathRootRefusalNotice(request.data?.code, request.data?.message)
+        ?? remoteRefusalNotice(request.data?.code);
       if (hint) stderrLine(hint);
       return {
         exitCode: leaseRefusalExit(request.data?.code), outcome: "error", code: request.data?.code,
@@ -2799,6 +2989,63 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
 
     leaseProvisioned = true; // from here a Helper may act on this lease
     let state = request.data.state;
+    // 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";
+    placement.mode = request.data.execution_mode ?? null;
+    placement.hostKey = request.data.host_key ?? null;
+    placement.requesterHost = request.data.requester_host ?? null;
+    if (executionRequest === "remote" && !remoteLease) {
+      const cleanup = await requestCleanup();
+      return {
+        exitCode: EXIT.BACKEND, outcome: "error", code: "REMOTE_UNSUPPORTED", leaseId, cleanup,
+        error: `--remote was requested but the control plane placed lease ${leaseId} as ${request.data.execution_mode ?? "a co-located (pre-remote) lease"}; ` +
+          "it was released. The server may predate remote leases — retry without --remote, or after it is upgraded.",
+      };
+    }
+    let sshTarget = request.data.ssh_target ?? request.data.connection?.ssh_target ?? null;
+    if (remoteLease && opts.callbackPort != null) {
+      // Codex #1077 P1 / BOT-2184: `auto` placed this run remote; release before any upload
+      // or forward rather than open an -R listener that may be exposed.
+      const cleanup = await requestCleanup();
+      return { exitCode: EXIT.INVALID, outcome: "error", code: CALLBACK_PORT_UNSUPPORTED_REMOTE, leaseId, cleanup, error: CALLBACK_PORT_REMOTE_REFUSAL };
+    }
+    if (remoteLease) {
+      // Fail fast when the server SAYS the host has no SSH destination (the key is
+      // present but empty); a server that only reports it on the active read is
+      // checked again once the lease is active.
+      const advertised = request.data.ssh_target !== undefined || request.data.connection?.ssh_target !== undefined;
+      if (advertised) {
+        try { assertSshTarget(sshTarget, placement.hostKey); } catch (error) {
+          const cleanup = await requestCleanup();
+          return { exitCode: EXIT.BACKEND, outcome: "error", code: error.code ?? "REMOTE_UNREACHABLE", leaseId, error: error.message, cleanup };
+        }
+      }
+      if (!bundle || !request.data.bundle_upload_url) {
+        const cleanup = await requestCleanup();
+        return {
+          exitCode: EXIT.BACKEND, outcome: "error", code: bundle ? "BUNDLE_UPLOAD_URL_MISSING" : "BUNDLE_REQUIRED", leaseId, cleanup,
+          error: bundle
+            ? `the control plane placed lease ${leaseId} on ${placement.hostKey ?? "a remote host"} without a bundle_upload_url; it was released`
+            : `lease ${leaseId} was placed on ${placement.hostKey ?? "a remote host"} but this run has no stack bundle; it was released`,
+        };
+      }
+      // Codex #1077 P1: a stalled PUT must not outlive a SIGINT/SIGTERM — the signal
+      // handler aborts the active wait, and that now includes the upload.
+      activeWaitAbort = new AbortController();
+      const uploaded = await uploadBundle(request.data.bundle_upload_url, bundle, { signal: activeWaitAbort.signal });
+      activeWaitAbort = null;
+      if (receivedSignal) {
+        const cleanup = await requestCleanup();
+        return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup };
+      }
+      if (!uploaded?.ok) {
+        const cleanup = await requestCleanup();
+        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 };
+      stderrLine(`stack: lease ${leaseId} is remote on ${placement.hostKey ?? "?"} — uploaded the ${bundle.size}-byte stack bundle (sha256 ${bundle.sha256.slice(0, 12)}…)`);
+    }
     if (receivedSignal) {
       const cleanup = await requestCleanup();
       return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup };
@@ -2874,13 +3121,36 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup };
     }
 
-    connectionFile = await writeConnection(safeConnectionPath(opts.connectionFile, leaseId), current.data.connection);
+    placement.hostKey = current.data.host_key ?? placement.hostKey;
+    placement.mode = current.data.execution_mode ?? placement.mode ?? (remoteLease ? "remote" : null);
+    let childConnection = current.data.connection;
+    if (remoteLease) {
+      // BOT-2142: forward every stack port over ONE ssh and hand the child the local ports.
+      sshTarget = current.data.connection?.ssh_target ?? current.data.ssh_target ?? sshTarget;
+      try {
+        tunnel = await openTunnel({ connection: current.data.connection, sshTarget, hostKey: placement.hostKey, callbackPort: opts.callbackPort ?? null });
+      } catch (error) {
+        const cleanup = await requestCleanup();
+        return { exitCode: EXIT.BACKEND, outcome: "error", code: error?.code ?? "REMOTE_UNREACHABLE", leaseId, error: String(error?.message ?? error), cleanup };
+      }
+      placement.transport = "ssh-forward";
+      placement.forwards = tunnel.forwards.map(({ name, remote, local }) => ({ name, remote, local }));
+      for (const f of tunnel.forwards.filter((x) => x.remapped)) stderrLine(`stack: forward ${f.name} remapped: local ${f.local} → ${placement.hostKey ?? "remote"} ${f.remote}`);
+      childConnection = tunnel.connection;
+      const forwardTarget = sshTarget;
+      tunnel.onExit((exit) => {
+        if (childResult) return;
+        tunnelLost = { ...exit, target: forwardTarget };
+        stopChild("SIGTERM", EXIT.LEASE_FAILED);
+      });
+    }
+    connectionFile = await writeConnection(safeConnectionPath(opts.connectionFile, leaseId), childConnection);
     if (receivedSignal) {
       const cleanup = await requestCleanup();
       return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup };
     }
     if (isDenoIntegrationLane(childArgv)) {
-      leasedTestConfig = await materializeTestConfig(execution.worktreeRoot, leaseId, current.data.connection, { edgeMountRoot: stackDirFor(execution) });
+      leasedTestConfig = await materializeTestConfig(execution.worktreeRoot, leaseId, childConnection, { edgeMountRoot: stackDirFor(execution) });
     }
     if (receivedSignal) {
       const cleanup = await requestCleanup();
@@ -2890,6 +3160,10 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       ...process.env,
       BOTBUDDY_STACK_LEASE_ID: leaseId,
       BOTBUDDY_STACK_CONNECTION_FILE: connectionFile,
+      // BOT-2142: lets a lane's own checks (e.g. the port-owner preflight) know the
+      // listeners are SSH forwards to another host, not this machine's Docker.
+      BOTBUDDY_STACK_EXECUTION_MODE: remoteLease ? "remote" : (placement.mode ?? "local"),
+      BOTBUDDY_STACK_TRANSPORT: placement.transport,
       ...(leasedTestConfig ? {
         BB_INTEGRATION_ENV_FILE: leasedTestConfig.envFile,
         BB_STACK_CONFIG: leasedTestConfig.stackConfig,
@@ -2903,6 +3177,12 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     // there would fail on a missing package.json AFTER the stack was provisioned.
     // The child therefore always runs in the (canonicalised) worktree root.
     const childCwd = execution.worktreeRoot;
+    if (tunnelLost) {
+      // The forwards died between being verified and the child starting.
+      await closeTunnel();
+      const cleanup = await requestCleanup();
+      return tunnelLostResult(tunnelLost, { leaseId, cleanup, childExitCode: null });
+    }
     child = startChild(childArgv, childEnv, childCwd);
     leaseIdleTtlSecs = current.data.idle_ttl_secs ?? opts.idleTtl ?? 1800;
     const cadenceMs = Math.max(1_000, Math.floor(leaseIdleTtlSecs * 1000 / 3));
@@ -2927,7 +3207,11 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     if (heartbeat) clock.clearInterval(heartbeat);
     if (retention) { clock.clearInterval(retention); retention = null; }
     if (hardTimer) clock.clearTimeout(hardTimer);
+    await closeTunnel();
     const cleanup = await requestCleanup();
+    if (tunnelLost && !receivedSignal) {
+      return tunnelLostResult(tunnelLost, { leaseId, cleanup, childExitCode: childResult.code, fenced: fencing, ...(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) {
@@ -2942,6 +3226,8 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
     if (heartbeat) clock.clearInterval(heartbeat);
     if (retention) clock.clearInterval(retention);
     if (hardTimer) clock.clearTimeout(hardTimer);
+    // BOT-2142: forwards never outlive the batch, whichever path ended it.
+    await closeTunnel();
     if (connectionFile) await removeConnection(connectionFile);
     if (leasedTestConfig) await Promise.all([removeConnection(leasedTestConfig.envFile), removeConnection(leasedTestConfig.stackConfig)]);
     // Release the materialization lock only once the batch (and its signed reap)
@@ -2968,6 +3254,14 @@ async function cmdRun(opts, childArgv) {
     ...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,
+    ...(result.parkReason ? { park_reason: result.parkReason } : {}),
+    // BOT-2142: where the lease ran and how the child reached it.
+    execution_mode: result.execution?.mode ?? null,
+    execution_host_key: result.execution?.hostKey ?? null,
+    requester_host: result.execution?.requesterHost ?? null,
+    transport: result.execution?.transport ?? "none",
+    ...(result.execution?.forwards ? { forwards: result.execution.forwards } : {}),
+    ...(result.execution?.bundle ? { bundle: result.execution.bundle } : {}),
     fenced: result.fenced ?? false, error: result.error ?? result.cleanup?.error ?? null,
     // BOT-2099: a platform auth/availability blip during the park is reported as an
     // incident (reason, window, attempts, recovered) — never as the lease's outcome.