@botbuddy/cli 1.64.25 → 1.64.26

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # 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.

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.64.25",
-  "source_commit": "c07e6d20430392a68124bc1ec8f8675202725aab",
-  "source_sha256": "41b187e7b8afceb34b0435e24796d9b313cb0255f17ca8c1eae30c7de81ee87b",
+  "release_version": "1.64.26",
+  "source_commit": "3c0c0a5b3043740906a1d230d2e52bfb040af538",
+  "source_sha256": "37ab46e615c285d102088320e3106cbc968d5c42f345e48051980173eaeffba2",
   "target": "darwin-arm64",
-  "sha256": "94b11bbe78ce60791202df0cb36a4d4eddca15c353ad8adcc9007bedf3f3513c"
+  "sha256": "1c61bc84457da670166622fe9ef8fc7295a1f2286591e7cb8850aed78023858b"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.64.25",
-  "source_commit": "c07e6d20430392a68124bc1ec8f8675202725aab",
-  "source_sha256": "41b187e7b8afceb34b0435e24796d9b313cb0255f17ca8c1eae30c7de81ee87b",
+  "release_version": "1.64.26",
+  "source_commit": "3c0c0a5b3043740906a1d230d2e52bfb040af538",
+  "source_sha256": "37ab46e615c285d102088320e3106cbc968d5c42f345e48051980173eaeffba2",
   "target": "linux-x64",
-  "sha256": "2f219ac1910318da6483fe4c5e590c3cdb101b03cf4c67032a14254735130ff8"
+  "sha256": "718ad319db010d21e1ac51da283f7d64d2cd9c9313abbc16912d1e560426be2e"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.64.25",
-  "source_commit": "c07e6d20430392a68124bc1ec8f8675202725aab",
-  "source_sha256": "41b187e7b8afceb34b0435e24796d9b313cb0255f17ca8c1eae30c7de81ee87b",
+  "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": "94b11bbe78ce60791202df0cb36a4d4eddca15c353ad8adcc9007bedf3f3513c",
+      "sha256": "1c61bc84457da670166622fe9ef8fc7295a1f2286591e7cb8850aed78023858b",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "2f219ac1910318da6483fe4c5e590c3cdb101b03cf4c67032a14254735130ff8",
+      "sha256": "718ad319db010d21e1ac51da283f7d64d2cd9c9313abbc16912d1e560426be2e",
       "mode": "0755"
     }
   }

package/package.json

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

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 } : {}),