@botbuddy/cli 1.42.0 → 1.43.0

package/package.json

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

package/src/docker-hygiene.mjs

@@ -12,9 +12,11 @@ import { VERSION } from "./version.mjs";
 import { machineUuid } from "./machine-id.mjs";
 
 export const SCHEMA_VERSION = 1;
-export const DEFAULT_PROJECTED_ENDPOINTS = 10;
-export const DEFAULT_WARN_PRESSURE = 192;
-export const DEFAULT_FAIL_PRESSURE = 224;
+// BOT-2206: preflight applies policy v3's network term (BOT-2202). Docker's built-in
+// default-address-pools are 172.17–31.0.0/16 as /16s (15) + 192.168.0.0/16 as /20s (16).
+export const DEFAULT_NETWORK_LIMIT = 31;
+// The relay's accepted upper bound for `network_limit` (Helper DockerAddressPools).
+const MAX_NETWORK_LIMIT = 1_000_000;
 
 // BOT-1681 / BOT-1630 Step 3 — explicit Docker-engine allowlist. The org cut the
 // dev fleet back from OrbStack to Docker Desktop (OrbStack Helper heap runaway,
@@ -93,7 +95,8 @@ COMMANDS
   hygiene      Inventory stopped Supabase containers and empty
                supabase_network_* bridge networks. This is a dry-run unless
                --apply is explicitly present.
-  preflight    Read-only network-pressure check for a prospective managed stack.
+  preflight    Read-only check that the Docker daemon has a network for one more
+               managed stack (the server's admission network term).
 
 REQUIRED SELECTOR
   --context <name>     Explicit Docker context, e.g. orbstack
@@ -114,10 +117,12 @@ HYGIENE OPTIONS
                        Without it, no mutation.
   --json               Emit exactly one compact machine-readable receipt.
 
-PREFLIGHT OPTIONS
-  --projected-endpoints <n>  Expected endpoints in the new stack (default ${DEFAULT_PROJECTED_ENDPOINTS})
-  --warn-pressure <n>        Warn threshold (default ${DEFAULT_WARN_PRESSURE})
-  --fail-pressure <n>        Refuse threshold (default ${DEFAULT_FAIL_PRESSURE})
+PREFLIGHT
+  Counts user-defined bridge networks against the daemon's network limit, read
+  from docker info DefaultAddressPools (absent or malformed: Docker's default
+  ${DEFAULT_NETWORK_LIMIT}). The default bridge holds one subnet, so a start is
+  admitted while bridges + 1 <= limit - 1; it warns when the start would take the
+  last network and refuses (exit 2) when none is left. Endpoints are not scored.
   --json                       Emit exactly one compact machine-readable receipt.
 
   Engine allowlist (preflight): OrbStack and Docker Desktop are admitted by
@@ -169,15 +174,6 @@ const BUILTIN_NETWORKS = new Set(["bridge", "host", "none"]);
 // project's resources before its first container reaches running state.
 const ACTIVE_STATES = new Set(["created", "running", "paused", "restarting", "removing"]);
 
-function positiveInteger(value, option, errors, { allowZero = false } = {}) {
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed < (allowZero ? 0 : 1)) {
-    errors.push(`${option} must be ${allowZero ? "a non-negative" : "a positive"} integer`);
-    return null;
-  }
-  return parsed;
-}
-
 export function parseDockerArgs(argv) {
   const [command, ...rest] = argv;
   const errors = [];
@@ -189,9 +185,6 @@ export function parseDockerArgs(argv) {
     candidateIds: [],
     apply: false,
     json: false,
-    projectedEndpoints: DEFAULT_PROJECTED_ENDPOINTS,
-    warnPressure: DEFAULT_WARN_PRESSURE,
-    failPressure: DEFAULT_FAIL_PRESSURE,
   };
 
   const needValue = (option, index) => {
@@ -246,30 +239,12 @@ export function parseDockerArgs(argv) {
         }
         break;
       }
-      case "--projected-endpoints": {
-        const value = needValue(arg, i);
-        if (value !== null) {
-          opts.projectedEndpoints = positiveInteger(value, arg, errors, { allowZero: true });
-          i += 1;
-        }
-        break;
-      }
-      case "--warn-pressure": {
-        const value = needValue(arg, i);
-        if (value !== null) {
-          opts.warnPressure = positiveInteger(value, arg, errors);
-          i += 1;
-        }
+      case "--projected-endpoints":
+      case "--warn-pressure":
+      case "--fail-pressure":
+        errors.push(`${arg} was retired (BOT-2206): preflight now checks Docker networks against the daemon's network limit, like server admission; endpoints are not scored`);
+        if (rest[i + 1] !== undefined && !rest[i + 1].startsWith("--")) i += 1;
         break;
-      }
-      case "--fail-pressure": {
-        const value = needValue(arg, i);
-        if (value !== null) {
-          opts.failPressure = positiveInteger(value, arg, errors);
-          i += 1;
-        }
-        break;
-      }
       case "--apply": opts.apply = true; break;
       case "--json": opts.json = true; break;
       case "--help":
@@ -306,9 +281,6 @@ export function parseDockerArgs(argv) {
       if (!opts.lockSlot || opts.lockSlot === "default") errors.push("--apply requires a non-default --lock-slot from the owning stack lifecycle");
       if (opts.candidateIds.length === 0) errors.push("--apply requires at least one exact --candidate-id from the reviewed dry run");
     }
-    if (opts.warnPressure !== null && opts.failPressure !== null && opts.failPressure <= opts.warnPressure) {
-      errors.push("--fail-pressure must be greater than --warn-pressure");
-    }
   }
 
   return { command, opts, errors };
