@botbuddy/cli 1.29.4 → 1.30.0

package/package.json

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

package/src/docker-hygiene.mjs

@@ -15,6 +15,56 @@ export const SCHEMA_VERSION = 1;
 export const DEFAULT_PROJECTED_ENDPOINTS = 10;
 export const DEFAULT_WARN_PRESSURE = 192;
 export const DEFAULT_FAIL_PRESSURE = 224;
+
+// 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,
+// SG ENT-4356 F4), so preflight must admit Docker Desktop deliberately instead of
+// hard-requiring OrbStack. Each entry maps `docker info`.OperatingSystem to a
+// stable `validation` label persisted on the lease and matched at teardown, plus
+// an optional secondary identity guard. Anything not listed fails closed. The
+// `orbstack_unavailable` fault label is deliberately NOT an admitted engine.
+export const DOCKER_ENGINE_ALLOWLIST = Object.freeze([
+  Object.freeze({ operating_system: "OrbStack", validation: "orbstack", identity: /orbstack/i }),
+  Object.freeze({ operating_system: "Docker Desktop", validation: "docker-desktop", identity: null }),
+]);
+
+// `hygiene` DELETES containers, so it keeps the original OrbStack-only fence
+// (BOT-1630 Must-NOT-1). Only the read-only `preflight` widens to the full
+// allowlist; that is what stack leases gate on.
+const HYGIENE_ENGINE_ALLOWLIST = Object.freeze(
+  DOCKER_ENGINE_ALLOWLIST.filter((entry) => entry.validation === "orbstack"),
+);
+
+// Validation labels the stack-lease target identity/fence accepts, shared with
+// stack.mjs so provision and teardown agree on what a valid engine looks like.
+export const ADMITTED_DOCKER_VALIDATIONS = Object.freeze(
+  new Set(DOCKER_ENGINE_ALLOWLIST.map((entry) => entry.validation)),
+);
+
+// Optional fleet override: `BOTBUDDY_DOCKER_ENGINES` (comma-separated validation
+// labels, e.g. "orbstack") narrows admission for machines that must stay on a
+// single engine. Unset/blank → the org-default full allowlist. Because this is a
+// SAFETY control that RESTRICTS admission, a non-empty value that names no known
+// engine label (a typo like "orbstak", or only empties) fails CLOSED with an
+// error rather than silently widening back to the default — otherwise a
+// misspelled restriction would admit exactly the engine it meant to block
+// (Codex P2). Known-but-inapplicable labels (e.g. "docker-desktop" for the
+// OrbStack-only hygiene command) narrow to nothing and fall back to the command's
+// inherent base, which is the same or stricter — never wider.
+export function resolveEngineAllowlist(command, env = process.env) {
+  const base = command === "hygiene" ? HYGIENE_ENGINE_ALLOWLIST : DOCKER_ENGINE_ALLOWLIST;
+  const raw = env?.BOTBUDDY_DOCKER_ENGINES;
+  if (typeof raw !== "string" || !raw.trim()) return base;
+  const requested = raw.split(",").map((label) => label.trim().toLowerCase()).filter(Boolean);
+  const unknown = requested.filter((label) => !ADMITTED_DOCKER_VALIDATIONS.has(label));
+  if (requested.length === 0 || unknown.length > 0) {
+    throw new Error(`engine_override_invalid: BOTBUDDY_DOCKER_ENGINES="${raw}" names no usable engine label${unknown.length ? ` (unknown: ${unknown.join(", ")})` : ""}; known labels: ${[...ADMITTED_DOCKER_VALIDATIONS].join(", ")}`);
+  }
+  const wanted = new Set(requested);
+  const narrowed = base.filter((entry) => wanted.has(entry.validation));
+  return narrowed.length > 0 ? narrowed : base;
+}
+
 const INSPECT_BATCH_SIZE = 10;
 const MAX_APPLY_BUDGET_MS = 5 * 60 * 1000;
 const MAX_DOCKER_COMMAND_MS = 30 * 1000;
@@ -50,8 +100,10 @@ REQUIRED SELECTOR
   --endpoint <uri>     Explicit Docker endpoint, e.g.
                        unix:///Users/me/.orbstack/run/docker.sock
 
