@botbuddy/cli 1.4.1 → 1.5.0

package/src/docker-hygiene.mjs

@@ -0,0 +1,1062 @@
+// BOT-1405 — dry-run-first OrbStack/Supabase hygiene.
+//
+// This module deliberately uses Docker's narrow object removal commands. It
+// never constructs a prune, volume, force-remove, or context-switch command.
+// Every daemon operation carries an explicit --context or --host selector.
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { callToolJson } from "./api.mjs";
+import { acquireStackLock, lockPathForProject, projectIdFromConfig } from "./stack-file-lock.mjs";
+
+export const SCHEMA_VERSION = 1;
+export const DEFAULT_PROJECTED_ENDPOINTS = 10;
+export const DEFAULT_WARN_PRESSURE = 192;
+export const DEFAULT_FAIL_PRESSURE = 224;
+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;
+
+export const EXIT = Object.freeze({
+  OK: 0,
+  PRESSURE: 2,
+  INVALID: 4,
+  DOCKER: 5,
+  DELETE_FAILED: 6,
+  UNSUPPORTED: 7,
+});
+
+export const DOCKER_HELP = `botbuddy docker — safe local OrbStack/Supabase hygiene
+
+USAGE
+  botbuddy docker hygiene (--context <name> | --endpoint <uri>) [--ticket <BOT|ENT-N>] [--json]
+  botbuddy docker hygiene (--context <name> | --endpoint <uri>) --apply
+      --ticket <BOT|ENT-N> --lock-slot <stable-slot>
+      --candidate-id <id> [--candidate-id <id> ...] [--json]
+  botbuddy docker preflight (--context <name> | --endpoint <uri>) [options] [--json]
+
+COMMANDS
+  hygiene      Inventory stopped Supabase containers and empty
+               supabase_network_* bridge networks. This is a dry-run unless
+               --apply is explicitly present.
+  preflight    Read-only network-pressure check for a prospective managed stack.
+
+REQUIRED SELECTOR
+  --context <name>     Explicit Docker context, e.g. orbstack
+  --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.
+
+HYGIENE OPTIONS
+  --ticket <BOT|ENT-N> Scope discovery/apply to the owning ticket's project.
+  --lock-slot <slot>   Stable supabase_local slot used by the stack lifecycle.
+                       Apply acquires it on this machine before Docker inventory.
+  --candidate-id <id>  Exact reviewed dry-run candidate to apply; repeatable.
+  --apply              Delete only the ticket-owned reviewed IDs after revalidation.
+                       Without it, no mutation.
+  --json               Emit exactly one compact machine-readable receipt.
+
+PREFLIGHT OPTIONS
+  --projected-endpoints <n>  Expected endpoints in the new stack (default ${DEFAULT_PROJECTED_ENDPOINTS})
+  --warn-pressure <n>        Warn threshold (default ${DEFAULT_WARN_PRESSURE})
+  --fail-pressure <n>        Refuse threshold (default ${DEFAULT_FAIL_PRESSURE})
+  --json                       Emit exactly one compact machine-readable receipt.
+
+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.
+  • Apply first holds the same project file lock as repository test lanes, then
+    holds the matching BotBuddy supabase_local lock for the whole transaction.
+  • Reentrant lock grants are refused; cleanup is bounded to five minutes and
+    stops at least one minute before the advertised lock expiry.
+  • Apply requires the exact candidate IDs copied from the reviewed dry run.
+  • Removes only stopped, project-labelled Supabase containers in inactive stacks.
+  • Removes only empty supabase_network_* bridge networks in inactive stacks.
+  • Re-inspects every candidate immediately before deletion.
+  • Never force-removes a resource, never runs a prune command, and never removes volumes.
+
+EXAMPLES
+  botbuddy docker hygiene --context orbstack --ticket BOT-1405 --json
+  botbuddy docker hygiene --context orbstack --apply --ticket BOT-1405 \\
+    --lock-slot botbuddy-web-bot-1405 \\
+    --candidate-id 0123456789abcdef
+  botbuddy docker preflight --context orbstack --json`;
+
+const BUILTIN_NETWORKS = new Set(["bridge", "host", "none"]);
+// `created` is treated as active because Docker Compose may have created a
+// project's resources before its first container reaches running state.
+const ACTIVE_STATES = new Set(["created", "running", "paused", "restarting", "removing"]);
+
+function positiveInteger(value, option, errors, { allowZero = false } = {}) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < (allowZero ? 0 : 1)) {
+    errors.push(`${option} must be ${allowZero ? "a non-negative" : "a positive"} integer`);
+    return null;
+  }
+  return parsed;
+}
+
+export function parseDockerArgs(argv) {
+  const [command, ...rest] = argv;
+  const errors = [];
+  const opts = {
+    context: null,
+    endpoint: null,
+    ticket: null,
+    lockSlot: null,
+    candidateIds: [],
+    apply: false,
+    json: false,
+    projectedEndpoints: DEFAULT_PROJECTED_ENDPOINTS,
+    warnPressure: DEFAULT_WARN_PRESSURE,
+    failPressure: DEFAULT_FAIL_PRESSURE,
+  };
+
+  const needValue = (option, index) => {
+    const value = rest[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+      errors.push(`${option} needs a value`);
+      return null;
+    }
+    return value;
+  };
+
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    switch (arg) {
+      case "--context": {
+        const value = needValue(arg, i);
+        if (value !== null) {
+          opts.context = value;
+          i += 1;
+        }
+        break;
+      }
+      case "--endpoint": {
+        const value = needValue(arg, i);
+        if (value !== null) {
+          opts.endpoint = value;
+          i += 1;
+        }
+        break;
+      }
+      case "--ticket": {
+        const value = needValue(arg, i);
+        if (value !== null) {
+          opts.ticket = value.toUpperCase();
+          i += 1;
+        }
+        break;
+      }
+      case "--candidate-id": {
+        const value = needValue(arg, i);
+        if (value !== null) {
+          opts.candidateIds.push(value);
+          i += 1;
+        }
+        break;
+      }
+      case "--lock-slot": {
+        const value = needValue(arg, i);
+        if (value !== null) {
+          opts.lockSlot = value;
+          i += 1;
+        }
+        break;
+      }
+      case "--projected-endpoints": {
+        const value = needValue(arg, i);
+        if (value !== null) {
+          opts.projectedEndpoints = positiveInteger(value, arg, errors, { allowZero: true });
+          i += 1;
+        }
+        break;
+      }
+      case "--warn-pressure": {
+        const value = needValue(arg, i);
+        if (value !== null) {
+          opts.warnPressure = positiveInteger(value, arg, errors);
+          i += 1;
+        }
+        break;
+      }
+      case "--fail-pressure": {
+        const value = needValue(arg, i);
+        if (value !== null) {
+          opts.failPressure = positiveInteger(value, arg, errors);
+          i += 1;
+        }
+        break;
+      }
+      case "--apply": opts.apply = true; break;
+      case "--json": opts.json = true; break;
+      case "--help":
+      case "-h":
+        break;
+      default:
+        errors.push(`unknown option: ${arg}`);
+    }
+  }
+
+  if (!command || !["hygiene", "preflight", "help"].includes(command)) {
+    errors.push(`unknown docker command: ${command ?? "(missing)"}`);
+  }
+  if (command !== "help") {
+    if (Boolean(opts.context) === Boolean(opts.endpoint)) {
+      errors.push("exactly one of --context <name> or --endpoint <uri> is required");
+    }
+    if (command === "preflight" && opts.apply) errors.push("--apply is not valid for the read-only preflight command");
+    if (opts.ticket && !/^(BOT|ENT)-[1-9][0-9]*$/.test(opts.ticket)) {
+      errors.push("--ticket must be a BOT-N or ENT-N identifier");
+    }
+    if (new Set(opts.candidateIds).size !== opts.candidateIds.length) {
+      errors.push("--candidate-id values must be unique");
+    }
+    if (command === "preflight" && (opts.ticket || opts.lockSlot || opts.candidateIds.length > 0)) {
+      errors.push("--ticket, --lock-slot, and --candidate-id are not valid for preflight");
+    }
+    if (command === "hygiene" && !opts.apply && opts.lockSlot) errors.push("--lock-slot is valid only together with --apply");
+    if (command === "hygiene" && !opts.apply && opts.candidateIds.length > 0) {
+      errors.push("--candidate-id is valid only together with --apply");
+    }
+    if (command === "hygiene" && opts.apply) {
+      if (!opts.ticket) errors.push("--apply requires --ticket <BOT|ENT-N> as cleanup authority");
+      if (!opts.lockSlot || opts.lockSlot === "default") errors.push("--apply requires a non-default --lock-slot from the owning stack lifecycle");
+      if (opts.candidateIds.length === 0) errors.push("--apply requires at least one exact --candidate-id from the reviewed dry run");
+    }
+    if (opts.warnPressure !== null && opts.failPressure !== null && opts.failPressure <= opts.warnPressure) {
+      errors.push("--fail-pressure must be greater than --warn-pressure");
+    }
+  }
+
+  return { command, opts, errors };
+}
+
+function defaultDockerRunner(args, { timeoutMs = MAX_DOCKER_COMMAND_MS } = {}) {
+  const env = { ...process.env };
+  delete env.DOCKER_CONTEXT;
+  delete env.DOCKER_HOST;
+  return spawnSync("docker", args, {
+    encoding: "utf8",
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+    maxBuffer: 4 * 1024 * 1024,
+    timeout: timeoutMs,
+  });
+}
+
+function deadlineBoundDockerRunner(runDocker, deadlineAt, monotonicNow) {
+  let budgetExpired = false;
+  return (args) => {
+    if (budgetExpired) {
+      return { status: null, stdout: "", stderr: "lock safety budget expired before Docker access" };
+    }
+    const remainingMs = deadlineAt - monotonicNow();
+    if (remainingMs <= 0) {
+      budgetExpired = true;
+      return { status: null, stdout: "", stderr: "lock safety budget expired before Docker access" };
+    }
+    const result = runDocker(args, { timeoutMs: Math.max(1, Math.min(MAX_DOCKER_COMMAND_MS, remainingMs)) });
+    if (monotonicNow() > deadlineAt) {
+      budgetExpired = true;
+      // A successful exact-ID removal is irreversible. Preserve its stdout/status
+      // so the receipt remains truthful, then let the workflow record the deletion
+      // and stop before issuing another Docker command.
+      if (!result?.error && result?.status === 0) {
+        return { ...result, budgetExpiredAfterSuccess: true };
+      }
+      return { status: null, stdout: "", stderr: "lock safety budget expired during Docker access" };
+    }
+    return result;
+  };
+}
+
+function defaultBranchResolver() {
+  const result = spawnSync("git", ["branch", "--show-current"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    maxBuffer: 64 * 1024,
+  });
+  if (result?.error || result?.status !== 0) {
+    throw new Error("apply must run from the owning ticket worktree (unable to resolve the current Git branch)");
+  }
+  const branch = String(result.stdout || "").trim();
+  if (!branch) throw new Error("apply must run from the owning ticket worktree (detached or empty Git branch)");
+  return branch;
+}
+
+function boundedArgv(args) {
+  if (args.length <= 10) return args.join(" ");
+  return `${args.slice(0, 10).join(" ")} … (${args.length - 10} more arguments)`;
+}
+
+function commandFailure(args, result) {
+  const detail = String(result?.stderr || result?.error?.message || "Docker command failed")
+    .trim()
+    .replace(/\s+/g, " ")
+    .slice(0, 500);
+  return new Error(`docker ${boundedArgv(args)} failed (exit ${result?.status ?? "spawn"})${detail ? `: ${detail}` : ""}`);
+}
+
+function runChecked(runDocker, args) {
+  const result = runDocker(args);
+  if (result?.error || result?.status !== 0) throw commandFailure(args, result);
+  return String(result.stdout || "");
+}
+
+function parseJson(text, label) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${label} returned malformed JSON`);
+  }
+}
+
+function selectorArgs(opts) {
+  return opts.context ? ["--context", opts.context] : ["--host", opts.endpoint];
+}
+
+function selected(runDocker, selector, args) {
+  return runChecked(runDocker, [...selector, ...args]);
+}
+
+function nonEmptyLines(text) {
+  return text.split(/\r?\n/).map((value) => value.trim()).filter(Boolean);
+}
+
+function inspectInBatches(runDocker, selector, kind, ids, extraArgs = []) {
+  const resources = [];
+  for (let offset = 0; offset < ids.length; offset += INSPECT_BATCH_SIZE) {
+    const batch = ids.slice(offset, offset + INSPECT_BATCH_SIZE);
+    const inspected = parseJson(
+      selected(runDocker, selector, [kind, "inspect", ...extraArgs, ...batch]),
+      `docker ${kind} inspect`,
+    );
+    if (!Array.isArray(inspected)) throw new Error(`Docker ${kind} inventory returned an unexpected shape`);
+    resources.push(...inspected);
+  }
+  return resources;
+}
+
+function projectIdentity(resource) {
+  const labels = resource?.Config?.Labels || resource?.Labels || {};
+  const value = labels["com.supabase.cli.project"] || labels["com.docker.compose.project"];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+export function projectMatchesTicket(project, ticket) {
+  if (typeof project !== "string" || typeof ticket !== "string") return false;
+  const match = /^(BOT|ENT)-([1-9][0-9]*)$/.exec(ticket.toUpperCase());
+  if (!match) return false;
+  const [, team, number] = match;
+  const prefixes = team === "BOT" ? ["bot"] : ["ent", "sgent"];
+  const parts = project.toLowerCase().split(/[-_]+/).filter(Boolean);
+  return parts.some((part, index) => prefixes.some((prefix) => (
+    part === `${prefix}${number}` || (part === prefix && parts[index + 1] === number)
+  )));
+}
+
+export function branchMatchesTicket(branch, ticket) {
+  if (typeof branch !== "string" || typeof ticket !== "string") return false;
+  const match = /^(BOT|ENT)-([1-9][0-9]*)$/.exec(ticket.toUpperCase());
+  if (!match) return false;
+  const [, team, number] = match;
+  const prefix = team.toLowerCase();
+  const parts = branch.toLowerCase().split(/[/_-]+/).filter(Boolean);
+  return parts.some((part, index) => part === `${prefix}${number}`
+    || (part === prefix && parts[index + 1] === number));
+}
+
+export function lockSlotForProject(project, ticket) {
+  if (!projectMatchesTicket(project, ticket)) return null;
+  return ticket.toUpperCase().startsWith("ENT-") ? `supplyspark-ent-${project}` : project;
+}
+
+function containerName(resource) {
+  return String(resource?.Name || "").replace(/^\//, "");
+}
+
+function isActiveContainer(resource) {
+  const state = resource?.State || {};
+  return Boolean(state.Running || state.Paused || state.Restarting || state.Removing)
+    || ACTIVE_STATES.has(String(state.Status || "").toLowerCase());
+}
+
+function resourceSort(left, right) {
+  const typeOrder = { container: 0, network: 1 };
+  return (typeOrder[left.type] ?? 9) - (typeOrder[right.type] ?? 9)
+    || String(left.name).localeCompare(String(right.name))
+    || String(left.id).localeCompare(String(right.id));
+}
+
+function skippedResource(type, resource, reason, extra = {}) {
+  return {
+    type,
+    id: String(resource?.Id || ""),
+    name: type === "container" ? containerName(resource) : String(resource?.Name || ""),
+    project: projectIdentity(resource),
+    reason,
+    ...extra,
+  };
+}
+
+export function classifyInventory({ containers = [], networks = [] } = {}) {
+  const activeProjects = new Set();
+  for (const resource of containers) {
+    const name = containerName(resource);
+    const project = projectIdentity(resource);
+    if (name.startsWith("supabase_") && project && isActiveContainer(resource)) activeProjects.add(project);
+  }
+
+  const candidates = [];
+  const skipped = [];
+  let supabaseContainers = 0;
+
+  for (const resource of containers) {
+    const name = containerName(resource);
+    if (!name.startsWith("supabase_")) continue;
+    supabaseContainers += 1;
+    if (isActiveContainer(resource)) continue;
+    const project = projectIdentity(resource);
+    if (!project) {
+      skipped.push(skippedResource("container", resource, "missing_project_identity"));
+      continue;
+    }
+    if (activeProjects.has(project)) {
+      skipped.push(skippedResource("container", resource, "active_stack"));
+      continue;
+    }
+    candidates.push({
+      type: "container",
+      id: String(resource.Id),
+      name,
+      project,
+      state: String(resource?.State?.Status || "stopped"),
+      reclaimable_bytes: Number.isFinite(Number(resource.SizeRw)) ? Number(resource.SizeRw) : 0,
+    });
+  }
+
+  let supabaseNetworks = 0;
+  let userBridgeNetworks = 0;
+  let attachedEndpoints = 0;
+  for (const resource of networks) {
+    const name = String(resource?.Name || "");
+    const driver = String(resource?.Driver || "");
+    const attachments = resource?.Containers && typeof resource.Containers === "object"
+      ? Object.keys(resource.Containers).length
+      : 0;
+    if (driver === "bridge" && !BUILTIN_NETWORKS.has(name)) {
+      userBridgeNetworks += 1;
+      attachedEndpoints += attachments;
+    }
+    if (!name.startsWith("supabase_network_")) continue;
+    supabaseNetworks += 1;
+    if (BUILTIN_NETWORKS.has(name)) {
+      skipped.push(skippedResource("network", resource, "built_in_network", { driver, attached_containers: attachments }));
+      continue;
+    }
+    if (driver !== "bridge") {
+      skipped.push(skippedResource("network", resource, "non_bridge_network", { driver, attached_containers: attachments }));
+      continue;
+    }
+    const project = projectIdentity(resource);
+    if (!project) {
+      skipped.push(skippedResource("network", resource, "missing_project_identity", { driver, attached_containers: attachments }));
+      continue;
+    }
+    if (attachments > 0) {
+      skipped.push(skippedResource("network", resource, "attached_containers", { driver, attached_containers: attachments }));
+      continue;
+    }
+    if (activeProjects.has(project)) {
+      skipped.push(skippedResource("network", resource, "active_stack", { driver, attached_containers: 0 }));
+      continue;
+    }
+    candidates.push({
+      type: "network",
+      id: String(resource.Id),
+      name,
+      project,
+      driver,
+      attached_containers: 0,
+      reclaimable_bytes: 0,
+    });
+  }
+
+  return {
+    active_projects: [...activeProjects].sort(),
+    candidates: candidates.sort(resourceSort),
+    skipped: skipped.sort(resourceSort),
+    counts: {
+      containers: containers.length,
+      networks: networks.length,
+      supabase_containers: supabaseContainers,
+      supabase_networks: supabaseNetworks,
+      user_bridge_networks: userBridgeNetworks,
+      attached_endpoints: attachedEndpoints,
+    },
+  };
+}
+
+function readInventory(runDocker, selector) {
+  const containerIds = nonEmptyLines(selected(runDocker, selector, ["container", "ls", "--all", "--quiet", "--no-trunc", "--filter", "name=supabase_"]));
+  const containers = containerIds.length
+    ? inspectInBatches(runDocker, selector, "container", containerIds, ["--size"])
+    : [];
+  const networkIds = nonEmptyLines(selected(runDocker, selector, ["network", "ls", "--quiet", "--no-trunc"]));
+  const networks = networkIds.length
+    ? inspectInBatches(runDocker, selector, "network", networkIds)
+    : [];
+  return { containers, networks };
+}
+
+function validateOrbStack(runDocker, opts) {
+  let resolvedEndpoint = 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`);
+  }
+
+  const selector = selectorArgs(opts);
+  const info = parseJson(selected(runDocker, selector, ["info", "--format", "{{json .}}"]), "docker info");
+  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"})`);
+  }
+
+  return {
+    selector,
+    receipt: {
+      requested: opts.context ? { type: "context", value: opts.context } : { type: "endpoint", value: opts.endpoint },
+      resolved_endpoint: resolvedEndpoint,
+      validation: "orbstack",
+      server: {
+        id: info.ID || null,
+        name: info.Name || null,
+        version: info.ServerVersion || null,
+        operating_system: info.OperatingSystem || null,
+        kernel_version: info.KernelVersion || null,
+      },
+    },
+  };
+}
+
+export function evaluatePressure({
+  bridgeNetworks,
+  attachedEndpoints,
+  projectedEndpoints = DEFAULT_PROJECTED_ENDPOINTS,
+  warn = DEFAULT_WARN_PRESSURE,
+  fail = DEFAULT_FAIL_PRESSURE,
+}) {
+  const current = Number(bridgeNetworks) + (2 * Number(attachedEndpoints));
+  const projected = current + 1 + (2 * Number(projectedEndpoints));
+  return {
+    metric: "conservative_network_pressure_units",
+    formula: "bridge_networks + (2 * attached_endpoints)",
+    current_pressure_units: current,
+    projected_pressure_units: projected,
+    projected_endpoints: Number(projectedEndpoints),
+    warn_pressure: Number(warn),
+    fail_pressure: Number(fail),
+    status: projected >= fail ? "fail" : projected >= warn ? "warn" : "ok",
+    note: "Conservative pressure proxy; OrbStack does not expose a kernel interface ceiling through the Docker API.",
+  };
+}
+
+function baseReceipt(command, opts, now) {
+  return {
+    schema_version: SCHEMA_VERSION,
+    command,
+    outcome: "ok",
+    apply: command === "hygiene" && opts.apply,
+    timestamp: now().toISOString(),
+    context: null,
+    inventory: null,
+    active_projects: [],
+    candidates: [],
+    candidate_reclaimable_bytes: 0,
+    deleted: [],
+    reclaimed_space_bytes: 0,
+    skipped: [],
+    pressure: null,
+    warnings: [],
+    errors: [],
+    recommendation: null,
+    authority: {
+      ticket: opts.ticket,
+      worktree_branch: null,
+      reviewed_candidate_ids: [...opts.candidateIds],
+      file_lock: null,
+      stack_lock: null,
+    },
+  };
+}
+
+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);
+    receipt.skipped.sort(resourceSort);
+  }
+}
+
+function recommendationFor(opts, apply = false, candidates = []) {
+  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 (!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;
+  const ids = candidates.map((item) => ` --candidate-id ${item.id}`).join("");
+  return ids
+    ? `botbuddy docker hygiene ${selector} --apply --ticket ${opts.ticket} --lock-slot ${lockSlot || "<owning-stack-slot>"}${ids}`
+    : `No ticket-owned candidates remain for ${opts.ticket}; do not run apply.`;
+}
+
+export function runDockerWorkflow(argv, {
+  runDocker = defaultDockerRunner,
+  resolveBranch = defaultBranchResolver,
+  lockAuthority = null,
+  deadlineAt = null,
+  monotonicNow = Date.now,
+  platform = process.platform,
+  now = () => new Date(),
+} = {}) {
+  const parsed = parseDockerArgs(argv);
+  const receipt = baseReceipt(parsed.command || "unknown", parsed.opts, now);
+
+  if (parsed.errors.length > 0) {
+    receipt.outcome = "error";
+    receipt.errors = parsed.errors;
+    return { exitCode: EXIT.INVALID, receipt, json: parsed.opts.json };
+  }
+  if (platform !== "darwin") {
+    receipt.outcome = "error";
+    receipt.errors = [`unsupported platform: ${platform}; OrbStack hygiene is macOS-only`];
+    return { exitCode: EXIT.UNSUPPORTED, receipt, json: parsed.opts.json };
+  }
+  if (parsed.opts.apply) {
+    try {
+      const branch = resolveBranch();
+      receipt.authority.worktree_branch = branch;
+      if (!branchMatchesTicket(branch, parsed.opts.ticket)) {
+        throw new Error(`current branch ${branch} does not own ${parsed.opts.ticket}; run apply from that ticket's worktree`);
+      }
+    } catch (error) {
+      receipt.outcome = "refused";
+      receipt.errors = [error.message];
+      return { exitCode: EXIT.INVALID, receipt, json: parsed.opts.json };
+    }
+    if (!lockAuthority?.held || lockAuthority.slot !== parsed.opts.lockSlot) {
+      receipt.outcome = "refused";
+      receipt.errors = ["apply requires a confirmed BotBuddy supabase_local lock for --lock-slot before Docker inventory"];
+      return { exitCode: EXIT.DOCKER, receipt, json: parsed.opts.json };
+    }
+    receipt.authority.stack_lock = {
+      host: lockAuthority.host,
+      slot: lockAuthority.slot,
+      resource_id: lockAuthority.resourceId || null,
+      resource_name: lockAuthority.resourceName || null,
+      granted_seconds_remaining: lockAuthority.secondsRemaining || null,
+      apply_budget_ms: lockAuthority.applyBudgetMs || null,
+      held: true,
+    };
+    deadlineAt ??= monotonicNow() + MAX_APPLY_BUDGET_MS;
+    runDocker = deadlineBoundDockerRunner(runDocker, deadlineAt, monotonicNow);
+  }
+
+  let validated;
+  let inventory;
+  try {
+    validated = validateOrbStack(runDocker, parsed.opts);
+    receipt.context = validated.receipt;
+    inventory = classifyInventory(readInventory(runDocker, validated.selector));
+    receipt.recommendation = recommendationFor(parsed.opts);
+  } catch (error) {
+    receipt.outcome = "error";
+    receipt.errors = [error.message];
+    return { exitCode: EXIT.DOCKER, receipt, json: parsed.opts.json };
+  }
+
+  receipt.inventory = inventory.counts;
+  receipt.active_projects = inventory.active_projects;
+  receipt.skipped = [...inventory.skipped];
+
+  const ticketCandidates = parsed.opts.ticket
+    ? inventory.candidates.filter((item) => projectMatchesTicket(item.project, parsed.opts.ticket))
+    : inventory.candidates;
+  if (parsed.opts.ticket) {
+    for (const item of inventory.candidates) {
+      if (!projectMatchesTicket(item.project, parsed.opts.ticket)) {
+        addSkipOnce(receipt, { ...item, reason: "ticket_mismatch" });
+      }
+    }
+  }
+  receipt.candidates = ticketCandidates;
+  receipt.candidate_reclaimable_bytes = ticketCandidates.reduce((total, item) => total + item.reclaimable_bytes, 0);
+
+  if (parsed.command === "preflight") {
+    receipt.pressure = evaluatePressure({
+      bridgeNetworks: inventory.counts.user_bridge_networks,
+      attachedEndpoints: inventory.counts.attached_endpoints,
+      projectedEndpoints: parsed.opts.projectedEndpoints,
+      warn: parsed.opts.warnPressure,
+      fail: parsed.opts.failPressure,
+    });
+    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.");
+    } 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.");
+      return { exitCode: EXIT.PRESSURE, receipt, json: parsed.opts.json };
+    }
+    return { exitCode: EXIT.OK, receipt, json: parsed.opts.json };
+  }
+
+  if (!parsed.opts.apply) {
+    receipt.outcome = "dry_run";
+    receipt.recommendation = recommendationFor(parsed.opts, true, ticketCandidates);
+    return { exitCode: EXIT.OK, receipt, json: parsed.opts.json };
+  }
+
+  const requestedCandidates = [];
+  for (const id of parsed.opts.candidateIds) {
+    const discovered = inventory.candidates.find((item) => item.id === id);
+    if (!discovered) {
+      receipt.errors.push(`candidate ${id} is not currently eligible; run a fresh ticket-scoped dry run`);
+      continue;
+    }
+    if (!projectMatchesTicket(discovered.project, parsed.opts.ticket)) {
+      receipt.errors.push(`candidate ${id} project ${discovered.project} does not belong to ${parsed.opts.ticket}`);
+      continue;
+    }
+    const expectedSlot = lockSlotForProject(discovered.project, parsed.opts.ticket);
+    if (parsed.opts.lockSlot !== expectedSlot) {
+      receipt.errors.push(`candidate ${id} project ${discovered.project} requires lock slot ${expectedSlot}, not ${parsed.opts.lockSlot}`);
+      continue;
+    }
+    requestedCandidates.push(discovered);
+  }
+  if (receipt.errors.length > 0) {
+    receipt.outcome = "refused";
+    return { exitCode: EXIT.INVALID, receipt, json: parsed.opts.json };
+  }
+
+  for (const candidate of requestedCandidates) {
+    let fresh;
+    try {
+      fresh = classifyInventory(readInventory(runDocker, validated.selector));
+    } catch (error) {
+      receipt.errors.push(`revalidation failed before ${candidate.type} ${candidate.id}: ${error.message}`);
+      addSkipOnce(receipt, { ...candidate, reason: "revalidation_failed" });
+      continue;
+    }
+    const revalidated = fresh.candidates.find((item) => item.type === candidate.type
+      && item.id === candidate.id
+      && projectMatchesTicket(item.project, parsed.opts.ticket));
+    if (!revalidated) {
+      const refusal = fresh.skipped.find((item) => item.type === candidate.type && item.id === candidate.id);
+      const skipped = refusal || { ...candidate, reason: "disappeared" };
+      addSkipOnce(receipt, skipped);
+      receipt.errors.push(`candidate ${candidate.id} refused during revalidation: ${skipped.reason}`);
+      continue;
+    }
+
+    const args = candidate.type === "container"
+      ? [...validated.selector, "container", "rm", candidate.id]
+      : [...validated.selector, "network", "rm", candidate.id];
+    const result = runDocker(args);
+    if (result?.error || result?.status !== 0) {
+      const error = commandFailure(args, result);
+      receipt.errors.push(error.message);
+      addSkipOnce(receipt, { ...candidate, reason: "delete_failed" });
+      continue;
+    }
+    receipt.deleted.push({
+      type: candidate.type,
+      id: candidate.id,
+      name: candidate.name,
+      project: candidate.project,
+      reclaimed_bytes: candidate.reclaimable_bytes,
+    });
+    receipt.reclaimed_space_bytes += candidate.reclaimable_bytes;
+    if (result.budgetExpiredAfterSuccess) {
+      receipt.errors.push(`lock safety budget expired after successful ${candidate.type} deletion ${candidate.id}; deletion evidence was preserved and further Docker access was stopped`);
+      break;
+    }
+  }
+
+  if (receipt.errors.length > 0) {
+    receipt.outcome = receipt.deleted.length > 0 ? "partial_failure" : "refused";
+    return { exitCode: EXIT.DELETE_FAILED, receipt, json: parsed.opts.json };
+  }
+  receipt.outcome = "applied";
+  receipt.recommendation = "Cleanup complete; run botbuddy docker preflight with the same explicit selector before starting the next managed stack.";
+  return { exitCode: EXIT.OK, receipt, json: parsed.opts.json };
+}
+
+export function formatBytes(bytes) {
+  const value = Number(bytes) || 0;
+  if (value < 1024) return `${value} B`;
+  const units = ["KiB", "MiB", "GiB", "TiB"];
+  let current = value;
+  let unit = -1;
+  do {
+    current /= 1024;
+    unit += 1;
+  } while (current >= 1024 && unit < units.length - 1);
+  return `${current.toFixed(current >= 10 ? 1 : 2)} ${units[unit]}`;
+}
+
+export function formatHumanReceipt(receipt) {
+  const context = receipt.context
+    ? `${receipt.context.requested.type}=${receipt.context.requested.value} → ${receipt.context.resolved_endpoint}`
+    : "not validated";
+  const lines = [
+    `[botbuddy docker] ${receipt.command}: ${receipt.outcome}`,
+    `Context: ${context}`,
+  ];
+  if (receipt.context?.server) {
+    lines.push(`Server: ${receipt.context.server.operating_system} ${receipt.context.server.version || "unknown"} (${receipt.context.server.kernel_version || "unknown kernel"})`);
+  }
+  if (receipt.inventory) {
+    lines.push(`Inventory: ${receipt.inventory.supabase_containers} Supabase containers; ${receipt.inventory.supabase_networks} Supabase networks; active projects: ${receipt.active_projects.join(", ") || "none"}`);
+  }
+  lines.push(receipt.authority?.ticket
+    ? `Authority: ticket=${receipt.authority.ticket}; branch=${receipt.authority.worktree_branch || "dry-run only"}; reviewed IDs=${receipt.authority.reviewed_candidate_ids.join(", ") || "none (dry run)"}`
+    : "Authority: detection-only; pass an owning ticket before selecting apply IDs");
+  if (receipt.authority?.stack_lock) {
+    lines.push(`Stack lock: host=${receipt.authority.stack_lock.host}; slot=${receipt.authority.stack_lock.slot}; granted=${receipt.authority.stack_lock.granted_seconds_remaining || "unknown"}s; budget=${receipt.authority.stack_lock.apply_budget_ms || "unknown"}ms; released=${receipt.authority.stack_lock.released === true}`);
+  }
+  lines.push(`Candidates (${receipt.candidates.length}, potential ${formatBytes(receipt.candidate_reclaimable_bytes)}):`);
+  for (const item of receipt.candidates) lines.push(`  ${item.type} ${item.id} ${item.name} project=${item.project}`);
+  if (receipt.candidates.length === 0) lines.push("  none");
+  lines.push(`Deleted (${receipt.deleted.length}, reclaimed ${formatBytes(receipt.reclaimed_space_bytes)}):`);
+  for (const item of receipt.deleted) lines.push(`  ${item.type} ${item.id} ${item.name}`);
+  if (receipt.deleted.length === 0) lines.push("  none");
+  lines.push(`Skipped (${receipt.skipped.length}):`);
+  for (const item of receipt.skipped) lines.push(`  ${item.type} ${item.id} ${item.name} — ${item.reason}`);
+  if (receipt.skipped.length === 0) lines.push("  none");
+  if (receipt.pressure) {
+    lines.push(`Pressure: ${receipt.pressure.projected_pressure_units} projected (${receipt.pressure.status}; warn ${receipt.pressure.warn_pressure}, fail ${receipt.pressure.fail_pressure})`);
+  }
+  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}`);
+  return lines.join("\n");
+}
+
+export function cmdDocker(argv) {
+  if (argv.length === 0 || argv[0] === "help" || argv.includes("--help") || argv.includes("-h")) {
+    console.log(DOCKER_HELP);
+    return;
+  }
+  return runDockerCommand(argv).then((result) => {
+    if (result.json) console.log(JSON.stringify(result.receipt));
+    else console.log(formatHumanReceipt(result.receipt));
+    if (result.exitCode !== EXIT.OK) process.exitCode = result.exitCode;
+  });
+}
+
+function refusedResult(argv, message, exitCode = EXIT.DOCKER, now = () => new Date()) {
+  const parsed = parseDockerArgs(argv);
+  const receipt = baseReceipt(parsed.command || "unknown", parsed.opts, now);
+  receipt.outcome = "refused";
+  receipt.errors = [message];
+  return { exitCode, receipt, json: parsed.opts.json };
+}
+
+function lockIdentity(data) {
+  const raw = typeof data?.raw === "string" ? data.raw : typeof data?.message === "string" ? data.message : "";
+  const resourceId = raw.match(/\[resource_id: ([0-9a-f-]+)\]/i)?.[1] || data?.resource_id || null;
+  const resourceLockId = data?.resource_lock_id || null;
+  const resourceName = raw.match(/\(resource: ([^)]+)\)/)?.[1] || data?.resource_name || data?.resource || null;
+  return { resourceId, resourceLockId, resourceName };
+}
+
+function lockGrantTiming(data) {
+  const raw = typeof data?.raw === "string" ? data.raw : typeof data?.message === "string" ? data.message : "";
+  const secondsRemaining = Number(data?.seconds_remaining ?? raw.match(/~([0-9]+)s\)/i)?.[1]);
+  return {
+    alreadyHeld: data?.already_held === true || /already held/i.test(raw),
+    secondsRemaining: Number.isFinite(secondsRemaining) && secondsRemaining > 0 ? secondsRemaining : null,
+  };
+}
+
+function resolveLocalProjectId() {
+  const config = readFileSync("supabase/config.toml", "utf8");
+  const projectId = projectIdFromConfig(config);
+  if (!projectId) throw new Error("supabase/config.toml has no project_id");
+  return projectId;
+}
+
+export async function runDockerCommand(argv, options = {}) {
+  const parsed = parseDockerArgs(argv);
+  const runWorkflow = options.runWorkflow ?? runDockerWorkflow;
+  const workflowOptions = options.workflowOptions ?? {};
+  if (parsed.errors.length > 0 || parsed.command !== "hygiene" || !parsed.opts.apply) {
+    return runWorkflow(argv, workflowOptions);
+  }
+
+  const resolveProjectId = options.resolveProjectId ?? resolveLocalProjectId;
+  const fileLockPathForProject = options.fileLockPathForProject ?? lockPathForProject;
+  const acquireFileLock = options.acquireFileLock ?? acquireStackLock;
+  let projectId;
+  let fileLockPath;
+  let fileLock;
+  try {
+    projectId = resolveProjectId();
+    if (!projectId) throw new Error("project identity is empty");
+    fileLockPath = fileLockPathForProject(projectId);
+    fileLock = await acquireFileLock(fileLockPath);
+  } catch (error) {
+    return refusedResult(argv, `cross-worktree Supabase file lock not acquired: ${error.message}`, EXIT.DOCKER, workflowOptions.now);
+  }
+
+  let result;
+  try {
+    result = await runDockerCommandWithBotBuddyLock(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) {
+      result.receipt.authority.file_lock.held = false;
+      result.receipt.authority.file_lock.released = true;
+    }
+  }
+}
+
+async function runDockerCommandWithBotBuddyLock(argv, {
+  callTool = callToolJson,
+  runWorkflow = runDockerWorkflow,
+  workflowOptions = {},
+  machineHost = hostname(),
+  monotonicNow = Date.now,
+} = {}) {
+  const parsed = parseDockerArgs(argv);
+  if (parsed.errors.length > 0 || parsed.command !== "hygiene" || !parsed.opts.apply) {
+    return runWorkflow(argv, workflowOptions);
+  }
+
+  const acquired = await callTool("acquire_lock", {
+    resource_type: "container",
+    subtype: "supabase_local",
+    host: machineHost,
+    slot: parsed.opts.lockSlot,
+    mode: "lock",
+    ticket_id: parsed.opts.ticket,
+    no_pr_reason: "local OrbStack hygiene",
+  });
+  if (!acquired?.ok || acquired.isError || acquired.data?.success === false) {
+    const detail = acquired?.data?.message || acquired?.error || "lock was busy or unavailable";
+    const refused = refusedResult(argv, `BotBuddy supabase_local lock not acquired: ${detail}`, EXIT.DOCKER, workflowOptions.now);
+    if (acquired?.data?.queued === true) {
+      const queuedIdentity = lockIdentity(acquired.data);
+      const retireArgs = queuedIdentity.resourceId && queuedIdentity.resourceLockId
+        ? { resource_id: queuedIdentity.resourceId, resource_lock_id: queuedIdentity.resourceLockId }
+        : null;
+      let retired = false;
+      let alreadyAbsent = false;
+      let retirementError = null;
+      if (retireArgs) {
+        const retirement = await callTool("retire_queued_lock_attempt", retireArgs);
+        const retirementOk = Boolean(retirement?.ok && !retirement.isError && retirement.data?.success !== false);
+        retired = retirementOk && retirement.data?.retired === true;
+        alreadyAbsent = retirementOk && retirement.data?.retired === false;
+        if (!retirementOk) retirementError = retirement?.data?.message || retirement?.error || "unknown retirement error";
+      } else {
+        retirementError = "busy response did not include an exact resource and queued-ledger identity";
+      }
+      refused.receipt.authority.queued_lock_attempt = {
+        resource_id: queuedIdentity.resourceId,
+        resource_lock_id: queuedIdentity.resourceLockId,
+        resource_name: queuedIdentity.resourceName,
+        retired,
+        already_absent: alreadyAbsent,
+      };
+      if (retirementError) {
+        refused.receipt.errors.push(`failed to retire queued lock attempt: ${retirementError}`);
+      }
+    }
+    return refused;
+  }
+
+  const timing = lockGrantTiming(acquired.data);
+  if (timing.alreadyHeld) {
+    return refusedResult(argv, "BotBuddy supabase_local lock is already held by another process using this agent identity; refusing reentrant cleanup", EXIT.DOCKER, workflowOptions.now);
+  }
+
+  const identity = lockIdentity(acquired.data);
+  if (!identity.resourceId && !identity.resourceName) {
+    const fallbackName = `supabase_local:${machineHost}:${parsed.opts.lockSlot}`;
+    const fallbackRelease = await callTool("release_lock", { resource_name: fallbackName });
+    const releaseNote = fallbackRelease?.ok && !fallbackRelease.isError
+      ? "fallback release succeeded"
+      : "fallback release failed; the lock will expire by TTL";
+    return refusedResult(argv, `BotBuddy granted the stack lock without a releasable identity; refusing Docker access (${releaseNote})`, EXIT.DOCKER, workflowOptions.now);
+  }
+  if (!timing.secondsRemaining || timing.secondsRemaining * 1000 <= LOCK_EXPIRY_RESERVE_MS) {
+    const failedTimingRelease = await callTool("release_lock", identity.resourceId
+      ? { resource_id: identity.resourceId }
+      : { resource_name: identity.resourceName });
+    const releaseNote = failedTimingRelease?.ok && !failedTimingRelease.isError
+      ? "release succeeded"
+      : "release failed; the lock will expire by TTL";
+    return refusedResult(argv, `BotBuddy stack lock grant did not provide a safe remaining TTL; refusing Docker access (${releaseNote})`, EXIT.DOCKER, workflowOptions.now);
+  }
+  const applyBudgetMs = Math.min(MAX_APPLY_BUDGET_MS, timing.secondsRemaining * 1000 - LOCK_EXPIRY_RESERVE_MS);
+  const lockAuthority = {
+    held: true,
+    host: machineHost,
+    slot: parsed.opts.lockSlot,
+    secondsRemaining: timing.secondsRemaining,
+    applyBudgetMs,
+    ...identity,
+  };
+
+  let result;
+  let thrown;
+  try {
+    result = runWorkflow(argv, {
+      ...workflowOptions,
+      lockAuthority,
+      deadlineAt: monotonicNow() + applyBudgetMs,
+      monotonicNow,
+    });
+  } catch (error) {
+    thrown = error;
+  }
+  if (result?.receipt?.authority && !result.receipt.authority.stack_lock) {
+    result.receipt.authority.stack_lock = {
+      host: lockAuthority.host,
+      slot: lockAuthority.slot,
+      resource_id: lockAuthority.resourceId || null,
+      resource_name: lockAuthority.resourceName || null,
+      granted_seconds_remaining: lockAuthority.secondsRemaining,
+      apply_budget_ms: lockAuthority.applyBudgetMs,
+      held: true,
+    };
+  }
+  const released = await callTool("release_lock", identity.resourceId
+    ? { resource_id: identity.resourceId }
+    : { resource_name: identity.resourceName });
+  if (thrown) throw thrown;
+  if (!released?.ok || released.isError) {
+    result.receipt.errors.push(`BotBuddy supabase_local lock release failed: ${released?.error || "unknown release error"}`);
+    result.receipt.outcome = result.receipt.deleted.length > 0 ? "partial_failure" : "refused";
+    result.exitCode = EXIT.DELETE_FAILED;
+  } else if (result.receipt.authority?.stack_lock) {
+    result.receipt.authority.stack_lock.held = false;
+    result.receipt.authority.stack_lock.released = true;
+  }
+  return result;
+}