@botbuddy/cli 1.40.11 → 1.40.12

package/package.json

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

package/src/commands.mjs

@@ -28,6 +28,7 @@ import { createTelemetryOutbox } from "./telemetry-outbox.mjs";
 import { attestTelemetryCredential, loadTelemetryIdentity, loadTelemetryLocation } from "./telemetry-config.mjs";
 import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
 import { doctorAgentAuth, doctorHelp, parseDoctorArgs, readClientKeyStrict, repairFailureRecovery } from "./agent-doctor.mjs";
+import { formatPublishIp, isLoopbackIp, probeEnginePublishIp, publishIpFix } from "./docker-publish-ip.mjs";
 import { clearAgentState, selfHealAgentSession } from "./agent-session.mjs";
 import { runUsage, usageStatus } from "./usage/sync.mjs";
 import { installUsageAgent, usageAgentStatus } from "./usage/launchd.mjs";
@@ -251,11 +252,17 @@ ${SETUP_BLOCK}`);
 export async function cmdDoctor(args, {
   log = (line) => console.log(line), errorLog = (line) => console.error(line),
   doctor = doctorAgentAuth, usageReport = doctorUsageSync, bootstrapReport = doctorBootstrapState,
+  publishReport = () => probeEnginePublishIp(),
 } = {}) {
   const parsed = parseDoctorArgs(args);
   if (parsed.help) { log(doctorHelp()); return 0; }
   if (parsed.errors.length) { errorLog(`bb doctor: ${parsed.errors.join("; ")}`); return 4; }
   const result = await doctor({ fix: parsed.fix, printExports: parsed.printExports });
+  // BOT-2146: where would this host's engine publish a leased stack's ports?
+  // Informational (read-only, never changes the exit code); reported only when
+  // doctor reports stack leases at all.
+  const publish = result.report.stack_lease ? await publishReport().catch(() => null) : null;
+  if (publish) result.report.stack_lease = { ...result.report.stack_lease, publish_ip: publish };
   // BOT-1021: informational only — never changes doctor's exit code.
   const usage = await usageReport().catch(() => null);
   // BOT-1945 (AC-3): informational, like usage sync — never changes the exit code.
@@ -269,7 +276,10 @@ export async function cmdDoctor(args, {
     log(`agent session: ${result.report.session.status}${result.report.session.minted_with ? ` (minted_with: ${result.report.session.minted_with})` : ""}`);
     if (result.report.stack_lease) {
       const sl = result.report.stack_lease;
-      log(`stack lease: ${sl.capability} (host ${sl.host}, machine id ${sl.machine_id_readable ? "readable" : "unavailable"})${sl.reason ? ` — ${sl.reason}` : ""}`);
+      log(`stack lease: ${sl.capability} (host ${sl.host}, machine id ${sl.machine_id_readable ? "readable" : "unavailable"})${sl.reason ? ` — ${sl.reason}` : ""}${publish ? ` ${formatPublishIp(publish)}` : ""}`);
+      if (publish && !isLoopbackIp(publish.publish_ip)) {
+        log(`stack publish: leased stacks on this host are reachable beyond loopback (\`bb stack up --local-exec\` refuses; the Helper refuses ports_exposed_beyond_loopback) — fix: ${publishIpFix(publish.engine)}`);
+      }
     }
     if (result.report.recovery) log(`recovery: ${result.report.recovery}`);
     if (bootstrap) log(formatBootstrapLine(bootstrap));

package/src/docker-publish-ip.mjs