-  Exactly one selector is required. The target must identify itself as
-  OrbStack; the ambient Docker context and DOCKER_HOST are never trusted.
+  Exactly one selector is required; the ambient Docker context and DOCKER_HOST
+  are never trusted. hygiene (which deletes) admits only OrbStack. preflight
+  admits an allowlisted engine — OrbStack or Docker Desktop — and refuses any
+  other daemon with engine_not_allowed:<OperatingSystem>.
 
 HYGIENE OPTIONS
   --ticket <BOT|ENT-N> Scope discovery/apply to the owning ticket's project.
@@ -68,6 +120,11 @@ PREFLIGHT OPTIONS
   --fail-pressure <n>        Refuse threshold (default ${DEFAULT_FAIL_PRESSURE})
   --json                       Emit exactly one compact machine-readable receipt.
 
+  Engine allowlist (preflight): OrbStack and Docker Desktop are admitted by
+  default. Set BOTBUDDY_DOCKER_ENGINES to a comma-separated list of engine
+  labels (orbstack, docker-desktop) to keep a fleet on a single engine, e.g.
+  BOTBUDDY_DOCKER_ENGINES=orbstack.
+
 SAFETY
   • Apply requires a ticket that matches each candidate's Docker project label.
   • Apply must run from a Git worktree branch carrying that same ticket.
@@ -90,8 +147,10 @@ RELIABILITY MEASUREMENT
 
 LIFECYCLE
   Use one worktree and one ticket-scoped managed stack for one test/fix batch;
-  finish or reap that stack before starting another. Run preflight before start,
-  and ticket-scoped dry-run hygiene when pressure warns or refuses admission.
+  finish or reap that stack before starting another. Run preflight before start.
+  When pressure warns or refuses: on OrbStack, run ticket-scoped dry-run hygiene;
+  on Docker Desktop (where hygiene stays OrbStack-only) release your own idle stack
+  with 'botbuddy stack done <lease>' instead.
 
 PERSISTENT ORBSTACK GHOSTS
   If an exact ID remains listed but OrbStack cannot inspect it, inventory is
@@ -672,7 +731,7 @@ function readInventory(runDocker, selector) {
   };
 }
 
