@botbuddy/cli 1.64.24 → 1.64.26

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.64.26
+
+- `bb stack run --remote` (and auto runs placed remotely) never binds a local port in the leased serving band 61000–64999 any more. SSH forwards whose remote number falls in that band are remapped to a port outside it, remapped and probe ports are picked from explicit out-of-band candidates instead of the kernel's ephemeral range, and the requester origin and native callback gateway are reserved outside the band too. A `--callback-port` inside the band is refused with `CALLBACK_PORT_RESERVED` before anything is probed or spawned. This stops a remote lease's tunnel from taking ports a co-located stack on the same machine was just given.
+
+## 1.64.25
+
+- `bb pw` staging-pool takes now durably queue a secret-free, server-attributed telemetry receipt before a browser receives the single-use session. The receipt never includes the state file, path, credential, or caller-selected tenant/session/ticket/PR; a successor session reconciles an undelivered receipt under its verified source-session attribution.
+
 ## 1.64.20
 
 - Session checkpoint writes are deprecated. Keep delivery and acceptance evidence on the Linear ticket; the compatibility MCP tool returns a deprecation notice without writing a checkpoint.

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.64.24",
-  "source_commit": "7bfc909b46cc2bf6f7d45264be7e52ca16e69e13",
-  "source_sha256": "680b44125605dea4db83af948177743740b848b08f26619329e949e5a2e6253a",
+  "release_version": "1.64.26",
+  "source_commit": "3c0c0a5b3043740906a1d230d2e52bfb040af538",
+  "source_sha256": "37ab46e615c285d102088320e3106cbc968d5c42f345e48051980173eaeffba2",
   "target": "darwin-arm64",
-  "sha256": "554e01cb52c8966c4946b467858873733afadc9f645e7add1598098bc7ec7b98"
+  "sha256": "1c61bc84457da670166622fe9ef8fc7295a1f2286591e7cb8850aed78023858b"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.64.24",
-  "source_commit": "7bfc909b46cc2bf6f7d45264be7e52ca16e69e13",
-  "source_sha256": "680b44125605dea4db83af948177743740b848b08f26619329e949e5a2e6253a",
+  "release_version": "1.64.26",
+  "source_commit": "3c0c0a5b3043740906a1d230d2e52bfb040af538",
+  "source_sha256": "37ab46e615c285d102088320e3106cbc968d5c42f345e48051980173eaeffba2",
   "target": "linux-x64",
-  "sha256": "01533501078482e1ac720ba05cd763c6f4196831ad55c6c15dcf5e8dda30d459"
+  "sha256": "718ad319db010d21e1ac51da283f7d64d2cd9c9313abbc16912d1e560426be2e"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.64.24",
-  "source_commit": "7bfc909b46cc2bf6f7d45264be7e52ca16e69e13",
-  "source_sha256": "680b44125605dea4db83af948177743740b848b08f26619329e949e5a2e6253a",
+  "release_version": "1.64.26",
+  "source_commit": "3c0c0a5b3043740906a1d230d2e52bfb040af538",
+  "source_sha256": "37ab46e615c285d102088320e3106cbc968d5c42f345e48051980173eaeffba2",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "554e01cb52c8966c4946b467858873733afadc9f645e7add1598098bc7ec7b98",
+      "sha256": "1c61bc84457da670166622fe9ef8fc7295a1f2286591e7cb8850aed78023858b",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "01533501078482e1ac720ba05cd763c6f4196831ad55c6c15dcf5e8dda30d459",
+      "sha256": "718ad319db010d21e1ac51da283f7d64d2cd9c9313abbc16912d1e560426be2e",
       "mode": "0755"
     }
   }

package/package.json

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

package/src/pw/staging-auth.mjs

