@botbuddy/cli 1.18.0 → 1.19.0

package/package.json

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

package/src/docker-hygiene.mjs

@@ -8,6 +8,7 @@ import { readFileSync } from "node:fs";
 import { hostname } from "node:os";
 import { callToolJson } from "./api.mjs";
 import { acquireStackLock, lockPathForProject, projectIdFromConfig } from "./stack-file-lock.mjs";
+import { VERSION } from "./version.mjs";
 import { machineUuid } from "./machine-id.mjs";
 
 export const SCHEMA_VERSION = 1;
@@ -18,6 +19,7 @@ const INSPECT_BATCH_SIZE = 10;
 const MAX_APPLY_BUDGET_MS = 5 * 60 * 1000;
 const MAX_DOCKER_COMMAND_MS = 30 * 1000;
 const LOCK_EXPIRY_RESERVE_MS = 60 * 1000;
+const TELEMETRY_TIMEOUT_MS = 2 * 1000;
 
 export const EXIT = Object.freeze({
   OK: 0,
@@ -79,6 +81,18 @@ SAFETY
   • Re-inspects every candidate immediately before deletion.
   • Never force-removes a resource, never runs a prune command, and never removes volumes.
 
+RELIABILITY MEASUREMENT
+  After the local safety decision is complete, the CLI makes one best-effort
+  aggregate reliability report. Docker IDs, names, endpoints, labels, paths,
+  commands, and raw errors are not uploaded. Reporting is observational only:
+  success, rejection, unavailability, or timeout never changes cleanup safety,
+  command arguments, or the local exit code.
+
+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.
+
 PERSISTENT ORBSTACK GHOSTS
   If an exact ID remains listed but OrbStack cannot inspect it, inventory is
   reported but cleanup refuses. Restart or repair OrbStack, then rerun the
@@ -329,6 +343,11 @@ function selected(runDocker, selector, args) {
   return runChecked(runDocker, [...selector, ...args]);
 }
 
+function isDockerDaemonUnavailable(error) {
+  return /(?:cannot connect to (?:the )?docker daemon|docker daemon is not running|error during connect|dial unix[^\n]*(?:connection refused|no such file or directory)|orbstack[^\n]*daemon[^\n]*unavailable)/i
+    .test(String(error?.message ?? error ?? ""));
+}
+
 function nonEmptyLines(text) {
   return text.split(/\r?\n/).map((value) => value.trim()).filter(Boolean);
 }
@@ -655,15 +674,26 @@ function readInventory(runDocker, selector) {
 
 function validateOrbStack(runDocker, opts) {
   let resolvedEndpoint = opts.endpoint;
+  let targetHintsOrbStack = /orbstack/i.test(String(opts.endpoint || ""));
   if (opts.context) {
     const inspected = parseJson(runChecked(runDocker, ["context", "inspect", opts.context]), "docker context inspect");
     const context = Array.isArray(inspected) ? inspected[0] : inspected;
     resolvedEndpoint = context?.Endpoints?.docker?.Host || null;
     if (!resolvedEndpoint) throw new Error(`Docker context ${opts.context} has no Docker endpoint`);
+    targetHintsOrbStack = /orbstack/i.test(`${context?.Name || opts.context} ${context?.Metadata?.Description || ""} ${resolvedEndpoint}`);
   }
 
   const selector = selectorArgs(opts);
-  const info = parseJson(selected(runDocker, selector, ["info", "--format", "{{json .}}"]), "docker info");
+  let info;
+  try {
+    info = parseJson(selected(runDocker, selector, ["info", "--format", "{{json .}}"]), "docker info");
+  } catch (error) {
+    if (targetHintsOrbStack && isDockerDaemonUnavailable(error)) {
+      error.reliabilityEventKind = "orbstack_unavailable";
+      error.resolvedEndpoint = resolvedEndpoint;
+    }
+    throw error;
+  }
   const osIsOrbStack = info?.OperatingSystem === "OrbStack";
   const identity = `${info?.KernelVersion || ""} ${info?.Name || ""} ${info?.ServerVersion || ""}`;
   if (!osIsOrbStack || !/orbstack/i.test(identity)) {
@@ -741,6 +771,7 @@ function baseReceipt(command, opts, now) {
     warnings: [],
     errors: [],
     recommendation: null,
+    telemetry: { status: "not_attempted" },
     authority: {
       ticket: opts.ticket,
       worktree_branch: null,
@@ -751,6 +782,119 @@ function baseReceipt(command, opts, now) {
   };
 }
 
+export function buildReliabilityTelemetry(receipt, { dedupeKey } = {}) {
+  const unavailable = receipt.context?.validation === "orbstack_unavailable";
+  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
+  // 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) {
+    return null;
+  }
+  const eventKind = unavailable
+    ? "orbstack_unavailable"
+    : ghostInventory
+      ? "ghost_inventory"
+      : receipt.command === "preflight"
+        ? "capacity_observed"
+        : receipt.apply ? "hygiene_apply" : "hygiene_dry_run";
+  const event = {
+    schema_version: SCHEMA_VERSION,
+    event_kind: eventKind,
+    dedupe_key: dedupeKey,
+    observed_at: receipt.timestamp,
+    outcome: receipt.outcome,
+    active_supabase_projects: receipt.active_projects?.length ?? 0,
+    bridge_networks: receipt.inventory?.user_bridge_networks ?? 0,
+    attached_endpoints: receipt.inventory?.attached_endpoints ?? 0,
+    unknown_resources: (receipt.inventory_errors?.length ?? 0)
+      + (receipt.skipped?.filter((item) => item.reason === "missing_project_identity").length ?? 0),
+    candidate_count: receipt.candidates?.length ?? 0,
+    deleted_count: receipt.deleted?.length ?? 0,
+    skipped_count: receipt.skipped?.length ?? 0,
+    reclaimed_bytes: receipt.reclaimed_space_bytes ?? 0,
+    current_pressure_units: receipt.pressure?.current_pressure_units ?? null,
+    projected_pressure_units: receipt.pressure?.projected_pressure_units ?? null,
+    preflight_status: receipt.pressure
+      ? ({ ok: "admissible", warn: "warn", fail: "refused" }[receipt.pressure.status] ?? "unknown")
+      : null,
+    ...(unavailable || ghostInventory ? { fault_class: eventKind } : {}),
+    cli_version: VERSION,
+    // Docker exposes the OrbStack VM kernel build, not the OrbStack app
+    // release. Leaving the version absent is scientifically safer than
+    // stratifying observations on a mislabeled kernel dimension.
+    docker_version: receipt.context?.server?.version ?? null,
+  };
+  // The parser treats omitted and null optional values equivalently, while
+  // JSON Schema correctly declares only the concrete scalar types. Keep the
+  // official CLI payload schema-valid by omitting absence rather than sending
+  // explicit nulls through strict MCP gateways.
+  return Object.fromEntries(Object.entries(event).filter(([, value]) => value != null));
+}
+
+async function reportReliability(result, options) {
+  const reportableOutage = result?.receipt?.context?.validation === "orbstack_unavailable";
+  if (!result?.receipt?.context?.server && !reportableOutage) return result;
+  const callTool = options.callTool ?? callToolJson;
+  const createDedupeKey = options.telemetryDedupeKey
+    ?? (() => `cli:${result.receipt.command}:${crypto.randomUUID()}`);
+  const telemetryNow = options.telemetryNow ?? options.workflowOptions?.now ?? (() => new Date());
+  let observedAt;
+  try {
+    observedAt = telemetryNow().toISOString();
+  } catch {
+    result.receipt.telemetry = { status: "unavailable", code: "invalid_observation_time" };
+    return result;
+  }
+  const telemetry = buildReliabilityTelemetry(result.receipt, { dedupeKey: createDedupeKey() });
+  if (!telemetry) return result;
+  const event = {
+    ...telemetry,
+    // The receipt timestamp marks command start. Measurement correlation must
+    // instead use the instant the complete inventory/safety decision exists;
+    // otherwise a bounded but slow Docker census can age a just-in-time
+    // preflight outside the stack-attempt correlation window.
+    observed_at: observedAt,
+  };
+  const controller = new AbortController();
+  const timeoutMs = options.telemetryTimeoutMs ?? TELEMETRY_TIMEOUT_MS;
+  // Race the ENTIRE tool call — credential resolution (resolveCallAuth, which can
+  // block on a macOS Keychain prompt) AND the HTTP request — against the timeout.
+  // runLocalExecPreflight routes through this wrapper and cmdUp awaits it, so
+  // aborting only the eventual fetch would let a blocked Keychain read hang stack
+  // admission despite the timer (BOT-1421 review). The abort is still fired.
+  let timer;
+  const TIMED_OUT = Symbol("reliability-telemetry-timeout");
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort(new Error("telemetry timeout"));
+      resolve(TIMED_OUT);
+    }, timeoutMs);
+  });
+  try {
+    const reported = await Promise.race([
+      callTool("report_host_reliability", event, { signal: controller.signal }),
+      timeout,
+    ]);
+    result.receipt.telemetry = reported === TIMED_OUT
+      ? { status: "unavailable", code: "report_timeout" }
+      : reported?.ok && !reported.isError && reported.data?.success !== false
+        ? { status: "reported", inserted: reported.data?.inserted !== false }
+        : reported?.ok
+          ? { status: "rejected", code: String(reported.data?.code || "report_rejected").slice(0, 80) }
+          : { status: "unavailable", code: String(reported?.error || "report_unavailable").slice(0, 80) };
+  } catch (error) {
+    result.receipt.telemetry = {
+      status: "unavailable",
+      code: error?.name === "AbortError" ? "report_timeout" : "report_unavailable",
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+  return result;
+}
+
 function addSkipOnce(receipt, item) {
   if (!receipt.skipped.some((existing) => existing.type === item.type && existing.id === item.id && existing.reason === item.reason)) {
     receipt.skipped.push(item);
@@ -833,6 +977,16 @@ export function runDockerWorkflow(argv, {
   } catch (error) {
     receipt.outcome = "error";
     receipt.errors = [error.message];
+    if (error.reliabilityEventKind === "orbstack_unavailable") {
+      receipt.context = {
+        requested: parsed.opts.context
+          ? { type: "context", value: parsed.opts.context }
+          : { type: "endpoint", value: parsed.opts.endpoint },
+        resolved_endpoint: error.resolvedEndpoint || parsed.opts.endpoint || null,
+        validation: "orbstack_unavailable",
+        server: null,
+      };
+    }
     return { exitCode: EXIT.DOCKER, receipt, json: parsed.opts.json };
   }
 
@@ -1025,6 +1179,7 @@ export function formatHumanReceipt(receipt) {
   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(`Reliability telemetry: ${receipt.telemetry?.status || "not_attempted"}`);
   for (const warning of receipt.warnings) lines.push(`Warning: ${warning}`);
   for (const error of receipt.errors) lines.push(`Error: ${error}`);
   if (receipt.recommendation) lines.push(`Next: ${receipt.recommendation}`);
@@ -1080,7 +1235,7 @@ export async function runDockerCommand(argv, options = {}) {
   const runWorkflow = options.runWorkflow ?? runDockerWorkflow;
   const workflowOptions = options.workflowOptions ?? {};
   if (parsed.errors.length > 0 || parsed.command !== "hygiene" || !parsed.opts.apply) {
-    return runWorkflow(argv, workflowOptions);
+    return reportReliability(await runWorkflow(argv, workflowOptions), options);
   }
 
   const resolveProjectId = options.resolveProjectId ?? resolveLocalProjectId;
@@ -1104,7 +1259,6 @@ export async function runDockerCommand(argv, options = {}) {
     if (result?.receipt?.authority) {
       result.receipt.authority.file_lock = { project_id: projectId, path: fileLockPath, held: true, released: false };
     }
-    return result;
   } finally {
     fileLock.release();
     if (result?.receipt?.authority?.file_lock) {
@@ -1112,6 +1266,7 @@ export async function runDockerCommand(argv, options = {}) {
       result.receipt.authority.file_lock.released = true;
     }
   }
+  return reportReliability(result, options);
 }
 
 async function runDockerCommandWithBotBuddyLock(argv, {

package/src/stack.mjs

@@ -30,7 +30,7 @@ import { randomUUID } from "crypto";
 import { callToolJson } from "./api.mjs";
 import { SERVER_URL, getConfig } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
-import { runDockerWorkflow } from "./docker-hygiene.mjs";
+import { runDockerCommand, runDockerWorkflow } from "./docker-hygiene.mjs";
 import { bold, dim, yellow } from "./utils.mjs";
 
 export const STACK_SCHEMA_VERSION = 1;
@@ -497,7 +497,15 @@ const nonQueued = (s) => s != null && s !== "queued";
 const isReaped = (s) => s === "reaping" || s === "reaped";
 
 /** Read-only pressure gate used before local managed-stack provisioning. */
-export function runLocalExecPreflight(opts, runWorkflow = runDockerWorkflow) {
+export async function runLocalExecPreflight(opts, runCommand = runDockerCommand) {
+  const selector = opts.dockerContext
+    ? ["--context", opts.dockerContext]
+    : ["--endpoint", opts.dockerEndpoint];
+  return runCommand(["preflight", ...selector, "--json"]);
+}
+
+/** Read-only daemon identity check for teardown; never report provision telemetry. */
+export async function runLocalExecTargetCheck(opts, runWorkflow = runDockerWorkflow) {
   const selector = opts.dockerContext
     ? ["--context", opts.dockerContext]
     : ["--endpoint", opts.dockerEndpoint];
@@ -670,7 +678,7 @@ export async function cmdUp(opts, {
   let localPreflight = null;
   let localDockerTarget = null;
   if (opts.localExec) {
-    const checked = runPreflight(opts);
+    const checked = await runPreflight(opts);
     localPreflight = compactPreflight(checked.receipt);
     localDockerTarget = dockerTargetFromPreflight(checked.receipt);
     if (checked.exitCode !== 0 || !localDockerTarget) {
@@ -725,7 +733,7 @@ export async function cmdUp(opts, {
       // Capacity may have changed while this command was queued. Re-run the
       // non-mutating gate immediately before `supabase start`; on refusal,
       // release the minted lease and never invoke the local provisioner.
-      const checked = runPreflight(opts);
+      const checked = await runPreflight(opts);
       localPreflight = compactPreflight(checked.receipt);
       localDockerTarget = dockerTargetFromPreflight(checked.receipt);
       if (checked.exitCode !== 0 || !localDockerTarget) {
@@ -740,10 +748,41 @@ export async function cmdUp(opts, {
           lease_cancellation: leaseCancellation,
         }), opts, EXIT.LEASE_FAILED);
       }
+      // Reserve the queued provision job for THIS agent BEFORE `supabase start`.
+      // Otherwise a Helper can claim it while the local provisioner runs, winning
+      // the later activation race and leaving an untracked local stack (two
+      // provisioners contending for one slot). If the reservation is LOST, nothing
+      // local has started yet, so it is safe to atomically release the minted lease
+      // and free the slot (BOT-1421 review).
+      // Persist the validated Docker target with the reservation so that if the
+      // provisioner partially starts a stack and then fails, the fenced lease can
+      // still be torn down by `stack done --local-exec` (BOT-1421 review).
+      const reserved = await callTool("reserve_stack_lease", {
+        lease_id: leaseId,
+        connection: connectionWithDockerTarget({}, localDockerTarget),
+      });
+      if (!reserved.ok || !reserved.data?.success) {
+        const cancelled = await callTool("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+        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" };
+        return emitResult(buildReceipt({
+          command: "up", outcome: "error", lease_id: leaseId, state, slot,
+          error: reserved.data?.code || reserved.error || "could not reserve the provision job for local execution",
+          lease_cancellation: leaseCancellation,
+        }), opts, EXIT.LEASE_FAILED);
+      }
       let conn;
       try {
         conn = connectionWithDockerTarget(localProvisionFn(opts, localDockerTarget), localDockerTarget);
       } catch (e) {
+        // Once the local provisioner has run, `supabase start` may have created
+        // (or fully started) containers even on a nonzero exit or a status-parse
+        // failure. Cancelling here would reap the lease and free the slot while
+        // that stack is still up — the exact orphaned/contended-slot hazard this
+        // change closes. Leave the lease FENCED (provisioning, reserved to us) so
+        // `botbuddy stack done` / the reaper tears the stack down first (BOT-1421
+        // review); do NOT cancel.
         return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: e.message }), opts, EXIT.LEASE_FAILED);
       }
       const act = await callTool("activate_stack_lease", { lease_id: leaseId, connection: conn });
@@ -795,7 +834,7 @@ async function cmdTouch(leaseId, opts) {
 
 export async function cmdDone(leaseId, opts, {
   callTool = callToolJson,
-  runPreflight = runLocalExecPreflight,
+  runPreflight = runLocalExecTargetCheck,
   proveLegacyTarget = proveLegacyLocalExecTarget,
   localTeardownFn = localTeardown,
   emitResult = emit,
@@ -811,7 +850,7 @@ export async function cmdDone(leaseId, opts, {
     }
     const expected = current.data.connection?.botbuddy_docker_target;
     let checked;
-    try { checked = runPreflight(opts); } catch (error) {
+    try { checked = await runPreflight(opts); } catch (error) {
       return emitResult(buildReceipt({ command: "done", outcome: "refused", lease_id: leaseId,
         error: `could not validate teardown Docker target: ${error.message}` }), opts, EXIT.LEASE_FAILED);
     }