@botbuddy/cli 1.4.2 → 1.5.0

package/src/profile-bootstrap.test.mjs

@@ -13,7 +13,7 @@ test("BOT-1353: the published CLI identifies this profile-bootstrap release", as
     cwd: new URL("..", import.meta.url),
   });
 
-  assert.equal(stdout.trim(), "botbuddy v1.4.2");
+  assert.equal(stdout.trim(), "botbuddy v1.5.0");
 });
 
 test("BOT-1382: profile --help succeeds and documents the subcommands", async () => {

package/src/stack-file-lock.mjs

@@ -0,0 +1,180 @@
+// BOT-904 / BOT-1405 — canonical cross-worktree local Supabase mutex.
+//
+// This module lives in the published CLI so both repository test wrappers and
+// `botbuddy docker hygiene --apply` use the exact same lock path and protocol.
+// macOS has no flock(1), so acquisition uses an atomically linked lockfile with
+// dead/stale-holder recovery.
+import { randomUUID } from "node:crypto";
+import { linkSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { hostname, tmpdir } from "node:os";
+import { join } from "node:path";
+
+let tmpCounter = 0;
+
+export function projectIdFromConfig(configText) {
+  const match = String(configText).match(/^\s*project_id\s*=\s*"([^"]+)"/m);
+  return match ? match[1] : null;
+}
+
+export function dbPortFromConfig(configText) {
+  const lines = String(configText).split(/\r?\n/);
+  let inDb = false;
+  for (const line of lines) {
+    const section = /^\s*\[([^\]]+)\]/.exec(line);
+    if (section) {
+      inDb = section[1].trim() === "db";
+      continue;
+    }
+    if (!inDb) continue;
+    const match = /^\s*port\s*=\s*(\d+)/.exec(line);
+    if (match) return match[1];
+  }
+  return null;
+}
+
+export function lockPathForProject(projectId) {
+  return join(tmpdir(), `botbuddy-stack-${projectId}.lock`);
+}
+
+function isAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export function reclaimPathForLock(path) {
+  return `${path}.reclaim`;
+}
+
+/** Serialize stale replacement. An abandoned guard fails closed; recursively
+ * stale-stealing a reclaim guard would recreate the race this guard prevents. */
+export async function acquireReclaimGuard(
+  path,
+  { timeoutMs = 300_000, pollMs = 500, now = () => Date.now(), sleep = defaultSleep } = {},
+) {
+  const deadline = now() + timeoutMs;
+  const ownerToken = randomUUID();
+  const tmp = `${path}.${process.pid}.${tmpCounter++}.tmp`;
+  const payload = JSON.stringify({ pid: process.pid, host: hostname(), owner_token: ownerToken });
+  for (;;) {
+    try {
+      writeFileSync(tmp, payload);
+      linkSync(tmp, path);
+      try { unlinkSync(tmp); } catch { /* best-effort temp cleanup */ }
+      let released = false;
+      return {
+        path,
+        release() {
+          if (released) return;
+          released = true;
+          try {
+            const current = JSON.parse(readFileSync(path, "utf8"));
+            if (current.owner_token !== ownerToken) return;
+            unlinkSync(path);
+          } catch { /* already gone, corrupt, or superseded */ }
+        },
+      };
+    } catch (error) {
+      try { unlinkSync(tmp); } catch { /* temp may not exist */ }
+      if (error.code !== "EEXIST") throw error;
+      if (now() >= deadline) {
+        throw new Error(`stack-lock: timed out after ${timeoutMs}ms waiting for stale-reclaim guard ${path}`);
+      }
+      await sleep(pollMs);
+    }
+  }
+}
+
+function inspectExistingLock(path, now, staleMs) {
+  let raw;
+  try { raw = readFileSync(path, "utf8"); } catch { return { exists: false }; }
+  let holder = null;
+  try { holder = JSON.parse(raw); } catch { /* corrupt: use mtime */ }
+  const sameHost = holder && holder.host === hostname();
+  const sameHostDead = sameHost && !isAlive(holder.pid);
+  let tooOld;
+  if (holder) {
+    tooOld = now() - (holder.startedAt ?? 0) > staleMs;
+  } else {
+    let mtimeMs;
+    try { mtimeMs = statSync(path).mtimeMs; } catch { return { exists: false }; }
+    tooOld = now() - mtimeMs > staleMs;
+  }
+  return { exists: true, raw, holder, stealable: sameHost ? sameHostDead : tooOld };
+}
+
+export async function acquireStackLock(
+  path,
+  {
+    timeoutMs = 300_000,
+    staleMs = 900_000,
+    pollMs = 500,
+    now = () => Date.now(),
+    sleep = defaultSleep,
+    acquireReclaim = acquireReclaimGuard,
+  } = {},
+) {
+  const deadline = now() + timeoutMs;
+  const tmp = `${path}.${process.pid}.${tmpCounter++}.tmp`;
+  const ownerToken = randomUUID();
+  const payload = JSON.stringify({
+    pid: process.pid,
+    host: hostname(),
+    startedAt: now(),
+    owner_token: ownerToken,
+  });
+  for (;;) {
+    try {
+      writeFileSync(tmp, payload);
+      linkSync(tmp, path);
+      try { unlinkSync(tmp); } catch { /* best-effort temp cleanup */ }
+      let released = false;
+      return {
+        path,
+        release() {
+          if (released) return;
+          released = true;
+          try {
+            const current = JSON.parse(readFileSync(path, "utf8"));
+            if (current.owner_token !== ownerToken) return;
+            unlinkSync(path);
+          } catch { /* already gone, corrupt, or superseded: never unlink blindly */ }
+        },
+      };
+    } catch (error) {
+      try { unlinkSync(tmp); } catch { /* temp may not exist */ }
+      if (error.code !== "EEXIST") throw error;
+
+      const observed = inspectExistingLock(path, now, staleMs);
+      if (!observed.exists) continue;
+      if (observed.stealable) {
+        const guard = await acquireReclaim(reclaimPathForLock(path), {
+          timeoutMs: Math.max(1, deadline - now()), pollMs, now, sleep,
+        });
+        try {
+          const current = inspectExistingLock(path, now, staleMs);
+          if (current.exists && current.raw === observed.raw && current.stealable) {
+            try { unlinkSync(path); } catch { /* vanished: retry */ }
+          }
+        } finally {
+          guard.release();
+        }
+        continue;
+      }
+      if (now() >= deadline) {
+        throw new Error(
+          `stack-lock: timed out after ${timeoutMs}ms waiting for ${path} ` +
+          `(held by pid ${observed.holder?.pid} on ${observed.holder?.host}). Another worktree ` +
+          "is using the shared local Supabase stack.",
+        );
+      }
+      await sleep(pollMs);
+    }
+  }
+}

package/src/stack.mjs

@@ -29,6 +29,7 @@ import { basename, dirname, join, relative, isAbsolute } from "path";
 import { randomUUID } from "crypto";
 import { callToolJson } from "./api.mjs";
 import { SERVER_URL, getConfig } from "./config.mjs";
+import { runDockerWorkflow } from "./docker-hygiene.mjs";
 import { bold, dim, yellow } from "./utils.mjs";
 
 export const STACK_SCHEMA_VERSION = 1;
@@ -71,10 +72,15 @@ ${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.
 
 ${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.
 
 ${bold("run OPTIONS")}
   --repo <repo>          Required approved repository name.
@@ -146,10 +152,17 @@ export function parseStackArgs(argv) {
     prId: null, prUrl: null, purpose: null, idleTtl: null, stackPath: ".",
     timeout: DEFAULT_TIMEOUT_SEC, provisionTimeout: null, reapTimeout: 300, hardTtl: null,
     connectionFile: null, noWait: false, localExec: false,
+    dockerContext: null, dockerEndpoint: null,
     disposition: "destroy", json: false, receiptMaxBytes: DEFAULT_RECEIPT_MAX_BYTES,
   };
   const positionals = [];
-  const need = (name, v) => { if (v === undefined) { errors.push(`${name} needs a value`); return false; } return true; };
+  const need = (name, v) => {
+    if (v === undefined || String(v).startsWith("--")) {
+      errors.push(`${name} needs a value`);
+      return false;
+    }
+    return true;
+  };
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     switch (a) {
@@ -213,6 +226,8 @@ export function parseStackArgs(argv) {
       }
       case "--no-wait": opts.noWait = true; break;
       case "--local-exec": opts.localExec = true; break;
+      case "--docker-context": if (need(a, rest[i + 1])) opts.dockerContext = rest[++i]; break;
+      case "--docker-endpoint": if (need(a, rest[i + 1])) opts.dockerEndpoint = rest[++i]; break;
       case "--stop": opts.disposition = "stop"; break;
       case "--destroy": opts.disposition = "destroy"; break;
       case "--json": opts.json = true; break;
@@ -229,6 +244,12 @@ export function parseStackArgs(argv) {
   if (command && ["status", "touch", "done"].includes(command) && !leaseId) {
     errors.push(`${command} needs a <lease_id>`);
   }
+  if (["up", "done"].includes(command) && opts.localExec && Boolean(opts.dockerContext) === Boolean(opts.dockerEndpoint)) {
+    errors.push(`--local-exec ${command} requires exactly one of --docker-context <name> or --docker-endpoint <uri>`);
+  }
+  if ((opts.dockerContext || opts.dockerEndpoint) && !(["up", "done"].includes(command) && opts.localExec)) {
+    errors.push("--docker-context and --docker-endpoint are valid only with `stack up --local-exec` or `stack done --local-exec`");
+  }
   if (command === "run") {
     if (!opts.repo) errors.push("run needs --repo <approved-repo>");
     if (!opts.ticket || !/^[A-Z][A-Z0-9]*-\d+$/i.test(opts.ticket)) errors.push("run needs --ticket <BOT-n|ENT-n>");
@@ -467,8 +488,120 @@ const isActive = (s) => s === "active";
 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) {
+  const selector = opts.dockerContext
+    ? ["--context", opts.dockerContext]
+    : ["--endpoint", opts.dockerEndpoint];
+  return runWorkflow(["preflight", ...selector, "--json"]);
+}
+
+export function dockerEnvForSelector(opts, env = process.env) {
+  const selected = { ...env };
+  delete selected.DOCKER_CONTEXT;
+  delete selected.DOCKER_HOST;
+  if (opts.dockerContext) selected.DOCKER_CONTEXT = opts.dockerContext;
+  else selected.DOCKER_HOST = opts.dockerEndpoint;
+  return selected;
+}
+
+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 ||
+      typeof serverId !== "string" || !serverId) return null;
+  return { validation: "orbstack", resolved_endpoint: endpoint, server_id: serverId };
+}
+
+export function connectionWithDockerTarget(connection, target) {
+  if (!target?.resolved_endpoint || !target?.server_id) {
+    throw new Error("cannot persist an incomplete Docker target identity");
+  }
+  return { ...(connection || {}), botbuddy_docker_target: { ...target } };
+}
+
+function dockerTargetsMatch(expected, actual) {
+  return expected?.validation === "orbstack" && actual?.validation === "orbstack" &&
+    expected.resolved_endpoint === actual.resolved_endpoint && expected.server_id === actual.server_id;
+}
+
+function dockerEnvForTarget(target, env = process.env) {
+  const selected = { ...env };
+  delete selected.DOCKER_CONTEXT;
+  delete selected.DOCKER_HOST;
+  selected.DOCKER_HOST = target.resolved_endpoint;
+  return selected;
+}
+
+/**
+ * Compatibility fence for leases activated by CLI <1.5.0, before the daemon
+ * identity was persisted in `connection`. We cannot reconstruct the old daemon
+ * ID by guesswork. Instead, prove that the caller is in the exact registered
+ * worktree/stack path and that `supabase status`, pinned to the freshly validated
+ * OrbStack endpoint, reports the same non-secret API + DB endpoints stored on
+ * the lease. Only then may that observed daemon be used for teardown.
+ */
+export function proveLegacyLocalExecTarget(lease, observedTarget, opts, run = spawnSync, cwd = process.cwd()) {
+  if (!observedTarget?.resolved_endpoint || !observedTarget?.server_id) {
+    return { ok: false, error: "fresh OrbStack target identity is incomplete" };
+  }
+  let execution;
+  try {
+    execution = resolveStackPath(cwd, opts?.stackPath || ".");
+  } catch (error) {
+    return { ok: false, error: `could not resolve the invoking stack path: ${error.message}` };
+  }
+  if (!lease?.worktree_root || lease.worktree_root !== execution.worktreeRoot ||
+      (lease.stack_path || ".") !== execution.stackPath) {
+    return { ok: false, error: "legacy lease worktree/stack metadata does not exactly match the invoking worktree" };
+  }
+
+  const stackDir = execution.stackPath === "."
+    ? execution.worktreeRoot
+    : join(execution.worktreeRoot, execution.stackPath);
+  const status = run("supabase", ["status", "-o", "json", "--workdir", stackDir], {
+    encoding: "utf8",
+    env: dockerEnvForTarget(observedTarget),
+  });
+  if (status?.error || status?.status !== 0) {
+    return { ok: false, error: "legacy stack is not provably live on the freshly validated OrbStack endpoint" };
+  }
+  const live = parseSupabaseStatus(status.stdout || "");
+  const stored = lease.connection || {};
+  if (typeof stored.api_url !== "string" || typeof stored.db_url !== "string" ||
+      live.api_url !== stored.api_url || live.db_url !== stored.db_url) {
+    return { ok: false, error: "live Supabase connection on the observed OrbStack daemon does not match the legacy lease connection" };
+  }
+  let dbPort = null;
+  try { dbPort = new URL(live.db_url).port || null; } catch { /* exact URL already matched; omit display-only port */ }
+  return {
+    ok: true,
+    evidence: {
+      method: "legacy_worktree_connection_match",
+      worktree_root: execution.worktreeRoot,
+      stack_path: execution.stackPath,
+      api_url: live.api_url,
+      db_port: dbPort,
+      resolved_endpoint: observedTarget.resolved_endpoint,
+      server_id: observedTarget.server_id,
+    },
+  };
+}
+
+function compactPreflight(receipt) {
+  return {
+    outcome: receipt.outcome,
+    context: receipt.context,
+    pressure: receipt.pressure,
+    warnings: receipt.warnings,
+    errors: receipt.errors,
+    recommendation: receipt.recommendation,
+  };
+}
+
 /** LOUD local-exec fallback: bring a stack up in the cwd via the Supabase CLI. */
-function localProvision() {
+function localProvision(opts, dockerTarget) {
   // Pin a LOCAL origin so `supabase start` never bakes the repo's prod origin into the
   // edge runtime (BOT-903 / Codex P1). Refuse rather than risk crossing into production.
   const url = resolveLocalSupabaseUrl();
@@ -480,7 +613,7 @@ function localProvision() {
         "export VITE_SUPABASE_URL=http://127.0.0.1:<port> first.",
     );
   }
-  const spawnEnv = { ...process.env, VITE_SUPABASE_URL: url };
+  const spawnEnv = { ...dockerEnvForTarget(dockerTarget), VITE_SUPABASE_URL: url };
   process.stderr.write(`${yellow("⚠ LOCAL-EXEC FALLBACK")} — no BotBuddy Helper; running ${bold("supabase start")} in this worktree (VITE_SUPABASE_URL=${url}).\n`);
   const start = spawnSync("supabase", ["start", "--workdir", process.cwd()], { encoding: "utf8", env: spawnEnv });
   if (start.status !== 0) {
@@ -491,9 +624,12 @@ function localProvision() {
 }
 
 /** LOUD local-exec fallback: tear the stack down in the cwd. Returns true iff it succeeded. */
-function localTeardown() {
+export function localTeardown(_opts, dockerTarget, spawn = spawnSync, env = process.env) {
   process.stderr.write(`${yellow("⚠ LOCAL-EXEC FALLBACK")} — running ${bold("supabase stop")} in this worktree.\n`);
-  const res = spawnSync("supabase", ["stop", "--workdir", process.cwd()], { encoding: "utf8" });
+  const res = spawn("supabase", ["stop", "--workdir", process.cwd()], {
+    encoding: "utf8",
+    env: dockerEnvForTarget(dockerTarget, env),
+  });
   if (res.status !== 0) {
     process.stderr.write(`${yellow("⚠")} stack: supabase stop returned ${res.status}: ${(res.stderr || res.stdout || "").slice(0, 300)}\n`);
   }
@@ -508,19 +644,42 @@ function emit(receipt, opts, code) {
 
 // ── command orchestration ────────────────────────────────────────────────────
 
-async function cmdUp(opts) {
+export async function cmdUp(opts, {
+  runPreflight = runLocalExecPreflight,
+  callTool = callToolJson,
+  authProvider = stackAuthHeader,
+  localProvisionFn = localProvision,
+  emitResult = emit,
+} = {}) {
   let slot;
   try { slot = deriveSlot(opts); } catch (e) {
-    return emit(buildReceipt({ command: "up", outcome: "error", error: e.message }), opts, EXIT.INVALID);
+    return emitResult(buildReceipt({ command: "up", outcome: "error", error: e.message }), opts, EXIT.INVALID);
   }
-  const auth = stackAuthHeader();
-  if (!auth) return emit(buildReceipt({ command: "up", outcome: "error", error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
   let execution;
   try { execution = resolveStackPath(process.cwd(), opts.stackPath); } catch (e) {
-    return emit(buildReceipt({ command: "up", outcome: "error", error: (e).message }), opts, EXIT.INVALID);
+    return emitResult(buildReceipt({ command: "up", outcome: "error", error: (e).message }), opts, EXIT.INVALID);
   }
+  let localPreflight = null;
+  let localDockerTarget = null;
+  if (opts.localExec) {
+    const checked = runPreflight(opts);
+    localPreflight = compactPreflight(checked.receipt);
+    localDockerTarget = dockerTargetFromPreflight(checked.receipt);
+    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",
+        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`);
+    }
+  }
+  const auth = authProvider();
+  if (!auth) return emitResult(buildReceipt({ command: "up", outcome: "error", error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
 
-  const req = await callToolJson("request_stack_lease", {
+  const req = await callTool("request_stack_lease", {
     slot, host_key: opts.host || undefined, repo: opts.repo || undefined,
     ticket_id: opts.ticket || undefined, ticket_url: opts.ticketUrl || undefined,
     pr_id: opts.prId || undefined, pr_url: opts.prUrl || undefined,
@@ -530,57 +689,78 @@ async function cmdUp(opts) {
   });
   if (!req.ok) {
     return req.auth
-      ? emit(buildReceipt({ command: "up", outcome: "error", error: req.error || "unauthorized" }), opts, EXIT.AUTH)
-      : emit(buildReceipt({ command: "up", outcome: "error", error: req.error || "request failed" }), opts, EXIT.BACKEND);
+      ? emitResult(buildReceipt({ command: "up", outcome: "error", error: req.error || "unauthorized" }), opts, EXIT.AUTH)
+      : emitResult(buildReceipt({ command: "up", outcome: "error", error: req.error || "request failed" }), opts, EXIT.BACKEND);
   }
   const d = req.data;
   if (!d.success) {
-    return emit(buildReceipt({ command: "up", outcome: "error", code: d.code, error: d.message || d.code || "request refused", slot }), opts, EXIT.BACKEND);
+    return emitResult(buildReceipt({ command: "up", outcome: "error", code: d.code, error: d.message || d.code || "request refused", slot }), opts, EXIT.BACKEND);
   }
   let leaseId = d.lease_id;
   let state = d.state;
 
   if (state === "queued") {
     if (opts.noWait) {
-      return emit(buildReceipt({ command: "up", outcome: "queued", lease_id: leaseId, state, host_key: d.host_key, slot, queued: true, queue_position: d.queue_position, holders: d.holders }), opts, EXIT.QUEUED);
+      return emitResult(buildReceipt({ command: "up", outcome: "queued", lease_id: leaseId, state, host_key: d.host_key, slot, queued: true, queue_position: d.queue_position, holders: d.holders }), opts, EXIT.QUEUED);
     }
     // Park zero-poll until the lease leaves the queue (granted in BOT-1187 order).
     const parked = await waitForLease(leaseId, nonQueued, () => false, { timeoutSec: opts.timeout, auth });
-    if (parked.timeout) return emit(buildReceipt({ command: "up", outcome: "timeout", lease_id: leaseId, state: "queued", slot, error: `parked ${opts.timeout}s without capacity` }), opts, EXIT.TIMEOUT);
-    if (parked.auth) return emit(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: "unauthorized on wait stream" }), opts, EXIT.AUTH);
-    if (parked.error) return emit(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: parked.error }), opts, EXIT.BACKEND);
+    if (parked.timeout) return emitResult(buildReceipt({ command: "up", outcome: "timeout", lease_id: leaseId, state: "queued", slot, error: `parked ${opts.timeout}s without capacity` }), opts, EXIT.TIMEOUT);
+    if (parked.auth) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: "unauthorized on wait stream" }), opts, EXIT.AUTH);
+    if (parked.error) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: parked.error }), opts, EXIT.BACKEND);
     state = parked.state || "provisioning";
   }
 
   // Reach `active`: local-exec provisions itself; otherwise wait for the Helper.
   if (state !== "active") {
     if (opts.localExec) {
+      // 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);
+      localPreflight = compactPreflight(checked.receipt);
+      localDockerTarget = dockerTargetFromPreflight(checked.receipt);
+      if (checked.exitCode !== 0 || !localDockerTarget) {
+        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: "refused", lease_id: leaseId, state, slot,
+          error: checked.receipt.errors?.[0] || "OrbStack preflight did not return a stable Docker server identity",
+          preflight: localPreflight,
+          lease_cancellation: leaseCancellation,
+        }), opts, EXIT.LEASE_FAILED);
+      }
       let conn;
-      try { conn = localProvision(); } catch (e) {
-        return emit(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: e.message }), opts, EXIT.LEASE_FAILED);
+      try {
+        conn = connectionWithDockerTarget(localProvisionFn(opts, localDockerTarget), localDockerTarget);
+      } catch (e) {
+        return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: e.message }), opts, EXIT.LEASE_FAILED);
       }
-      const act = await callToolJson("activate_stack_lease", { lease_id: leaseId, connection: conn });
+      const act = await callTool("activate_stack_lease", { lease_id: leaseId, connection: conn });
       if (!act.ok || !act.data?.success) {
-        return emit(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: act.error || act.data?.code || "activate failed" }), opts, EXIT.BACKEND);
+        return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: act.error || act.data?.code || "activate failed" }), opts, EXIT.BACKEND);
       }
     } else {
       const active = await waitForLease(leaseId, isActive, isReaped, { timeoutSec: opts.timeout, auth });
-      if (active.timeout) return emit(buildReceipt({ command: "up", outcome: "timeout", lease_id: leaseId, state, slot, error: `provisioning did not reach active in ${opts.timeout}s (Helper may be down — retry with --local-exec)` }), opts, EXIT.TIMEOUT);
-      if (active.failed) return emit(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, state: active.state, error: "lease was reaped before it became active" }), opts, EXIT.LEASE_FAILED);
-      if (active.error) return emit(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: active.error }), opts, EXIT.BACKEND);
+      if (active.timeout) return emitResult(buildReceipt({ command: "up", outcome: "timeout", lease_id: leaseId, state, slot, error: `provisioning did not reach active in ${opts.timeout}s (Helper may be down — retry with --local-exec)` }), opts, EXIT.TIMEOUT);
+      if (active.failed) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, state: active.state, error: "lease was reaped before it became active" }), opts, EXIT.LEASE_FAILED);
+      if (active.error) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: active.error }), opts, EXIT.BACKEND);
     }
   }
 
   // Authoritative final read (connection block, current state).
-  const got = await callToolJson("get_stack_lease", { lease_id: leaseId });
+  const got = await callTool("get_stack_lease", { lease_id: leaseId });
   const g = got.ok && got.data?.success ? got.data : null;
   if (!g || g.state !== "active") {
-    return emit(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, state: g?.state, error: g ? `lease is ${g.state}, not active` : (got.error || "could not read lease") }), opts, g?.state && isReaped(g.state) ? EXIT.LEASE_FAILED : EXIT.BACKEND);
+    return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, state: g?.state, error: g ? `lease is ${g.state}, not active` : (got.error || "could not read lease") }), opts, g?.state && isReaped(g.state) ? EXIT.LEASE_FAILED : EXIT.BACKEND);
   }
-  return emit(buildReceipt({
+  return emitResult(buildReceipt({
     command: "up", outcome: "active", lease_id: leaseId, state: "active",
     host_key: g.host_key, slot: g.slot, connection: g.connection,
     idle_ttl_secs: g.idle_ttl_secs, resource_name: g.resource_name,
+    ...(localPreflight ? { preflight: localPreflight } : {}),
   }), opts, EXIT.OK);
 }
 
@@ -605,10 +785,50 @@ async function cmdTouch(leaseId, opts) {
   return emit(buildReceipt({ command: "touch", outcome: "touched", lease_id: leaseId, last_used_at: r.data.last_used_at }), opts, EXIT.OK);
 }
 
-async function cmdDone(leaseId, opts) {
-  const r = await callToolJson("release_stack_lease", { lease_id: leaseId, disposition: opts.disposition });
-  if (!r.ok) return emit(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, error: r.error }), opts, r.auth ? EXIT.AUTH : EXIT.BACKEND);
-  if (!r.data.success) return emit(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, code: r.data.code, error: r.data.code }), opts, EXIT.BACKEND);
+export async function cmdDone(leaseId, opts, {
+  callTool = callToolJson,
+  runPreflight = runLocalExecPreflight,
+  proveLegacyTarget = proveLegacyLocalExecTarget,
+  localTeardownFn = localTeardown,
+  emitResult = emit,
+} = {}) {
+  let dockerTarget = null;
+  let legacyTargetProof = null;
+  if (opts.localExec) {
+    const current = await callTool("get_stack_lease", { lease_id: leaseId });
+    if (!current.ok || !current.data?.success) {
+      return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId,
+        error: current.error || current.data?.code || "could not verify the lease Docker target" }), opts,
+      current.auth ? EXIT.AUTH : EXIT.BACKEND);
+    }
+    const expected = current.data.connection?.botbuddy_docker_target;
+    let checked;
+    try { checked = 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);
+    }
+    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",
+        expected_docker_target: expected || null, observed_docker_target: dockerTarget,
+      }), opts, EXIT.LEASE_FAILED);
+    }
+    if (!expected) {
+      const proof = proveLegacyTarget(current.data, dockerTarget, opts);
+      if (!proof?.ok) {
+        return emitResult(buildReceipt({ command: "done", outcome: "refused", lease_id: leaseId,
+          error: `pre-1.5.0 lease has no persisted Docker target and compatibility proof failed: ${proof?.error || "unknown proof failure"}; lease and slot remain fenced`,
+          expected_docker_target: null, observed_docker_target: dockerTarget,
+        }), opts, EXIT.LEASE_FAILED);
+      }
+      legacyTargetProof = proof.evidence;
+    }
+  }
+
+  const r = await callTool("release_stack_lease", { lease_id: leaseId, disposition: opts.disposition });
+  if (!r.ok) return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, error: r.error }), opts, r.auth ? EXIT.AUTH : EXIT.BACKEND);
+  if (!r.data.success) return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, code: r.data.code, error: r.data.code }), opts, EXIT.BACKEND);
   let state = r.data.state;
   if (opts.localExec && state === "reaping") {
     // Only finalize once the stack is PROVABLY down. A failed `supabase stop` (Docker
@@ -616,17 +836,18 @@ async function cmdDone(leaseId, opts) {
     // the next queued lease, which would collide with containers still running on this
     // slot (Codex P1). Leave the lease in `reaping` (slot stays fenced) for a retry /
     // the reaper. Fail with a non-zero exit so the caller knows teardown is incomplete.
-    if (!localTeardown()) {
-      return emit(buildReceipt({
+    if (!localTeardownFn(opts, dockerTarget)) {
+      return emitResult(buildReceipt({
         command: "done", outcome: "error", lease_id: leaseId, state,
         error: "local `supabase stop` failed — NOT finalizing; the slot stays fenced. Tear the stack down and re-run `stack done --local-exec`, or let the reaper reconcile.",
       }), opts, EXIT.LEASE_FAILED);
     }
-    const fin = await callToolJson("finalize_stack_lease", { lease_id: leaseId });
+    const fin = await callTool("finalize_stack_lease", { lease_id: leaseId });
     if (fin.ok && fin.data?.success) state = fin.data.state;
     else process.stderr.write(`${yellow("⚠")} stack: finalize failed (${fin.error || fin.data?.code}); the reaper will reconcile.\n`);
   }
-  return emit(buildReceipt({ command: "done", outcome: "released", lease_id: leaseId, state, disposition: opts.disposition }), opts, EXIT.OK);
+  return emitResult(buildReceipt({ command: "done", outcome: "released", lease_id: leaseId, state, disposition: opts.disposition,
+    ...(legacyTargetProof ? { legacy_target_proof: legacyTargetProof } : {}) }), opts, EXIT.OK);
 }
 
 const SIGNAL_EXIT = Object.freeze({ SIGINT: 130, SIGTERM: 143, SIGHUP: 129 });