@botbuddy/cli 1.4.1 → 1.5.0

package/src/stack.test.mjs

@@ -5,15 +5,19 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
+import { EventEmitter } from "node:events";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { mkdtempSync, writeFileSync, mkdirSync, realpathSync } from "node:fs";
+import { mkdtempSync, writeFileSync, mkdirSync, realpathSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 
 import {
   EXIT, STACK_HELP, STACK_SCHEMA_VERSION, DEFAULT_RECEIPT_MAX_BYTES,
   deriveSlot, parseStackArgs, buildReceipt, truncateReceipt,
   parseSupabaseStatus, eventStreamBase, resolveLocalSupabaseUrl, resolveStackPath,
+  runLocalExecPreflight, dockerEnvForSelector, dockerTargetFromPreflight, connectionWithDockerTarget,
+  proveLegacyLocalExecTarget, localTeardown, cmdUp, cmdDone,
+  runStackLifecycle, materializeLeasedTestConfig, waitForLease,
 } from "./stack.mjs";
 
 const BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "botbuddy.mjs");
@@ -55,7 +59,7 @@ test("deriveSlot: throws when undeterminable", () => {
 test("parseStackArgs: up options", () => {
   const { command, opts, errors } = parseStackArgs([
     "up", "--slot", "56322", "--host", "mac", "--repo", "botbuddy-web",
-    "--ticket", "BOT-1220", "--stack-path", "infra/local", "--idle-ttl", "600", "--timeout", "120", "--no-wait", "--local-exec",
+    "--ticket", "BOT-1220", "--stack-path", "infra/local", "--idle-ttl", "600", "--timeout", "120", "--no-wait", "--local-exec", "--docker-context", "orbstack",
   ]);
   assert.equal(errors.length, 0);
   assert.equal(command, "up");
@@ -66,6 +70,326 @@ test("parseStackArgs: up options", () => {
   assert.equal(opts.timeout, 120);
   assert.equal(opts.noWait, true);
   assert.equal(opts.localExec, true);
+  assert.equal(opts.dockerContext, "orbstack");
+});
+test("parseStackArgs: local-exec up requires exactly one explicit Docker selector", () => {
+  assert.match(parseStackArgs(["up", "--slot", "x", "--local-exec"]).errors.join(" "), /docker-context.*docker-endpoint/i);
+  assert.match(parseStackArgs([
+    "up", "--slot", "x", "--local-exec", "--docker-context", "orbstack", "--docker-endpoint", "unix:///tmp/docker.sock",
+  ]).errors.join(" "), /exactly one/i);
+  assert.deepEqual(parseStackArgs([
+    "up", "--slot", "x", "--local-exec", "--docker-endpoint", "unix:///Users/test/.orbstack/run/docker.sock",
+  ]).errors, []);
+});
+
+test("parseStackArgs: local-exec done requires exactly one explicit Docker selector", () => {
+  assert.match(parseStackArgs(["done", "lease-1", "--local-exec"]).errors.join(" "), /docker-context.*docker-endpoint/i);
+  assert.equal(parseStackArgs([
+    "done", "lease-1", "--local-exec", "--docker-context", "orbstack",
+  ]).errors.length, 0);
+  assert.ok(parseStackArgs([
+    "done", "lease-1", "--local-exec", "--docker-context", "orbstack", "--docker-endpoint", "unix:///tmp/docker.sock",
+  ]).errors.length > 0);
+});
+test("parseStackArgs: a missing Docker selector value preserves the following flag", () => {
+  const parsed = parseStackArgs(["up", "--slot", "x", "--local-exec", "--docker-context", "--json"]);
+  assert.equal(parsed.opts.json, true);
+  assert.match(parsed.errors.join(" "), /--docker-context needs a value/i);
+});
+
+test("runLocalExecPreflight delegates the explicit selector and preserves refusal", () => {
+  const calls = [];
+  const expected = { exitCode: 2, receipt: { outcome: "refused", pressure: { status: "fail" } }, json: true };
+  const actual = runLocalExecPreflight({ dockerContext: "orbstack", dockerEndpoint: null }, (args) => {
+    calls.push(args);
+    return expected;
+  });
+  assert.deepEqual(calls, [["preflight", "--context", "orbstack", "--json"]]);
+  assert.equal(actual, expected);
+});
+
+test("dockerEnvForSelector replaces ambient Docker routing with the preflight target", () => {
+  assert.deepEqual(dockerEnvForSelector(
+    { dockerContext: "orbstack", dockerEndpoint: null },
+    { PATH: "/bin", DOCKER_CONTEXT: "desktop-linux", DOCKER_HOST: "tcp://wrong" },
+  ), { PATH: "/bin", DOCKER_CONTEXT: "orbstack" });
+  assert.deepEqual(dockerEnvForSelector(
+    { dockerContext: null, dockerEndpoint: "unix:///Users/test/.orbstack/run/docker.sock" },
+    { PATH: "/bin", DOCKER_CONTEXT: "desktop-linux" },
+  ), { PATH: "/bin", DOCKER_HOST: "unix:///Users/test/.orbstack/run/docker.sock" });
+});
+
+test("localTeardown passes the explicit Docker selector to supabase stop", () => {
+  let invocation;
+  const ok = localTeardown(
+    { dockerContext: "orbstack", dockerEndpoint: null },
+    { validation: "orbstack", resolved_endpoint: "unix:///Users/test/.orbstack/run/docker.sock", server_id: "daemon-1" },
+    (command, args, options) => {
+      invocation = { command, args, env: options.env };
+      return { status: 0, stdout: "", stderr: "" };
+    },
+    { PATH: "/bin", DOCKER_CONTEXT: "desktop-linux", DOCKER_HOST: "tcp://wrong" },
+  );
+  assert.equal(ok, true);
+  assert.deepEqual(invocation, {
+    command: "supabase",
+    args: ["stop", "--workdir", process.cwd()],
+    env: { PATH: "/bin", DOCKER_HOST: "unix:///Users/test/.orbstack/run/docker.sock" },
+  });
+});
+
+const targetReceipt = (serverId, endpoint = "unix:///Users/test/.orbstack/run/docker.sock") => ({
+  context: {
+    validation: "orbstack",
+    resolved_endpoint: endpoint,
+    server: { id: serverId, name: "orbstack", operating_system: "OrbStack" },
+  },
+  pressure: { status: "ok" },
+});
+
+test("dockerTargetFromPreflight requires a resolved OrbStack server identity", () => {
+  assert.deepEqual(dockerTargetFromPreflight(targetReceipt("daemon-1")), {
+    validation: "orbstack",
+    resolved_endpoint: "unix:///Users/test/.orbstack/run/docker.sock",
+    server_id: "daemon-1",
+  });
+  assert.equal(dockerTargetFromPreflight(targetReceipt(null)), null);
+});
+
+test("connectionWithDockerTarget persists the validated target in the lease connection", () => {
+  const target = dockerTargetFromPreflight(targetReceipt("daemon-1"));
+  assert.deepEqual(connectionWithDockerTarget({ api_url: "http://127.0.0.1:56321" }, target), {
+    api_url: "http://127.0.0.1:56321",
+    botbuddy_docker_target: target,
+  });
+});
+
+test("cmdDone refuses before release when teardown targets a different Docker daemon", async () => {
+  const tools = [];
+  let emitted;
+  const code = await cmdDone("lease-1", {
+    localExec: true, dockerContext: "orbstack", dockerEndpoint: null,
+    disposition: "destroy", receiptMaxBytes: DEFAULT_RECEIPT_MAX_BYTES,
+  }, {
+    callTool: async (name) => {
+      tools.push(name);
+      return { ok: true, data: { success: true, state: "active", connection: {
+        botbuddy_docker_target: dockerTargetFromPreflight(targetReceipt("daemon-1")),
+      } } };
+    },
+    runPreflight: () => ({ exitCode: 0, receipt: targetReceipt("daemon-2") }),
+    localTeardownFn: () => { throw new Error("must not stop"); },
+    emitResult: (receipt, _opts, exitCode) => { emitted = receipt; return exitCode; },
+  });
+  assert.equal(code, EXIT.LEASE_FAILED);
+  assert.deepEqual(tools, ["get_stack_lease"]);
+  assert.equal(emitted.outcome, "refused");
+});
+
+test("proveLegacyLocalExecTarget accepts only an exact owning-worktree and live connection match", () => {
+  const target = dockerTargetFromPreflight(targetReceipt("daemon-1"));
+  const worktreeRoot = realpathSync(process.cwd());
+  const lease = {
+    worktree_root: worktreeRoot,
+    stack_path: ".",
+    connection: {
+      api_url: "http://127.0.0.1:56321",
+      db_url: "postgresql://postgres:postgres@127.0.0.1:56322/postgres",
+    },
+  };
+  const spawned = [];
+  const proof = proveLegacyLocalExecTarget(lease, target, { stackPath: "." }, (command, args, options) => {
+    spawned.push({ command, args, env: options.env });
+    return { status: 0, stdout: JSON.stringify({
+      API_URL: lease.connection.api_url,
+      DB_URL: lease.connection.db_url,
+    }), stderr: "" };
+  });
+
+  assert.equal(proof.ok, true);
+  assert.equal(proof.evidence.method, "legacy_worktree_connection_match");
+  assert.equal(spawned[0].env.DOCKER_HOST, target.resolved_endpoint);
+  assert.deepEqual(spawned[0].args, ["status", "-o", "json", "--workdir", worktreeRoot]);
+
+  const mismatch = proveLegacyLocalExecTarget(lease, target, { stackPath: "." }, () => ({
+    status: 0,
+    stdout: JSON.stringify({ API_URL: "http://127.0.0.1:64321", DB_URL: lease.connection.db_url }),
+    stderr: "",
+  }));
+  assert.equal(mismatch.ok, false);
+  assert.match(mismatch.error, /connection.*does not match/i);
+});
+
+test("cmdDone safely tears down a pre-1.5.0 lease after the legacy compatibility proof", async () => {
+  const tools = [];
+  let emitted;
+  const target = dockerTargetFromPreflight(targetReceipt("daemon-1"));
+  const code = await cmdDone("lease-legacy", {
+    localExec: true, dockerContext: "orbstack", dockerEndpoint: null, stackPath: ".",
+    disposition: "destroy", receiptMaxBytes: DEFAULT_RECEIPT_MAX_BYTES,
+  }, {
+    callTool: async (name) => {
+      tools.push(name);
+      if (name === "get_stack_lease") return { ok: true, data: {
+        success: true, state: "active", worktree_root: process.cwd(), stack_path: ".",
+        connection: { api_url: "http://127.0.0.1:56321", db_url: "postgresql://127.0.0.1:56322/postgres" },
+      } };
+      if (name === "release_stack_lease") return { ok: true, data: { success: true, state: "reaping" } };
+      if (name === "finalize_stack_lease") return { ok: true, data: { success: true, state: "reaped" } };
+      throw new Error(`unexpected tool ${name}`);
+    },
+    runPreflight: () => ({ exitCode: 0, receipt: targetReceipt("daemon-1") }),
+    proveLegacyTarget: () => ({ ok: true, evidence: { method: "legacy_worktree_connection_match" } }),
+    localTeardownFn: () => true,
+    emitResult: (receipt, _opts, exitCode) => { emitted = receipt; return exitCode; },
+  });
+
+  assert.equal(code, EXIT.OK);
+  assert.deepEqual(tools, ["get_stack_lease", "release_stack_lease", "finalize_stack_lease"]);
+  assert.deepEqual(emitted.legacy_target_proof, { method: "legacy_worktree_connection_match" });
+});
+
+test("cmdDone refuses a legacy lease before release when compatibility proof is absent", async () => {
+  const tools = [];
+  let emitted;
+  const code = await cmdDone("lease-legacy", {
+    localExec: true, dockerContext: "orbstack", dockerEndpoint: null, stackPath: ".",
+    disposition: "destroy", receiptMaxBytes: DEFAULT_RECEIPT_MAX_BYTES,
+  }, {
+    callTool: async (name) => {
+      tools.push(name);
+      return { ok: true, data: { success: true, state: "active", connection: { api_url: "http://127.0.0.1:56321" } } };
+    },
+    runPreflight: () => ({ exitCode: 0, receipt: targetReceipt("daemon-1") }),
+    proveLegacyTarget: () => ({ ok: false, error: "legacy worktree metadata is missing" }),
+    localTeardownFn: () => { throw new Error("must not stop"); },
+    emitResult: (receipt, _opts, exitCode) => { emitted = receipt; return exitCode; },
+  });
+
+  assert.equal(code, EXIT.LEASE_FAILED);
+  assert.deepEqual(tools, ["get_stack_lease"]);
+  assert.match(emitted.error, /legacy worktree metadata is missing/i);
+});
+
+test("cmdDone stops and finalizes only after the fresh Docker identity matches the lease", async () => {
+  const tools = [];
+  let teardownTarget;
+  const target = dockerTargetFromPreflight(targetReceipt("daemon-1"));
+  const code = await cmdDone("lease-1", {
+    localExec: true, dockerContext: "orbstack", dockerEndpoint: null,
+    disposition: "destroy", receiptMaxBytes: DEFAULT_RECEIPT_MAX_BYTES,
+  }, {
+    callTool: async (name) => {
+      tools.push(name);
+      if (name === "get_stack_lease") return { ok: true, data: { success: true, state: "active", connection: { botbuddy_docker_target: target } } };
+      if (name === "release_stack_lease") return { ok: true, data: { success: true, state: "reaping" } };
+      if (name === "finalize_stack_lease") return { ok: true, data: { success: true, state: "reaped" } };
+      throw new Error(`unexpected tool ${name}`);
+    },
+    runPreflight: () => ({ exitCode: 0, receipt: targetReceipt("daemon-1") }),
+    localTeardownFn: (_opts, actual) => { teardownTarget = actual; return true; },
+    emitResult: (_receipt, _opts, exitCode) => exitCode,
+  });
+  assert.equal(code, EXIT.OK);
+  assert.deepEqual(tools, ["get_stack_lease", "release_stack_lease", "finalize_stack_lease"]);
+  assert.deepEqual(teardownTarget, target);
+});
+
+test("cmdUp refuses pressure before lease request or local provisioning", async () => {
+  const events = [];
+  let emitted;
+  const code = await cmdUp({
+    slot: "botbuddy-web-bot-1405", repo: "botbuddy-web", ticket: "BOT-1405",
+    stackPath: ".", localExec: true, dockerContext: "orbstack", dockerEndpoint: null,
+  }, {
+    runPreflight: () => ({
+      exitCode: 2,
+      receipt: {
+        outcome: "refused", context: { selector: "orbstack" },
+        pressure: { status: "fail", projected_pressure_units: 224 },
+        warnings: [], errors: ["interface pressure refusal"], recommendation: "run hygiene",
+      },
+      json: true,
+    }),
+    callTool: async (...args) => { events.push(["tool", ...args]); throw new Error("must not request a lease"); },
+    localProvisionFn: () => { events.push(["provision"]); throw new Error("must not start Supabase"); },
+    emitResult: (receipt, _opts, exitCode) => { emitted = receipt; return exitCode; },
+  });
+
+  assert.equal(code, EXIT.LEASE_FAILED);
+  assert.equal(emitted.outcome, "refused");
+  assert.equal(emitted.preflight.pressure.status, "fail");
+  assert.deepEqual(events, []);
+});
+
+test("cmdUp atomically cancels an unclaimed lease when the just-in-time preflight refuses", async () => {
+  const tools = [];
+  let preflights = 0;
+  let emitted;
+  const okReceipt = {
+    ...targetReceipt("daemon-1"), outcome: "ok", pressure: { status: "ok" },
+    warnings: [], errors: [], recommendation: "none",
+  };
+  const refusedReceipt = {
+    ...targetReceipt("daemon-1"), outcome: "refused", pressure: { status: "fail" },
+    warnings: [], errors: ["interface pressure refusal"], recommendation: "run hygiene",
+  };
+  const code = await cmdUp({
+    slot: "botbuddy-web-bot-1405", host: "test-mac", repo: "botbuddy-web", ticket: "BOT-1405",
+    stackPath: ".", localExec: true, dockerContext: "orbstack", dockerEndpoint: null,
+    timeout: 60, noWait: false, json: false,
+  }, {
+    authProvider: () => ({ Authorization: "test" }),
+    runPreflight: () => ({
+      exitCode: preflights++ === 0 ? 0 : 2,
+      receipt: preflights === 1 ? okReceipt : refusedReceipt,
+      json: true,
+    }),
+    callTool: async (tool, args) => {
+      tools.push([tool, args]);
+      if (tool === "request_stack_lease") return { ok: true, data: { success: true, lease_id: "lease-1", state: "provisioning" } };
+      if (tool === "cancel_unclaimed_stack_lease") return { ok: true, data: { success: true, state: "reaped", provision_job_cancelled: true } };
+      throw new Error(`unexpected tool ${tool}`);
+    },
+    localProvisionFn: () => { throw new Error("must not start Supabase"); },
+    emitResult: (receipt, _opts, exitCode) => { emitted = receipt; return exitCode; },
+  });
+
+  assert.equal(code, EXIT.LEASE_FAILED);
+  assert.deepEqual(tools.map(([tool]) => tool), ["request_stack_lease", "cancel_unclaimed_stack_lease"]);
+  assert.equal(emitted.outcome, "refused");
+  assert.deepEqual(emitted.lease_cancellation, { success: true, state: "reaped", provision_job_cancelled: true });
+});
+
+test("cmdUp persists the validated Docker identity used by local provisioning", async () => {
+  const target = dockerTargetFromPreflight(targetReceipt("daemon-1"));
+  let provisionTarget;
+  let activatedConnection;
+  const code = await cmdUp({
+    slot: "botbuddy-web-bot-1405", host: "test-mac", repo: "botbuddy-web", ticket: "BOT-1405",
+    stackPath: ".", localExec: true, dockerContext: "orbstack", dockerEndpoint: null,
+    timeout: 60, noWait: false, json: false,
+  }, {
+    authProvider: () => ({ Authorization: "test" }),
+    runPreflight: () => ({ exitCode: 0, receipt: { ...targetReceipt("daemon-1"), outcome: "ok", warnings: [], errors: [] } }),
+    localProvisionFn: (_opts, actualTarget) => {
+      provisionTarget = actualTarget;
+      return { api_url: "http://127.0.0.1:56321" };
+    },
+    callTool: async (name, args) => {
+      if (name === "request_stack_lease") return { ok: true, data: { success: true, lease_id: "lease-1", state: "provisioning" } };
+      if (name === "activate_stack_lease") {
+        activatedConnection = args.connection;
+        return { ok: true, data: { success: true, state: "active" } };
+      }
+      if (name === "get_stack_lease") return { ok: true, data: { success: true, state: "active", slot: "botbuddy-web-bot-1405", connection: activatedConnection } };
+      throw new Error(`unexpected tool ${name}`);
+    },
+    emitResult: (_receipt, _opts, exitCode) => exitCode,
+  });
+  assert.equal(code, EXIT.OK);
+  assert.deepEqual(provisionTarget, target);
+  assert.deepEqual(activatedConnection.botbuddy_docker_target, target);
 });
 test("parseStackArgs: rejects absolute and escaping stack paths", () => {
   assert.ok(parseStackArgs(["up", "--stack-path", "/tmp/stack"]).errors.length > 0);
@@ -99,6 +423,242 @@ test("parseStackArgs: --stop sets disposition stop (default destroy)", () => {
   assert.equal(parseStackArgs(["done", "id"]).opts.disposition, "destroy");
   assert.equal(parseStackArgs(["done", "id", "--stop"]).opts.disposition, "stop");
 });
+test("BOT-1346: run requires an argv boundary and rejects direct Docker fallback", () => {
+  assert.ok(parseStackArgs(["run", "--repo", "botbuddy-web", "--ticket", "BOT-1346"]).errors.some((e) => e.includes("executable")));
+  assert.ok(parseStackArgs(["run", "--repo", "botbuddy-web", "--ticket", "BOT-1346", "--local-exec", "--", "echo", "ok"]).errors.some((e) => e.includes("forbidden")));
+  const parsed = parseStackArgs(["run", "--repo", "botbuddy-web", "--ticket", "BOT-1346", "--", "node", "-e", "process.exit(0)"]);
+  assert.equal(parsed.errors.length, 0);
+  assert.deepEqual(parsed.childArgv, ["node", "-e", "process.exit(0)"]);
+});
+
+test("BOT-1346: a clean lease-stream EOF honours the original deadline", async () => {
+  const requests = [];
+  const expired = await waitForLease(
+    "lease-1346", () => false, () => false,
+    { timeoutSec: 5, deadlineMs: Date.now() - 1, auth: { Authorization: "Bearer test" } },
+    async (_url, options = {}) => {
+      requests.push(options.method ?? "GET");
+      if (options.method === "POST") return new Response(JSON.stringify({ cursor_start: null }), { status: 200 });
+      return new Response(new ReadableStream({ start(controller) { controller.close(); } }), { status: 200 });
+    },
+  );
+  assert.deepEqual(expired, { timeout: true });
+  assert.deepEqual(requests, ["POST", "GET"]);
+});
+
+test("BOT-1346: a stalled lease-wait registration is aborted at its deadline", async () => {
+  let registrationSignal = null;
+  const result = await waitForLease(
+    "lease-1346", () => false, () => false,
+    { timeoutSec: 0.02, auth: { Authorization: "Bearer test" } },
+    async (_url, options = {}) => {
+      registrationSignal = options.signal;
+      return await new Promise((_resolve, reject) => options.signal.addEventListener("abort", () => reject(new Error("aborted")), { once: true }));
+    },
+  );
+  assert.equal(registrationSignal.aborted, true);
+  assert.deepEqual(result, { timeout: true });
+});
+
+test("BOT-1346: stack run owns active → argv child → signed reap and never exposes connection", async () => {
+  const calls = [];
+  const signals = new EventEmitter();
+  const fakeChild = new EventEmitter(); fakeChild.pid = 4242;
+  let written = null; const removed = []; let childCall = null;
+  const result = await runStackLifecycle(
+    { repo: "botbuddy-web", ticket: "BOT-1346", stackPath: ".", timeout: 5, reapTimeout: 5, connectionFile: "/tmp/bot-1346-connection.json" },
+    ["pnpm", "test:all"],
+    {
+      auth: { Authorization: "Bearer test" }, signals,
+      api: {
+        request: async () => ({ ok: true, data: { success: true, lease_id: "lease-1346", state: "active" } }),
+        get: async () => ({ ok: true, data: { success: true, state: "active", idle_ttl_secs: 30, connection: { db_url: "postgres://secret" } } }),
+        touch: async () => ({ ok: true, data: { success: true } }),
+        release: async (id) => { calls.push(["release", id]); return { ok: true, data: { success: true, state: "reaping" } }; },
+      },
+      wait: async (_id, done) => done("reaped") ? { woke: true, state: "reaped" } : { woke: true, state: "active" },
+      writeConnection: async (path, connection) => { written = { path, connection }; return path; },
+      materializeTestConfig: async () => ({
+        envFile: "/tmp/bot-1346-integration.env",
+        stackConfig: "/tmp/bot-1346-stack.toml",
+      }),
+      removeConnection: async (path) => { removed.push(path); },
+      startChild: (argv, env, cwd) => { childCall = { argv, env, cwd }; queueMicrotask(() => fakeChild.emit("exit", 7, null)); return fakeChild; },
+      clock: { setInterval: () => ({ unref() {} }), clearInterval() {}, setTimeout: () => ({ unref() {} }), clearTimeout() {} },
+    },
+  );
+  assert.equal(result.exitCode, 7, "successful cleanup must not mask the child failure");
+  assert.deepEqual(childCall.argv, ["pnpm", "test:all"], "argv is forwarded without shell parsing");
+  assert.equal(childCall.env.BOTBUDDY_STACK_LEASE_ID, "lease-1346");
+  assert.equal(childCall.env.BOTBUDDY_STACK_CONNECTION_FILE, written.path);
+  assert.equal(childCall.env.BB_INTEGRATION_ENV_FILE, "/tmp/bot-1346-integration.env");
+  assert.equal(childCall.env.BB_STACK_CONFIG, "/tmp/bot-1346-stack.toml");
+  assert.equal(written.connection.db_url, "postgres://secret");
+  assert.deepEqual(removed.sort(), [written.path, "/tmp/bot-1346-integration.env", "/tmp/bot-1346-stack.toml"].sort());
+  assert.deepEqual(calls, [["release", "lease-1346"]]);
+  assert.doesNotMatch(JSON.stringify(result), /postgres:\/\/secret/);
+});
+
+test("BOT-1346: materialized integration environment uses the leased database port", async () => {
+  const root = mkdtempSync(join(tmpdir(), "bb-stack-integration-"));
+  const integrationDir = join(root, "supabase", "functions", "_test", "integration");
+  mkdirSync(integrationDir, { recursive: true });
+  writeFileSync(join(integrationDir, ".env.integration"), "SUPABASE_URL=http://127.0.0.1:56321\nINTEGRATION_DB_PORT=56322\n");
+  const config = await materializeLeasedTestConfig(root, "lease-port", {
+    api_url: "http://127.0.0.1:64321", db_port: 64322, anon_key: "anon", service_role_key: "service", project_id: "leased-project",
+  });
+  assert.match(readFileSync(config.envFile, "utf8"), /^INTEGRATION_DB_PORT=64322$/m);
+  assert.match(readFileSync(config.stackConfig, "utf8"), /port = 64322/);
+});
+
+test("BOT-1346: materialized integration config removes dotenv if its TOML write fails", async () => {
+  const root = mkdtempSync(join(tmpdir(), "bb-stack-integration-"));
+  const integrationDir = join(root, "supabase", "functions", "_test", "integration");
+  mkdirSync(integrationDir, { recursive: true });
+  writeFileSync(join(integrationDir, ".env.integration"), "SUPABASE_URL=http://127.0.0.1:56321\n");
+  const writes = []; const removed = [];
+  await assert.rejects(
+    materializeLeasedTestConfig(root, "lease-cleanup", {
+      api_url: "http://127.0.0.1:64321", db_port: 64322, anon_key: "anon", service_role_key: "service", project_id: "leased-project",
+    }, {
+      writePrivate: async (path) => { writes.push(path); if (writes.length === 2) throw new Error("ENOSPC"); },
+      removePrivate: async (path) => { removed.push(path); },
+    }),
+    /ENOSPC/,
+  );
+  assert.equal(writes.length, 2);
+  assert.deepEqual(removed, [writes[0]]);
+});
+
+test("BOT-1346: queue wait errors retain a failed signed-cleanup receipt", async () => {
+  const result = await runStackLifecycle(
+    { repo: "botbuddy-web", ticket: "BOT-1346", stackPath: ".", timeout: 5, reapTimeout: 5 },
+    ["pnpm", "test:integration"],
+    {
+      auth: { Authorization: "Bearer test" }, signals: new EventEmitter(),
+      api: {
+        request: async () => ({ ok: true, data: { success: true, lease_id: "lease-queue-error", state: "queued" } }),
+        release: async (_leaseId, signal) => {
+          assert(signal instanceof AbortSignal, "cleanup release receives the reap deadline signal");
+          return { ok: false, error: "signed reap unavailable" };
+        },
+      },
+      wait: async () => ({ error: "lease stream broke" }),
+    },
+  );
+  assert.equal(result.exitCode, EXIT.LEASE_FAILED);
+  assert.equal(result.cleanup.ok, false);
+  assert.match(result.cleanup.error, /signed reap unavailable/);
+});
+
+test("BOT-1346: queue timeout receipt retains a failed cleanup result", async () => {
+  const result = await runStackLifecycle(
+    { repo: "botbuddy-web", ticket: "BOT-1346", stackPath: ".", timeout: 5, reapTimeout: 5 }, ["pnpm", "test:integration"],
+    {
+      auth: { Authorization: "Bearer test" }, signals: new EventEmitter(),
+      api: {
+        request: async () => ({ ok: true, data: { success: true, lease_id: "lease-queued", state: "queued" } }),
+        release: async () => ({ ok: false, error: "release rejected" }),
+      },
+      wait: async () => ({ timeout: true }),
+      clock: { setInterval: () => ({ unref() {} }), clearInterval() {}, setTimeout: () => ({ unref() {} }), clearTimeout() {} },
+    },
+  );
+  assert.equal(result.exitCode, EXIT.TIMEOUT);
+  assert.equal(result.cleanup.ok, false);
+  assert.match(result.cleanup.error, /release rejected/);
+});
+
+test("BOT-1346: interruption during lease creation releases the lease once its ID arrives", async () => {
+  const signals = new EventEmitter();
+  let resolveRequest; let releases = 0;
+  const pending = runStackLifecycle(
+    { repo: "botbuddy-web", ticket: "BOT-1346", stackPath: ".", timeout: 5, reapTimeout: 5 }, ["pnpm", "test:integration"],
+    {
+      auth: { Authorization: "Bearer test" }, signals,
+      api: {
+        request: () => new Promise((resolve) => { resolveRequest = resolve; }),
+        release: async () => { releases++; return { ok: true, data: { success: true, state: "reaping" } }; },
+      },
+      wait: async () => ({ woke: true, state: "reaped" }),
+      clock: { setInterval: () => ({ unref() {} }), clearInterval() {}, setTimeout: () => ({ unref() {} }), clearTimeout() {} },
+    },
+  );
+  signals.emit("SIGINT");
+  resolveRequest({ ok: true, data: { success: true, lease_id: "lease-interrupted-request", state: "queued" } });
+  const result = await pending;
+  assert.equal(result.exitCode, 130);
+  assert.equal(releases, 1);
+  assert.equal(result.cleanup.ok, true);
+});
+
+test("BOT-1346: forced hard TTL cannot turn an incomplete child run into success", async () => {
+  const fakeChild = new EventEmitter(); fakeChild.pid = 4244;
+  let hardTimeout;
+  const result = await runStackLifecycle(
+    { repo: "botbuddy-web", ticket: "BOT-1346", stackPath: ".", timeout: 5, reapTimeout: 5, hardTtl: 1 }, ["node", "-e", "process.exit(0)"],
+    {
+      auth: { Authorization: "Bearer test" }, signals: new EventEmitter(),
+      api: {
+        request: async () => ({ ok: true, data: { success: true, lease_id: "lease-ttl", state: "active" } }),
+        get: async () => ({ ok: true, data: { success: true, state: "active", connection: {} } }),
+        touch: async () => ({ ok: true, data: { success: true } }),
+        release: async () => ({ ok: true, data: { success: true, state: "reaping" } }),
+      },
+      wait: async () => ({ woke: true, state: "reaped" }), writeConnection: async (path) => path, removeConnection: async () => {},
+      startChild: () => { queueMicrotask(() => { hardTimeout(); fakeChild.emit("exit", 0, null); }); return fakeChild; },
+      clock: { setInterval: () => ({ unref() {} }), clearInterval() {}, setTimeout: (fn) => { hardTimeout = fn; return { unref() {} }; }, clearTimeout() {} },
+    },
+  );
+  assert.equal(result.exitCode, EXIT.TIMEOUT);
+});
+
+test("BOT-1346: a fenced lease cannot report a gracefully-stopped child as success", async () => {
+  const fakeChild = new EventEmitter(); fakeChild.pid = 4245;
+  let heartbeat;
+  const result = await runStackLifecycle(
+    { repo: "botbuddy-web", ticket: "BOT-1346", stackPath: ".", timeout: 5, reapTimeout: 5 }, ["node", "-e", "process.exit(0)"],
+    {
+      auth: { Authorization: "Bearer test" }, signals: new EventEmitter(),
+      api: {
+        request: async () => ({ ok: true, data: { success: true, lease_id: "lease-fenced", state: "active" } }),
+        get: async () => ({ ok: true, data: { success: true, state: "active", connection: {} } }),
+        touch: async () => ({ ok: false, error: "lease unavailable" }),
+        release: async () => ({ ok: true, data: { success: true, state: "reaping" } }),
+      },
+      wait: async () => ({ woke: true, state: "reaped" }), writeConnection: async (path) => path, removeConnection: async () => {},
+      startChild: () => { queueMicrotask(async () => { await heartbeat(); fakeChild.emit("exit", 0, null); }); return fakeChild; },
+      clock: { setInterval: (fn) => { heartbeat = fn; return { unref() {} }; }, clearInterval() {}, setTimeout: () => ({ unref() {} }), clearTimeout() {} },
+    },
+  );
+  assert.equal(result.exitCode, EXIT.LEASE_FAILED);
+  assert.equal(result.fenced, true);
+});
+
+test("BOT-1346: stack run reports failed signed cleanup after a successful child", async () => {
+  const fakeChild = new EventEmitter(); fakeChild.pid = 4243;
+  const result = await runStackLifecycle(
+    { repo: "botbuddy-web", ticket: "BOT-1346", stackPath: ".", timeout: 5, reapTimeout: 5 },
+    ["node", "-e", "process.exit(0)"],
+    {
+      auth: { Authorization: "Bearer test" }, signals: new EventEmitter(),
+      api: {
+        request: async () => ({ ok: true, data: { success: true, lease_id: "lease-unreaped", state: "active" } }),
+        get: async () => ({ ok: true, data: { success: true, state: "active", connection: {} } }),
+        touch: async () => ({ ok: true, data: { success: true } }),
+        release: async () => ({ ok: true, data: { success: true, state: "reaping" } }),
+      },
+      wait: async () => ({ timeout: true }),
+      writeConnection: async (path) => path,
+      removeConnection: async () => {},
+      startChild: () => { queueMicrotask(() => fakeChild.emit("exit", 0, null)); return fakeChild; },
+      clock: { setInterval: () => ({ unref() {} }), clearInterval() {}, setTimeout: () => ({ unref() {} }), clearTimeout() {} },
+    },
+  );
+  assert.equal(result.childExitCode, 0);
+  assert.equal(result.exitCode, EXIT.CLEANUP_FAILED);
+  assert.equal(result.cleanup.ok, false);
+});
 
 // ── receipts ─────────────────────────────────────────────────────────────────
 test("buildReceipt: stamps schema_version", () => {
@@ -155,7 +715,7 @@ test("resolveLocalSupabaseUrl: ignores a NON-local exported origin (refuses →
 
 // ── --help snapshot (AC-4) ───────────────────────────────────────────────────
 test("STACK_HELP documents the four subcommands and every exit code", () => {
-  for (const s of ["stack up", "stack status", "stack touch", "stack done", "--local-exec", "--no-wait"]) {
+  for (const s of ["stack up", "stack status", "stack touch", "stack done", "--local-exec", "--docker-context", "--no-wait"]) {
     assert.ok(STACK_HELP.includes(s), `help missing ${s}`);
   }
   for (const s of ["0 ok", "2 park timed out", "3 not authenticated", "4 invalid", "5 backend", "6 lease failed", "7 internal"]) {