@botbuddy/cli 1.31.1 → 1.32.0

package/package.json

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

package/src/agent-key.mjs

@@ -9,6 +9,8 @@
 // (supabase/functions/_shared/sessionToken.ts). The prior `bb_agent_` shape is
 // accepted as a legacy alias for one release (its hash is already on `sessions`).
 // This is a SHAPE check only — authorization is the server's hashed lookup.
+import { TIER3_LEGACY, credentialTier } from "./credential-kinds.mjs";
+
 export const AGENT_KEY_RE = /^bb_(agent|sess)_[0-9a-f]{64}$/;
 
 // BOT-1649: BOTBUDDY_AGENT_SESSION_TOKEN names the short-lived credential
@@ -32,3 +34,57 @@ export function readAgentSessionTokenEnv(env = process.env) {
 
 // Deprecated exported alias for downstream CLI integrations.
 export const readAgentKeyEnv = readAgentSessionTokenEnv;
+
+// BOT-1701 (AC-6) — one canonical stderr nudge when a tier-3 legacy alias is used
+// for a wait/run: a legacy CLI flag (--agent-key / --session-token), a legacy env
+// var (BOTBUDDY_AGENT_KEY / BOTBUDDY_SESSION_TOKEN) that actually supplied the
+// token, or a bb_agent_-prefixed token value. Returns a SINGLE line (never more)
+// naming the canonical flag + env, or null when only canonical names were used.
+// The caller writes it to STDERR only, so a machine-parseable stdout receipt is
+// byte-identical to a canonical-flag run. Precedence matches the CLI: a token
+// flag overrides the env, so the env is only "used" when no token flag was given.
+// The value passed after any tier-3 token flag (canonical or legacy), or null.
+function tokenAfterFlag(argv, flags) {
+  for (let i = 0; i < argv.length; i++) {
+    if (flags.includes(argv[i])) return argv[i + 1] ?? null;
+  }
+  return null;
+}
+
+export function legacyAgentAliasHint({ argv = [], env = process.env, token = null } = {}) {
+  const tier3 = credentialTier(3);
+  const canonicalFlag = tier3.flag; // --agent-session-token
+  const canonicalEnv = tier3.env; // BOTBUDDY_AGENT_SESSION_TOKEN
+  const tokenFlags = [canonicalFlag, ...TIER3_LEGACY.flags];
+
+  // Only the CLI's own args count. `bb run/test … -- <workload> --agent-key …`
+  // forwards a workload after `--` whose identically named flags are NOT BotBuddy
+  // credentials, so never scan past the separator (Codex R6).
+  const sep = argv.indexOf("--");
+  const cliArgs = sep === -1 ? argv : argv.slice(0, sep);
+
+  const legacyFlagUsed = TIER3_LEGACY.flags.some((f) => cliArgs.includes(f));
+  const flagToken = tokenAfterFlag(cliArgs, tokenFlags);
+  const anyTokenFlag = flagToken !== null || legacyFlagUsed || cliArgs.includes(canonicalFlag);
+
+  // The value the env would supply (canonical wins), so a bb_agent_ VALUE behind
+  // the canonical flag/env is nudged even though the NAME is canonical.
+  let legacyEnvUsed = false;
+  let envToken = null;
+  if (!anyTokenFlag) {
+    const canonical = typeof env[canonicalEnv] === "string" ? env[canonicalEnv].trim() : "";
+    if (canonical) {
+      envToken = env[canonicalEnv];
+    } else {
+      for (const e of TIER3_LEGACY.envs) {
+        if (typeof env[e] === "string" && env[e].trim() !== "") { legacyEnvUsed = true; envToken = env[e]; break; }
+      }
+    }
+  }
+
+  const effectiveToken = token ?? flagToken ?? envToken;
+  const legacyPrefixUsed = typeof effectiveToken === "string" && effectiveToken.startsWith(TIER3_LEGACY.prefix);
+
+  if (!legacyFlagUsed && !legacyEnvUsed && !legacyPrefixUsed) return null;
+  return `note: --agent-key / --session-token / $BOTBUDDY_AGENT_KEY / ${TIER3_LEGACY.prefix} are one-release legacy aliases — use ${canonicalFlag} or $${canonicalEnv} (docs/agent-connectivity.md)`;
+}

package/src/credential-kinds.mjs

@@ -30,6 +30,48 @@ export const CREDENTIAL_PREFIXES = [
   { prefix: "bb_", kind: "legacy", label: "legacy personal key" },
 ];
 
+// BOT-1701 — the ONE canonical per-tier credential contract. The same noun,
+// prefix, CLI flag, env var, and `credential_kind` for each tier, named the same
+// way EVERYWHERE it is met: the setup-block help text, the connectivity guide's
+// tier table, the `bb wait/run/test/pw --help` flags, the connectivity error
+// strings, and the server's `whoami credential_kind`. A drift test
+// (credential-naming-contract.test.mjs) fails when any of those surfaces names a
+// tier-3 credential by anything other than the canonical noun/flag/env below.
+// Decided by BOT-1649 — do not re-decide here. Additive only: legacy aliases
+// (TIER3_LEGACY) keep working for one release and are listed separately so a
+// surface can name them ONLY on a line that says "alias"/"legacy".
+/**
+ * @typedef {{ tier: 1|2|3, noun: string, prefix: string, flag: string|null, env: string, kind: string }} CredentialTier
+ * @type {ReadonlyArray<CredentialTier>}
+ */
+export const CREDENTIAL_TIERS = Object.freeze([
+  Object.freeze({ tier: 1, noun: "client key", prefix: "bb_cli_", flag: null, env: "BOTBUDDY_CLIENT_KEY", kind: "cli" }),
+  Object.freeze({ tier: 2, noun: "MCP key", prefix: "bb_mcp_", flag: null, env: "BOTBUDDY_MCP_KEY", kind: "mcp" }),
+  Object.freeze({ tier: 3, noun: "agent session token", prefix: "bb_sess_", flag: "--agent-session-token", env: "BOTBUDDY_AGENT_SESSION_TOKEN", kind: "agent_session" }),
+]);
+
+/**
+ * The tier-3 legacy aliases, accepted for one release. Kept apart from the
+ * canonical table so a surface can name them only on an "alias"/"legacy" line and
+ * the CLI can nudge an operator toward the canonical flag/env (BOT-1701 AC-6).
+ */
+export const TIER3_LEGACY = Object.freeze({
+  flags: Object.freeze(["--agent-key", "--session-token"]),
+  envs: Object.freeze(["BOTBUDDY_AGENT_KEY", "BOTBUDDY_SESSION_TOKEN"]),
+  prefix: "bb_agent_",
+});
+
+/** The canonical tier row for a tier number (1|2|3), or undefined. */
+export function credentialTier(tier) {
+  return CREDENTIAL_TIERS.find((t) => t.tier === tier);
+}
+
+/** The canonical tier row whose prefix a secret carries, or undefined. */
+export function credentialTierByPrefix(secret) {
+  if (typeof secret !== "string") return undefined;
+  return CREDENTIAL_TIERS.find((t) => secret.startsWith(t.prefix));
+}
+
 /**
  * Classify a raw secret by its prefix.
  * @param {unknown} secret

package/src/pw/run.mjs

@@ -7,13 +7,13 @@ import { canonicalizeHostString } from "./host.mjs";
 import { resolveAgentBinding } from "../wait-profile.mjs";
 import { loadConfig, getConfig } from "../config.mjs";
 import { VERSION } from "../version.mjs";
-import { readAgentSessionTokenEnv, AGENT_KEY_RE } from "../agent-key.mjs";
+import { readAgentSessionTokenEnv, AGENT_KEY_RE, legacyAgentAliasHint } from "../agent-key.mjs";
 import { clearAgentState, isRejectedCachedMcpSession, resolveAgentSessionCredential } from "../agent-session.mjs";
 // BOT-1488: canonicalize the raw hostname the SAME way acquire_resources does
 // server-side, so the lane name bb-pw builds/matches/prints is the one the lock
 // kernel actually stored ("jonos-mbp:8", not "Jonos-MBP.localdomain:8").
 const hostFor = (env) => canonicalizeHostString(env.PLAYWRIGHT_MCP_HOST || env.HOSTNAME || os.hostname());
-function help(out) { out.write("Usage: pw [--tenant <slug>] [--session-id <id>] <lane> <verb> [args…]\n\nAliases: bb-pw <lane> <verb> [args…]   ·   botbuddy pw <lane> <verb> [args…]\n         (all three drive the same lock-gated Playwright lane)\n\n--session-id <id>  accept a lane held by this arming-session agent id (from\n                   register_agent); defaults to $BOTBUDDY_SESSION_ID, then the\n                   id saved by `botbuddy register`.\n--tenant <slug>    override the worktree .botbuddy-agent.json tenant when falling\n                   back to the .mcp.json ($BOTBUDDY_MCP_KEY) credential.\n"); }
+function help(out) { out.write("Usage: pw [--tenant <slug>] [--session-id <id>] [--agent-session-token <token>] <lane> <verb> [args…]\n\nAliases: bb-pw <lane> <verb> [args…]   ·   botbuddy pw <lane> <verb> [args…]\n         (all three drive the same lock-gated Playwright lane)\n\n--session-id <id>  accept a lane held by this arming-session agent id (from\n                   register_agent); defaults to $BOTBUDDY_SESSION_ID, then the\n                   id saved by `botbuddy register`.\n--agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN);\n                   --agent-key / --session-token are one-release legacy aliases.\n--tenant <slug>    override the worktree .botbuddy-agent.json tenant when falling\n                   back to the .mcp.json ($BOTBUDDY_MCP_KEY) credential.\n"); }
 function redact(value, secretValues = []) { return secretValues.reduce((text, secret) => secret ? text.split(secret).join("[redacted]") : text, String(value ?? "")); }
 // BOT-1488: the register_agent identity for this machine, persisted by
 // `botbuddy register` into ~/.botbuddy/config.json. This is the SESSION agent
@@ -99,9 +99,28 @@ export async function runPw(argv, deps = {}) {
   if (code !== 0) stderr.write(`${versionLine()} — if your checkout's cli/package.json is newer, this global is stale: npm i -g @botbuddy/cli@latest, or run node cli/bin/bb-pw.mjs from the repo.\n`);
   return code;
 }
+// The leading option/value pairs bb pw consumes before the lane/verb (mirrors the
+// while-loop in runPwInner). Everything after the first non-option (the lane) is a
+// Playwright workload argument and is never a BotBuddy credential.
+const PW_LEADING_FLAGS = ["--tenant", "--session-id", "--agent-session-token", "--agent-key", "--session-token"];
+function leadingPwOptions(args) {
+  const lead = [];
+  for (let i = 0; i < args.length && PW_LEADING_FLAGS.includes(args[i]); i += 2) {
+    lead.push(args[i]);
+    if (i + 1 < args.length) lead.push(args[i + 1]);
+  }
+  return lead;
+}
+
 async function runPwInner(argv, deps = {}) {
   const env = deps.env ?? process.env, stdout = deps.stdout ?? process.stdout, stderr = deps.stderr ?? process.stderr; let args = [...argv]; if (["--help", "-h"].includes(args[0])) { help(stdout); return 0; }
   if (["--version", "-v"].includes(args[0])) { stdout.write(`${versionLine()}\n`); return 0; }
+  // BOT-1701 (AC-6): one stderr nudge for a tier-3 legacy flag/env alias. bb pw
+  // only recognizes credential flags as LEADING options (the while-loop below);
+  // a `--agent-key` after the lane/verb is a Playwright workload argument, not a
+  // BotBuddy credential, so scan only the leading options (Codex R9).
+  const aliasHint = legacyAgentAliasHint({ argv: leadingPwOptions(args), env });
+  if (aliasHint) stderr.write(`bb pw: ${aliasHint}\n`);
   // BOT-1649: --agent-session-token / $BOTBUDDY_AGENT_SESSION_TOKEN is canonical;
   // legacy flags and env aliases remain accepted as a
   // session identity alongside --session-id, so a token-armed session need not

package/src/run.mjs

@@ -14,7 +14,7 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { callToolJson } from "./api.mjs";
 import { parseLaneEvents, laneCaseCounts, flushLaneCases, buildLaneSummary, laneSummaryFilename } from "./test-lane-events.mjs";
-import { AGENT_KEY_RE, readAgentSessionTokenEnv } from "./agent-key.mjs";
+import { AGENT_KEY_RE, readAgentSessionTokenEnv, legacyAgentAliasHint } from "./agent-key.mjs";
 import { clearAgentState, isRejectedCachedMcpSession, resolveAgentSessionCredential } from "./agent-session.mjs";
 import { createTelemetryOutbox } from "./telemetry-outbox.mjs";
 import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
@@ -532,9 +532,14 @@ export async function cmdRun(args) {
     return;
   }
   if (args[0] === "help" || args[0] === "--help") {
-    console.log("botbuddy run --session-id <id> --environment <local|preview|staging|production|none> [--timeout <sec>] [--rerun-reason <json>] -- <command> [args...]\nbotbuddy run --foreground --kind <test|wait|browser|ci|hook|stack> --environment <local|preview|staging|production|none> -- <command> [args...]\nbotbuddy run cancel <run_id>");
+    console.log("botbuddy run --session-id <id> --environment <local|preview|staging|production|none> [--timeout <sec>] [--rerun-reason <json>] -- <command> [args...]\nbotbuddy run --foreground --kind <test|wait|browser|ci|hook|stack> --environment <local|preview|staging|production|none> -- <command> [args...]\nbotbuddy run cancel <run_id>\n  --agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN); --agent-key / --session-token are one-release legacy aliases");
     return;
   }
+  // BOT-1701 (AC-6): one stderr nudge when a tier-3 legacy flag/env alias is used
+  // (stderr only, so the stdout receipt stays byte-identical). A cached bb_agent_
+  // token is nudged inside resolveAgentSessionCredential.
+  const aliasHint = legacyAgentAliasHint({ argv: args, env: process.env });
+  if (aliasHint) process.stderr.write(`botbuddy run: ${aliasHint}\n`);
   if (args.includes("--foreground")) {
     let identity;
     try { identity = await loadTelemetryIdentity(); }

package/src/setup-block.mjs

@@ -8,46 +8,39 @@
 // session persistence; normal operator output must never turn that into a
 // multi-command credential handoff.
 
+import { credentialTier } from "./credential-kinds.mjs";
+
 /** The canonical guide, referenced from every SETUP block and recovery. */
 export const CONNECTIVITY_GUIDE = "docs/agent-connectivity.md";
 
 // The three connectivity credential tiers, named consistently everywhere. A
 // connectivity error names the MISSING tier and the exact next command; the
 // guide's tiered table and the help SETUP block use these same labels.
+//
+// BOT-1701: the noun, prefix, flag, env, and kind for each tier are OWNED by
+// credential-kinds.mjs (CREDENTIAL_TIERS) — the single source of truth. This map
+// only adds the setup-specific fields (the tier number, the `setup` command, and
+// the scope). A drift test asserts every user-facing surface agrees with the
+// canonical table, so `label`/`prefix`/`env`/`flag` here can never fork from it.
 export const TIERS = Object.freeze({
   // Tier 1 — per-machine client key. `bb login`, USER-scoped (reaches every
   // tenant you belong to; each request pins one). Never a wait credential.
-  client: Object.freeze({
-    n: 1,
-    label: "client key",
-    prefix: "bb_cli_",
-    env: "BOTBUDDY_CLIENT_KEY",
-    setup: "bb login",
-    scope: "user",
-  }),
+  client: Object.freeze({ ...tierFields(1), setup: "bb login", scope: "user" }),
   // Tier 2 — per-tenant MCP config key. `bb mcp setup`, TENANT-bound, lives in
   // .mcp.json under $BOTBUDDY_MCP_KEY. Authenticates MCP calls + register_agent.
-  mcp: Object.freeze({
-    n: 2,
-    label: "MCP key",
-    prefix: "bb_mcp_",
-    env: "BOTBUDDY_MCP_KEY",
-    setup: "bb mcp setup",
-    scope: "tenant",
-  }),
-  // Tier 3 — per-session agent token, tenant-bound, 8 h TTL, revoked on
+  mcp: Object.freeze({ ...tierFields(2), setup: "bb mcp setup", scope: "tenant" }),
+  // Tier 3 — per-session agent session token, tenant-bound, 8 h TTL, revoked on
   // re-register. The CLI caches it in .botbuddy/agent-state.json and restores
   // it automatically for wait/run/test/pw.
-  session: Object.freeze({
-    n: 3,
-    label: "session token",
-    prefix: "bb_sess_",
-    env: "BOTBUDDY_AGENT_SESSION_TOKEN",
-    setup: "register_agent",
-    scope: "session",
-  }),
+  session: Object.freeze({ ...tierFields(3), setup: "register_agent", scope: "session" }),
 });
 
+/** Project a canonical CREDENTIAL_TIERS row onto the TIERS shape (n/label/…). */
+function tierFields(tier) {
+  const t = credentialTier(tier);
+  return { n: t.tier, label: t.noun, prefix: t.prefix, env: t.env, flag: t.flag };
+}
+
 /**
  * The shared SETUP block reproduced verbatim in every `--help` output. Plain
  * text (no ANSI) so the snapshot test can match it byte-for-byte across surfaces.

package/src/stack-file-lock.mjs

@@ -11,9 +11,25 @@ import { join } from "node:path";
 
 let tmpCounter = 0;
 
+// Decode the escape sequences a TOML BASIC string ("...") allows, so an escaped value
+// compares equal to its literal form (BOT-1711 Codex R15): `"shared\u002Dcanonical"` and
+// `"shared-canonical"` are the same project to Supabase. LITERAL strings ('...') are raw.
+function decodeTomlBasicString(s) {
+  return String(s).replace(/\\(u[0-9A-Fa-f]{4}|U[0-9A-Fa-f]{8}|[btnfr"\\])/g, (_m, esc) => {
+    if (esc[0] === "u" || esc[0] === "U") return String.fromCodePoint(parseInt(esc.slice(1), 16));
+    return { b: "\b", t: "\t", n: "\n", f: "\f", r: "\r", '"': '"', "\\": "\\" }[esc];
+  });
+}
+
 export function projectIdFromConfig(configText) {
-  const match = String(configText).match(/^\s*project_id\s*=\s*"([^"]+)"/m);
-  return match ? match[1] : null;
+  // TOML accepts BASIC ("...", with escapes) and LITERAL ('...', raw) strings; match either
+  // so neither a single-quoted nor an escaped project_id can bypass identity checks
+  // (BOT-1711 Codex R6/R15). The basic-string body allows escaped quotes (`\"`).
+  const text = String(configText);
+  const basic = text.match(/^\s*project_id\s*=\s*"((?:[^"\\]|\\.)*)"/m);
+  if (basic) return decodeTomlBasicString(basic[1]);
+  const literal = text.match(/^\s*project_id\s*=\s*'([^']*)'/m);
+  return literal ? literal[1] : null;
 }
 
 export function dbPortFromConfig(configText) {

package/src/stack.mjs

@@ -32,6 +32,7 @@ import { SERVER_URL, getConfig } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
 import { AGENT_KEY_RE, readAgentKeyEnv } from "./agent-key.mjs";
 import { runDockerCommand, runDockerWorkflow, ADMITTED_DOCKER_VALIDATIONS } from "./docker-hygiene.mjs";
+import { projectIdFromConfig } from "./stack-file-lock.mjs";
 import { machineUuid } from "./machine-id.mjs";
 import { bold, dim, yellow } from "./utils.mjs";
 
@@ -70,11 +71,15 @@ ${bold("up OPTIONS")}
   --repo <repo>          Repository the batch is for (e.g. botbuddy-web).
   --ticket <BOT-123>     Ticket the batch is for (also used to derive the slot).
   --stack-path <relative> Stack directory inside the registered worktree (default: .).
+                         REQUIRED with --local-exec: point it at a slot-derived stack whose
+                         supabase/config.toml declares a DISTINCT project_id + remapped ports
+                         (never the worktree root's shared canonical project).
   --purpose <text>       Free-text purpose recorded on the lease.
   --idle-ttl <seconds>   Idle seconds before the reaper STOPS an unused stack (default 1800).
   --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.
+  --local-exec           FALLBACK (no Helper): run 'supabase start' in an ISOLATED --stack-path
+                         stack and self-activate. Refused at the worktree root (shared stack).
   --docker-context <name> Explicit Docker context for the mandatory local preflight
                          (an allowlisted engine: OrbStack or Docker Desktop, e.g. desktop-linux).
   --docker-endpoint <uri> Explicit Docker endpoint instead of --docker-context.
@@ -253,6 +258,15 @@ export function parseStackArgs(argv) {
   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>`);
   }
+  // BOT-1711: a local-exec `up` must isolate the leased stack in a --stack-path subdirectory
+  // (its own supabase/config.toml → distinct project_id + remapped ports). The worktree root
+  // is the developer's shared canonical dev stack; `supabase start`/`stop` there is the exact
+  // clobber this closes. `done` needs no --stack-path (the teardown dir comes from the lease).
+  if (command === "up" && opts.localExec && (typeof opts.stackPath !== "string" || opts.stackPath === ".")) {
+    errors.push("--local-exec up requires --stack-path <isolated-stack-dir>: an isolated leased stack must not be the " +
+      "worktree root's default (shared canonical) project. Point --stack-path at a slot-derived stack directory with its " +
+      "own supabase/config.toml (distinct project_id + remapped ports).");
+  }
   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`");
   }
@@ -292,29 +306,6 @@ export function truncateReceipt(receipt, maxBytes = DEFAULT_RECEIPT_MAX_BYTES) {
   };
 }
 
-/**
- * Resolve a LOCAL Supabase API origin to pin into the `supabase start` environment
- * (BOT-903 / Codex P1): without `VITE_SUPABASE_URL` pinned, config.toml's
- * `env(VITE_SUPABASE_URL)` falls back to the repo's `.env` PRODUCTION origin, so the
- * "disposable" local edge runtime would address `https://api.bot-buddy.ai`. Precedence:
- *   1. an already-exported local (`127.0.0.1`/`localhost`) `VITE_SUPABASE_URL`;
- *   2. `http://127.0.0.1:<[api] port>` read from `./supabase/config.toml`.
- * Returns null when neither is available — the caller then REFUSES to run `supabase
- * start` rather than risk crossing into production.
- */
-export function resolveLocalSupabaseUrl(env = process.env, cwd = process.cwd()) {
-  const cur = env.VITE_SUPABASE_URL;
-  if (cur && /(127\.0\.0\.1|localhost)/.test(cur)) return cur;
-  try {
-    const toml = readFileSync(`${cwd}/supabase/config.toml`, "utf8");
-    // The [api] section's `port = NNNNN` (stop at the next section header).
-    const section = /\[api\]([\s\S]*?)(\n\[|$)/.exec(toml);
-    const m = section && /\bport\s*=\s*(\d+)/.exec(section[1]);
-    if (m) return `http://127.0.0.1:${m[1]}`;
-  } catch { /* no config.toml here */ }
-  return null;
-}
-
 /** Resolve the requested stack directory once, before it leaves the coding
  * machine. This closes both `..` and symlink escapes; the server separately
  * verifies the resulting root is a registered worktree on the selected host. */
@@ -597,24 +588,30 @@ function dockerEnvForTarget(target, env = process.env) {
  * 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()) {
+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;
+  if (!lease?.worktree_root) {
+    return { ok: false, error: "legacy lease has no recorded worktree_root" };
+  }
+  // BOT-1711 (Codex R10): prove the caller is in the lease's REGISTERED worktree root, and
+  // take the stack subdirectory from the LEASE's recorded stack_path — NOT from opts.stackPath.
+  // `stack done <id> --local-exec` carries no --stack-path, so re-resolving opts.stackPath
+  // ("." by default) would reject every non-root legacy lease as an invoking-worktree mismatch.
+  let callerRoot;
   try {
-    execution = resolveStackPath(cwd, opts?.stackPath || ".");
+    callerRoot = realpathSync(cwd);
   } catch (error) {
-    return { ok: false, error: `could not resolve the invoking stack path: ${error.message}` };
+    return { ok: false, error: `could not resolve the invoking worktree: ${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" };
+  if (lease.worktree_root !== callerRoot) {
+    return { ok: false, error: "legacy lease worktree does not match the invoking worktree" };
   }
-
-  const stackDir = execution.stackPath === "."
-    ? execution.worktreeRoot
-    : join(execution.worktreeRoot, execution.stackPath);
+  const leaseStackPath = lease.stack_path || ".";
+  const stackDir = leaseStackPath === "."
+    ? lease.worktree_root
+    : join(lease.worktree_root, leaseStackPath);
   const status = run("supabase", ["status", "-o", "json", "--workdir", stackDir], {
     encoding: "utf8",
     env: dockerEnvForTarget(observedTarget),
@@ -634,8 +631,8 @@ export function proveLegacyLocalExecTarget(lease, observedTarget, opts, run = sp
     ok: true,
     evidence: {
       method: "legacy_worktree_connection_match",
-      worktree_root: execution.worktreeRoot,
-      stack_path: execution.stackPath,
+      worktree_root: lease.worktree_root,
+      stack_path: leaseStackPath,
       api_url: live.api_url,
       db_port: dbPort,
       resolved_endpoint: observedTarget.resolved_endpoint,
@@ -655,33 +652,282 @@ function compactPreflight(receipt) {
   };
 }
 
-/** LOUD local-exec fallback: bring a stack up in the cwd via the Supabase CLI. */
-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();
-  if (!url) {
+/**
+ * BOT-903 / BOT-1711 (Codex P1) — pin the edge origin to the ISOLATED stack's OWN
+ * `[api] port`.
+ *
+ * `supabase start` bakes `VITE_SUPABASE_URL` into the edge runtime. Trusting an ambient
+ * local `VITE_SUPABASE_URL` is unsafe for a leased stack: if the caller has exported the
+ * shared canonical stack's origin, `supabase start` brings the isolated project up but
+ * bakes the SHARED stack's URL into its edge runtime, so tests that follow those URLs
+ * escape the leased stack into shared data (and without any local origin it would fall
+ * back to the repo's PRODUCTION origin). The isolated stack's own `[api] port` is
+ * therefore authoritative: require it, and reject an ambient LOCAL origin whose port
+ * does not match it. Throws a caller-facing Error otherwise.
+ */
+export function resolveIsolatedStackApiUrl(stackDir, env = process.env, read = readFileSync) {
+  let port = null;
+  try {
+    const toml = read(`${stackDir}/supabase/config.toml`, "utf8");
+    // Derive the API port from the SAME comment-aware, section-qualified, integer-normalizing
+    // parser used for isolation (BOT-1711 R16): a separate ad-hoc regex here diverged — it
+    // treated a commented `# [api]\n# port =` as config and mis-pinned the edge origin.
+    port = portMapInConfig(toml).get("api.port") ?? null;
+  } catch { /* handled below */ }
+  if (!port) {
+    throw new Error(
+      `refusing --local-exec: the isolated stack at ${stackDir} declares no supabase/config.toml [api] port — ` +
+        "cannot pin the leased stack's own edge origin (the edge runtime must emit the leased stack's URLs, not the shared stack's).",
+    );
+  }
+  const origin = `http://127.0.0.1:${port}`;
+  const ambient = env.VITE_SUPABASE_URL;
+  if (ambient) {
+    let host = null; let ambientPort = null;
+    try { const u = new URL(ambient); host = u.hostname; ambientPort = u.port; } catch { /* non-URL ambient is ignored */ }
+    if ((host === "127.0.0.1" || host === "localhost") && ambientPort !== String(port)) {
+      throw new Error(
+        `refusing --local-exec: ambient VITE_SUPABASE_URL (${ambient}) is a LOCAL origin whose port does not match the ` +
+          `isolated stack's API port (${origin}); the edge runtime would emit another stack's URLs. Unset VITE_SUPABASE_URL ` +
+          "or point it at the leased stack.",
+      );
+    }
+  }
+  return origin;
+}
+
+/** Resolve the absolute stack directory (where `supabase/config.toml` lives) for a
+ * resolved {worktreeRoot, stackPath}. `"."` is the worktree root itself. */
+export function stackDirFor(execution) {
+  return execution.stackPath === "."
+    ? execution.worktreeRoot
+    : join(execution.worktreeRoot, execution.stackPath);
+}
+
+/** Absolute stack directory a lease was provisioned in, from its recorded
+ * worktree_root/stack_path (BOT-1711 teardown). Falls back to `cwd` for a lease
+ * that predates worktree_root recording. */
+export function leaseStackDir(lease, cwd = process.cwd()) {
+  const worktreeRoot = lease?.worktree_root;
+  if (!worktreeRoot) return cwd;
+  const stackPath = lease?.stack_path || ".";
+  return stackPath === "." ? worktreeRoot : join(worktreeRoot, stackPath);
+}
+
+/** Read a `supabase/config.toml` project_id under `dir`, or null if unreadable. */
+function projectIdUnder(dir, read = readFileSync) {
+  try { return projectIdFromConfig(read(`${dir}/supabase/config.toml`, "utf8")); }
+  catch { return null; }
+}
+
+/** Every port a `config.toml` allocates, as a SECTION-QUALIFIED map `"<section>.<key>" ->
+ * "<port>"` (e.g. `api.port`, `db.shadow_port`, `inbucket.pop3_port`). Section-qualified so
+ * the SAME `port` key under [api]/[db]/[studio]/[inbucket] stays distinct, which lets a
+ * target be checked for BOTH completeness (declares every port the root does) and
+ * disjointness (shares no port value). */
+// Normalize any valid TOML integer literal to its decimal string: decimal (with `_`
+// separators), or `0x`/`0o`/`0b` radix forms. Returns null for a non-integer. Without this
+// a hex/octal port (`0xdc01` == 56321) or a separated one (`56_321`) would parse as a
+// truncated value and bypass the port-collision checks while Supabase binds the full port
+// (BOT-1711 Codex R11/R14).
+function tomlIntToDecimal(token) {
+  const cleaned = String(token).replace(/_/g, "");
+  const n = Number(cleaned);
+  return Number.isInteger(n) && n >= 0 ? String(n) : null;
+}
+
+// TOML decimal integers may carry a leading sign (`+56321`); radix forms may not. A
+// negative value is rejected downstream by tomlIntToDecimal (BOT-1711 Codex R15).
+const TOML_INT_PORT = "(0[xX][0-9A-Fa-f_]+|0[oO][0-7_]+|0[bB][01_]+|[+-]?[0-9][0-9_]*)";
+
+function portMapInConfig(toml) {
+  const map = new Map();
+  let section = "";
+  const bare = new RegExp(`^((?:[A-Za-z0-9]+_)?port)\\s*=\\s*${TOML_INT_PORT}`);
+  // Dotted TOML key form (BOT-1711 R16): `api.port = N` / `db.shadow_port = N`, section-
+  // qualified inline instead of under a `[section]` header. Normalizes to the same key.
+  const dotted = new RegExp(`^([A-Za-z0-9_]+)\\.((?:[A-Za-z0-9]+_)?port)\\s*=\\s*${TOML_INT_PORT}`);
+  for (const raw of String(toml).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith("#")) continue; // comments are not configuration
+    const sec = /^\[([^\]]+)\]/.exec(line);
+    if (sec) { section = sec[1].trim(); continue; }
+    const dot = dotted.exec(line);
+    if (dot) {
+      const dec = tomlIntToDecimal(dot[3]);
+      if (dec != null) map.set(`${dot[1]}.${dot[2]}`, dec);
+      continue;
+    }
+    const m = bare.exec(line);
+    if (m) {
+      const dec = tomlIntToDecimal(m[2]);
+      if (dec != null) map.set(`${section}.${m[1]}`, dec);
+    }
+  }
+  return map;
+}
+
+/** Read a stack directory's identity — project_id + its COMPLETE, section-qualified port
+ * allocation — from its `supabase/config.toml`, in one read. Empty/null when unreadable. */
+function readStackIdentity(dir, read = readFileSync) {
+  try {
+    const toml = read(`${dir}/supabase/config.toml`, "utf8");
+    return { project: projectIdFromConfig(toml), ports: portMapInConfig(toml) };
+  } catch { return { project: null, ports: new Map() }; }
+}
+
+/**
+ * BOT-1711 (Codex P1) — is a MODERN lease's recorded teardown target NON-isolated,
+ * i.e. the worktree root or a stack whose project_id is the worktree default? A
+ * pre-1.32 client could have minted a modern lease (one that carries a
+ * botbuddy_docker_target) at the worktree root (`stack_path "."`); tearing it down
+ * with `supabase stop` there would stop the shared canonical stack. Refuse those.
+ * Root (`stack_path "."`) is always non-isolated; for a subdir the project_id check
+ * is best-effort (unreadable config ⇒ treated as isolated, since the parse+provision
+ * guards already blocked a same-project subdir at `up`). Never mutates.
+ */
+export function localExecTeardownIsNonIsolated(lease, read = readFileSync) {
+  const stackPath = lease?.stack_path || ".";
+  if (stackPath === ".") return true;
+  const worktreeRoot = lease?.worktree_root;
+  if (!worktreeRoot) return false;
+  const rootProject = projectIdUnder(worktreeRoot, read);
+  const stackProject = projectIdUnder(join(worktreeRoot, stackPath), read);
+  return Boolean(rootProject && stackProject && rootProject === stackProject);
+}
+
+/**
+ * BOT-1711 — the ISOLATION invariant for `--local-exec`.
+ *
+ * `supabase start`/`stop` operate whatever `project_id` the target `supabase/config.toml`
+ * declares. A leased batch must bring up a *disposable, isolated* stack — never the
+ * developer's shared canonical dev stack (the worktree root's committed default project).
+ * Running local-exec at the worktree root would `supabase start` (and later `supabase stop`)
+ * the shared canonical stack — the exact accident BOT-1711 documents (a `stack done` that
+ * stopped 12 shared containers).
+ *
+ * So refuse unless the target stack declares BOTH a project_id AND a COMPLETE port
+ * allocation DISTINCT from the worktree root's default stack. A project_id alone is not
+ * enough (Codex R2 P2): a config copied from the root with only project_id changed still
+ * binds the shared allocation's ports, so `supabase start` would squat the canonical
+ * endpoints if the shared stack is down, or fail after reserving the lease if it is up.
+ * And comparing only the API/DB ports is not enough (Codex R3 P2): the root also allocates
+ * `shadow_port`, Studio, Inbucket, analytics, and inspector ports, any of which a partial
+ * copy could still share. So require the leased stack's ENTIRE set of allocated ports to be
+ * disjoint from the root's. An isolated leased stack lives in a `--stack-path` subdirectory
+ * whose `supabase/config.toml` carries its own project_id AND a fully remapped port set (the
+ * SG<n> pattern / the canonical slot allocation). Throws otherwise; never mutates anything.
+ */
+export function assertIsolatedLocalExecTarget(execution, read = readFileSync) {
+  const stackDir = stackDirFor(execution);
+  const stack = readStackIdentity(stackDir, read);
+  if (!stack.project) {
+    throw new Error(
+      `refusing --local-exec: no supabase/config.toml project_id under ${execution.stackPath} — ` +
+        "an isolated leased stack needs its own supabase/config.toml (distinct project_id + remapped ports).",
+    );
+  }
+  const root = execution.stackPath === "." ? stack : readStackIdentity(execution.worktreeRoot, read);
+  // FAIL CLOSED (Codex R6 P1): if the worktree-root identity is unreadable — absent, or a
+  // project_id the parser doesn't recognize — isolation cannot be proven and the port checks
+  // would be vacuous, yet the shared canonical containers may still be running (e.g. its
+  // config was renamed/regenerated). Refuse rather than accept an unprovable target.
+  if (execution.stackPath !== "." && !root.project) {
+    throw new Error(
+      "refusing --local-exec: cannot read the worktree root's supabase/config.toml project_id, so isolation from the " +
+        "shared canonical stack cannot be proven (its containers may still be running). Ensure the worktree root has a " +
+        "readable supabase/config.toml before running an isolated leased stack.",
+    );
+  }
+  if (root.project && stack.project === root.project) {
+    throw new Error(
+      `refusing --local-exec: the target stack project_id "${stack.project}" is the worktree's default ` +
+        "(shared canonical) project — `supabase start`/`stop` here would operate the shared dev stack, not an " +
+        "isolated leased stack. Point --stack-path at a slot-derived stack directory whose supabase/config.toml " +
+        "declares a DISTINCT project_id and remapped ports (mirror the repo's SG<n> isolation).",
+    );
+  }
+  // COMPLETENESS (Codex R4 P2): every port the shared stack allocates must be explicitly
+  // declared by the target too. A port the target OMITS falls back to Supabase's default,
+  // which the config never reveals and which collides with any other default-using stack —
+  // and provisioning then fails only AFTER the lease is reserved (a fenced lease). Require
+  // the full allocation up front instead.
+  const missing = [...root.ports.keys()].filter((k) => !stack.ports.has(k));
+  if (missing.length) {
+    throw new Error(
+      `refusing --local-exec: the target stack omits port(s) the shared stack allocates (${missing.join(", ")}) — ` +
+        "an omitted port falls back to Supabase's default and collides with other stacks. Declare and remap the COMPLETE " +
+        "port allocation in the leased stack's supabase/config.toml (e.g. via the canonical slot allocation).",
+    );
+  }
+  // INTERNAL UNIQUENESS (Codex R8 P2): two of the target's OWN services on the same port
+  // (e.g. api.port == db.port) would make `supabase start` collide internally — after the
+  // lease is reserved, leaving it fenced. Each declared port must be distinct.
+  const stackValues = [...stack.ports.values()];
+  const intraDupes = [...new Set(stackValues.filter((v, i) => stackValues.indexOf(v) !== i))];
+  if (intraDupes.length) {
+    throw new Error(
+      `refusing --local-exec: the target stack assigns the same port to multiple services (${intraDupes.join(", ")}) — ` +
+        "`supabase start` would collide internally. Give every service a distinct port in the leased stack's supabase/config.toml.",
+    );
+  }
+  // DISJOINTNESS: no port VALUE may be shared with the canonical allocation, or
+  // `supabase start` binds the shared endpoints (squatting them if the shared stack is
+  // down, or failing after the lease is reserved if it is up).
+  const rootValues = new Set(root.ports.values());
+  const shared = [...new Set(stack.ports.values())].filter((v) => rootValues.has(v));
+  if (shared.length) {
     throw new Error(
-      "refusing --local-exec: cannot determine a LOCAL Supabase API origin (no supabase/config.toml [api] port " +
-        "in this directory, and VITE_SUPABASE_URL is not a 127.0.0.1/localhost origin). `supabase start` would bake " +
-        "the repository's PRODUCTION origin into the edge runtime — run from a repo with supabase/config.toml, or " +
-        "export VITE_SUPABASE_URL=http://127.0.0.1:<port> first.",
+      `refusing --local-exec: the target stack reuses the worktree default stack's port(s) ${shared.join(", ")} — ` +
+        "`supabase start` would bind the shared allocation's endpoints. Remap ALL of the leased stack's ports in its " +
+        "supabase/config.toml (api/db/shadow/studio/inbucket/analytics/inspector), e.g. via the canonical slot allocation.",
     );
   }
-  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 });
+}
+
+/**
+ * BOT-1711 (Codex R7 P2) — the COMPLETE non-mutating pre-flight for a local-exec target,
+ * run in `cmdUp` BEFORE any lease is minted or reserved. It proves both:
+ *   1. config isolation from the shared canonical stack (`assertIsolatedLocalExecTarget`), and
+ *   2. that the edge origin resolves to the leased stack's own [api] port and no ambient
+ *      `VITE_SUPABASE_URL` points at another stack (`resolveIsolatedStackApiUrl`).
+ * Both were previously proven only inside `localProvision` (post-reserve), so a target known
+ * invalid before any container started still left a fenced lease. Throws on any failure.
+ */
+export function validateLocalExecTarget(execution, env = process.env, read = readFileSync) {
+  assertIsolatedLocalExecTarget(execution, read);
+  resolveIsolatedStackApiUrl(stackDirFor(execution), env, read);
+}
+
+/** LOUD local-exec fallback: bring an ISOLATED stack up in the resolved stack dir. */
+export function localProvision(opts, dockerTarget, execution, spawn = spawnSync, env = process.env) {
+  const stackDir = stackDirFor(execution);
+  // BOT-1711: never operate the repo's default (shared canonical) project.
+  assertIsolatedLocalExecTarget(execution);
+  // Pin the edge origin to the ISOLATED stack's OWN [api] port (BOT-903 / BOT-1711 Codex
+  // P1): never the repo's prod origin, and never an ambient shared-stack origin — either
+  // would make the isolated stack's edge runtime emit another stack's URLs.
+  const url = resolveIsolatedStackApiUrl(stackDir, env);
+  const spawnEnv = { ...dockerEnvForTarget(dockerTarget, env), VITE_SUPABASE_URL: url };
+  process.stderr.write(`${yellow("⚠ LOCAL-EXEC FALLBACK")} — no BotBuddy Helper; running ${bold("supabase start")} in ${stackDir} (VITE_SUPABASE_URL=${url}).\n`);
+  const start = spawn("supabase", ["start", "--workdir", stackDir], { encoding: "utf8", env: spawnEnv });
   if (start.status !== 0) {
     throw new Error(`supabase start failed (${start.status}): ${(start.stderr || start.stdout || "").slice(0, 400)}`);
   }
-  const status = spawnSync("supabase", ["status", "-o", "json"], { encoding: "utf8", env: spawnEnv });
-  return parseSupabaseStatus(status.stdout || "");
+  const status = spawn("supabase", ["status", "-o", "json", "--workdir", stackDir], { encoding: "utf8", env: spawnEnv });
+  const conn = parseSupabaseStatus(status.stdout || "");
+  // BOT-1711 (Codex R5 P2): persist the PROVISIONED project_id on the lease connection so
+  // teardown can detect a config that was edited/regenerated between `up` and `done` and
+  // refuse rather than `supabase stop` a replacement stack.
+  const provisionedProject = projectIdUnder(stackDir);
+  if (provisionedProject) conn.project_id = provisionedProject;
+  return conn;
 }
 
