@botbuddy/cli 1.40.10 → 1.40.12

package/package.json

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

package/src/agent-doctor.mjs

@@ -1,7 +1,6 @@
 // BOT-1649 — diagnose and repair a worktree's short-lived agent credential
 // without ever printing the token unless the operator explicitly requests an
 // export snippet for the current shell.
-import { hostname } from "node:os";
 import { readAgentBinding } from "./wait-profile.mjs";
 import { resolveOwnerToken, CLIENT_KEY_SERVICE, OWNER_TOKEN_SERVICE } from "./cli-credentials.mjs";
 import { readKeychainSecret } from "./agent-credential-store.mjs";
@@ -9,6 +8,7 @@ import { getConfig } from "./config.mjs";
 import { isAgentStateFresh, readAgentState } from "./agent-state.mjs";
 import { selfHealAgentSession } from "./agent-session.mjs";
 import { machineUuid } from "./machine-id.mjs";
+import { machineHost } from "./machine-host.mjs";
 
 export function parseDoctorArgs(argv = []) {
   const parsed = { fix: false, printExports: false, json: false, errors: [] };
@@ -97,6 +97,16 @@ function applyStackLeaseCapability(report, capability) {
   if (!capability || typeof capability.status !== "string") return;
   report.stack_lease.capability = capability.status;
   if (capability.reason) report.stack_lease.reason = capability.reason;
+  if (capability.reported_host && capability.enrolled_host) {
+    report.stack_lease.hostname_drift = {
+      reported: capability.reported_host,
+      enrolled: capability.enrolled_host,
+      remedies: [
+        "use the macOS LocalHostName reported by `scutil --get LocalHostName`",
+        "or re-enrol the Helper if this is intentionally a different machine",
+      ],
+    };
+  }
   if (capability.status !== "established" && !report.recovery) {
     report.recovery = `stack leases need a device-consented Helper on this machine: ${capability.reason ?? "worktree not attested"}`;
   }
@@ -126,7 +136,7 @@ export async function doctorAgentAuth({
   // inside selfHeal, which the `--fix` gate skips when it reports the key missing.
   ownerToken = readClientKeyStrict,
   selfHeal = selfHealAgentSession,
-  hostFn = hostname, machineUuidFn = machineUuid,
+  hostFn = machineHost, machineUuidFn = machineUuid,
 } = {}) {
   let owner = null;
   let ownerReadFailed = false;
@@ -140,6 +150,7 @@ export async function doctorAgentAuth({
   // LaunchAgent). Env only, exactly like selfHealAgentSession; never the value.
   const mcpEnv = typeof bound?.mcpEnv === "string" && bound.mcpEnv ? bound.mcpEnv : null;
   const mcpKeyInEnv = Boolean(mcpEnv && typeof env?.[mcpEnv] === "string" && env[mcpEnv]);
+  const resolvedHost = await hostFn();
   const report = {
     schema_version: 1,
     worktree: cwd,
@@ -156,7 +167,7 @@ export async function doctorAgentAuth({
     // is known only after a register call, so a plain `bb doctor` reports `unverified`
     // and `--fix` re-registers to (re)establish it (`established` | `unattested`).
     stack_lease: {
-      host: hostFn(),
+      host: resolvedHost,
       machine_id_readable: Boolean(machineUuidFn()),
       capability: "unverified",
     },

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/machine-host.mjs

@@ -0,0 +1,26 @@
+import { execFile } from "node:child_process";
+import { hostname, platform } from "node:os";
+import { promisify } from "node:util";
+import { canonicalizeHostString } from "./pw/host.mjs";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Return the host identity used by Helper enrolment. macOS's kernel hostname can
+ * follow DHCP; Bonjour LocalHostName is stable and is what the Helper records.
+ */
+export async function machineHost({
+  platformFn = platform,
+  hostnameFn = hostname,
+  execFileFn = execFileAsync,
+} = {}) {
+  if (platformFn() !== "darwin") return hostnameFn();
+  try {
+    const { stdout } = await execFileFn("scutil", ["--get", "LocalHostName"]);
+    const localName = canonicalizeHostString(stdout);
+    if (localName) return `${localName}.local`;
+  } catch {
+    // Minimal shells can lack scutil; the existing hostname behaviour is safe.
+  }
+  return hostnameFn();
+}

package/src/session-bootstrap.mjs

@@ -8,6 +8,8 @@ import { clearAgentSessionIfMatches, drainPendingCleanup, recordPendingCleanup }
 import { readAgentBinding } from "./wait-profile.mjs";
 import { resolveAgentKey, resolveOwnerToken } from "./cli-credentials.mjs";
 import { getConfig } from "./config.mjs";
+import { machineHost } from "./machine-host.mjs";
+import { machineUuid } from "./machine-id.mjs";
 
 // BOT-1650 → BOT-1649 reconciliation: the harness session lives in the ONE
 // unified client cache (agent-state.mjs), written in main's `agent_session_token`
@@ -29,7 +31,7 @@ export async function loadHarnessSession({ cwd = process.cwd() } = {}) {
 /** Persist a bootstrap-issued session into the unified cache. The bootstrap RPC
  * does not echo the tenant, so derive it from the committed binding exactly as
  * selfHealAgentSession does; host/worktree/minted_at are derived locally. */
-export async function saveHarnessSession(session, { cwd = process.cwd() } = {}) {
+export async function saveHarnessSession(session, { cwd = process.cwd(), machineHostFn = machineHost } = {}) {
   const root = await worktreeRoot(cwd);
   let tenant;
   try { tenant = (await readAgentBinding(root))?.tenant; } catch { tenant = undefined; }
@@ -39,7 +41,7 @@ export async function saveHarnessSession(session, { cwd = process.cwd() } = {})
     agent_session_token: session.session_token,
     session_id: session.session_id ?? null,
     ...(tenant ? { tenant } : {}),
-    host: os.hostname(),
+    host: await machineHostFn(),
     worktree: root,
     minted_at: new Date().toISOString(),
     expires_at: session.expires_at,
@@ -218,6 +220,8 @@ export async function bootstrapHarnessSession({
   model = null,
   effort = null,
   harness = type,
+  machineHostFn = machineHost,
+  machineUuidFn = machineUuid,
   call = callToolJson,
   callOptions = undefined,
   resolveCleanupOptions = durableCleanupOptions,
@@ -249,11 +253,14 @@ export async function bootstrapHarnessSession({
     // bootstrap straight through so the server reuses a still-live incarnation
     // or rotates a truly expired one; never revoke an active wait from a stale
     // local timestamp.
+    const host = await machineHostFn();
+    const hardwareUuid = machineUuidFn();
     const response = await call("bootstrap_agent_session", {
       name,
       type,
       harness_session_id: harnessSessionId,
-      host: os.hostname(),
+      host,
+      ...(hardwareUuid ? { machine_uuid: hardwareUuid } : {}),
       worktree,
       ...(branch ? { branch } : {}),
       ...(ticketId ? { ticket_id: ticketId } : {}),

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