@botbuddy/cli 1.62.3 → 1.62.5

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.62.3",
-  "source_commit": "f360d97780f33ea528695c412fe995921def79e4",
-  "source_sha256": "f51d8ebb381b6f6ed5cdcaa820cc37b4b464c87f4f83057336e7db52c57b5d26",
+  "release_version": "1.62.5",
+  "source_commit": "abebdf325df18fd2d61b76971c59c2d57fd512a1",
+  "source_sha256": "c936de9003230430258fd3ee54cc3fc6aa74618312bbf875a16c47b2320975ce",
   "target": "darwin-arm64",
-  "sha256": "5a19b567b8faf0e956bacaab84b5106cc79809fe0330924b4af1af91ce9c90f3"
+  "sha256": "3695d85ceebb29aeea8f764924286918409a1fe60c0da85d0e37dff20e893754"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.62.3",
-  "source_commit": "f360d97780f33ea528695c412fe995921def79e4",
-  "source_sha256": "f51d8ebb381b6f6ed5cdcaa820cc37b4b464c87f4f83057336e7db52c57b5d26",
+  "release_version": "1.62.5",
+  "source_commit": "abebdf325df18fd2d61b76971c59c2d57fd512a1",
+  "source_sha256": "c936de9003230430258fd3ee54cc3fc6aa74618312bbf875a16c47b2320975ce",
   "target": "linux-x64",
-  "sha256": "89be3a9a5d26a7ba8ef5c7463c174be158ca7567efc0b2b736f3dbcdd50a1a0d"
+  "sha256": "f391c6f146dda4ea93ce60a856e4d3e63d64e467c0b928af0299a97b8df626f2"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.62.3",
-  "source_commit": "f360d97780f33ea528695c412fe995921def79e4",
-  "source_sha256": "f51d8ebb381b6f6ed5cdcaa820cc37b4b464c87f4f83057336e7db52c57b5d26",
+  "release_version": "1.62.5",
+  "source_commit": "abebdf325df18fd2d61b76971c59c2d57fd512a1",
+  "source_sha256": "c936de9003230430258fd3ee54cc3fc6aa74618312bbf875a16c47b2320975ce",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "5a19b567b8faf0e956bacaab84b5106cc79809fe0330924b4af1af91ce9c90f3",
+      "sha256": "3695d85ceebb29aeea8f764924286918409a1fe60c0da85d0e37dff20e893754",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "89be3a9a5d26a7ba8ef5c7463c174be158ca7567efc0b2b736f3dbcdd50a1a0d",
+      "sha256": "f391c6f146dda4ea93ce60a856e4d3e63d64e467c0b928af0299a97b8df626f2",
       "mode": "0755"
     }
   }

package/package.json

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

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

@@ -22,7 +22,7 @@
 // Dependency-free (Node stdlib only).
 
 import { spawn, spawnSync } from "node:child_process";
