@botbuddy/cli 1.62.4 → 1.63.0

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.62.4",
-  "source_commit": "1cc371424a95b39915a3e882a428688bced7386a",
-  "source_sha256": "8d9dd0daf489c418b04d34b57696a6f97a9346d141f9266dda3a74e7ca87d4cf",
+  "release_version": "1.63.0",
+  "source_commit": "cfcfef9b5adb90a7a7dfb2fd8cfad0206464149a",
+  "source_sha256": "9f30dd9147ad173965dfc2a5f1c8b209c32d760a82c3edd6cbf560108e95a5f0",
   "target": "darwin-arm64",
-  "sha256": "4ce65712c580403552a1d15f9dce56149dfdf48d121c634a6f5c748cb48e85fd"
+  "sha256": "5d57767abb24be43ba64e17b57d9aa396c4149f4b89101e6a0346da57ec5ea41"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.62.4",
-  "source_commit": "1cc371424a95b39915a3e882a428688bced7386a",
-  "source_sha256": "8d9dd0daf489c418b04d34b57696a6f97a9346d141f9266dda3a74e7ca87d4cf",
+  "release_version": "1.63.0",
+  "source_commit": "cfcfef9b5adb90a7a7dfb2fd8cfad0206464149a",
+  "source_sha256": "9f30dd9147ad173965dfc2a5f1c8b209c32d760a82c3edd6cbf560108e95a5f0",
   "target": "linux-x64",
-  "sha256": "4993e29705d75254afd21fadcbef568faf8650471df1bbcd9a96a6c5d3d2a254"
+  "sha256": "33e0e6ba075a7486a02e4a3638bce10e1df41ddfe8315685e285cf144a149ea7"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.62.4",
-  "source_commit": "1cc371424a95b39915a3e882a428688bced7386a",
-  "source_sha256": "8d9dd0daf489c418b04d34b57696a6f97a9346d141f9266dda3a74e7ca87d4cf",
+  "release_version": "1.63.0",
+  "source_commit": "cfcfef9b5adb90a7a7dfb2fd8cfad0206464149a",
+  "source_sha256": "9f30dd9147ad173965dfc2a5f1c8b209c32d760a82c3edd6cbf560108e95a5f0",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "4ce65712c580403552a1d15f9dce56149dfdf48d121c634a6f5c748cb48e85fd",
+      "sha256": "5d57767abb24be43ba64e17b57d9aa396c4149f4b89101e6a0346da57ec5ea41",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "4993e29705d75254afd21fadcbef568faf8650471df1bbcd9a96a6c5d3d2a254",
+      "sha256": "33e0e6ba075a7486a02e4a3638bce10e1df41ddfe8315685e285cf144a149ea7",
       "mode": "0755"
     }
   }

package/package.json

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

package/src/stack-forward-attestation.mjs