-function validateOrbStack(runDocker, opts) {
+function validateDockerEngine(runDocker, opts, allowlist = DOCKER_ENGINE_ALLOWLIST) {
   let resolvedEndpoint = opts.endpoint;
   let targetHintsOrbStack = /orbstack/i.test(String(opts.endpoint || ""));
   if (opts.context) {
@@ -694,10 +753,14 @@ function validateOrbStack(runDocker, opts) {
     }
     throw error;
   }
-  const osIsOrbStack = info?.OperatingSystem === "OrbStack";
   const identity = `${info?.KernelVersion || ""} ${info?.Name || ""} ${info?.ServerVersion || ""}`;
-  if (!osIsOrbStack || !/orbstack/i.test(identity)) {
-    throw new Error(`Docker target is not OrbStack (OperatingSystem=${info?.OperatingSystem || "unknown"}, kernel=${info?.KernelVersion || "unknown"})`);
+  const engine = allowlist.find((entry) =>
+    entry.operating_system === info?.OperatingSystem &&
+    (!entry.identity || entry.identity.test(identity)));
+  if (!engine) {
+    // Fail closed on any daemon we do not positively recognise. The reason string
+    // is stable (`engine_not_allowed:<OperatingSystem>`) so wrappers can branch on it.
+    throw new Error(`engine_not_allowed:${info?.OperatingSystem || "unknown"} (Docker target is not an allowlisted engine; OperatingSystem=${info?.OperatingSystem || "unknown"}, kernel=${info?.KernelVersion || "unknown"}, admitted=${allowlist.map((entry) => entry.operating_system).join(", ") || "(none)"})`);
   }
 
   return {
@@ -705,7 +768,7 @@ function validateOrbStack(runDocker, opts) {
     receipt: {
       requested: opts.context ? { type: "context", value: opts.context } : { type: "endpoint", value: opts.endpoint },
       resolved_endpoint: resolvedEndpoint,
-      validation: "orbstack",
+      validation: engine.validation,
       server: {
         id: info.ID || null,
         name: info.Name || null,
@@ -784,6 +847,15 @@ function baseReceipt(command, opts, now) {
 
 export function buildReliabilityTelemetry(receipt, { dedupeKey } = {}) {
   const unavailable = receipt.context?.validation === "orbstack_unavailable";
+  // BOT-1681: the reliability experiment (BOT-1421, `v_orbstack_*`) is OrbStack-only
+  // and correlates rows by host/time with no engine stratum. A newly-admitted Docker
+  // Desktop preflight must NOT emit an unlabeled `capacity_observed` row that would
+  // contaminate the OrbStack strata, so suppress telemetry for any non-OrbStack
+  // engine outright. (Engine-stratified reliability reporting is BOT-1543/BOT-1630.)
+  const validation = receipt.context?.validation;
+  if (validation && validation !== "orbstack" && !unavailable) {
+    return null;
+  }
   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
@@ -902,10 +974,22 @@ function addSkipOnce(receipt, item) {
   }
 }
 
-function recommendationFor(opts, apply = false, candidates = []) {
+function recommendationFor(opts, apply = false, candidates = [], engine = "orbstack") {
   const selector = opts.context ? `--context ${opts.context}` : `--endpoint ${opts.endpoint}`;
   const ticket = opts.ticket ? ` --ticket ${opts.ticket}` : "";
-  if (!apply) return `botbuddy docker hygiene ${selector}${ticket}`;
+  if (!apply) {
+    // BOT-1681: `docker hygiene` is OrbStack-only, so recommending it on a
+    // non-OrbStack engine (e.g. Docker Desktop) would hand back a command that
+    // refuses with engine_not_allowed. Give a remedy that actually works there.
+    if (engine !== "orbstack") {
+      // Only recommend the OWNERSHIP-SCOPED remedy. Never suggest broad supabase_*
+      // container removal here: it bypasses hygiene's ticket filter, reviewed
+      // candidate IDs, and file/stack locks, so on a shared host it could delete a
+      // stopped service belonging to another live stack (Codex round-7 P2).
+      return `docker hygiene is OrbStack-only; on ${engine} reduce Docker load by releasing your own idle stack leases (botbuddy stack done <lease>), then retry`;
+    }
+    return `botbuddy docker hygiene ${selector}${ticket}`;
+  }
   if (!opts.ticket) return `botbuddy docker hygiene ${selector} --ticket <BOT-or-ENT-ticket>`;
   const projects = [...new Set(candidates.map((item) => item.project))];
   const lockSlot = projects.length === 1 ? lockSlotForProject(projects[0], opts.ticket) : null;
@@ -923,6 +1007,7 @@ export function runDockerWorkflow(argv, {
   monotonicNow = Date.now,
   platform = process.platform,
   now = () => new Date(),
+  env = process.env,
 } = {}) {
   const parsed = parseDockerArgs(argv);
   const receipt = baseReceipt(parsed.command || "unknown", parsed.opts, now);
@@ -970,10 +1055,10 @@ export function runDockerWorkflow(argv, {
   let validated;
   let inventory;
   try {
-    validated = validateOrbStack(runDocker, parsed.opts);
+    validated = validateDockerEngine(runDocker, parsed.opts, resolveEngineAllowlist(parsed.command, env));
     receipt.context = validated.receipt;
     inventory = classifyInventory(readInventory(runDocker, validated.selector));
-    receipt.recommendation = recommendationFor(parsed.opts);
+    receipt.recommendation = recommendationFor(parsed.opts, false, [], validated.receipt.validation);
   } catch (error) {
     receipt.outcome = "error";
     receipt.errors = [error.message];
@@ -1013,7 +1098,12 @@ export function runDockerWorkflow(argv, {
     for (const item of receipt.inventory_errors) {
       receipt.errors.push(`${item.type} ${item.id}${item.name ? ` (${item.name})` : ""} remains listed but cannot be authoritatively inspected: ${item.error}`);
     }
-    receipt.recommendation = "Persistent OrbStack inventory blocker: restart or repair OrbStack, then rerun the hygiene dry run with the same explicit selector; never use broad cleanup.";
+    // BOT-1681: this inventory-error path is shared by preflight, which now admits
+    // Docker Desktop. Keep the OrbStack remedy for OrbStack, but never tell a Docker
+    // Desktop operator to "repair OrbStack" or run the OrbStack-only hygiene dry run.
+    receipt.recommendation = receipt.context?.validation === "orbstack"
+      ? "Persistent OrbStack inventory blocker: restart or repair OrbStack, then rerun the hygiene dry run with the same explicit selector; never use broad cleanup."
+      : `Persistent Docker inventory blocker: restart or repair the ${receipt.context?.server?.operating_system || "Docker"} daemon, then rerun preflight with the same explicit selector; never use broad cleanup.`;
     return { exitCode: EXIT.DOCKER, receipt, json: parsed.opts.json };
   }
 
@@ -1025,12 +1115,20 @@ export function runDockerWorkflow(argv, {
       warn: parsed.opts.warnPressure,
       fail: parsed.opts.failPressure,
     });
+    // 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.
+    const pressureEngine = receipt.context?.validation;
     if (receipt.pressure.status === "warn") {
       receipt.outcome = "warn";
-      receipt.warnings.push("Projected OrbStack network pressure is at or above the warning threshold; run dry-run hygiene before starting another stack.");
+      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.");
     } else if (receipt.pressure.status === "fail") {
       receipt.outcome = "refused";
-      receipt.errors.push("Projected OrbStack network pressure is at or above the refusal threshold; cleanup or release an owning stack before start.");
+      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.");
       return { exitCode: EXIT.PRESSURE, receipt, json: parsed.opts.json };
     }
     return { exitCode: EXIT.OK, receipt, json: parsed.opts.json };

package/src/stack.mjs

@@ -31,7 +31,7 @@ import { callToolJson } from "./api.mjs";
 import { SERVER_URL, getConfig } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
 import { AGENT_KEY_RE, readAgentKeyEnv } from "./agent-key.mjs";
-import { runDockerCommand, runDockerWorkflow } from "./docker-hygiene.mjs";
+import { runDockerCommand, runDockerWorkflow, ADMITTED_DOCKER_VALIDATIONS } from "./docker-hygiene.mjs";
 import { machineUuid } from "./machine-id.mjs";
 import { bold, dim, yellow } from "./utils.mjs";
 
@@ -75,15 +75,18 @@ ${bold("up OPTIONS")}
   --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).
   --local-exec           FALLBACK (no Helper): run 'supabase start' locally and self-activate.
-  --docker-context <name> Explicit OrbStack Docker context for the mandatory local preflight.
-  --docker-endpoint <uri> Explicit OrbStack endpoint instead of --docker-context.
+  --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.
 
 ${bold("done OPTIONS")}
   --stop                 Keep volumes (cheap re-provision next batch). Default: destroy.
   --local-exec           FALLBACK (no Helper): run 'supabase stop' locally and self-finalize.
-  --docker-context <name> Explicit OrbStack context used by the matching local-exec up.
-  --docker-endpoint <uri> Explicit OrbStack endpoint instead of --docker-context.
-                         Pre-1.5.0 leases also require exact worktree + live connection proof.
+  --docker-context <name> Explicit Docker context used by the matching local-exec up
+                         (OrbStack or Docker Desktop; must match the engine that provisioned the lease).
+  --docker-endpoint <uri> Explicit Docker endpoint instead of --docker-context.
+                         Pre-1.5.0 leases have no persisted target and stay OrbStack-only; they also
+                         require exact worktree + live connection proof.
 
 ${bold("run OPTIONS")}
   --repo <repo>          Required approved repository name.
@@ -528,7 +531,15 @@ export async function runLocalExecTargetCheck(opts, runWorkflow = runDockerWorkf
   const selector = opts.dockerContext
     ? ["--context", opts.dockerContext]
     : ["--endpoint", opts.dockerEndpoint];
-  return runWorkflow(["preflight", ...selector, "--json"]);
+  // BOT-1681 — teardown is an IDENTITY check against the daemon already persisted
+  // on the lease, not a new-admission decision. The BOTBUDDY_DOCKER_ENGINES fleet
+  // override gates PROVISIONING only; honouring it here would reject a still-valid
+  // Docker Desktop lease the moment a host is pinned to orbstack, fencing the lease
+  // and its stack slot forever (Codex P2). Validate against the full engine
+  // allowlist and let dockerTargetsMatch fence the observed daemon to the lease.
+  const env = { ...process.env };
+  delete env.BOTBUDDY_DOCKER_ENGINES;
+  return runWorkflow(["preflight", ...selector, "--json"], { env });
 }
 
 export function dockerEnvForSelector(opts, env = process.env) {
@@ -544,9 +555,14 @@ export function dockerTargetFromPreflight(receipt) {
   const context = receipt?.context;
   const endpoint = context?.resolved_endpoint;
   const serverId = context?.server?.id;
-  if (context?.validation !== "orbstack" || typeof endpoint !== "string" || !endpoint ||
+  const validation = context?.validation;
+  // BOT-1681 — accept any allowlisted engine (orbstack, docker-desktop), not a
+  // hardcoded "orbstack". Carry the real engine label so teardown fences to the
+  // exact engine that provisioned the lease. Fault labels (e.g. orbstack_unavailable)
+  // are not admitted validations, so they still return null.
+  if (!ADMITTED_DOCKER_VALIDATIONS.has(validation) || typeof endpoint !== "string" || !endpoint ||
       typeof serverId !== "string" || !serverId) return null;
-  return { validation: "orbstack", resolved_endpoint: endpoint, server_id: serverId };
+  return { validation, resolved_endpoint: endpoint, server_id: serverId };
 }
 
 export function connectionWithDockerTarget(connection, target) {
@@ -556,8 +572,12 @@ export function connectionWithDockerTarget(connection, target) {
   return { ...(connection || {}), botbuddy_docker_target: { ...target } };
 }
 
-function dockerTargetsMatch(expected, actual) {
-  return expected?.validation === "orbstack" && actual?.validation === "orbstack" &&
+export function dockerTargetsMatch(expected, actual) {
+  // BOT-1681 — the fence is still exact: provision and teardown must agree on the
+  // engine (validation), the resolved endpoint, AND the daemon server_id. Widening
+  // the allowlist must never let a cross-engine or cross-daemon target match.
+  return ADMITTED_DOCKER_VALIDATIONS.has(expected?.validation) &&
+    expected?.validation === actual?.validation &&
     expected.resolved_endpoint === actual.resolved_endpoint && expected.server_id === actual.server_id;
 }
 
@@ -705,12 +725,16 @@ export async function cmdUp(opts, {
     if (checked.exitCode !== 0 || !localDockerTarget) {
       return emitResult(buildReceipt({
         command: "up", outcome: "refused", slot,
-        error: checked.receipt.errors?.[0] || "OrbStack preflight did not return a stable Docker server identity",
+        error: checked.receipt.errors?.[0] || "the local preflight did not return a stable Docker server identity",
         preflight: localPreflight,
       }), opts, EXIT.LEASE_FAILED);
     }
     if (checked.receipt.outcome === "warn") {
-      process.stderr.write(`${yellow("⚠")} stack: OrbStack preflight warns of interface pressure; cleanup is recommended before another stack.\n`);
+      // BOT-1681: surface the engine-aware recommendation (dry-run hygiene is
+      // OrbStack-only) rather than a hardcoded OrbStack cleanup instruction.
+      const engine = checked.receipt.context?.validation === "orbstack" ? "OrbStack" : "Docker";
+      const remedy = checked.receipt.recommendation || "reduce Docker load before starting another stack";
+      process.stderr.write(`${yellow("⚠")} stack: ${engine} preflight warns of network pressure; ${remedy}.\n`);
     }
   }
   const auth = await authProvider();
@@ -926,11 +950,23 @@ export async function cmdDone(leaseId, opts, {
     dockerTarget = dockerTargetFromPreflight(checked.receipt);
     if (expected && !dockerTargetsMatch(expected, dockerTarget)) {
       return emitResult(buildReceipt({ command: "done", outcome: "refused", lease_id: leaseId,
-        error: "teardown Docker target does not exactly match the OrbStack server persisted at provisioning; lease and slot remain fenced",
+        error: "teardown Docker target does not exactly match the Docker daemon persisted at provisioning; lease and slot remain fenced",
         expected_docker_target: expected || null, observed_docker_target: dockerTarget,
       }), opts, EXIT.LEASE_FAILED);
     }
     if (!expected) {
+      // BOT-1681: legacy (pre-1.5.0) leases carry no persisted botbuddy_docker_target,
+      // and proveLegacyLocalExecTarget authorizes teardown from only the worktree +
+      // live API/DB URLs — not the engine. Those leases were created under OrbStack and
+      // the compatibility contract still pins them there, so keep this path OrbStack-only:
+      // a Docker Desktop daemon (newly admitted by the preflight allowlist for MODERN
+      // leases) must never authorize teardown of a targetless legacy OrbStack lease.
+      if (dockerTarget?.validation !== "orbstack") {
+        return emitResult(buildReceipt({ command: "done", outcome: "refused", lease_id: leaseId,
+          error: `pre-1.5.0 lease has no persisted Docker target; only an OrbStack daemon may authorize legacy teardown, not ${dockerTarget?.validation || "an unverified engine"}; lease and slot remain fenced`,
+          expected_docker_target: null, observed_docker_target: dockerTarget,
+        }), opts, EXIT.LEASE_FAILED);
+      }
       const proof = proveLegacyTarget(current.data, dockerTarget, opts);
       if (!proof?.ok) {
         return emitResult(buildReceipt({ command: "done", outcome: "refused", lease_id: leaseId,