-import { connect, createServer } from "node:net";
+import { connect, createServer, isIP } from "node:net";
 
 export const SSH_FORWARD_OPTIONS = Object.freeze([
   "-N", "-T",
@@ -299,7 +299,7 @@ export async function openSshForwards({
  * `GatewayPorts yes` silently binds it on every interface, exposing this machine's
  * callback service to the host's network. The CLI cannot read sshd_config, so after the
  * forward is up it asks the host which address the listener really holds and refuses
- * anything but loopback (fail closed: no lsof, no listener, unreadable → refused).
+ * anything but loopback (fail closed: no inventory, no listener, unreadable → refused).
  */
 export function verifyCallbackLoopback({ sshBin, sshTarget, port, env = process.env, run = spawnSync, label = null }) {
   const what = label ?? `the reverse forward for --callback-port ${port}`;
@@ -307,18 +307,47 @@ export function verifyCallbackLoopback({ sshBin, sshTarget, port, env = process.
     `${what} on ${sshTarget} could not be proven loopback-only (${why}). ` +
       "An sshd with GatewayPorts yes binds -R forwards on every interface; set GatewayPorts no (or clientspecified) on the host, " +
       "or run without --callback-port.", extra);
+  const checkedPort = validPort(port);
+  if (checkedPort == null) throw fail("invalid listener port");
+  // Linux lsof cannot see root-owned sshd sockets from an unprivileged login (BOT-2743).
+  // ss reads the socket table without process visibility; -p is deliberately omitted.
+  // Dispatch on the remote OS in the SAME SSH invocation, with no guessed fallback.
+  const command = `case "$(uname -s)" in Linux) printf 'bb-ss-v1\\n'; ss -H -ltn '( sport = :${checkedPort} )';; ` +
+    `Darwin) lsof -nP -iTCP:${checkedPort} -sTCP:LISTEN -Fn;; ` +
+    "*) printf 'unsupported listener inventory platform\\n' >&2; exit 69;; esac";
   // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- fixed argv; target validated; integer port.
   const r = run(sshBin, [
     "-T", "-o", "BatchMode=yes", "-o", "ControlMaster=no", "-o", "ControlPath=none", "--", sshTarget,
-    `lsof -nP -iTCP:${Number(port)} -sTCP:LISTEN -Fn`,
+    command,
   ], { encoding: "utf8", env, timeout: 15_000 });
   if (r.error || r.status !== 0) {
     const tail = String(r.stderr || r.error?.message || "").trim().split("\n").slice(-1)[0];
     // lsof exits 1 with no output when nothing listens.
-    if (r.status === 1 && !String(r.stdout || "").trim()) throw fail(`no listener on the host's port ${port}`, { noListener: true });
-    throw fail(`could not run lsof on the host (exit ${r.status ?? "?"}${tail ? `: ${tail}` : ""})`);
+    if (!r.error && r.status === 1 && !String(r.stdout || "").trim() && !String(r.stderr || "").trim()) {
+      throw fail(`no listener on the host's port ${port}`, { noListener: true });
+    }
+    throw fail(`could not inspect host sockets with ss/lsof (exit ${r.status ?? "?"}${tail ? `: ${tail}` : ""})`);
+  }
+  const output = String(r.stdout || "");
+  let addresses;
+  if (output.startsWith("bb-ss-v1\n")) {
+    addresses = output.slice("bb-ss-v1\n".length).split("\n").filter((line) => line.trim()).map((line) => {
+      // ss -H -ltn: State Recv-Q Send-Q Local-Address:Port Peer-Address:Port.
+      // Reject the whole answer on any bad row: silently skipping a wildcard is unsafe.
+      const fields = line.trim().split(/\s+/);
+      const local = /^(.+):(\d+)$/.exec(fields[3] ?? "");
+      let address = local?.[1];
+      if (address?.startsWith("[") && address.endsWith("]")) address = address.slice(1, -1);
+      const family = isIP(address ?? "");
+      if (fields.length !== 5 || fields[0] !== "LISTEN" || !/^\d+$/.test(fields[1]) || !/^\d+$/.test(fields[2]) ||
+          !local || Number(local[2]) !== checkedPort || (!family && address !== "*")) {
+        throw fail("malformed ss listener inventory");
+      }
+      return `${family === 6 ? `[${address}]` : address}:${checkedPort}`;
+    });
+  } else {
+    addresses = output.split("\n").filter((l) => l.startsWith("n")).map((l) => l.slice(1).trim());
   }
-  const addresses = String(r.stdout || "").split("\n").filter((l) => l.startsWith("n")).map((l) => l.slice(1).trim());
   if (!addresses.length) throw fail(`no listener on the host's port ${port}`, { noListener: true });
   const exposed = addresses.filter((a) => !(a.startsWith("127.") || a.startsWith("[::1]:") || a.startsWith("localhost:")));
   if (exposed.length) throw fail(`the host listens on ${exposed.join(", ")}`, { exposed, listeners: addresses });

package/src/stack.mjs

@@ -3777,7 +3777,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