@@ -0,0 +1,131 @@
+// BOT-2738: live transport evidence belongs to the process holding the tunnel,
+// not a connection file which can outlive it. This private Unix socket is a
+// local capability only; cmdStatus still authenticates the lease server-side.
+import { createServer, get } from "node:http";
+import { chmod, lstat, mkdtemp, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+
+export const FORWARD_ATTESTATION_ENV = "BOTBUDDY_STACK_FORWARD_ATTESTATION_SOCKET";
+const failure = () => new Error("live stack forward attestation unavailable");
+
+export function ownsLsofSocket(output, ownerPid, socketPath, platform = process.platform) {
+  if (!["darwin", "linux"].includes(platform)) return false;
+  // Linux's native n field appends the socket type; Darwin's does not.
+  // Match the complete dialect-specific field, never trim arbitrary suffixes:
+  // a literal " type=STREAM" may itself be part of an untrusted pathname.
+  const expected = `n${socketPath}${platform === "linux" ? " type=STREAM" : ""}`;
+  let ownedProcess = false;
+  for (const field of String(output ?? "").split("\n")) {
+    if (field.startsWith("p")) ownedProcess = field === `p${ownerPid}`;
+    else if (ownedProcess && field === expected) return true;
+  }
+  return false;
+}
+
+// A caller can replace an environment value or create its own socket. Require
+// kernel evidence that this endpoint belongs to a live ancestor of the status
+// process, rather than granting trust to the capability path or response alone.
+function assertAncestorEndpoint(socketPath, ownerPid) {
+  if (!Number.isInteger(ownerPid) || ownerPid <= 1 || /[\r\n]/.test(socketPath)) throw failure();
+  let pid = process.ppid;
+  let found = false;
+  for (let depth = 0; depth < 32 && pid > 1; depth++) {
+    if (pid === ownerPid) { found = true; break; }
+    const parent = spawnSync("/bin/ps", ["-p", String(pid), "-o", "ppid="], { encoding: "utf8", timeout: 2000, maxBuffer: 1024 });
+    if (parent.status !== 0 || !/^\s*\d+\s*$/.test(parent.stdout)) throw failure();
+    const next = Number(parent.stdout.trim());
+    if (next === pid) throw failure();
+    pid = next;
+  }
+  if (!found) throw failure();
+  const lsof = process.platform === "darwin" ? "/usr/sbin/lsof" : "/usr/bin/lsof";
+  const held = spawnSync(lsof, ["-nP", "-a", "-U", "-p", String(ownerPid), "-F", "pn"], { encoding: "utf8", timeout: 2000, maxBuffer: 256 * 1024 });
+  if (held.status !== 0 || !ownsLsofSocket(held.stdout, ownerPid, socketPath)) throw failure();
+}
+
+function validForwards(rows) {
+  return Array.isArray(rows) && rows.length > 0 && rows.length <= 32
+    && rows.every((row) => typeof row?.name === "string" && row.name.length > 0 && row.name.length <= 64
+      && [row.local, row.remote].every((p) => Number.isInteger(p) && p > 0 && p <= 65535))
+    && ["name", "local", "remote"].every((key) => new Set(rows.map((r) => r[key])).size === rows.length);
+}
+
+export async function startForwardAttestation({ leaseId, sshTarget, forwards, isLive }) {
+  if (typeof leaseId !== "string" || !leaseId || typeof sshTarget !== "string" || !sshTarget
+    || !validForwards(forwards) || typeof isLive !== "function" || isLive() !== true) throw failure();
+  const snapshot = {
+    schema_version: 1, lease_id: leaseId, ssh_target: sshTarget, owner_pid: process.pid,
+    forwards: forwards.map(({ name, local, remote }) => ({ name, local, remote })),
+  };
+  const root = await mkdtemp(join(tmpdir(), "bb-f-"));
+  const socketPath = join(root, "f");
+  const server = createServer((request, response) => {
+    let allowed = false;
+    try {
+      const url = new URL(request.url, "http://local");
+      allowed = request.method === "GET" && url.pathname === "/forwards"
+        && url.searchParams.size === 1 && url.searchParams.get("lease_id") === leaseId && isLive() === true;
+    } catch { /* Unknown evidence is a refusal. */ }
+    response.writeHead(allowed ? 200 : 409, { "content-type": "application/json", "connection": "close" });
+    response.end(JSON.stringify(allowed ? snapshot : { error: "forward attestation unavailable" }));
+  });
+  try {
+    await chmod(root, 0o700);
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(socketPath, resolve);
+    });
+    await chmod(socketPath, 0o600);
+    server.unref();
+  } catch {
+    server.closeAllConnections();
+    server.close();
+    await rm(root, { recursive: true, force: true });
+    throw failure();
+  }
+  let closed;
+  return {
+    socketPath,
+    close() {
+      return closed ??= (async () => {
+        server.closeAllConnections();
+        await new Promise((resolve) => server.close(resolve));
+        await rm(root, { recursive: true, force: true });
+      })();
+    },
+  };
+}
+
+export async function readForwardAttestation({ socketPath, leaseId, sshTarget }) {
+  if (!socketPath) return null;
+  try {
+    const [socket, directory] = await Promise.all([lstat(socketPath), lstat(dirname(socketPath))]);
+    if (!socket.isSocket() || !directory.isDirectory()
+      || socket.uid !== process.getuid() || directory.uid !== process.getuid()
+      || (socket.mode & 0o777) !== 0o600 || (directory.mode & 0o777) !== 0o700) throw failure();
+    const payload = await new Promise((resolve, reject) => {
+      const request = get({ socketPath, path: `/forwards?lease_id=${encodeURIComponent(leaseId)}` }, (response) => {
+        if (response.statusCode !== 200) { response.resume(); reject(failure()); return; }
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          body += chunk;
+          if (body.length > 16 * 1024) request.destroy(failure());
+        });
+        response.on("error", reject);
+        response.on("end", () => {
+          try { resolve(JSON.parse(body)); } catch { reject(failure()); }
+        });
+      });
+      const deadline = setTimeout(() => request.destroy(failure()), 2000);
+      request.on("close", () => clearTimeout(deadline));
+      request.on("error", reject);
+    });
+    if (payload?.schema_version !== 1 || payload.lease_id !== leaseId
+      || payload.ssh_target !== sshTarget || !validForwards(payload.forwards)) throw failure();
+    assertAncestorEndpoint(socketPath, payload.owner_pid);
+    return payload.forwards;
+  } catch { throw failure(); }
+}