-/** LOUD local-exec fallback: tear the stack down in the cwd. Returns true iff it succeeded. */
-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 = spawn("supabase", ["stop", "--workdir", process.cwd()], {
+/** 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], {
     encoding: "utf8",
     env: dockerEnvForTarget(dockerTarget, env),
   });
@@ -707,6 +953,7 @@ export async function cmdUp(opts, {
   waitFn = waitForLease,
   emitResult = emit,
   machineUuidFn = machineUuid,
+  assertIsolated = validateLocalExecTarget,
 } = {}) {
   let slot;
   try { slot = deriveSlot(opts); } catch (e) {
@@ -719,6 +966,16 @@ export async function cmdUp(opts, {
   let localPreflight = null;
   let localDockerTarget = null;
   if (opts.localExec) {
+    // BOT-1711 (Codex R2/R7 P2): prove BOTH config isolation from the resolved --stack-path
+    // AND the edge origin (no ambient VITE_SUPABASE_URL pointing at another stack) BEFORE any
+    // backend mutation. `resolveStackPath` canonicalizes `..`/symlinks, so a target the parser
+    // missed (e.g. `--stack-path ./` → the worktree root) is only caught here. Running this
+    // non-mutating validation now means an invalid target is refused before a lease is ever
+    // minted or reserved, so it can never leave a fenced lease.
+    try { assertIsolated(execution); }
+    catch (e) {
+      return emitResult(buildReceipt({ command: "up", outcome: "refused", slot, error: e.message }), opts, EXIT.LEASE_FAILED);
+    }
     const checked = await runPreflight(opts);
     localPreflight = compactPreflight(checked.receipt);
     localDockerTarget = dockerTargetFromPreflight(checked.receipt);
@@ -768,6 +1025,10 @@ export async function cmdUp(opts, {
   }
   let leaseId = d.lease_id;
   let state = d.state;
+  // BOT-1711 (Codex R13): request_stack_lease returned an EXISTING active lease (reused),
+  // rather than a freshly minted queued/provisioning one. A reused lease was not provisioned
+  // in this invocation, so its recorded metadata cannot be trusted for a local-exec target.
+  const reusedExisting = state === "active";
 
   if (state === "queued") {
     if (opts.noWait) {
@@ -802,18 +1063,38 @@ export async function cmdUp(opts, {
           lease_cancellation: leaseCancellation,
         }), opts, EXIT.LEASE_FAILED);
       }
+      // BOT-1711 (Codex R8 P2): the target config could have been edited while this lease
+      // was QUEUED for capacity. Re-run the non-mutating target validation NOW, before
+      // reserving the provision job; on failure atomically release the minted lease so a
+      // config invalidated during the queue wait never leaves a fenced lease.
+      try { assertIsolated(execution); }
+      catch (e) {
+        const cancelled = await call("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: e.message,
+          lease_cancellation: leaseCancellation,
+        }), opts, EXIT.LEASE_FAILED);
+      }
       // Reserve the queued provision job for THIS agent BEFORE `supabase start`.
       // Otherwise a Helper can claim it while the local provisioner runs, winning
       // the later activation race and leaving an untracked local stack (two
       // provisioners contending for one slot). If the reservation is LOST, nothing
       // local has started yet, so it is safe to atomically release the minted lease
       // and free the slot (BOT-1421 review).
-      // Persist the validated Docker target with the reservation so that if the
-      // provisioner partially starts a stack and then fails, the fenced lease can
-      // still be torn down by `stack done --local-exec` (BOT-1421 review).
+      // Persist the validated Docker target AND the target stack's project_id with the
+      // reservation (BOT-1711 Codex R14): if the provisioner partially starts a stack and
+      // then exits nonzero, the fenced lease still carries a provisioned identity so
+      // `stack done --local-exec` recognises it as a current-client lease (not an untrusted
+      // pre-1.32 one) and can tear the partial stack down instead of refusing.
+      const reservedProjectId = projectIdUnder(stackDirFor(execution));
+      const reservedConnection = connectionWithDockerTarget(
+        reservedProjectId ? { project_id: reservedProjectId } : {}, localDockerTarget);
       const reserved = await call("reserve_stack_lease", {
         lease_id: leaseId,
-        connection: connectionWithDockerTarget({}, localDockerTarget),
+        connection: reservedConnection,
       });
       if (!reserved.ok || !reserved.data?.success) {
         // A Helper can win the reservation race by taking the queued provision
@@ -857,7 +1138,7 @@ export async function cmdUp(opts, {
       } else {
         let conn;
         try {
-          conn = connectionWithDockerTarget(localProvisionFn(opts, localDockerTarget), localDockerTarget);
+          conn = connectionWithDockerTarget(localProvisionFn(opts, localDockerTarget, execution), localDockerTarget);
         } catch (e) {
           // Once the local provisioner has run, `supabase start` may have created
           // (or fully started) containers even on a nonzero exit or a status-parse
@@ -888,6 +1169,37 @@ export async function cmdUp(opts, {
   if (!g || g.state !== "active") {
     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);
   }
+  // BOT-1711 (Codex R12 P1): `request_stack_lease` REUSES an existing active lease for this
+  // slot (e.g. a pre-1.32 lease recorded with stack_path "."). The isolation validation above
+  // only covers the newly requested --stack-path, so a reused lease could hand back a
+  // different (possibly shared-root) connection as "active". Refuse a lease whose recorded
+  // worktree/stack does not match the validated target instead of returning it.
+  if (opts.localExec) {
+    const leaseStackPath = g.stack_path || ".";
+    const stackMismatch = leaseStackPath !== execution.stackPath;
+    const worktreeMismatch = g.worktree_root != null && g.worktree_root !== execution.worktreeRoot;
+    if (stackMismatch || worktreeMismatch) {
+      return emitResult(buildReceipt({
+        command: "up", outcome: "refused", lease_id: leaseId, state: "active", slot,
+        error: `refusing --local-exec: the active lease is bound to ${g.worktree_root || "<unknown>"} / stack_path "${leaseStackPath}", ` +
+          `not the validated ${execution.worktreeRoot} / "${execution.stackPath}" — an existing lease for this slot was reused and ` +
+          "points at a different (possibly shared) stack. Release that lease with `stack done`, or use a slot dedicated to this stack.",
+        observed_worktree_root: g.worktree_root || null, observed_stack_path: leaseStackPath,
+      }), opts, EXIT.LEASE_FAILED);
+    }
+    // BOT-1711 (Codex R13 P1): a REUSED lease whose metadata matches can still be a pre-1.32
+    // lease that recorded this path but actually provisioned the worktree ROOT — its recorded
+    // stack_path lies. The only trustworthy signal is a persisted provisioned identity, which
+    // only BOT-1711+ local provisioning writes. Refuse a reused lease that lacks it.
+    if (reusedExisting && !g.connection?.project_id) {
+      return emitResult(buildReceipt({
+        command: "up", outcome: "refused", lease_id: leaseId, state: "active", slot,
+        error: "refusing --local-exec: reused an existing active lease with no persisted provisioned identity " +
+          "(project_id) — a pre-1.32 lease recorded this stack_path but may have provisioned the shared worktree root, so its " +
+          "connection cannot be trusted as the isolated stack. Release it with `stack done` and re-provision, or use a dedicated slot.",
+      }), opts, EXIT.LEASE_FAILED);
+    }
+  }
   return emitResult(buildReceipt({
     command: "up", outcome: "active", lease_id: leaseId, state: "active",
     host_key: g.host_key, slot: g.slot, connection: g.connection,
@@ -934,6 +1246,7 @@ export async function cmdDone(leaseId, opts, {
   const call = (name, args, callOptions = {}) => callTool(name, args, { ...callOptions, auth });
   let dockerTarget = null;
   let legacyTargetProof = null;
+  let teardownDir = process.cwd();
   if (opts.localExec) {
     const current = await call("get_stack_lease", { lease_id: leaseId });
     if (!current.ok || !current.data?.success) {
@@ -941,7 +1254,57 @@ export async function cmdDone(leaseId, opts, {
         error: current.error || current.data?.code || "could not verify the lease Docker target" }), opts,
       current.auth ? EXIT.AUTH : EXIT.BACKEND);
     }
+    // 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.
+    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.
+    // This covers a modern lease minted at the root by a pre-1.32 client AND a pre-1.5
+    // targetless legacy lease: the legacy connection-match proof would otherwise authorize
+    // `supabase stop --workdir <worktreeRoot>`, which stops the shared canonical stack.
+    // Matching endpoints do not prove the shared stack is disposable. Fail closed; the
+    // operator / `botbuddy docker hygiene` reclaims it. (A legacy lease with a genuinely
+    // isolated non-root stack_path still reaches the proof path below.)
+    if (localExecTeardownIsNonIsolated(current.data)) {
+      return emitResult(buildReceipt({ command: "done", outcome: "refused", lease_id: leaseId,
+        error: "refusing --local-exec teardown: this lease targets the worktree root (default/shared canonical project); " +
+          "`supabase stop` here would stop the shared stack. Reclaim it with `botbuddy docker hygiene` or the operator, not local-exec. " +
+          "Lease and slot remain fenced.",
+        observed_stack_path: current.data.stack_path || ".",
+      }), opts, EXIT.LEASE_FAILED);
+    }
+    // BOT-1711 (Codex R5 P2): if the stack directory's config was edited/regenerated between
+    // `up` and `done`, its project_id no longer matches what was provisioned — `supabase stop`
+    // there would stop a REPLACEMENT stack while the original containers keep running, and the
+    // old lease would still finalize. Refuse on project drift (the provisioned project_id is
+    // persisted on the lease connection at `up`).
+    const provisionedProject = current.data.connection?.project_id;
+    if (provisionedProject) {
+      const currentProject = projectIdUnder(teardownDir);
+      if (currentProject && currentProject !== provisionedProject) {
+        return emitResult(buildReceipt({ command: "done", outcome: "refused", lease_id: leaseId,
+          error: `refusing --local-exec teardown: ${teardownDir} now declares project_id "${currentProject}" but the lease ` +
+            `provisioned "${provisionedProject}" — its config changed since provisioning, so \`supabase stop\` could stop a ` +
+            "replacement stack and orphan the original. Reclaim with `botbuddy docker hygiene` or the operator.",
+          provisioned_project_id: provisionedProject, observed_project_id: currentProject,
+        }), opts, EXIT.LEASE_FAILED);
+      }
+    }
     const expected = current.data.connection?.botbuddy_docker_target;
+    // BOT-1711 (Codex R13 P1): a modern-target lease that lacks a persisted provisioned
+    // project_id was NOT provisioned by BOT-1711+ local-exec (e.g. a pre-1.32 lease that
+    // recorded a non-root stack_path but actually started the worktree ROOT). Its recorded
+    // path cannot be trusted to point `supabase stop` at the right stack, and there is no
+    // identity to compare, so fail closed rather than risk stopping an unrelated stack.
+    if (expected && !current.data.connection?.project_id) {
+      return emitResult(buildReceipt({ command: "done", outcome: "refused", lease_id: leaseId,
+        error: "refusing --local-exec teardown: this lease has a Docker target but no persisted provisioned identity " +
+          "(project_id) — it predates BOT-1711 isolated provisioning and its recorded stack_path may not match the stack it " +
+          "actually started. Reclaim it with `botbuddy docker hygiene` or the operator, not local-exec.",
+        observed_stack_path: current.data.stack_path || ".",
+      }), opts, EXIT.LEASE_FAILED);
+    }
     let checked;
     try { checked = await runPreflight(opts); } catch (error) {
       return emitResult(buildReceipt({ command: "done", outcome: "refused", lease_id: leaseId,
@@ -988,7 +1351,7 @@ export 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 (!localTeardownFn(opts, dockerTarget)) {
+    if (!localTeardownFn(teardownDir, 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.",

package/src/test-lane.mjs

@@ -21,7 +21,7 @@ import { execFileSync } from "node:child_process";
 
 import { EXIT, launchRun, receiptPath, DEFAULT_TIMEOUT_SECONDS } from "./run.mjs";
 import { callToolJson } from "./api.mjs";
-import { readAgentSessionTokenEnv } from "./agent-key.mjs";
+import { readAgentSessionTokenEnv, legacyAgentAliasHint } from "./agent-key.mjs";
 import { clearAgentState, isRejectedCachedMcpSession, resolveAgentSessionCredential } from "./agent-session.mjs";
 
 // EXIT.{OK,INVALID,BACKEND,INTERNAL} plus a --wait timeout code (AC-9).
@@ -338,7 +338,8 @@ function laneList(cwd) {
 }
 
 function testHelp() {
-  console.log(`botbuddy test <lane> [--session-id <uuid>] [--environment local] [--ticket <KEY>] [--pr <n>] [--repo <owner/repo>] [--lane-kind <${LANE_KINDS.join("|")}>] [--wait] [--json] [-- <extra args>]
+  console.log(`botbuddy test <lane> [--session-id <uuid>] [--agent-session-token <token>] [--environment local] [--ticket <KEY>] [--pr <n>] [--repo <owner/repo>] [--lane-kind <${LANE_KINDS.join("|")}>] [--wait] [--json] [-- <extra args>]
+  --agent-session-token <token>  session credential (env $BOTBUDDY_AGENT_SESSION_TOKEN); --agent-key / --session-token are one-release legacy aliases
 botbuddy test list      List the lanes configured in .botbuddy/lanes.json
 botbuddy test help      Show this help
 
@@ -351,6 +352,9 @@ export async function cmdTest(args, { cwd = process.cwd() } = {}) {
   const { subcommand } = parseTestArgs(args);
   if (subcommand === "help" || args[0] === "--help" || args[0] === "-h") { testHelp(); return; }
   if (subcommand === "list") { process.exitCode = laneList(cwd); return; }
+  // BOT-1701 (AC-6): one stderr nudge for a tier-3 legacy flag/env alias.
+  const aliasHint = legacyAgentAliasHint({ argv: args, env: process.env });
+  if (aliasHint) process.stderr.write(`botbuddy test: ${aliasHint}\n`);
   const result = await launchTestLane(args, { cwd });
   process.stdout.write(result.line + "\n");
   // --wait (AC-9): after launch, block until the run completes and exit with the

package/src/wait.mjs

@@ -18,7 +18,7 @@ import { readAgentBinding, withPrincipalReceipt } from "./wait-profile.mjs";
 import { VERSION } from "./version.mjs";
 import { fileURLToPath } from "node:url";
 import { latestPublicCliCommand } from "./public-invocation.mjs";
-import { AGENT_KEY_RE, readAgentSessionTokenEnv } from "./agent-key.mjs";
+import { AGENT_KEY_RE, readAgentSessionTokenEnv, legacyAgentAliasHint } from "./agent-key.mjs";
 import { clearAgentState, hasBootstrapAgentSession, isRejectedCachedSession, resolveAgentSessionCredential, selfHealAgentSession } from "./agent-session.mjs";
 import { touchAgentStateExpiry } from "./agent-state.mjs";
 import { SETUP_BLOCK } from "./setup-block.mjs";
@@ -1344,6 +1344,16 @@ async function acknowledgeSavedWait(id) {
 
 export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   if (argv.length === 0 || argv[0] === "--offset") return inspectSavedWaits(argv);
+  // BOT-1701 (AC-6): one stderr nudge for a tier-3 legacy alias (flag, env, or a
+  // bb_agent_ token value), emitted BEFORE any subcommand dispatch so the
+  // credentialed recovery actions (resume/cancel/acknowledge) warn too (Codex R7).
+  // STDERR only, so a machine-parseable stdout receipt is byte-identical. Skipped
+  // on the internal recovery re-entry (resumeSavedWait recurses into runWait with
+  // recoveryLocalWaitId set) so a resume never nudges twice (Codex R8).
+  if (recoveryLocalWaitId == null) {
+    const aliasHint = legacyAgentAliasHint({ argv, env: process.env });
+    if (aliasHint) process.stderr.write(`botbuddy wait: ${aliasHint}\n`);
+  }
   if (argv[0] === "resume") {
     const id = argv[1];
     if (!id || argv.length > 2) return emitSavedWaitError(new WaitCheckpointError("wait_not_resumable", "select exactly one saved wait: bb wait resume <local_wait_id>"));