@botbuddy/cli 1.33.10 → 1.34.0

package/package.json

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

package/src/api.mjs

@@ -5,7 +5,7 @@ import { AGENT_KEY_RE } from "./agent-key.mjs";
 // BOT-1864: api.mjs ↔ agent-session.mjs is a deliberate import cycle — each side
 // only CALLS the other's functions at request time, never at module evaluation.
 import { resolveAgentSessionCredential } from "./agent-session.mjs";
-import { die, cyan, dim, yellow, prettyJson } from "./utils.mjs";
+import { die, red, cyan, dim, yellow, prettyJson } from "./utils.mjs";
 
 // Same slug shape the server accepts on `?tenant=`.
 const TENANT_PIN_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
@@ -57,7 +57,7 @@ async function genericEndpoint({ tenant = null, resolvePin = resolveDefaultTenan
 // tenant-bound agent key (from `botbuddy profile setup`) is the fallback.
 // BOT-1864: the generic commands (`bb call`, resources, heartbeat/locks/tasks)
 // first honour this worktree's tier-3 session — see resolveCallAuth.
-async function authHeader(toolName = null, { resolveAuth = resolveCallAuth } = {}) {
+async function authHeader(toolName = null, { resolveAuth = resolveCallAuth, exitCode = 1 } = {}) {
   const resolved = await resolveAuth({ toolName, preferSession: true });
   if (resolved.auth) {
     const expiresAt = resolved.ownerExpiresAt ?? null;
@@ -66,12 +66,15 @@ async function authHeader(toolName = null, { resolveAuth = resolveCallAuth } = {
     }
     return resolved;
   }
+  // BOT-1896: a missing/expired local credential is auth-class — callTool passes
+  // CALL_EXIT.AUTH so it never collapses into the generic exit 1.
+  const fail = (msg) => { console.error(`${red("✗")} ${msg}`); process.exit(exitCode); };
   const code = resolved.error?.error;
-  if (code === "token_expired") die(`Token expired. Run: ${cyan("botbuddy login")} to re-authenticate.`);
+  if (code === "token_expired") fail(`Token expired. Run: ${cyan("botbuddy login")} to re-authenticate.`);
   if (code === "session_token_malformed") {
-    die(`The agent session token has an unexpected shape (source: ${resolved.error.source ?? "unknown"}). Run: ${cyan("bb doctor --fix")} in this checkout.`);
+    fail(`The agent session token has an unexpected shape (source: ${resolved.error.source ?? "unknown"}). Run: ${cyan("bb doctor --fix")} in this checkout.`);
   }
-  die(`Not authenticated. Run: ${cyan("botbuddy login")}`);
+  fail(`Not authenticated. Run: ${cyan("botbuddy login")}`);
 }
 
 // BOT-1864: a cached session the server rejects (revoked by a concurrent
@@ -96,39 +99,200 @@ async function requestEndpoint(resolved, { tenant, resolvePin }) {
   return SESSION_SOURCES.has(resolved?.source) ? toolEndpoint(tenant) : genericEndpoint({ tenant, resolvePin });
 }
 
-export async function callTool(toolName, args = {}, { fetchImpl = fetch, auth = null, tenant = null, resolvePin = resolveDefaultTenantPin, resolveAuth = resolveCallAuth, log = (line) => console.log(line) } = {}) {
+// BOT-1896: `botbuddy call` (and every command riding callTool) exits with a
+// code that tells a tenant gate WHY it failed: AUTH when BotBuddy refused the
+// credential (fail closed), TRANSPORT when BotBuddy could not be reached or
+// answered with a gateway/5xx failure (the only case that may degrade to a
+// local-only lock). The values reuse `botbuddy stack`'s EXIT table (stack.mjs:
+// AUTH 3, BACKEND 5) — restated rather than imported because stack.mjs imports
+// this module; bot1896-call-auth-exit.test.mjs pins them equal.
+// ERROR (1) is the generic failure: a reachable server said something other than
+// "ok" or "auth" (a proxy 404, a 429 page, …). A gate must fail closed on it —
+// only TRANSPORT licenses a local-only fallback.
+export const CALL_EXIT = Object.freeze({ OK: 0, ERROR: 1, AUTH: 3, TRANSPORT: 5 });
+
+// BOT-1896: mirror of the server's AUTH_CLASS_ERROR_CODES
+// (supabase/functions/_shared/lib/authDenial.ts), used when an older server
+// sends a typed code without `error_class`. Pinned equal by the same test.
+export const CALL_AUTH_ERROR_CODES = new Set([
+  "scope_denied",
+  "session_token_revoked",
+  "session_token_expired",
+  "session_token_scope",
+  "credential_unknown",
+  "credential_missing",
+  "MCP_REAUTH_TENANT_REQUIRED",
+  "MCP_TENANT_PIN_REQUIRED",
+  "MCP_TENANT_SESSION_MISMATCH",
+  "MCP_TENANT_MEMBERSHIP_REQUIRED",
+  "MCP_TENANT_PIN_UNSUPPORTED",
+]);
+
+// BOT-1896: the codes the server's 401 gates emit when a request authenticated
+// as nothing — a dead/absent credential, never a tenant refusal.
+const UNAUTHENTICATED_CODES = new Set(["credential_unknown", "credential_missing", "session_token_revoked", "session_token_expired"]);
+
+function typedCodeOf(fields) {
+  if (!fields || typeof fields !== "object") return null;
+  const raw = fields.error_code ?? fields.code;
+  return typeof raw === "string" && raw ? raw : null;
+}
+
+function isAuthClass(fields) {
+  return Boolean(fields && typeof fields === "object" &&
+    (fields.error_class === "auth" || CALL_AUTH_ERROR_CODES.has(typedCodeOf(fields))));
+}
+
+/**
+ * BOT-1896: classify one tools/call exchange. Pure — no I/O.
+ *   kind "ok"           — a normal result (printed as before, exit 0)
+ *   kind "tool_error"   — a non-auth isError result (printed as before, exit 0)
+ *   kind "server_error" — a non-auth JSON-RPC error (die as before, exit 1)
+ *   kind "auth"         — BotBuddy refused the credential → receipt, CALL_EXIT.AUTH
+ *   kind "transport"    — no HTTP response, or a 5xx → receipt, CALL_EXIT.TRANSPORT
+ *   kind "http_error"   — any other HTTP failure (non-JSON or error-less 4xx,
+ *                         a non-JSON 2xx) → receipt, CALL_EXIT.ERROR (fail closed)
+ * The receipt carries the server's `error_code` and typed fields UNCHANGED. A
+ * 401/403 is auth even with no typed code (an older server), never transport.
+ */
+export function classifyCallResponse({ status = null, data = null, transportError = null, parseError = null } = {}) {
+  if (transportError) {
+    return {
+      kind: "transport",
+      receipt: { ok: false, error_class: "transport", error_code: "transport_error", http_status: null, message: String(transportError?.message ?? transportError) },
+    };
+  }
+  const authStatus = status === 401 || status === 403;
+  if (parseError || !data || typeof data !== "object") {
+    if (authStatus) {
+      return { kind: "auth", receipt: { ok: false, error_class: "auth", error_code: "unauthorized", http_status: status, message: "BotBuddy refused the credential (no typed body)." } };
+    }
+    // Codex P1 (PR #970): only a 5xx gateway page reads as transport. A reachable
+    // endpoint answering non-JSON with anything else (a proxy 404 from a wrong
+    // URL, a 429 rate-limit page) must fail closed, never license a fallback.
+    return typeof status === "number" && status >= 500
+      ? { kind: "transport", receipt: { ok: false, error_class: "transport", error_code: "invalid_response", http_status: status, message: `BotBuddy returned a non-JSON response (HTTP ${status}).` } }
+      : httpError(status, `BotBuddy returned a non-JSON response (HTTP ${status ?? "?"}).`);
+  }
+  const rpcError = data.error && typeof data.error === "object" ? data.error : null;
+  if (rpcError) {
+    const detail = rpcError.data && typeof rpcError.data === "object" ? rpcError.data : {};
+    if (isAuthClass(detail) || authStatus || rpcError.code === -32001) {
+      return {
+        kind: "auth",
+        receipt: { ok: false, ...detail, error_class: "auth", error_code: typedCodeOf(detail) ?? "unauthorized", http_status: status, message: rpcError.message ?? null },
+      };
+    }
+    if (typeof status === "number" && status >= 500) {
+      return { kind: "transport", receipt: { ok: false, error_class: "transport", error_code: "server_unavailable", http_status: status, message: rpcError.message ?? null } };
+    }
+    return { kind: "server_error", receipt: null };
+  }
+  // A bare REST-style `{ error }` body (not JSON-RPC).
+  if (typeof data.error === "string") {
+    if (isAuthClass(data) || authStatus) {
+      return { kind: "auth", receipt: { ok: false, ...data, error_class: "auth", error_code: typedCodeOf(data) ?? "unauthorized", http_status: status, message: data.error } };
+    }
+    if (typeof status === "number" && status >= 500) {
+      return { kind: "transport", receipt: { ok: false, error_class: "transport", error_code: "server_unavailable", http_status: status, message: data.error } };
+    }
+    return { kind: "server_error", receipt: null };
+  }
+  if (authStatus) {
+    return { kind: "auth", receipt: { ok: false, error_class: "auth", error_code: "unauthorized", http_status: status, message: null } };
+  }
+  if (typeof status === "number" && status >= 500) {
+    return { kind: "transport", receipt: { ok: false, error_class: "transport", error_code: "server_unavailable", http_status: status, message: null } };
+  }
+  if (typeof status === "number" && status >= 400) {
+    return httpError(status, null);
+  }
+  if (data.result?.isError === true) {
+    const first = data.result?.content?.[0]?.text;
+    let envelope = null;
+    try { envelope = typeof first === "string" ? JSON.parse(first) : null; } catch { envelope = null; }
+    if (isAuthClass(envelope)) {
+      const { success: _success, ...fields } = envelope;
+      return { kind: "auth", receipt: { ok: false, ...fields, error_class: "auth", error_code: typedCodeOf(envelope), http_status: status } };
+    }
+    return { kind: "tool_error", receipt: null };
+  }
+  return { kind: "ok", receipt: null };
+}
+
+function httpError(status, message) {
+  return { kind: "http_error", receipt: { ok: false, error_class: "http", error_code: `http_${status ?? "unknown"}`, http_status: status, message } };
+}
+
+function authFailureLine(receipt) {
+  const what = receipt.error_code === "scope_denied" && receipt.tool && receipt.required_scope
+    ? `scope_denied: \`${receipt.tool}\` requires the \`${receipt.required_scope}\` scope${receipt.key_prefix ? ` (presented a ${receipt.key_prefix} key)` : ""}`
+    : receipt.error_code;
+  return `BotBuddy refused the credential (${what}).${receipt.remedy ? ` ${receipt.remedy}` : ""}`;
+}
+
+export async function callTool(toolName, args = {}, { fetchImpl = fetch, auth = null, tenant = null, resolvePin = resolveDefaultTenantPin, resolveAuth = resolveCallAuth, log = (line) => console.log(line), errorLog = (line) => console.error(line) } = {}) {
   const body = {
     jsonrpc: "2.0",
     id: 1,
     method: "tools/call",
     params: { name: toolName, arguments: args },
   };
+  // BOT-1896: never throw on the wire — a fetch rejection or a non-JSON body is
+  // returned as a classified transport failure instead of an uncaught exit 1.
   const send = async (resolved) => {
     const headers = { "Content-Type": "application/json", ...resolved.auth };
-    const res = await fetchImpl(await requestEndpoint(resolved, { tenant, resolvePin }), { method: "POST", headers, body: JSON.stringify(body) });
-    return { status: res.status, data: await res.json() };
+    let res;
+    try {
+      res = await fetchImpl(await requestEndpoint(resolved, { tenant, resolvePin }), { method: "POST", headers, body: JSON.stringify(body) });
+    } catch (transportError) {
+      return { status: null, data: null, transportError };
+    }
+    try {
+      return { status: res.status, data: await res.json() };
+    } catch (parseError) {
+      return { status: res.status, data: null, parseError };
+    }
   };
 
-  const first = auth ? { auth, source: null } : await authHeader(toolName, { resolveAuth });
-  let { status, data } = await send(first);
+  const first = auth ? { auth, source: null } : await authHeader(toolName, { resolveAuth, exitCode: CALL_EXIT.AUTH });
+  let exchange = await send(first);
   let staleSession = false;
-  if (!auth && isRejectedCachedSessionResponse(first, status, data)) {
+  if (!auth && isRejectedCachedSessionResponse(first, exchange.status, exchange.data)) {
     const durable = await resolveAuth({ toolName, preferSession: false });
-    if (durable.auth) ({ status, data } = await send(durable));
+    if (durable.auth) exchange = await send(durable);
     else staleSession = true;
   }
+  const { status, data } = exchange;
   const exportedRejected = !auth && (first.source === "env" || first.source === "flag")
     && (status === 401 || status === 403 || data?.error?.code === -32001);
 
+  const code = data?.error?.data?.code;
+  const hint = code === "MCP_TENANT_PIN_REQUIRED"
+    ? ` Pin a tenant: ${cyan("botbuddy call <tool> --pin <slug>")}, ${cyan("BOTBUDDY_TENANT=<slug>")}, or run from a repo with ${dim(".botbuddy-agent.json")}.`
+    : staleSession
+      ? ` The cached agent session in this checkout was rejected; run ${cyan("bb doctor --fix")} here.`
+      : exportedRejected
+        ? ` The exported agent session token was rejected; unset ${cyan("BOTBUDDY_AGENT_SESSION_TOKEN")} (and its legacy aliases) to use this checkout's session or your login.`
+        : "";
+
+  const outcome = classifyCallResponse(exchange);
+  if (outcome.kind === "auth") {
+    log(JSON.stringify(outcome.receipt, null, 2));
+    errorLog(`${red("✗")} ${authFailureLine(outcome.receipt)}${hint}`);
+    return CALL_EXIT.AUTH;
+  }
+  if (outcome.kind === "transport") {
+    log(JSON.stringify(outcome.receipt, null, 2));
+    errorLog(`${red("✗")} BotBuddy unreachable (${outcome.receipt.error_code}${outcome.receipt.http_status ? `, HTTP ${outcome.receipt.http_status}` : ""}): ${outcome.receipt.message ?? ""}`);
+    return CALL_EXIT.TRANSPORT;
+  }
+  if (outcome.kind === "http_error") {
+    log(JSON.stringify(outcome.receipt, null, 2));
+    errorLog(`${red("✗")} BotBuddy answered HTTP ${outcome.receipt.http_status ?? "?"} (${outcome.receipt.error_code}); not treating this as unreachable.${hint}`);
+    return CALL_EXIT.ERROR;
+  }
   if (data.error?.message) {
-    const code = data.error?.data?.code;
-    const hint = code === "MCP_TENANT_PIN_REQUIRED"
-      ? ` Pin a tenant: ${cyan("botbuddy call <tool> --pin <slug>")}, ${cyan("BOTBUDDY_TENANT=<slug>")}, or run from a repo with ${dim(".botbuddy-agent.json")}.`
-      : staleSession
-        ? ` The cached agent session in this checkout was rejected; run ${cyan("bb doctor --fix")} here.`
-        : exportedRejected
-          ? ` The exported agent session token was rejected; unset ${cyan("BOTBUDDY_AGENT_SESSION_TOKEN")} (and its legacy aliases) to use this checkout's session or your login.`
-          : "";
     die(`Server error: ${data.error.message}${hint}`);
   }
 
@@ -260,13 +424,21 @@ export async function callToolJson(toolName, args = {}, { fetchImpl = fetch, sig
     // { error: { code: -32002, data: { code } } }). Surface that `code` so a
     // caller can tell a tenant refusal apart from a plain credential failure.
     // Best-effort: an opaque/bodyless 401/403 keeps the generic shape.
+    // BOT-1896: the unauthenticated 401 now carries a typed code too
+    // (credential_unknown / session_token_revoked / …). Those are exposed as
+    // `error_code` but NOT lifted into `code`, which callers (mcp-key,
+    // isRejectedCachedMcpSession) read as "a structured refusal other than a dead
+    // credential" — so a bad key keeps its not-authenticated / self-heal path.
     let code = null;
+    let errorCode = null;
     try {
       const body = await res.json();
       const raw = body?.error?.data?.code ?? body?.error?.code ?? body?.code ?? null;
-      if (typeof raw === "string" && raw) code = raw;
+      if (typeof raw === "string" && raw && !UNAUTHENTICATED_CODES.has(raw)) code = raw;
+      const typed = body?.error?.data?.error_code ?? body?.error_code ?? null;
+      if (typeof typed === "string" && typed) errorCode = typed;
     } catch { /* opaque body */ }
-    return { ok: false, auth: true, status: res.status, error: "unauthorized", ...(code ? { code } : {}) };
+    return { ok: false, auth: true, status: res.status, error: "unauthorized", ...(code ? { code } : {}), ...(errorCode ? { error_code: errorCode } : {}) };
   }
   let payload;
   try { payload = await res.json(); } catch { return { ok: false, status: res.status, error: "invalid_json" }; }

package/src/stack.mjs

@@ -27,7 +27,7 @@ import { open, unlink, readFile } from "fs/promises";
 import { tmpdir } from "os";
 import { basename, dirname, join, relative, isAbsolute } from "path";
 import { randomUUID } from "crypto";
-import { callToolJson } from "./api.mjs";
+import { callToolJson, CALL_AUTH_ERROR_CODES } from "./api.mjs";
 import { SERVER_URL, getConfig } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
 import { AGENT_KEY_RE, readAgentSessionTokenEnv } from "./agent-key.mjs";
@@ -696,6 +696,9 @@ export function stackPathRootRefusalNotice(code, message) {
  * reads as "the control plane is unhealthy, retry". Every other refusal keeps BACKEND (5).
  */
 export function leaseRefusalExit(code) {
+  // BOT-1896: an auth-class refusal (scope_denied, a tenant mismatch, …) is the
+  // server refusing the credential — never BACKEND, which a gate reads as "down".
+  if (CALL_AUTH_ERROR_CODES.has(code)) return EXIT.AUTH;
   return code === STACK_PATH_ROOT_REFUSED_CODE ? EXIT.INVALID : EXIT.BACKEND;
 }
 
@@ -1264,10 +1267,25 @@ export function localProvision(opts, dockerTarget, execution, spawn = spawnSync,
   return conn;
 }
 
-/** LOUD local-exec fallback: tear the stack down in `stackDir`. Returns true iff it succeeded. */
-export function localTeardown(stackDir, dockerTarget, spawn = spawnSync, env = process.env) {
-  process.stderr.write(`${yellow("⚠ LOCAL-EXEC FALLBACK")} — running ${bold("supabase stop")} in ${stackDir}.\n`);
-  const res = spawn("supabase", ["stop", "--workdir", stackDir], {
+/** Release dispositions `stack done` accepts (`--destroy` is the default, `--stop` keeps volumes). */
+export const STACK_DISPOSITIONS = Object.freeze(["destroy", "stop"]);
+
+/**
+ * LOUD local-exec fallback: tear the stack down in `stackDir`. Returns true iff it succeeded.
+ *
+ * BOT-1887: the teardown honours the lease's release `disposition`. `destroy` (the `done`
+ * default, and what the receipt reports) runs `supabase stop --no-backup`, which also deletes
+ * the project's data volumes (`supabase_db_/storage_/edge_runtime_<project_id>`); `--workdir`
+ * scopes that to the stack's own project_id, never `--all`. `stop` keeps the volumes for a
+ * cheap re-provision. An unknown disposition throws before Docker is touched.
+ */
+export function localTeardown(stackDir, dockerTarget, disposition, spawn = spawnSync, env = process.env) {
+  if (!STACK_DISPOSITIONS.includes(disposition)) {
+    throw new Error(`localTeardown: unknown disposition ${JSON.stringify(disposition)} (expected one of ${STACK_DISPOSITIONS.join(", ")})`);
+  }
+  const args = ["stop", "--workdir", stackDir, ...(disposition === "destroy" ? ["--no-backup"] : [])];
+  process.stderr.write(`${yellow("⚠ LOCAL-EXEC FALLBACK")} — running ${bold(`supabase ${args.join(" ")}`)} (disposition ${disposition}).\n`);
+  const res = spawn("supabase", args, {
     encoding: "utf8",
     env: dockerEnvForTarget(dockerTarget, env),
   });
@@ -1608,7 +1626,14 @@ export async function cmdDone(leaseId, opts, {
   let dockerTarget = null;
   let legacyTargetProof = null;
   let teardownDir = process.cwd();
+  let leaseBefore = null;
   if (opts.localExec) {
+    // BOT-1887: the disposition picks the local teardown (destroy deletes the project's
+    // volumes); refuse an unknown one BEFORE the lease is released into `reaping`.
+    if (!STACK_DISPOSITIONS.includes(opts.disposition)) {
+      return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId,
+        error: `unknown disposition ${JSON.stringify(opts.disposition)} (expected one of ${STACK_DISPOSITIONS.join(", ")})` }), opts, EXIT.INVALID);
+    }
     const current = await call("get_stack_lease", { lease_id: leaseId });
     if (!current.ok || !current.data?.success) {
       return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId,
@@ -1618,6 +1643,7 @@ export async function cmdDone(leaseId, opts, {
     // BOT-1711: tear down in the directory the stack was PROVISIONED in (the lease's
     // recorded worktree_root/stack_path), not the invoking cwd — otherwise `supabase
     // stop` at the worktree root would stop the shared canonical stack.
+    leaseBefore = current.data;
     teardownDir = leaseStackDir(current.data);
     // BOT-1711 (Codex P1, R4): refuse local-exec teardown of ANY lease whose target is the
     // worktree root / default project — BEFORE branching on the persisted Docker target.
@@ -1706,13 +1732,46 @@ export async function cmdDone(leaseId, opts, {
   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;
+  // BOT-1887 (Codex #972 P1): a lease that is ALREADY reaping (an idle reap that
+  // established `stop`, or a retried `destroy`) keeps its in-flight teardown contract —
+  // `release_stack_lease` returns that established `reap_disposition` and ignores the
+  // requested one. Tear down (and report) by the established contract, never the flag,
+  // so a retry can neither delete volumes a `stop` meant to keep nor keep a `destroy`'s.
+  // Codex #972 R2 (P2): a lease that was ALREADY reaped answers `noop` with no
+  // reap_disposition — nothing was torn down by this call, so report the disposition it
+  // was actually reaped with (the lease row carries it), never the newly requested flag;
+  // unknown → null. A never-provisioned lease is terminalized as `destroy` server-side.
+  let established = r.data.reap_disposition;
+  const alreadyReaped = established == null && state === "reaped" && r.data.noop === true;
+  if (alreadyReaped) {
+    // Codex #972 R3: the pre-release read is only authoritative if it ALREADY saw the
+    // lease reaped — a Helper can finalize it between that read and the release. Otherwise
+    // re-read, and refuse to emit an unverifiable receipt if that read fails.
+    let stored = leaseBefore?.state === "reaped" ? leaseBefore : null;
+    if (!stored) {
+      const got = await call("get_stack_lease", { lease_id: leaseId });
+      stored = got.ok && got.data?.success ? got.data : null;
+      if (!stored) {
+        return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, state,
+          error: `the lease was already reaped but its reap disposition could not be read (${got.error || got.data?.code || "unreadable"}); nothing was torn down` }), opts, got.auth ? EXIT.AUTH : EXIT.BACKEND);
+      }
+    }
+    established = stored.reap_disposition ?? null;
+  } else if (established == null && r.data.never_provisioned === true) {
+    established = "destroy";
+  }
+  if (established != null && !STACK_DISPOSITIONS.includes(established)) {
+    return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, state,
+      error: `the lease's established reap disposition ${JSON.stringify(established)} is unknown — NOT tearing down; the slot stays fenced` }), opts, EXIT.BACKEND);
+  }
+  const disposition = alreadyReaped ? established : (established ?? opts.disposition);
   if (opts.localExec && state === "reaping") {
     // Only finalize once the stack is PROVABLY down. A failed `supabase stop` (Docker
     // unavailable, etc.) must NOT finalize — finalize frees the slot lock and promotes
     // 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 (!localTeardownFn(teardownDir, dockerTarget)) {
+    if (!localTeardownFn(teardownDir, dockerTarget, disposition)) {
       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.",
@@ -1722,7 +1781,7 @@ export async function cmdDone(leaseId, opts, {
     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 emitResult(buildReceipt({ command: "done", outcome: "released", lease_id: leaseId, state, disposition: opts.disposition,
+  return emitResult(buildReceipt({ command: "done", outcome: "released", lease_id: leaseId, state, disposition,
     ...(legacyTargetProof ? { legacy_target_proof: legacyTargetProof } : {}) }), opts, EXIT.OK);
 }