package/src/stack-isolation.mjs

@@ -20,8 +20,9 @@
 // Supply Guard's `scripts/local-supabase-isolated.sh`, ported here because the
 // published CLI cannot import repo scripts and stays Node-stdlib only.
 import { createHash, randomUUID } from "node:crypto";
+import { spawnSync } from "node:child_process";
 import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { homedir, hostname } from "node:os";
+import { homedir, hostname, platform } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
 import { lockPathForProject, projectIdFromConfig } from "./stack-file-lock.mjs";
 
@@ -45,6 +46,75 @@ export const LEASED_PORT_STRIDE = 20;
  * never a silently shared stack. */
 export const LEASED_PORT_SLOTS = 200;
 
+// BOT-2490: identical hint name, epoch-millisecond format and ten-minute window
+// to Helper ServingPortAllocation.swift. Hints never override a live claim.
+const RELEASE_COOLDOWN_PREFIX = ".helper-released-";
+const RELEASE_COOLDOWN_MS = 600_000;
+
+/** Actual host TCP listeners, not merely the managed claim registry. */
+export function listeningTcpPorts({ run = spawnSync } = {}) {
+  const fail = (detail) => Object.assign(new Error(`refusing port allocation: lsof host TCP listener census failed (${detail}). Verify lsof is installed and can enumerate TCP listeners.`), { code: "stack_port_census_failed" });
+  let result;
+  try {
+    result = run(platform() === "darwin" ? "/usr/sbin/lsof" : "lsof", ["-nP", "-iTCP", "-sTCP:LISTEN", "-F", "n"], { encoding: "utf8", timeout: 10_000 });
+  } catch (error) { throw fail(error?.code ?? "lsof unavailable"); }
+  const { status, stdout, stderr, error } = result ?? {};
+  if (error) throw fail(error.code ?? "lsof execution error");
+  if (status === 1 && stdout === "" && stderr === "") return new Set();
+  if (status !== 0 || typeof stdout !== "string") throw fail(`lsof exit ${status ?? "unknown"}`);
+  // An exit-zero partial listing with diagnostics cannot establish that the
+  // omitted ports are free. Never turn it into a successful census.
+  if (typeof stderr !== "string" || stderr.trim()) throw fail("lsof diagnostics or unavailable stderr");
+  const ports = new Set();
+  for (const line of stdout.split(/\r?\n/)) {
+    if (!line) continue;
+    if (!line.startsWith("n")) {
+      // The captured `-F n` counterpart and lsof's field-output contract have
+      // mandatory process/file records in addition to the requested names.
+      if (!/^[pf]/.test(line)) throw fail("unexpected census record");
+      continue;
+    }
+    const colon = line.lastIndexOf(":");
+    if (colon < 2) throw fail("malformed listener record");
+    const token = line.slice(colon + 1);
+    const port = /^\d+$/.test(token) ? Number(token) : NaN;
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw fail("malformed listener record");
+    ports.add(port);
+  }
+  if (ports.size === 0) throw fail("incomplete listener census");
+  return ports;
+}
+
+function releaseCooldowns(registryDir, { readdir, read, now }) {
+  const cooling = new Map();
+  const fail = (operation, error) => Object.assign(new Error(`refusing port allocation: released-block cooldown ${operation} failed (${error?.code ?? "read error"}). Restore access to the port registry before retrying.`), { code: "stack_port_cooldown_failed" });
+  let names;
+  try { names = readdir(registryDir); } catch (error) { throw fail("enumeration", error); }
+  for (const name of names) {
+    if (!name.startsWith(RELEASE_COOLDOWN_PREFIX)) continue;
+    const token = name.slice(RELEASE_COOLDOWN_PREFIX.length);
+    const base = /^\d+$/.test(token) ? Number(token) : NaN;
+    // Atomic-write temporary files and non-candidate names are not cooldown
+    // evidence. Validate before I/O so irrelevant unreadable files cannot block.
+    if (!Number.isInteger(base) || base < LEASED_PORT_BASE || base >= LEASED_PORT_BASE + LEASED_PORT_SLOTS * LEASED_PORT_STRIDE || (base - LEASED_PORT_BASE) % LEASED_PORT_STRIDE !== 0) continue;
+    let raw;
+    try { raw = read(join(registryDir, name), "utf8").trim(); } catch (error) { throw fail("record read", error); }
+    const released = raw === "" ? NaN : Number(raw);
+    if (Number.isInteger(base) && Number.isFinite(released) && now() - released < RELEASE_COOLDOWN_MS) cooling.set(base, released);
+  }
+  return cooling;
+}
+
+function recordReleaseCooldown(registryDir, base, { write, rename, now, warn }) {
+  try {
+    atomicWrite(join(registryDir, `${RELEASE_COOLDOWN_PREFIX}${base}`), String(now()), { write, rename });
+    return true;
+  } catch (error) {
+    warn(`stack: could not record released port-block cooldown ${base}: ${error?.code ?? "write failed"}`);
+    return false;
+  }
+}
+
 /** How long a leased stack directory must have been untouched before another run
  * may collect it. Comfortably above the reaper's default 1800 s idle TTL, so a
  * batch whose owner process died but whose child/containers are still finishing is
@@ -930,6 +1000,12 @@ export function blocksForPorts(ports) {
 export function releaseLeasedStackClaim(stackDir, { registryDir = defaultPortRegistryDir(), io = {} } = {}) {
   const read = io.readFile ?? readFileSync;
   const remove = io.remove ?? rmSync;
+  const write = io.writeFile ?? writeFileSync;
+  const rename = io.rename ?? renameSync;
+  const now = io.now ?? Date.now;
+  const alive = io.alive ?? pidIsAlive;
+  const host = io.hostname ?? hostname;
+  const writeExclusive = io.writeExclusive ?? ((path, data) => writeFileSync(path, data, { flag: "wx" }));
   const marker = readStackMarker(stackDir, read);
   if (!marker || !Number.isInteger(marker.port_base)) return false;
   const path = portClaimPath(registryDir, marker.port_base);
@@ -938,8 +1014,13 @@ export function releaseLeasedStackClaim(stackDir, { registryDir = defaultPortReg
   const owner = marker.invocation_token ?? marker.project_id;
   if (!claim || (claim.invocation_token ?? claim.project_id) !== owner) return false;
   try {
-    remove(path, { force: true });
-    return true;
+    return withAllocationLock(registryDir, { writeExclusive, read, remove, now, alive, host, sleep: io.sleep }, () => {
+      const current = JSON.parse(read(path, "utf8"));
+      if ((current?.invocation_token ?? current?.project_id) !== owner) return false;
+      if (!recordReleaseCooldown(registryDir, marker.port_base, { write, rename, now, warn: io.warn ?? console.warn })) return false;
+      remove(path, { force: true });
+      return true;
+    });
   } catch {
     return false;
   }
@@ -1077,14 +1158,28 @@ export function reservePortBlocks(ports, { registryDir = defaultPortRegistryDir(
     /** Returns whether none of this invocation's claims remain (BOT-2237: a verified result). */
     release: () => {
       let allReleased = true;
+      // Do not create an allocation lock when the registry is unreadable: its
+      // ownership could not be re-read for safe unlock either. Re-check under
+      // the lock below before any unlink, so this is not an ownership shortcut.
       for (const block of claimed) {
-        let current = null;
-        // Codex #1168 R2 P2: a claim that is gone (ENOENT) is released; one that cannot be read
-        // or parsed is unverifiable — never unlinked blindly, and never reported as released.
-        try { current = JSON.parse(read(portClaimPath(registryDir, block), "utf8")); } catch (error) { if (error?.code !== "ENOENT") allReleased = false; continue; }
-        if (current?.invocation_token !== invocationToken) continue; // superseded: never unlink blindly
-        try { remove(portClaimPath(registryDir, block), { force: true }); } catch { allReleased = false; }
+        try { JSON.parse(read(portClaimPath(registryDir, block), "utf8")); }
+        catch (error) { if (error?.code !== "ENOENT") return false; }
       }
+      try { withAllocationLock(registryDir, { writeExclusive, read, remove, now, alive, host, sleep }, () => {
+        for (const block of claimed) {
+          let current = null;
+          // A missing claim is released; unreadable/corrupt is unverifiable.
+          try { current = JSON.parse(read(portClaimPath(registryDir, block), "utf8")); } catch (error) { if (error?.code !== "ENOENT") allReleased = false; continue; }
+          if (current?.invocation_token !== invocationToken) continue; // never unlink a superseding claim
+          try {
+            if (!recordReleaseCooldown(registryDir, block, { write, rename: io.rename ?? renameSync, now, warn: io.warn ?? console.warn })) {
+              allReleased = false;
+              continue;
+            }
+            remove(portClaimPath(registryDir, block), { force: true });
+          } catch { allReleased = false; }
+        }
+      }); } catch { allReleased = false; }
       return allReleased;
     },
   };