@@ -765,6 +737,7 @@ function validateDockerEngine(runDocker, opts, allowlist = DOCKER_ENGINE_ALLOWLI
 
   return {
     selector,
+    networkLimit: networkLimitFromDockerInfo(info),
     receipt: {
       requested: opts.context ? { type: "context", value: opts.context } : { type: "endpoint", value: opts.endpoint },
       resolved_endpoint: resolvedEndpoint,
@@ -780,29 +753,73 @@ function validateDockerEngine(runDocker, opts, allowlist = DOCKER_ENGINE_ALLOWLI
   };
 }
 
-export function evaluatePressure({
-  bridgeNetworks,
-  attachedEndpoints,
-  projectedEndpoints = DEFAULT_PROJECTED_ENDPOINTS,
-  warn = DEFAULT_WARN_PRESSURE,
-  fail = DEFAULT_FAIL_PRESSURE,
+function isIPv4(address) {
+  const octets = address.split(".");
+  return octets.length === 4 && octets.every((octet) => /^(0|[1-9][0-9]{0,2})$/.test(octet) && Number(octet) <= 255);
+}
+
+/**
+ * BOT-2206: how many bridge networks the daemon can allocate — the Helper's
+ * DockerAddressPools.networkLimit (0.2.26), so preflight and the census agree. Each
+ * IPv4 `DefaultAddressPools` entry yields 2^(Size − prefix) subnets; IPv6 pools never
+ * raise it. Absent pools (Docker's built-ins report null) or ANY malformed pool is
+ * unknown → Docker's default 31, never a partial sum and never a refusal.
+ */
+export function networkLimitFromDockerInfo(info) {
+  const fallback = { network_limit: DEFAULT_NETWORK_LIMIT, network_limit_source: "default" };
+  const pools = info?.DefaultAddressPools;
+  if (!Array.isArray(pools) || pools.length === 0) return fallback;
+  let total = 0;
+  let sawIPv4 = false;
+  for (const pool of pools) {
+    const parts = typeof pool?.Base === "string" ? pool.Base.split("/") : [];
+    const size = pool?.Size;
+    if (parts.length !== 2 || !/^[0-9]+$/.test(parts[1]) || !Number.isInteger(size)) return fallback;
+    const prefix = Number(parts[1]);
+    if (parts[0].includes(":")) {
+      if (prefix > 128 || size < prefix || size > 128) return fallback;
+      continue;
+    }
+    if (!isIPv4(parts[0]) || prefix > 32 || size < prefix || size > 32) return fallback;
+    sawIPv4 = true;
+    const bits = size - prefix;
+    total = Math.min(MAX_NETWORK_LIMIT, total + (bits >= 20 ? MAX_NETWORK_LIMIT : 2 ** bits));
+  }
+  return sawIPv4 && total > 0 ? { network_limit: total, network_limit_source: "daemon" } : fallback;
+}
+
+/**
+ * BOT-2206: policy v3's network term (BOT-2202), evaluated locally. The default
+ * `bridge` network holds one subnet, so one more start is admitted while
+ * `user bridges + 1 <= network_limit - 1`. It warns when that start takes the last
+ * usable network. current/projected_pressure_units keep the server's v3 meaning.
+ */
+export function evaluateNetworks({
+  userBridgeNetworks,
+  networkLimit = DEFAULT_NETWORK_LIMIT,
+  networkLimitSource = "default",
 }) {
-  const current = Number(bridgeNetworks) + (2 * Number(attachedEndpoints));
-  const projected = current + 1 + (2 * Number(projectedEndpoints));
-  const status = projected >= fail ? "fail" : projected >= warn ? "warn" : "ok";
+  const current = Number(userBridgeNetworks);
+  const limit = Number(networkLimit);
+  const usable = limit - 1;
+  const projected = current + 1;
+  const status = projected > usable ? "fail" : projected === usable ? "warn" : "ok";
   return {
-    metric: "conservative_network_pressure_units",
-    formula: "bridge_networks + (2 * attached_endpoints)",
+    metric: "docker_networks",
+    policy: "host_docker_pressure_v1",
+    policy_version: 3,
+    formula: "user_bridge_networks + 1 <= network_limit - 1",
+    network_limit: limit,
+    network_limit_source: networkLimitSource,
+    // Every network the daemon holds, including the default bridge: `networks n/limit`.
+    networks_in_use: current + 1,
+    network_free_slots: Math.max(0, usable - current),
     current_pressure_units: current,
     projected_pressure_units: projected,
-    projected_endpoints: Number(projectedEndpoints),
-    warn_pressure: Number(warn),
-    fail_pressure: Number(fail),
     status,
-    // BOT-1412: a host-wide interface-pressure refusal is not a per-stack
-    // `supabase_local` lock wait.  Emit the relay's capacity condition in the
-    // machine receipt so callers park on the global policy and receive the
-    // eventual capacity signal, rather than retrying Docker locally.
+    // BOT-1412: a host-wide refusal is not a per-stack `supabase_local` lock wait.
+    // Emit the relay's capacity condition so callers park on the global policy and
+    // receive the eventual capacity signal, rather than retrying Docker locally.
     ...(status === "fail" ? {
       wait: {
         kind: "global_capacity",
@@ -810,10 +827,15 @@ export function evaluatePressure({
         command: "bb-wait 'capacity:policy=host_docker_pressure_v1,slots>=1'",
       },
     } : {}),
-    note: "Conservative pressure proxy; OrbStack does not expose a kernel interface ceiling through the Docker API.",
   };
 }
 
+/** `networks 31/31 (default limit)` — the preflight's one-line network verdict. */
+export function formatNetworks(pressure) {
+  const source = pressure.network_limit_source === "daemon" ? "daemon address pools" : "Docker default limit";
+  return `networks ${pressure.networks_in_use}/${pressure.network_limit} (${source})`;
+}
+
 function baseReceipt(command, opts, now) {
   return {
     schema_version: SCHEMA_VERSION,
@@ -858,7 +880,7 @@ export function buildReliabilityTelemetry(receipt, { dedupeKey } = {}) {
   }
   const ghostInventory = (receipt.inventory_errors?.length ?? 0) > 0;
   // A successful target check is not a capacity measurement. If discovery
-  // fails before evaluatePressure produces a decision, suppress the generic
+  // fails before evaluateNetworks produces a decision, suppress the generic
   // observation so the evidence view cannot count a zero-filled false pass.
   // Classified daemon and persistent-inventory faults remain reportable.
   if (receipt.command === "preflight" && !receipt.pressure && !unavailable && !ghostInventory) {
@@ -1108,13 +1130,12 @@ export function runDockerWorkflow(argv, {
   }
 
   if (parsed.command === "preflight") {
-    receipt.pressure = evaluatePressure({
-      bridgeNetworks: inventory.counts.user_bridge_networks,
-      attachedEndpoints: inventory.counts.attached_endpoints,
-      projectedEndpoints: parsed.opts.projectedEndpoints,
-      warn: parsed.opts.warnPressure,
-      fail: parsed.opts.failPressure,
+    receipt.pressure = evaluateNetworks({
+      userBridgeNetworks: inventory.counts.user_bridge_networks,
+      networkLimit: validated.networkLimit.network_limit,
+      networkLimitSource: validated.networkLimit.network_limit_source,
     });
+    const networks = formatNetworks(receipt.pressure);
     // BOT-1681: dry-run hygiene is the OrbStack-only remedy. On Docker Desktop it
     // refuses, so the pressure warning/refusal must not tell operators to run it;
     // point them at the engine-aware recommendation instead.
@@ -1122,13 +1143,13 @@ export function runDockerWorkflow(argv, {
     if (receipt.pressure.status === "warn") {
       receipt.outcome = "warn";
       receipt.warnings.push(pressureEngine === "orbstack"
-        ? "Projected OrbStack network pressure is at or above the warning threshold; run dry-run hygiene before starting another stack."
-        : "Projected Docker network pressure is at or above the warning threshold; reduce Docker load (see recommendation) before starting another stack.");
+        ? `This start takes the last free Docker network (${networks}); run dry-run hygiene before starting another stack.`
+        : `This start takes the last free Docker network (${networks}); reduce Docker load (see recommendation) before starting another stack.`);
     } else if (receipt.pressure.status === "fail") {
       receipt.outcome = "refused";
       receipt.errors.push(pressureEngine === "orbstack"
-        ? "Projected OrbStack network pressure is at or above the refusal threshold; cleanup or release an owning stack before start."
-        : "Projected Docker network pressure is at or above the refusal threshold; release an owning stack (see recommendation) before start.");
+        ? `No Docker network is free for another stack (${networks}); cleanup or release an owning stack before start.`
+        : `No Docker network is free for another stack (${networks}); release an owning stack (see recommendation) before start.`);
       return { exitCode: EXIT.PRESSURE, receipt, json: parsed.opts.json };
     }
     return { exitCode: EXIT.OK, receipt, json: parsed.opts.json };
@@ -1275,7 +1296,7 @@ export function formatHumanReceipt(receipt) {
   }
   if (!receipt.inventory_errors?.length) lines.push("  none");
   if (receipt.pressure) {
-    lines.push(`Pressure: ${receipt.pressure.projected_pressure_units} projected (${receipt.pressure.status}; warn ${receipt.pressure.warn_pressure}, fail ${receipt.pressure.fail_pressure})`);
+    lines.push(`Capacity: ${formatNetworks(receipt.pressure)} — ${receipt.pressure.status}; attached endpoints ${receipt.inventory?.attached_endpoints ?? "?"} (not scored)`);
   }
   lines.push(`Reliability telemetry: ${receipt.telemetry?.status || "not_attempted"}`);
   for (const warning of receipt.warnings) lines.push(`Warning: ${warning}`);

package/src/stack.mjs

@@ -60,6 +60,9 @@ const CALLBACK_PORT_REMOTE_REFUSAL =
   "(pre-forward GatewayPorts probe). Use --local-only for a run that needs a callback port.";
 export const DEFAULT_RECEIPT_MAX_BYTES = 10240;
 export const DEFAULT_TIMEOUT_SEC = 3600;
+/** BOT-2230: the bounds the control plane enforces on an owner place hold (hold_stack_lease_place). */
+export const HOLD_ON_TIMEOUT_MIN_SEC = 60;
+export const HOLD_ON_TIMEOUT_MAX_SEC = 14400;
 /** How often a run renews its stack directory's retention while it still exists
  * (BOT-1798): frequent enough to cover the pre-child queue/provision waits. */
 const RETENTION_REFRESH_MS = 5 * 60 * 1000;
@@ -104,6 +107,13 @@ ${bold("up OPTIONS")}
   --idle-ttl <seconds>   Idle seconds before the reaper STOPS an unused stack (default 1800).
   --timeout <seconds>    Max seconds to park for capacity before giving up (default ${DEFAULT_TIMEOUT_SEC}).
   --no-wait              If the host is full, print the queue position and exit (don't park).
+  --hold-on-timeout <seconds>
+                         BOT-2230: when the --timeout park runs out with the lease still queued,
+                         keep its queue place for <seconds> (60–14400) instead of losing it: the
+                         lease stays queued but is not dispatched, and re-running the same
+                         \`stack up\` (same agent + slot) before then re-attaches to it. The exit-2
+                         receipt carries queue_hold {held, until, queue_position}; \`stack done
+                         <lease_id>\` gives the place up.
   --claim-only           LOCAL-EXEC only: wait for and hold a provisioning lease without starting
                          Supabase. Resume with the identical \`stack up --local-exec\` command.
   --wait-capacity <dur>  Opt-in (BOT-2024): on a TRANSIENT HOST_CAPACITY_SOURCE_STALE refusal, park
@@ -255,7 +265,7 @@ export function parseStackArgs(argv) {
     slot: null, host: null, repo: null, ticket: null, ticketUrl: null,
     prId: null, prUrl: null, purpose: null, idleTtl: null, stackPath: ".", stackPathExplicit: false,
     timeout: DEFAULT_TIMEOUT_SEC, provisionTimeout: null, reapTimeout: 300, hardTtl: null,
-    connectionFile: null, noWait: false, claimOnly: false, localExec: false, waitCapacity: null,
+    connectionFile: null, noWait: false, claimOnly: false, localExec: false, waitCapacity: null, holdOnTimeout: null,
     dockerContext: null, dockerEndpoint: null,
     // BOT-2142: execution placement (null = command default), remote-lease callback + bundle cap.
     execution: null, remote: false, localOnly: false, callbackPort: null, bundleMaxBytes: null,
@@ -356,6 +366,15 @@ export function parseStackArgs(argv) {
         }
         break;
       }
+      case "--hold-on-timeout": {
+        if (need(a, rest[i + 1])) {
+          const n = Number(rest[++i]);
+          if (!Number.isInteger(n) || n < HOLD_ON_TIMEOUT_MIN_SEC || n > HOLD_ON_TIMEOUT_MAX_SEC) {
+            errors.push(`--hold-on-timeout must be a whole number of seconds from ${HOLD_ON_TIMEOUT_MIN_SEC} to ${HOLD_ON_TIMEOUT_MAX_SEC}`);
+          } else opts.holdOnTimeout = n;
+        }
+        break;
+      }
       case "--no-wait": opts.noWait = true; break;
       case "--claim-only": opts.claimOnly = true; break;
       case "--local-exec": opts.localExec = true; break;
@@ -410,6 +429,11 @@ export function parseStackArgs(argv) {
   if (opts.waitCapacity != null && !["up", "run"].includes(command)) {
     errors.push("--wait-capacity is valid only with `stack up` or `stack run`");
   }
+  if (opts.holdOnTimeout != null && command !== "up") {
+    errors.push("--hold-on-timeout is valid only with `stack up`");
+  } else if (opts.holdOnTimeout != null && opts.noWait) {
+    errors.push("--hold-on-timeout cannot be combined with --no-wait: without a park there is no timeout to keep a place across");
+  }
   if (opts.claimOnly && (command !== "up" || !opts.localExec)) {
     errors.push("--claim-only is valid only with `stack up --local-exec`");
   }
@@ -453,6 +477,22 @@ export function describeQueuePosition(d) {
   return d?.scored_ticket_id ? `${where}, scored under ${d.scored_ticket_id}` : where;
 }
 
+/**
+ * BOT-2230: hold a timed-out queued lease's place for its owner (`hold_stack_lease_place`).
+ * Never throws: a refusal or a control plane without the tool is reported as `held: false`
+ * with the server's code, so the caller decides (the hermetic lane then cancels as before).
+ */
+export async function holdQueuePlace(call, leaseId, holdSecs) {
+  let res;
+  try { res = await call("hold_stack_lease_place", { lease_id: leaseId, hold_secs: holdSecs }); }
+  catch (err) { return { held: false, code: null, error: String(err?.message ?? err) }; }
+  const d = res?.data;
+  if (res?.ok && d?.success) {
+    return { held: true, until: d.queue_hold_until ?? null, queue_position: d.queue_position ?? null, hold_secs: d.hold_secs ?? holdSecs };
+  }
+  return { held: false, code: d?.code ?? null, error: d?.message || d?.error || res?.error || "hold refused" };
+}
+
 /** BOT-2019: the queue fields a server returned for a queued lease, for a receipt. */
 /**
  * BOT-2099: the human lines for the server's unit ledger (`stack_lease_unit_ledger`) — who
@@ -2107,7 +2147,14 @@ export async function cmdUp(opts, {
       let ledger = d.ledger ?? null;
       try { const read = await call("get_stack_lease", { lease_id: leaseId }); if (read?.ok && read.data?.success && read.data.ledger) ledger = read.data.ledger; } catch { /* keep the request-time ledger */ }
       for (const line of describeUnitLedger(ledger)) process.stderr.write(`stack: ${line}\n`);
-      return emitResult(buildReceipt({ command: "up", outcome: "timeout", lease_id: leaseId, state: "queued", slot, error: `parked ${opts.timeout}s without capacity`, ...(ledger ? { unit_ledger: ledger } : {}) }), opts, EXIT.TIMEOUT);
+      // BOT-2230: keep the queue place for the owner's next attempt instead of losing it.
+      const queueHold = opts.holdOnTimeout ? await holdQueuePlace(call, leaseId, opts.holdOnTimeout) : null;
+      if (queueHold?.held) {
+        process.stderr.write(`stack: lease ${leaseId} keeps queue place ${queueHold.queue_position ?? "?"} until ${queueHold.until} — re-run the same \`stack up\` before then to re-attach (\`stack done ${leaseId}\` gives it up)\n`);
+      } else if (queueHold) {
+        process.stderr.write(`${yellow("⚠")} stack: lease ${leaseId} could not keep its queue place (${queueHold.code ?? "error"}: ${queueHold.error})\n`);
+      }
+      return emitResult(buildReceipt({ command: "up", outcome: "timeout", lease_id: leaseId, state: "queued", slot, error: `parked ${opts.timeout}s without capacity`, ...(ledger ? { unit_ledger: ledger } : {}), ...(queueHold ? { queue_hold: queueHold } : {}) }), opts, EXIT.TIMEOUT);
     }
     if (parked.auth) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: "unauthorized on wait stream" }), opts, EXIT.AUTH);
     if (parked.error) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: parked.error }), opts, EXIT.BACKEND);