@@ -297,7 +297,7 @@ async function requestPoolRefill({ ctxPool, persona, deps, env }) {
  * lock-gated lane held by this exact agent, and a staging (or untracked) browser
  * session. Returns the process exit code.
  */
-export async function runStagingAuth({ plan, host, env, deps, socketRun, resolveSession, stdout, stderr, holder = null }) {
+export async function runStagingAuth({ plan, host, env, deps, socketRun, resolveSession, stdout, stderr, holder = null, credential = null }) {
   const io = { stdout, stderr };
   const poolModule = deps.stagingPoolModule ?? await loadPool();
   const poolOptions = deps.stagingPool ?? {};
@@ -342,7 +342,13 @@ export async function runStagingAuth({ plan, host, env, deps, socketRun, resolve
   dropGone(ctx, generation);
   let claim;
   try {
-    claim = await poolModule.takeForLane({ persona: persona.email, owner: `lane-${plan.lane}@${host}`, poolId: ctxPool.poolId, tenantHint, ...poolOptions });
+    // The outbox writer is a child `bb call`; carry the gate-verified session
+    // credential into that child so it cannot select a cached/durable identity.
+    const sessionId = credential?.sessionId ?? env.BOTBUDDY_SESSION_ID;
+    const deliveryEnv = credential?.token
+      ? { ...env, BOTBUDDY_AGENT_SESSION_TOKEN: credential.token, BOTBUDDY_SESSION_ID: sessionId }
+      : env;
+    claim = await poolModule.takeForLane({ persona: persona.email, owner: `lane-${plan.lane}@${host}`, poolId: ctxPool.poolId, tenantHint, ...poolOptions, env: deliveryEnv, sessionId });
   } catch (error) {
     if (error?.code === "pool_empty") {
       const refill = await requestPoolRefill({ ctxPool, persona: persona.email, deps, env });

package/src/stack-callback-gateway.mjs

@@ -3,11 +3,14 @@
 import {createServer, request} from 'node:http';
 import {createHash,createHmac, timingSafeEqual} from 'node:crypto';
 import {Transform} from 'node:stream';
+import {TUNNEL_PORT_PICKS,admissibleTunnelPort,randomTunnelPort} from './stack-tunnel.mjs';
 export const CALLBACK_CAP_HEADER='x-botbuddy-callback-capability';
 const digest=value=>createHash('sha256').update(value).digest();
 export const CALLBACK_MAX_STREAM_BYTES=32*1024*1024;
 const sameBinding=(a,b)=>b&&typeof b==='object'&&Object.keys(a).length===Object.keys(b).length&&Object.keys(a).every(key=>a[key]===b[key]);
-export async function openCallbackGateway({callbackPort,binding,capability,lifetimeMs=30_000,now=Date.now,activate=true,readinessNonce=null}){
+// One listen attempt; both one-shot listeners are removed whichever fires, so retries never pile up.
+const listenOnce=(server,port)=>new Promise((resolve,reject)=>{const onError=error=>{server.off('listening',onListening);reject(error)};const onListening=()=>{server.off('error',onError);resolve()};server.once('error',onError);server.once('listening',onListening);server.listen(port,'127.0.0.1');});
+export async function openCallbackGateway({callbackPort,binding,capability,lifetimeMs=30_000,now=Date.now,activate=true,readinessNonce=null,pickPort=randomTunnelPort}){
  if(!Number.isInteger(callbackPort)||callbackPort<1024||callbackPort>65535||!binding||typeof binding!=='object'||!Object.isFrozen(binding)||typeof capability!=='string'||!/^[0-9a-f]{64}$/.test(capability)||lifetimeMs<1||lifetimeMs>30_000)throw Error('callback gateway admission refused');
  if(readinessNonce!==null&&!/^[0-9a-f]{32}$/.test(readinessNonce))throw Error('callback readiness identity refused');
  const bootstrapDeadline=now()+30_000,readinessPath=readinessNonce?'/.botbuddy/callback-ready/'+readinessNonce:null;
@@ -38,7 +41,13 @@ export async function openCallbackGateway({callbackPort,binding,capability,lifet
  const denySocket=(_req,socket)=>socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');server.on('connect',denySocket);server.on('upgrade',denySocket);
  let closePromise;const close=()=>{if(closePromise)return closePromise;closed=true;clearTimeout(timer);for(const controller of active)controller.abort();active.clear();server.closeAllConnections();closePromise=new Promise(resolve=>server.close(resolve));for(const listener of closeListeners)listener();return closePromise;};
  const refresh=(current,validForMs=lifetimeMs)=>{let matches=false;try{matches=sameBinding(binding,current)}catch{}if(closed||!matches||!Number.isFinite(validForMs)||validForMs<=0||validForMs>lifetimeMs){close();throw Error('callback binding changed');}deadline=now()+validForMs;clearTimeout(timer);timer=setTimeout(close,validForMs);timer.unref();};
- await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(0,'127.0.0.1',resolve);});
+ // BOT-2503: an explicit port outside the leased serving band, never listen(0) (its kernel range covers it).
+ let bound=false;
+ for(let tries=0;!bound&&tries<TUNNEL_PORT_PICKS;tries++){
+  const port=pickPort();if(!admissibleTunnelPort(port)||port===callbackPort)continue;
+  try{await listenOnce(server,port);bound=true}catch(error){if(error.code!=='EADDRINUSE'){close();throw error}}
+ }
+ if(!bound){close();throw Error('callback gateway could not bind a port outside the leased serving band');}
  if(activate)refresh(binding);else{timer=setTimeout(close,30_000);timer.unref();}
  return {port:server.address().port,refresh,close,onClose(listener){closeListeners.add(listener);if(closed)listener()},isLive:()=>!closed&&now()<deadline};
 }

package/src/stack-requester-origin.mjs

@@ -2,6 +2,7 @@
 // The CLI later binds it to exactly one API port on its owned SSH tunnel. This
 // listener is not itself an SSH forward and never supplies forward attestation.
 import {createServer,connect} from 'node:net';
+import {TUNNEL_PORT_PICKS,admissibleTunnelPort,inServingBand,randomTunnelPort} from './stack-tunnel.mjs';
 
 const fail=(code,message)=>{const error=Error(message);error.code=code;throw error};
 const validPort=value=>Number.isInteger(value)&&value>=1024&&value<=65535;
@@ -16,8 +17,13 @@ function apiPort(value){
  if(url.protocol!=='http:'||url.hostname!=='127.0.0.1'||url.username||url.password||url.pathname!=='/'||url.search||url.hash||!validPort(Number(url.port)))fail('REQUESTER_ORIGIN_FORWARD_REFUSED','API target must be the owned loopback HTTP endpoint');
  return Number(url.port);
 }
-export async function reserveRequesterOrigin({context,port=0}={}){
+// BOT-2503: port 0 means "pick one": explicit candidates outside the leased serving band,
+// never listen(0), whose kernel range covers it. An explicit serving-band port is refused
+// with REQUESTER_ORIGIN_PORT_RESERVED before anything binds.
+// avoidPorts: local numbers a caller's own service will bind later (the callback port), never picked.
+export async function reserveRequesterOrigin({context,port=0,pickPort=randomTunnelPort,avoidPorts=[]}={}){
  const snapshot=contextSnapshot(context);if(port!==0&&!validPort(port))fail('REQUESTER_ORIGIN_PORT_REFUSED','requester origin port refused');
+ if(port!==0&&inServingBand(port))fail('REQUESTER_ORIGIN_PORT_RESERVED','requester origin port is in the leased serving band');
  const sockets=new Set(),lossListeners=new Set();let route,closed=false,lostCode,closePromise;
  const live=()=>{try{return !closed&&route?.isLive()===true}catch{return false}};
  const close=code=>{
@@ -41,7 +47,15 @@ export async function reserveRequesterOrigin({context,port=0}={}){
   });
  });
  server.maxConnections=64;
- try{await new Promise((resolve,reject)=>{server.once('error',reject);server.listen({host:'127.0.0.1',port,exclusive:true},resolve)})}catch(error){await close();fail(error.code==='EADDRINUSE'?'REQUESTER_ORIGIN_PORT_BUSY':'REQUESTER_ORIGIN_BIND_FAILED','requester origin could not be reserved')}
+ const listenOn=candidate=>new Promise((resolve,reject)=>{const onError=error=>{server.off('listening',onListening);reject(error)};const onListening=()=>{server.off('error',onError);resolve()};server.once('error',onError);server.once('listening',onListening);server.listen({host:'127.0.0.1',port:candidate,exclusive:true})});
+ const avoid=new Set(avoidPorts.map(Number));
+ let bound=false;
+ for(let tries=0;!bound&&tries<(port!==0?1:TUNNEL_PORT_PICKS);tries++){
+  const candidate=port!==0?port:pickPort();
+  if(!admissibleTunnelPort(candidate)||!validPort(candidate)||(port===0&&avoid.has(candidate)))continue;
+  try{await listenOn(candidate);bound=true}catch(error){if(port!==0||error.code!=='EADDRINUSE'){await close();fail(error.code==='EADDRINUSE'?'REQUESTER_ORIGIN_PORT_BUSY':'REQUESTER_ORIGIN_BIND_FAILED','requester origin could not be reserved')}}
+ }
+ if(!bound){await close();fail('REQUESTER_ORIGIN_PORT_BUSY','requester origin could not be reserved outside the leased serving band')}
  const boundPort=server.address().port;server.on('error',()=>{void close('REQUESTER_ORIGIN_BIND_FAILED')});
  return{
   origin:'http://127.0.0.1:'+boundPort,

package/src/stack-tunnel.mjs

@@ -11,8 +11,10 @@
 //
 // 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);
+//   * a free local port keeps the remote number, a busy one gets a fresh port
+//     (the remap table is returned and lands on the receipt) — except that no
+//     tunnel listener, local or on the host, ever lands in the leased serving band
+//     (BOT-2503), so a serving-band remote number is always remapped;
 //   * `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
@@ -24,6 +26,42 @@
 import { spawn, spawnSync } from "node:child_process";
 import { connect, createServer, isIP } from "node:net";
 import { canonicalStackPorts, stackServicesForForwards } from "./stack-service-discovery.mjs";
+import { LEASED_PORT_BASE, LEASED_PORT_SLOTS, LEASED_PORT_STRIDE } from "./stack-isolation.mjs";
+
+/**
+ * BOT-2503: the band the CLI's local block chooser hands to co-located leased stacks
+ * (stack-isolation.mjs). A block is reserved before its containers listen, so a listener this
+ * module creates inside it — a forward keeping its remote number, a kernel-picked ephemeral
+ * port, a probe port — could take a port the co-located `supabase start` then fails to bind.
+ * Nothing the tunnel binds, locally or on the host, may fall in [START, END).
+ */
+export const SERVING_BAND_START = LEASED_PORT_BASE;
+export const SERVING_BAND_END = LEASED_PORT_BASE + LEASED_PORT_SLOTS * LEASED_PORT_STRIDE;
+export const inServingBand = (port) => Number(port) >= SERVING_BAND_START && Number(port) < SERVING_BAND_END;
+
+/**
+ * Where the tunnel picks ports itself (remapped forwards, the probe's host port and its held local
+ * port): explicit candidates the kernel never chooses for us, so nothing is filtered after a bind.
+ * Below the band, above Supply Guard's per-ticket blocks (56321 + n×10, n ≤ 399 → ≤ 60330); above
+ * it, the top of the port space. Other bands are listed in stack-isolation.mjs.
+ */
+export const TUNNEL_PORT_RANGES = Object.freeze([Object.freeze([60340, 60999]), Object.freeze([65000, 65535])]);
+/** Candidate selection is bounded: at most this many picks per port the tunnel needs. */
+export const TUNNEL_PORT_PICKS = 20;
+
+/** A port the tunnel may bind: a valid integer TCP port outside the serving band. */
+export const admissibleTunnelPort = (port) => Number.isInteger(port) && port > 0 && port <= 65535 && !inServingBand(port);
+
+/** A uniformly random port from TUNNEL_PORT_RANGES. */
+export function randomTunnelPort(random = Math.random) {
+  const total = TUNNEL_PORT_RANGES.reduce((sum, [lo, hi]) => sum + hi - lo + 1, 0);
+  let offset = Math.min(Math.floor(random() * total), total - 1);
+  for (const [lo, hi] of TUNNEL_PORT_RANGES) {
+    if (offset <= hi - lo) return lo + offset;
+    offset -= hi - lo + 1;
+  }
+  return TUNNEL_PORT_RANGES[0][0];
+}
 
 export const SSH_FORWARD_OPTIONS = Object.freeze([
   "-N", "-T",
@@ -91,11 +129,23 @@ function validPort(value) {
   return Number.isInteger(n) && n > 0 && n <= 65535 ? n : null;
 }
 
+/** BOT-2503: `-R` binds the callback number on the host and the caller's service holds it here,
+ * so a serving-band callback port is refused — never silently renumbered under its service. */
+function assertCallbackPortAdmissible(callbackPort) {
+  if (validPort(callbackPort) != null && inServingBand(callbackPort)) {
+    throw tunnelError("CALLBACK_PORT_RESERVED",
+      `--callback-port ${callbackPort} is inside the leased serving band ${SERVING_BAND_START}-${SERVING_BAND_END - 1}, where co-located stacks bind. ` +
+        `Serve the callback on a port outside that band (for example ${TUNNEL_PORT_RANGES[0][0]}-${TUNNEL_PORT_RANGES[0][1]}) and pass that port.`);
+  }
+}
+
 /** Every stack port the child may touch: api + db always, then `connection.ports[]`. */
 export function remotePortsFromConnection(connection) { return canonicalStackPorts(connection); }
 
-/** True when 127.0.0.1:<port> can be bound right now. */
+/** True when 127.0.0.1:<port> can be bound right now. A serving-band or invalid port is never
+ * free to the tunnel, and is not bound to find out (BOT-2503). */
 export function isLocalPortFree(port) {
+  if (!admissibleTunnelPort(port)) return Promise.resolve(false);
   return new Promise((resolve) => {
     const server = createServer();
     server.once("error", () => resolve(false));
@@ -103,31 +153,27 @@ export function isLocalPortFree(port) {
   });
 }
 
-/** 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));
-    });
-  });
+/** One explicit out-of-band candidate, returned when 127.0.0.1 can bind it right now, else null.
+ * Never listen(0): the kernel's ephemeral range covers the serving band (BOT-2503). */
+export async function pickFreeLocalPort({ random = Math.random, isFree = isLocalPortFree } = {}) {
+  const candidate = randomTunnelPort(random);
+  return await isFree(candidate) ? candidate : null;
 }
 
 /**
- * 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.
+ * Decide each forward's local port: the remote number when it is outside the serving band, free
+ * and not in `avoid`, otherwise a fresh out-of-band port (at most TUNNEL_PORT_PICKS picks; an
+ * invalid, in-band, used or avoided pick is discarded). 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++) {
+    if (admissibleTunnelPort(port) && !avoid.has(port) && !used.has(port) && await isFree(port)) local = port;
+    for (let tries = 0; local == null && tries < TUNNEL_PORT_PICKS; tries++) {
       const candidate = await pickFree();
-      if (!used.has(candidate) && !avoid.has(candidate)) local = candidate;
+      if (admissibleTunnelPort(candidate) && !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);
@@ -140,6 +186,16 @@ export async function planForwards(remotePorts, { isFree = isLocalPortFree, pick
 export function buildSshForwardArgv({ sshTarget, forwards, callbackPort = null }) {
   // `-v` only with a callback forward: OpenSSH then logs whether the host GRANTED this session's
   // `-R` (see openSshForwards `confirmRemoteForward`).
+  // BOT-2503: the last line before ssh binds anything — a caller that skipped planForwards still
+  // cannot bind into the serving band. Remote destinations are the stack's own ports, unchanged.
+  if (callbackPort != null) assertCallbackPortAdmissible(callbackPort);
+  for (const f of forwards) {
+    if (!admissibleTunnelPort(f.local) || validPort(f.remote) == null) {
+      throw tunnelError("REMOTE_UNREACHABLE",
+        `refusing to forward ${f.name ?? "a stack port"} from local port ${f.local}: a tunnel never binds an invalid port or one in the ` +
+          `leased serving band ${SERVING_BAND_START}-${SERVING_BAND_END - 1}`);
+    }
+  }
   const argv = [...(callbackPort != null ? ["-v"] : []), ...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", `${REVERSE_BIND}:${callbackPort}:127.0.0.1:${callbackPort}`);
@@ -336,9 +392,10 @@ export function verifyCallbackLoopback({ sshBin, sshTarget, port, env = process.
 }
 
 
-/** A random throwaway port in the dynamic range (49152–65535) for the GatewayPorts probe. */
+/** A random throwaway host port for the GatewayPorts probe, outside the serving band (BOT-2503:
+ * the serving host runs leased stacks in that band too). */
 export function randomProbePort(random = Math.random) {
-  return 49152 + Math.floor(random() * (65535 - 49152 + 1));
+  return randomTunnelPort(random);
 }
 
 const REMOTE_FORWARD_BUSY = /remote port forwarding failed|address already in use|cannot listen/i;
@@ -349,11 +406,27 @@ export const DEFAULT_PROBE_READY_MS = 10_000;
  * a listener that closes every connection without a byte — so no other local service can bind it
  * while a (possibly wildcard) probe listener on the host forwards there. Resolves { port, close }.
  */
-export function holdSilentLocalPort() {
+export async function holdSilentLocalPort({ pickPort = randomTunnelPort, listen = listenSilent } = {}) {
+  // BOT-2503: an explicit out-of-band port, never listen(0); a lost bind race picks again.
+  for (let tries = 0; tries < TUNNEL_PORT_PICKS; tries++) {
+    const port = pickPort();
+    if (!admissibleTunnelPort(port)) continue;
+    try {
+      return await listen(port);
+    } catch (error) {
+      if (error?.code !== "EADDRINUSE") throw error;
+    }
+  }
+  throw tunnelError("CALLBACK_NOT_LOOPBACK",
+    `the GatewayPorts probe could not hold a local port outside the serving band after ${TUNNEL_PORT_PICKS} picks, so no -R for ` +
+      "--callback-port was opened.");
+}
+
+function listenSilent(port) {
   return new Promise((resolve, reject) => {
     const server = createServer((socket) => socket.destroy());
     server.once("error", reject);
-    server.listen({ host: "127.0.0.1", port: 0, exclusive: true }, () => {
+    server.listen({ host: "127.0.0.1", port, exclusive: true }, () => {
       resolve({ port: server.address().port, close: () => new Promise((done) => server.close(() => done())) });
     });
   });
@@ -380,8 +453,13 @@ export async function probeGatewayPorts({
   const tried = new Set();
   let busyTail = "";
   for (let attempt = 1; attempt <= attempts; attempt++) {
-    let port = pickProbePort();
-    for (let i = 0; tried.has(port) && i < 20; i++) port = pickProbePort();
+    // BOT-2503: an invalid or serving-band pick never reaches ssh; at most TUNNEL_PORT_PICKS picks.
+    let port = null;
+    for (let i = 0; port == null && i < TUNNEL_PORT_PICKS; i++) {
+      const pick = pickProbePort();
+      if (admissibleTunnelPort(pick) && !tried.has(pick)) port = pick;
+    }
+    if (port == null) { busyTail = `no admissible probe port outside the serving band in ${TUNNEL_PORT_PICKS} picks`; continue; }
     tried.add(port);
     // P must be free on the host BEFORE the probe, or a listener seen afterwards could be someone
     // else's (a loopback one would pass a host that would expose ours). Taken → another port.
@@ -474,6 +552,11 @@ export async function establishSshTunnel({
   runRemote = spawnSync, probe = probeGatewayPorts, probeReadyTimeoutMs = DEFAULT_PROBE_READY_MS,
 }) {
   const target = assertSshTarget(sshTarget, hostKey);
+  // BOT-2503: before any probe, availability check or spawn.
+  if (callbackPort != null) assertCallbackPortAdmissible(callbackPort);
+  // The native callback route (BOT-2775) passes the caller's callback port here instead: its
+  // service holds that number on this machine, so it is refused in the band the same way.
+  for (const port of reserveLocalPorts) assertCallbackPortAdmissible(port);
   const remotePorts = remotePortsFromConnection(connection);
   const bin = sshBin || env.BOTBUDDY_STACK_SSH_BIN || "ssh";
   // BOT-2184: prove the host keeps -R listeners on loopback BEFORE the real callback forward

package/src/stack.mjs

@@ -271,7 +271,8 @@ ${bold("run OPTIONS")}
                          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").
+                         on the LOCAL ports (same numbers when free and outside the leased
+                         serving band 61000-64999, 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.
@@ -1079,18 +1080,24 @@ export async function resolveRunExecution(cwd, opts, { materialize = materialize
       // same. A busy port is never retargeted: a new origin makes a new variant, which the
       // control plane reprovisions through its canonical reap instead of re-adopting.
       previousPort = nonce == null ? idleOriginPort(worktreeRoot, stableDir) : null;
+      // BOT-2503: the caller's callback service binds --callback-port later; an origin never takes it.
+      const originAvoid = opts.callbackPort != null ? [opts.callbackPort] : [];
       if (previousPort != null) {
         try {
-          requesterOrigin = await reserveOrigin({ context: originContext, port: previousPort });
+          requesterOrigin = await reserveOrigin({ context: originContext, port: previousPort, avoidPorts: originAvoid });
           originContinuation = "previous";
         } catch (error) {
-          if (error?.code !== "REQUESTER_ORIGIN_PORT_BUSY") throw error;
-          originContinuation = "previous_port_busy";
-          warn(`stack: the idle stack's requester origin 127.0.0.1:${previousPort} is in use on this machine; reserving a new origin (the idle stack is reprovisioned, never retargeted)`);
+          // BOT-2503: an origin left in the leased serving band (by a CLI before this guard) is
+          // treated like a busy one: a new origin, and the idle stack is reprovisioned.
+          if (error?.code !== "REQUESTER_ORIGIN_PORT_BUSY" && error?.code !== "REQUESTER_ORIGIN_PORT_RESERVED") throw error;
+          originContinuation = error.code === "REQUESTER_ORIGIN_PORT_RESERVED" ? "previous_port_reserved" : "previous_port_busy";
+          warn(error.code === "REQUESTER_ORIGIN_PORT_RESERVED"
+            ? `stack: the idle stack's requester origin 127.0.0.1:${previousPort} is in the leased serving band; reserving a new origin (the idle stack is reprovisioned, never retargeted)`
+            : `stack: the idle stack's requester origin 127.0.0.1:${previousPort} is in use on this machine; reserving a new origin (the idle stack is reprovisioned, never retargeted)`);
         }
       }
       if (!requesterOrigin) {
-        requesterOrigin = await reserveOrigin({ context: originContext });
+        requesterOrigin = await reserveOrigin({ context: originContext, avoidPorts: originAvoid });
         originContinuation ??= "new";
       }
       // Validate the source config before anything is materialized: an explicit conflicting
@@ -5330,7 +5337,7 @@ export function runReceiptFields(result) {
     ...(result.callbackOutage ? { callback_outage: result.callbackOutage } : {}),
     // BOT-2780: the reserved requester origin generated auth links name (never a credential).
     ...(result.execution?.requesterOrigin ? { requester_origin: result.execution.requesterOrigin } : {}),
-    // BOT-2788: "previous" (an idle stack's origin re-reserved), "previous_port_busy" or "new".
+    // BOT-2788: "previous" (an idle stack's origin re-reserved), "previous_port_busy", "previous_port_reserved" (BOT-2503: in the serving band) or "new".
     ...(result.execution?.requesterOriginContinuation ? { requester_origin_continuation: result.execution.requesterOriginContinuation } : {}),
     ...(result.allocationRecovery ? { allocation_recovery: result.allocationRecovery } : {}),
     ...(result.execution?.forwards ? { forwards: result.execution.forwards } : {}),

package/src/staging-pool/cli.mjs

@@ -20,6 +20,7 @@
 // runs that copy).
 
 import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
 import * as nodeFs from "node:fs/promises";
 import { readFileSync, readdirSync, realpathSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
@@ -41,6 +42,7 @@ import { HUMAN_ONLY_COMMANDS, formatGuidance, guidance, installLine, isKnownCode
 import { RegistryError, choosePool, fetchRegisteredPools, whoamiTenant } from "./registry.mjs";
 import { STAGING_POOL_HELP } from "./help.mjs";
 import { refreshExistingRuntime } from "./refresh-runtime.mjs";
+import { enqueueStagingPoolTake, flushStagingPoolTakeOutbox, STAGING_POOL_TAKE_OUTBOX_MAX } from "./take-outbox.mjs";
 
 export const BUNDLE_FILES = Object.freeze([
   "binding.mjs",
@@ -58,6 +60,7 @@ export const BUNDLE_FILES = Object.freeze([
   "refresh-runtime.mjs",
   "signin-gotrue-totp.mjs",
   "state-file.mjs",
+  "take-outbox.mjs",
   "totp-botbuddy.mjs",
 ]);
 
@@ -263,6 +266,8 @@ export async function takeForLane({
   fetchImpl = globalThis.fetch,
   exec = promisify(execFile),
   uid = userInfo().uid,
+  env = process.env,
+  sessionId = env.BOTBUDDY_SESSION_ID,
   logger = () => {},
 } = {}) {
   const ctx = resolveInstalledPool({ home, poolId, tenantHint });
@@ -271,8 +276,44 @@ export async function takeForLane({
   if (!entry) assertPersonaAllowed(target, persona);
   const intervalSeconds = ctx.installed && !ctx.installed.error ? ctx.installed.intervalSeconds : undefined;
   const pool = buildPool({ ctx, target, now, logger, intervalSeconds, fetchImpl });
+  // Re-deliver earlier durable receipts before admitting another take. Otherwise
+  // a temporary MCP outage could fill the bounded outbox permanently even after
+  // the control plane recovers.
+  const priorDelivery = await flushStagingPoolTakeOutbox({
+    poolDir: ctx.paths.pool,
+    botbuddyBin: ctx.installed.botbuddyBin,
+    exec,
+    env,
+    sessionId,
+  });
+  if (priorDelivery.pending >= STAGING_POOL_TAKE_OUTBOX_MAX) {
+    throw Object.assign(new Error("The staging-pool take telemetry outbox is full; no session was handed over."), { code: "take_outbox_full" });
+  }
   try {
     const taken = await pool.take({ persona: entry.email, owner });
+    try {
+      // Persist before handing the browser its state. An unavailable control
+      // plane leaves a replayable intent; it never loses the take event.
+      await enqueueStagingPoolTake({
+        poolDir: ctx.paths.pool,
+        poolId: ctx.poolId,
+        personaAlias: entry.alias,
+        // Local slot names contain a persona-derived prefix and timestamp. The
+        // server needs replay correlation only, so persist a one-way opaque id.
+        slotId: createHash("sha256").update(taken.slotId).digest("hex"),
+        sessionId,
+      });
+      await flushStagingPoolTakeOutbox({
+        poolDir: ctx.paths.pool,
+        botbuddyBin: ctx.installed.botbuddyBin,
+        exec,
+        env,
+        sessionId,
+      });
+    } catch (telemetryError) {
+      await pool.discardTaken(taken.slotId).catch(() => {});
+      throw telemetryError;
+    }
     await requestRefill({ ctx, exec, uid });
     return { taken, target, binding: ctx.poolBinding, persona: entry, discard: () => pool.discardTaken(taken.slotId) };
   } catch (error) {

package/src/staging-pool/errors.mjs

@@ -129,6 +129,26 @@ export const ERROR_CODES = Object.freeze({
     "Taking a session from the pool failed unexpectedly (see detail).",
     "A filesystem or pool error outside the known cases.",
     `${AUTH}   # once; if it repeats, report this code and detail`, "retry_once"),
+  take_outbox_unreadable: entry("human", "repair",
+    "The durable staging-pool take receipt cannot be read, so no browser session was handed over.",
+    "The installed pool's receipt journal is unreadable or was edited outside the CLI.",
+    "bb staging-pool uninstall && " + INSTALL),
+  take_outbox_invalid: entry("human", "repair",
+    "The durable staging-pool take receipt is invalid, so no browser session was handed over.",
+    "The installed pool's receipt journal has an invalid pool, persona, or opaque slot record.",
+    "bb staging-pool uninstall && " + INSTALL),
+  take_outbox_full: entry("agent", "take",
+    "The durable staging-pool take receipt journal is full, so no browser session was handed over.",
+    "The control plane has not acknowledged prior secret-free take receipts.",
+    "bb staging-pool status --check   # report this code; do not retry in a loop", "report_blocker"),
+  take_outbox_locked: entry("agent", "take",
+    "Another staging-pool take is recording its durable receipt, so no browser session was handed over.",
+    "A concurrent take still owns the short receipt-journal mutation lock.",
+    `${AUTH}   # retry once; if it repeats, report this code`, "retry_once"),
+  take_outbox_session_required: entry("agent", "take",
+    "The staging-pool take has no registered work-session identity, so no browser session was handed over.",
+    "The agent session was not registered or its work-session environment was lost before the take began.",
+    "bb setup   # restore this worktree's registered session, then retry once", "retry_once"),
 
   // ── the pool's health (human repairs; agents report once and stop)
   // BOT-2836: a healthy pool emptied between ticks is a wait, not a repair. The take

package/src/staging-pool/take-outbox.mjs

@@ -0,0 +1,151 @@
+// BOT-2934: the local take is not handed to a browser until its secret-free
+// telemetry intent is atomically durable. Delivery is replayable by take_id;
+// the MCP server, never this file, derives tenant/agent/work-session context.
+import * as fs from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { join } from "node:path";
+
+const FILE = "take-outbox.json";
+const LOCK_FILE = "take-outbox.lock";
+export const STAGING_POOL_TAKE_OUTBOX_MAX = 64;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SESSION_RE = UUID_RE;
+const LOCK_ATTEMPTS = 50;
+const LOCK_RETRY_MS = 20;
+const LOCK_STALE_MS = 30_000;
+
+function valid(event) {
+  return event && typeof event === "object" &&
+    UUID_RE.test(event.take_id ?? "") &&
+    /^[a-z0-9][a-z0-9-]{0,63}$/.test(event.pool_id ?? "") &&
+    /^[a-z0-9][a-z0-9-]{0,39}$/.test(event.persona_alias ?? "") &&
+    /^[a-f0-9]{12,64}$/.test(event.slot_id ?? "") &&
+    SESSION_RE.test(event.origin_session_id ?? "") &&
+    /^[a-f0-9]{64}$/.test(event.origin_session_hash ?? "");
+}
+
+function sessionHash(sessionId) {
+  if (typeof sessionId !== "string" || !SESSION_RE.test(sessionId)) {
+    throw Object.assign(new Error("A registered BotBuddy work session is required to record a staging-pool take."), { code: "take_outbox_session_required" });
+  }
+  return createHash("sha256").update(sessionId.toLowerCase()).digest("hex");
+}
+
+const pathFor = (poolDir) => join(poolDir, FILE);
+const lockPathFor = (poolDir) => join(poolDir, LOCK_FILE);
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function withOutboxLock(poolDir, action) {
+  await fs.mkdir(poolDir, { recursive: true, mode: 0o700 });
+  const lockPath = lockPathFor(poolDir);
+  const token = randomUUID();
+  for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt += 1) {
+    let handle;
+    try {
+      handle = await fs.open(lockPath, "wx", 0o600);
+      await handle.writeFile(JSON.stringify({ token, created_at: new Date().toISOString() }) + "\n");
+      await handle.sync();
+      try {
+        return await action();
+      } finally {
+        await handle.close();
+        try {
+          const holder = JSON.parse(await fs.readFile(lockPath, "utf8"));
+          if (holder?.token === token) await fs.rm(lockPath, { force: true });
+        } catch { /* a later holder owns the path, or it is already released */ }
+      }
+    } catch (error) {
+      await handle?.close().catch(() => {});
+      if (error?.code !== "EEXIST") throw error;
+      try {
+        const stat = await fs.stat(lockPath);
+        if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+          const tomb = `${lockPath}.stale-${randomUUID()}`;
+          await fs.rename(lockPath, tomb);
+          await fs.rm(tomb, { force: true });
+          continue;
+        }
+      } catch (lockError) {
+        if (lockError?.code !== "ENOENT") throw lockError;
+      }
+      await pause(LOCK_RETRY_MS);
+    }
+  }
+  throw Object.assign(new Error("Another staging-pool take is recording its durable receipt; no session was handed over."), { code: "take_outbox_locked" });
+}
+
+async function read(poolDir) {
+  let source;
+  try {
+    source = await fs.readFile(pathFor(poolDir), "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw Object.assign(new Error("The staging-pool take outbox is unreadable; no session was handed over."), { code: "take_outbox_unreadable" });
+  }
+  let parsed;
+  try { parsed = JSON.parse(source); }
+  catch { throw Object.assign(new Error("The staging-pool take outbox is invalid; no session was handed over."), { code: "take_outbox_invalid" }); }
+  if (!parsed || typeof parsed !== "object" || parsed.version !== 1 || !Array.isArray(parsed.events) || !parsed.events.every(valid)) {
+    throw Object.assign(new Error("The staging-pool take outbox is invalid; no session was handed over."), { code: "take_outbox_invalid" });
+  }
+  return parsed.events;
+}
+
+async function write(poolDir, events) {
+  await fs.mkdir(poolDir, { recursive: true, mode: 0o700 });
+  const output = JSON.stringify({ version: 1, events: events.slice(-STAGING_POOL_TAKE_OUTBOX_MAX) }) + "\n";
+  const temporary = join(poolDir, `.${FILE}.${randomUUID()}.partial`);
+  const handle = await fs.open(temporary, "wx", 0o600);
+  try {
+    await handle.writeFile(output);
+    await handle.sync();
+  } finally { await handle.close(); }
+  try {
+    await fs.rename(temporary, pathFor(poolDir));
+    const directory = await fs.open(poolDir, "r");
+    try { await directory.sync(); } finally { await directory.close(); }
+  } catch (error) {
+    await fs.rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+export async function enqueueStagingPoolTake({ poolDir, poolId, personaAlias, slotId, sessionId, takeId = randomUUID() }) {
+  const event = { take_id: takeId, pool_id: poolId, persona_alias: personaAlias, slot_id: slotId, origin_session_id: sessionId.toLowerCase(), origin_session_hash: sessionHash(sessionId) };
+  if (!valid(event)) throw Object.assign(new Error("The staging-pool take telemetry intent is invalid."), { code: "take_outbox_invalid" });
+  return withOutboxLock(poolDir, async () => {
+    const events = await read(poolDir);
+    if (events.length >= STAGING_POOL_TAKE_OUTBOX_MAX) throw Object.assign(new Error("The staging-pool take telemetry outbox is full; no session was handed over."), { code: "take_outbox_full" });
+    events.push(event);
+    await write(poolDir, events);
+    return event;
+  });
+}
+
+export async function flushStagingPoolTakeOutbox({ poolDir, botbuddyBin, exec, env = process.env, sessionId }) {
+  const pending = await withOutboxLock(poolDir, () => read(poolDir));
+  const originSessionHash = sessionHash(sessionId);
+  const delivered = new Set();
+  for (let index = 0; index < pending.length; index += 1) {
+    const sameSession = pending[index].origin_session_hash === originSessionHash;
+    let body;
+    try {
+      const { origin_session_hash: _originSessionHash, origin_session_id, ...payload } = pending[index];
+      const tool = sameSession ? "record_staging_pool_take" : "reconcile_staging_pool_take";
+      const bodyPayload = sameSession ? payload : { ...payload, origin_session_id };
+      const result = await exec(botbuddyBin, ["call", tool, "--json", JSON.stringify(bodyPayload)], { env, timeout: 10_000, maxBuffer: 64 * 1024 });
+      body = JSON.parse(String(result?.stdout ?? ""));
+    } catch { continue; }
+    if (body?.success === true) delivered.add(pending[index].take_id);
+  }
+  if (!delivered.size) return { delivered: 0, pending: pending.length };
+  const remaining = await withOutboxLock(poolDir, async () => {
+    const current = await read(poolDir);
+    const next = current.filter((event) => !delivered.has(event.take_id));
+    if (next.length !== current.length) await write(poolDir, next);
+    return next.length;
+  });
+  return { delivered: delivered.size, pending: remaining };
+}
+
+export const stagingPoolTakeOutboxPath = pathFor;

package/src/wait-core.mjs

@@ -140,6 +140,31 @@ function parseParams(raw) {
   return params;
 }
 
+function parseStagingPoolParams(raw) {
+  const params = {};
+  for (const entry of String(raw ?? "").split(",").map((part) => part.trim())) {
+    if (!entry) continue;
+    const named = /^(pool|persona)=([^=,]+)$/.exec(entry);
+    const readiness = /^ready>=([0-9]+)$/.exec(entry);
+    const key = named?.[1] ?? (readiness ? "ready" : undefined);
+    const value = named?.[2] ?? readiness?.[1];
+    if (!key || value === undefined) throw new Error(`staging-pool does not accept ${entry}`);
+    if (Object.prototype.hasOwnProperty.call(params, key)) throw new Error(`staging-pool does not accept duplicate ${key}`);
+    params[key] = value;
+  }
+  const identifier = (value, label) => {
+    if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,119}$/.test(value)) {
+      throw new Error(`staging-pool ${label} must be a registered identifier`);
+    }
+    return value;
+  };
+  const pool = identifier(params.pool, "pool");
+  const persona = identifier(params.persona, "persona");
+  const ready = params.ready === undefined ? 1 : Number(params.ready);
+  if (!Number.isSafeInteger(ready) || ready < 1) throw new Error("staging-pool ready>= must be a positive integer");
+  return { pool, persona, ready };
+}
+
 function asBool(v) {
   if (v === true) return true;
   if (typeof v !== "string") return false;
@@ -225,6 +250,10 @@ const VALIDATORS = {
     if (!CANONICAL_UUID_RE.test(jobId)) throw new Error("staging-pool-refill id must be a canonical UUID");
     return { jobId };
   },
+  // BOT-2934 — server-side arm authorization resolves the caller's installed
+  // instance. The CLI grammar names only its registered pool/persona, never a
+  // host, so it cannot turn a different machine's inventory into readiness.
+  "staging-pool": (_p, raw) => parseStagingPoolParams(raw),
   // BOT-2888: a reporter waits for a revision after the last consumed update.
   // The server binds the report to the registering agent and tenant.
   feedback: (p, raw) => {
@@ -1320,6 +1349,19 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
         signal.subject_key === `staging-pool-refill:${params.jobId}` &&
         signal.payload?.job_id === params.jobId &&
         ["completed", "failed"].includes(signal.payload?.status);
+    case "staging-pool": {
+      const payload = signal.payload;
+      return signal.signal_type === "staging_pool" &&
+        payload?.schema_version === 1 &&
+        typeof payload.instance_id === "string" && payload.instance_id.length > 0 &&
+        signal.subject_key === `staging-pool:${payload.instance_id}:${payload.persona_alias}` &&
+        payload.pool_id === params.pool &&
+        payload.persona_alias === params.persona &&
+        Number.isSafeInteger(payload.epoch) && payload.epoch >= 1 &&
+        Number.isSafeInteger(payload.revision) && payload.revision >= 1 &&
+        Number.isSafeInteger(payload.ready_count) && payload.ready_count >= params.ready &&
+        payload.availability === "ready" && payload.freshness_phase === "fresh";
+    }
     case "feedback":
       return signal.signal_type === "feedback_update" &&
         signal.subject_key === `feedback:${params.feedbackId}` &&

package/src/wait.mjs

@@ -175,6 +175,10 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       completed or failed. This is the only condition of its
                                       wait and is available to each tenant agent that requested
                                       the deduped job; its terminal receipt is safe to display.
+  staging-pool:pool=<id>,persona=<alias>[,ready>=N]
+                                      Wait for N (default 1) fresh, takeable sessions on the
+                                      caller's authorized installed pool instance. This does not
+                                      reserve a session: after a match, run the auth command once.
   feedback:id=<feedback UUID>,after=<revision>
                                       Wait for a later update to your own feedback; use the
                                       revision you last consumed and read/acknowledge updates.
@@ -663,6 +667,8 @@ async function registerWait(opts, conditions, deadlineIso) {
       "command_run_single_condition_required",
       "staging_pool_refill_unavailable",
       "staging_pool_refill_single_condition_required",
+      "staging_pool_unavailable",
+      "staging_pool_single_condition_required",
       "feedback_wait_unavailable",
     ]);
     if (INVALID_CONDITION_CODES.has(body.error)) {