@@ -1225,16 +1320,20 @@ function portClaimPath(registryDir, portBase) {
   return join(registryDir, `${portBase}.json`);
 }
 
-/** The first free block at or after the identity's own hash-derived one. */
-function selectPortBase(preferred, taken) {
+/** Prefer non-cooling free blocks in hash order; otherwise oldest release first. */
+function selectPortBase(preferred, taken, cooling = new Map()) {
   const start = Math.floor((preferred - LEASED_PORT_BASE) / LEASED_PORT_STRIDE);
+  let oldest = null;
   for (let i = 0; i < LEASED_PORT_SLOTS; i++) {
     const candidate = LEASED_PORT_BASE + ((start + i) % LEASED_PORT_SLOTS) * LEASED_PORT_STRIDE;
-    if (!taken.has(candidate)) return candidate;
+    if (taken.has(candidate)) continue;
+    if (!cooling.has(candidate)) return candidate;
+    if (oldest === null || cooling.get(candidate) < cooling.get(oldest)) oldest = candidate;
   }
+  if (oldest !== null) return oldest;
   throw new Error(
     `refusing to materialize an isolated leased stack: all ${LEASED_PORT_SLOTS} leased port blocks ` +
-      `(${LEASED_PORT_BASE}-${LEASED_PORT_BASE + LEASED_PORT_SLOTS * LEASED_PORT_STRIDE - 1}) are held by live or retained stacks. ` +
+      `(${LEASED_PORT_BASE}-${LEASED_PORT_BASE + LEASED_PORT_SLOTS * LEASED_PORT_STRIDE - 1}) are held by live or retained stacks or host listeners. ` +
       "Finish or reap a batch before starting another.",
   );
 }
@@ -1659,6 +1758,9 @@ export function materializeRunStackDir(cwd, { slot, ticket, nonce, idleTtlSecs }
   const previous = dirExisted ? readStackMarker(stackDir, read) : null;
   const previousBlock = previous?.project_id === identity.projectId && Number.isInteger(previous?.port_base) ? previous.port_base : null;
   const portBase = withAllocationLock(registryDir, { writeExclusive, read, remove, now, alive, host, sleep }, () => {
+    const listening = new Set(blocksForPorts((io.listeningPorts ?? listeningTcpPorts)()));
+    const cooling = releaseCooldowns(registryDir, { readdir, read, now });
+    const raced = new Set();
     let preferred = previousBlock ?? identity.portBase;
     for (let attempt = 0; attempt < LEASED_PORT_SLOTS; attempt++) {
       const stale = new Set();
@@ -1669,7 +1771,17 @@ export function materializeRunStackDir(cwd, { slot, ticket, nonce, idleTtlSecs }
       for (const block of stale) {
         try { remove(portClaimPath(registryDir, block), { force: true }); } catch { /* best effort */ }
       }
-      const candidate = selectPortBase(preferred, taken);
+      // A running stack necessarily owns listeners. Only this exact retained
+      // invocation may re-adopt its block; a merely matching project is not proof.
+      let own = null;
+      try { own = JSON.parse(read(portClaimPath(registryDir, preferred), "utf8")); } catch { /* new allocation */ }
+      if (own?.invocation_token === invocationToken && own.project_id === identity.projectId) {
+        write(portClaimPath(registryDir, preferred), marker(preferred));
+        return preferred;
+      }
+      for (const block of listening) if (!taken.has(block)) taken.set(block, { projectId: "host TCP listener" });
+      for (const block of raced) if (!taken.has(block)) taken.set(block, { projectId: "exclusive claim collision" });
+      const candidate = selectPortBase(preferred, taken, cooling);
       try {
         writeExclusive(portClaimPath(registryDir, candidate), marker(candidate));
         return candidate;
@@ -1686,6 +1798,7 @@ export function materializeRunStackDir(cwd, { slot, ticket, nonce, idleTtlSecs }
           write(portClaimPath(registryDir, candidate), marker(candidate));
           return candidate;
         }
+        raced.add(candidate); // cooldown ordering must not select this collision again
         preferred = candidate + LEASED_PORT_STRIDE; // a peer won this one
       }
     }

package/src/stack-tunnel.mjs

@@ -286,6 +286,7 @@ export async function openSshForwards({
   }
   return {
     pid: child.pid,
+    isLive: () => !exited && !closing,
     argv,
     exited: exitPromise,
     onExit: (fn) => { listeners.push(fn); if (exited && !closing) fn({ ...exited, stderr: stderrText() }); },

package/src/stack.mjs

@@ -49,6 +49,7 @@ import { checkReadoptedStackMounts } from "./stack-mount-health.mjs";
 import { machineUuid } from "./machine-id.mjs";
 import { DEFAULT_BUNDLE_MAX_BYTES, buildStackBundle, uploadStackBundle, validateBundleIncludePath } from "./stack-bundle.mjs";
 import { assertSshTarget, establishSshTunnel } from "./stack-tunnel.mjs";
+import { FORWARD_ATTESTATION_ENV, startForwardAttestation, readForwardAttestation } from "./stack-forward-attestation.mjs";
 import { ENGINE_PUBLISHES_BEYOND_LOOPBACK, engineSocketIsLocal, formatPublishIp, isLoopbackIp, publishIpFix, resolvePublishIp } from "./docker-publish-ip.mjs";
 import { bold, dim, yellow } from "./utils.mjs";
 import { reportStackRunOutcome } from "./stack-run-outcome.mjs";
@@ -108,7 +109,8 @@ export const STACK_HELP = `${bold("botbuddy stack")} — one command for a batch
 
 ${bold("USAGE")}
   botbuddy stack up [options]        Request a lease; park if the host is full; hold it active
-  botbuddy stack status <lease_id>   Show a lease's state + connection
+  botbuddy stack status <lease_id>   Show a lease's state + connection; within a live remote run,
+                                   include the owner's attested local/remote forwards
   botbuddy stack touch  <lease_id>   Bump the idle clock (and report measured use) so the reaper doesn't stop it
   botbuddy stack done   <lease_id>   Release (done): idle the stack for re-adoption (--reap tears it down)
   botbuddy stack cancel <lease_id>   Give a queued lease's place up (= done --reap; BOT-2400)
@@ -2960,6 +2962,7 @@ export async function cmdUp(opts, {
 
 export async function cmdStatus(leaseId, opts, {
   rpc = retryingStackCall(), emitResult = emit, stderr = (line) => process.stderr.write(`${line}\n`),
+  forwardSocket = process.env[FORWARD_ATTESTATION_ENV],
 } = {}) {
   const auth = await rpc.init();
   if (!auth) return emitResult(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
@@ -2969,6 +2972,14 @@ export async function cmdStatus(leaseId, opts, {
     : emitResult(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, error: got.error }), opts, EXIT.BACKEND);
   const g = got.data;
   if (!g.success) return emitResult(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, code: g.code, error: g.code }), opts, EXIT.BACKEND);
+  let forwards;
+  if (g.state === "active" && forwardSocket) {
+    try {
+      forwards = await readForwardAttestation({ socketPath: forwardSocket, leaseId, sshTarget: g.connection?.ssh_target ?? g.ssh_target });
+    } catch {
+      return emitResult(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, code: "FORWARD_ATTESTATION_UNAVAILABLE", error: "live stack forward attestation unavailable" }), opts, EXIT.BACKEND);
+    }
+  }
   // BOT-2019: a queued lease names its server dispatch rank (or why it has none) and the
   // ticket it is scored under; a null position is reported, never a crash.
   const queued = g.state === "queued";
@@ -2976,7 +2987,9 @@ export async function cmdStatus(leaseId, opts, {
   if (queued) for (const line of describeUnitLedger(g.ledger)) stderr(`stack: ${line}`);
   return emitResult(buildReceipt({
     command: "status", outcome: g.state, lease_id: leaseId, state: g.state,
-    host_key: g.host_key, slot: g.slot, connection: g.connection,
+    host_key: g.host_key, slot: g.slot,
+    connection: forwards ? { ...g.connection, ssh_target: g.connection?.ssh_target ?? g.ssh_target } : g.connection,
+    ...(forwards ? { forwards } : {}),
     ...(queued ? queueReceiptFields(g) : { queue_position: g.queue_position }),
     idle_ttl_secs: g.idle_ttl_secs, queued: g.queued,
     // BOT-2099 (Codex #1057 R3): machine callers get the unit ledger of a queued lease too.
@@ -3621,6 +3634,7 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   let activeWaitAbort = null;
   // BOT-2142: the remote lease's forwards, and whether they died under a running child.
   let tunnel = null;
+  let forwardAttestation = null;
   let tunnelLost = null;
   const placement = { mode: null, hostKey: null, requesterHost: null, transport: "none", forwards: null, bundle: null, placementReason: null, considered: null };
   incidentBox.execution = placement;
@@ -3633,10 +3647,19 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
   // BOT-1803: a heartbeat touch found the lease preempted under the running child.
   let preempted = null;
   const closeTunnel = async () => {
-    if (!tunnel) return;
-    const open = tunnel;
-    tunnel = null;
-    try { await open.close(); } catch { /* best effort: the process is gone either way */ }
+    try {
+      if (forwardAttestation) {
+        const owner = forwardAttestation;
+        forwardAttestation = null;
+        await owner.close();
+      }
+    } finally {
+      if (tunnel) {
+        const open = tunnel;
+        tunnel = null;
+        try { await open.close(); } catch { /* best effort: the process is gone either way */ }
+      }
+    }
   };
 
   // BOT-1803: `idle` (only the normal end of a run) asks the server to idle the ACTIVE lease
@@ -3777,7 +3800,10 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       // A slot whose stack another live batch owns is a coordination refusal (the
       // same class as the server's duplicate-lease rejection), not bad arguments.
       const exitCode = error?.code === "stack_slot_busy" ? EXIT.BACKEND : EXIT.INVALID;
-      return { exitCode, outcome: "error", error: String(error?.message ?? error) };
+      // BOT-2490: retain listener/cooldown refusals in the existing public code field;
+      // keep the exit mapping and unrelated local-error semantics unchanged.
+      const code = ["stack_port_census_failed", "stack_port_cooldown_failed"].includes(error?.code) ? error.code : null;
+      return { exitCode, outcome: "error", ...(code ? { code } : {}), error: String(error?.message ?? error) };
     }
     // BOT-1798 (Codex #928 R13 P2): the queue and provisioning waits can outlast the
     // directory's initial retention, and a kill during them leaves a lease the
@@ -4349,13 +4375,17 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       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;
+      childConnection = { ...tunnel.connection, ssh_target: sshTarget };
       const forwardTarget = sshTarget;
       tunnel.onExit((exit) => {
         if (childResult) return;
         tunnelLost = { ...exit, target: forwardTarget };
         stopChild("SIGTERM", EXIT.LEASE_FAILED);
       });
+      forwardAttestation = await startForwardAttestation({
+        leaseId, sshTarget, forwards: placement.forwards,
+        isLive: () => Boolean(tunnel && !tunnelLost && !receivedSignal && tunnel.isLive()),
+      });
     }
     connectionFile = await writeConnection(safeConnectionPath(opts.connectionFile, leaseId), childConnection);
     if (receivedSignal) {
@@ -4373,6 +4403,8 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       ...process.env,
       BOTBUDDY_STACK_LEASE_ID: leaseId,
       BOTBUDDY_STACK_CONNECTION_FILE: connectionFile,
+      // A nested co-located run must not inherit its parent's capability.
+      [FORWARD_ATTESTATION_ENV]: forwardAttestation?.socketPath ?? "",
       // 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: servedRemote ? "remote" : (placement.mode ?? "local"),