@@ -0,0 +1,228 @@
+// BOT-2146 — where would this Docker engine publish a leased stack's ports?
+//
+// The Supabase CLI has no bind-address option: it publishes every stack port
+// with an UNSPECIFIED host IP, so the engine's default decides. With the
+// default, a leased stack (Postgres superuser `postgres:postgres`, demo JWTs)
+// listens on 0.0.0.0 and is reachable from the whole LAN.
+//
+// What controls that default, proven on Docker Desktop 4.91 / engine 29.8:
+//   • Docker Desktop: Settings → Resources → Network → "Port binding behavior"
+//     (`portBindingBehavior` in Desktop's own settings API): `local-only-port-binding`
+//     and `default-local-port-binding` publish unspecified ports on 127.0.0.1
+//     and ::1. `default-port-binding` (or unset) publishes on 0.0.0.0 and ::.
+//     The engine-level per-network option below is IGNORED by Desktop's
+//     host-side forwarder.
+//   • OrbStack / a plain Linux engine: daemon config `default-network-opts`
+//     → bridge → `com.docker.network.bridge.host_binding_ipv4`. The daemon
+//     `ip` key covers only the DEFAULT bridge; Supabase always creates its own
+//     `supabase_network_<project>`, so `ip` alone changes nothing here.
+//
+// Docker Desktop's settings are read from its backend API
+// (`GET /app/settings/flat` on ~/Library/Containers/com.docker.docker/Data/
+// backend.sock), the same resolved view its Settings UI renders. Reading the
+// settings-store.json in ~/Library/Group Containers instead BLOCKS: macOS App
+// Data protection holds the read on a consent prompt (measured on the MacBook,
+// 2026-10-07), which would hang `bb doctor` and `bb stack up`.
+//
+// Read-only: this module GETs settings, reads daemon config files and runs
+// `docker info`; it never changes engine configuration (a restart would kill
+// every live stack).
+import { spawnSync } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { request } from "node:http";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const ENGINE_PUBLISHES_BEYOND_LOOPBACK = "ENGINE_PUBLISHES_BEYOND_LOOPBACK";
+
+const DESKTOP_LOOPBACK = new Set(["local-only-port-binding", "default-local-port-binding"]);
+const DESKTOP_OPEN = "default-port-binding";
+const HOST_BINDING_IPV4 = "com.docker.network.bridge.host_binding_ipv4";
+
+export function dockerDesktopBackendSocket(home = homedir()) {
+  return join(home, "Library", "Containers", "com.docker.docker", "Data", "backend.sock");
+}
+
+/** GET a Docker Desktop backend API path over its unix socket → parsed JSON. */
+export function getDockerDesktopSettings({ socketPath = dockerDesktopBackendSocket(), timeoutMs = 5000, httpRequest = request } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = httpRequest({ socketPath, path: "/app/settings/flat", method: "GET", timeout: timeoutMs }, (res) => {
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => { body += chunk; });
+      res.on("end", () => {
+        if (res.statusCode !== 200) return reject(new Error(`docker desktop settings API returned HTTP ${res.statusCode}`));
+        resolve(body);
+      });
+    });
+    req.on("timeout", () => req.destroy(new Error("docker desktop settings API timed out")));
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+export function orbstackDockerConfigPath(home = homedir()) {
+  return join(home, ".orbstack", "config", "docker.json");
+}
+
+export const LINUX_DAEMON_CONFIG_PATH = "/etc/docker/daemon.json";
+
+/** `docker info --format '{{.OperatingSystem}}'` → the engine family, or null. */
+export function engineFromOperatingSystem(os) {
+  const value = typeof os === "string" ? os.trim() : "";
+  if (!value) return null;
+  if (value === "Docker Desktop") return "docker-desktop";
+  if (value === "OrbStack") return "orbstack";
+  return "docker-engine";
+}
+
+function parseObject(text) {
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Docker Desktop's flat settings (`/app/settings/flat`) → `{ publish_ip, setting }`. */
+export function parseDockerDesktopSettings(text) {
+  const settings = typeof text === "string" ? parseObject(text) : null;
+  if (!settings) return { publish_ip: "unknown", setting: "unreadable" };
+  const behavior = settings.portBindingBehavior;
+  if (behavior === undefined || behavior === null) return { publish_ip: "0.0.0.0", setting: "unset" };
+  if (DESKTOP_LOOPBACK.has(behavior)) return { publish_ip: "127.0.0.1", setting: behavior };
+  if (behavior === DESKTOP_OPEN) return { publish_ip: "0.0.0.0", setting: behavior };
+  return { publish_ip: "unknown", setting: String(behavior) };
+}
+
+/**
+ * A dockerd daemon.json (OrbStack's docker.json, /etc/docker/daemon.json) →
+ * `{ publish_ip, setting }`. `null` text means the file does not exist, which
+ * is the engine default: every interface.
+ */
+export function parseDaemonConfig(text) {
+  if (text === null || text === undefined) return { publish_ip: "0.0.0.0", setting: "absent" };
+  const config = parseObject(text);
+  if (!config) return { publish_ip: "unknown", setting: "unreadable" };
+  const ip = config["default-network-opts"]?.bridge?.[HOST_BINDING_IPV4];
+  if (typeof ip === "string" && ip) {
+    return { publish_ip: ip, setting: `default-network-opts.bridge.host_binding_ipv4=${ip}` };
+  }
+  return { publish_ip: "0.0.0.0", setting: "unset" };
+}
+
+/** IPv4 127.0.0.0/8 or IPv6 ::1. Anything else — including "unknown" — is not loopback. */
+export function isLoopbackIp(ip) {
+  if (typeof ip !== "string") return false;
+  if (ip === "::1") return true;
+  const octets = ip.split(".");
+  return octets.length === 4 && octets[0] === "127" &&
+    octets.every((o) => /^\d{1,3}$/.test(o) && Number(o) <= 255);
+}
+
+function readOrNull(readFile, path) {
+  try {
+    return readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/** Resolve the publish IP for a known engine family from its own settings. */
+export async function resolvePublishIp({
+  engine, home = homedir(), readFile = readFileSync, desktopSettings = () => getDockerDesktopSettings({ socketPath: dockerDesktopBackendSocket(home) }),
+} = {}) {
+  if (engine === "docker-desktop") {
+    const source = "docker-desktop:/app/settings/flat";
+    let text;
+    try { text = await desktopSettings(); } catch { return { engine, publish_ip: "unknown", setting: "settings_api_unreachable", source }; }
+    return { engine, ...parseDockerDesktopSettings(text), source };
+  }
+  if (engine === "orbstack" || engine === "docker-engine") {
+    const source = engine === "orbstack" ? orbstackDockerConfigPath(home) : LINUX_DAEMON_CONFIG_PATH;
+    try {
+      return { engine, ...parseDaemonConfig(readOrNull(readFile, source)), source };
+    } catch {
+      return { engine, publish_ip: "unknown", setting: "unreadable", source };
+    }
+  }
+  return { engine: "unknown", publish_ip: "unknown", setting: "engine_unknown", source: null };
+}
+
+/**
+ * Codex P1/P2 on #1076: the settings this module reads describe THIS
+ * machine's engine. They are evidence for a daemon only when its endpoint is
+ * that engine's own local unix socket, after resolving symlinks
+ * (`/var/run/docker.sock` → Docker Desktop's `~/.docker/run/docker.sock`). A
+ * tcp:// or ssh:// endpoint, a foreign socket, or one that cannot be resolved
+ * is not this machine's engine.
+ */
+export function engineSocketIsLocal(engine, endpoint, { home = homedir(), realpath = realpathSync } = {}) {
+  if (typeof endpoint !== "string" || !endpoint.startsWith("unix://")) return false;
+  let socketPath;
+  let realHome = home;
+  try { socketPath = realpath(endpoint.slice("unix://".length)); } catch { return false; }
+  try { realHome = realpath(home); } catch { /* compare against the literal home */ }
+  const under = (dir) => [join(home, dir) + "/", join(realHome, dir) + "/"];
+  const roots = {
+    "docker-desktop": [...under(join(".docker", "run")), ...under(join("Library", "Containers", "com.docker.docker"))],
+    orbstack: under(".orbstack"),
+  }[engine];
+  // A plain dockerd: /etc/docker/daemon.json configures whatever local unix
+  // socket it serves, so any resolvable local socket is its own.
+  if (engine === "docker-engine") return true;
+  return Boolean(roots) && roots.some((root) => socketPath.startsWith(root));
+}
+
+const notThisMachine = (engine, endpoint) =>
+  ({ engine: engine || "unknown", publish_ip: "unknown", setting: "endpoint_not_this_machines_engine", source: endpoint || null });
+
+/**
+ * Ask the engine what it is, then resolve — for the daemon the docker CLI
+ * would actually talk to: an explicit context or endpoint, else DOCKER_CONTEXT,
+ * else DOCKER_HOST, else the current context. Never reads this machine's
+ * settings for a daemon they do not describe.
+ */
+export async function probeEnginePublishIp({
+  spawn = spawnSync, home = homedir(), readFile = readFileSync, desktopSettings, context = null, endpoint = null,
+  env = process.env, realpath = realpathSync, timeoutMs = 20000,
+} = {}) {
+  const run = (args) => spawn("docker", args, { encoding: "utf8", timeout: timeoutMs, env });
+  let target = endpoint;
+  // Docker's own precedence: DOCKER_CONTEXT overrides DOCKER_HOST (Codex P1
+  // round 3 on #1076); `docker context inspect` with no name honours it.
+  if (!target && !context && !env.DOCKER_CONTEXT && env.DOCKER_HOST) target = env.DOCKER_HOST;
+  if (!target) {
+    const inspected = run(["context", "inspect", ...(context ? [context] : []), "--format", "{{.Endpoints.docker.Host}}"]);
+    target = inspected?.status === 0 ? String(inspected.stdout || "").trim() : "";
+  }
+  const selector = context ? ["--context", context] : endpoint ? ["--host", endpoint] : [];
+  const info = run([...selector, "info", "--format", "{{.OperatingSystem}}"]);
+  if (!info || info.status !== 0) return { engine: "unknown", publish_ip: "unknown", setting: "docker_info_failed", source: null };
+  const engine = engineFromOperatingSystem(info.stdout);
+  if (!engine) return { engine: "unknown", publish_ip: "unknown", setting: "docker_info_empty", source: null };
+  if (!engineSocketIsLocal(engine, target, { home, realpath })) return notThisMachine(engine, target);
+  return resolvePublishIp({ engine, home, readFile, ...(desktopSettings ? { desktopSettings } : {}) });
+}
+
+/** The operator fix, spelled out per engine. This module never applies it. */
+export function publishIpFix(engine) {
+  const restart = "Restarting the engine stops every running container, so do it when no stack lease is active on this host.";
+  if (engine === "docker-desktop") {
+    return "Docker Desktop → Settings → Resources → Network → Port binding behavior → Localhost only, then Apply & restart Docker Desktop " +
+      `(portBindingBehavior=local-only-port-binding). ${restart}`;
+  }
+  const opts = `"default-network-opts": {"bridge": {"${HOST_BINDING_IPV4}": "127.0.0.1"}}`;
+  if (engine === "orbstack") return `add ${opts} to ~/.orbstack/config/docker.json, then restart OrbStack. ${restart}`;
+  if (engine === "docker-engine") return `add ${opts} to /etc/docker/daemon.json, then restart dockerd. ${restart}`;
+  return "make the Docker engine reachable (docker info), then re-run `bb doctor` to read its port binding setting.";
+}
+
+export function formatPublishIp(result) {
+  const detail = result.engine === "docker-desktop"
+    ? `docker-desktop portBindingBehavior=${result.setting}`
+    : result.engine === "unknown" ? result.setting : `${result.engine} ${result.setting}`;
+  return `publish_ip=${result.publish_ip} (${detail})`;
+}

package/src/stack.mjs

@@ -25,7 +25,7 @@ import { writeLaneStatus } from "./lane-status.mjs";
 import { spawn, spawnSync } from "child_process";
 import { readFileSync, realpathSync } from "fs";
 import { open, unlink, readFile } from "fs/promises";
-import { tmpdir } from "os";
+import { homedir, tmpdir } from "os";
 import { basename, dirname, join, relative, isAbsolute } from "path";
 import { randomUUID } from "crypto";
 import { fileURLToPath } from "url";
@@ -39,6 +39,7 @@ import { runDockerCommand, runDockerWorkflow, ADMITTED_DOCKER_VALIDATIONS } from
 import { acquireStackLock, lockPathForProject, projectIdFromConfig } from "./stack-file-lock.mjs";
 import { assertLeasedStackIsolated, leasedStackIdentity, materializeRunStackDir, portMapInConfig, refreshLeasedStackRetention, releaseLeasedStackClaim, reservePortBlocks } from "./stack-isolation.mjs";
 import { machineUuid } from "./machine-id.mjs";
+import { ENGINE_PUBLISHES_BEYOND_LOOPBACK, engineSocketIsLocal, formatPublishIp, isLoopbackIp, publishIpFix, resolvePublishIp } from "./docker-publish-ip.mjs";
 import { bold, dim, yellow } from "./utils.mjs";
 
 export const STACK_SCHEMA_VERSION = 1;
@@ -96,6 +97,8 @@ ${bold("up OPTIONS")}
                          deadline (exit 2) and a failed wait (its own exit code) never retry.
   --local-exec           FALLBACK (no Helper): run 'supabase start' in an ISOLATED --stack-path
                          stack and self-activate. Refused at the worktree root (shared stack).
+                         Refused (exit 4, ENGINE_PUBLISHES_BEYOND_LOOPBACK) when the Docker
+                         engine would publish the stack's ports beyond loopback (BOT-2146).
   --docker-context <name> Explicit Docker context for the mandatory local preflight
                          (an allowlisted engine: OrbStack or Docker Desktop, e.g. desktop-linux).
   --docker-endpoint <uri> Explicit Docker endpoint instead of --docker-context.
@@ -1253,12 +1256,55 @@ const nonQueued = (s) => s != null && s !== "queued";
 // its full timeout instead of surfacing the failure immediately.
 const isReaped = (s) => s === "reaping" || s === "reaped" || s === "reap_failed";
 
-/** Read-only pressure gate used before local managed-stack provisioning. */
-export async function runLocalExecPreflight(opts, runCommand = runDockerCommand) {
+/**
+ * BOT-2146: the publish IP the validated engine would give a leased stack's
+ * ports. Read from the engine's own settings (Docker Desktop's settings API,
+ * OrbStack's docker.json); never modified here.
+ */
+export function localExecPublishIp(target, { home = homedir(), resolve = resolvePublishIp, realpath = realpathSync } = {}) {
+  // Codex P1/P2 on #1076: the setting read here describes THIS machine's
+  // engine (Desktop's settings API, OrbStack's docker.json). It is evidence
+  // only when the daemon the preflight validated is that engine's own local
+  // socket (symlinks resolved); anything else fails closed, unread.
+  if (!engineSocketIsLocal(target?.validation, target?.resolved_endpoint, { home, realpath })) {
+    return { engine: target?.validation || "unknown", publish_ip: "unknown", setting: "endpoint_not_this_machines_engine", source: target?.resolved_endpoint || null };
+  }
+  return resolve({ engine: target.validation, home });
+}
+
+/**
+ * Read-only gate used before local managed-stack provisioning: Docker pressure
+ * and identity, then (BOT-2146) where the engine would publish the stack. The
+ * Supabase CLI publishes every port with an unspecified host IP, so an engine
+ * that defaults to 0.0.0.0 puts a `postgres:postgres` superuser on the LAN.
+ * Local-exec has no Helper readiness check behind it, so it is refused here —
+ * fail closed when the setting cannot be read — with the operator fix.
+ */
+export async function runLocalExecPreflight(opts, runCommand = runDockerCommand, publishIp = localExecPublishIp) {
   const selector = opts.dockerContext
     ? ["--context", opts.dockerContext]
     : ["--endpoint", opts.dockerEndpoint];
-  return runCommand(["preflight", ...selector, "--json"]);
+  const checked = await runCommand(["preflight", ...selector, "--json"]);
+  const target = checked?.exitCode === 0 ? dockerTargetFromPreflight(checked.receipt) : null;
+  if (!target) return checked;
+  const exposure = await publishIp(target);
+  const receipt = { ...checked.receipt, publish_ip: exposure };
+  if (isLoopbackIp(exposure.publish_ip)) return { ...checked, receipt };
+  const error = `refusing --local-exec: ${ENGINE_PUBLISHES_BEYOND_LOOPBACK} — this Docker engine would publish the leased stack's ports on ` +
+    `${exposure.publish_ip}, not loopback (${formatPublishIp(exposure)}); every machine on the network could reach its Postgres ` +
+    `as superuser with the Supabase default credentials. Fix: ${publishIpFix(exposure.engine)}`;
+  return {
+    ...checked,
+    exitCode: EXIT.INVALID,
+    receipt: { ...receipt, outcome: "refused", code: ENGINE_PUBLISHES_BEYOND_LOOPBACK, errors: [error, ...(receipt.errors || [])] },
+  };
+}
+
+/** The exit code and receipt code for a refused local-exec preflight. */
+function localPreflightRefusal(receipt) {
+  return receipt?.code === ENGINE_PUBLISHES_BEYOND_LOOPBACK
+    ? { exitCode: EXIT.INVALID, code: ENGINE_PUBLISHES_BEYOND_LOOPBACK }
+    : { exitCode: EXIT.LEASE_FAILED, code: undefined };
 }
 
 /** Read-only daemon identity check for teardown; never report provision telemetry. */
@@ -1393,6 +1439,7 @@ function compactPreflight(receipt) {
     warnings: receipt.warnings,
     errors: receipt.errors,
     recommendation: receipt.recommendation,
+    ...(receipt.publish_ip ? { publish_ip: receipt.publish_ip } : {}),
   };
 }
 
@@ -1742,11 +1789,12 @@ export async function cmdUp(opts, {
     localPreflight = compactPreflight(checked.receipt);
     localDockerTarget = dockerTargetFromPreflight(checked.receipt);
     if (checked.exitCode !== 0 || !localDockerTarget) {
+      const refusal = localPreflightRefusal(checked.receipt);
       return emitResult(buildReceipt({
-        command: "up", outcome: "refused", slot,
+        command: "up", outcome: "refused", slot, ...(refusal.code ? { code: refusal.code } : {}),
         error: checked.receipt.errors?.[0] || "the local preflight did not return a stable Docker server identity",
         preflight: localPreflight,
-      }), opts, EXIT.LEASE_FAILED);
+      }), opts, refusal.exitCode);
     }
     if (checked.receipt.outcome === "warn") {
       // BOT-1681: surface the engine-aware recommendation (dry-run hygiene is
@@ -1941,12 +1989,13 @@ export async function cmdUp(opts, {
         const leaseCancellation = cancelled.ok && cancelled.data?.success
           ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
           : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+        const refusal = localPreflightRefusal(checked.receipt);
         return emitResult(buildReceipt({
-          command: "up", outcome: "refused", lease_id: leaseId, state, slot,
+          command: "up", outcome: "refused", lease_id: leaseId, state, slot, ...(refusal.code ? { code: refusal.code } : {}),
           error: checked.receipt.errors?.[0] || "OrbStack preflight did not return a stable Docker server identity",
           preflight: localPreflight,
           lease_cancellation: leaseCancellation,
-        }), opts, EXIT.LEASE_FAILED);
+        }), opts, refusal.exitCode);
       }
       // BOT-1711 (Codex R8 P2): the target config could have been edited while this lease
       // was QUEUED for capacity. Re-run the non-mutating target validation NOW, before