@botbuddy/cli 1.60.5 → 1.60.7

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.60.5",
-  "source_commit": "a49feea0a58695a606269a3e4ccd1f94afba7114",
-  "source_sha256": "173f7953ea95f0facc3230dc993d4b64aab54037d8a89dfdafe044ad66063bb7",
+  "release_version": "1.60.7",
+  "source_commit": "6299d1f0f325871a33f5aa28bff8dc8029e7350c",
+  "source_sha256": "ac9f92aeaec3cf0cb18de06f1e16b0ee2c44c413ec7c84866f949909611098f1",
   "target": "darwin-arm64",
-  "sha256": "a6b56a02eca424bcc5dc408b90f1d831456a241d04dcc59adc2210b071698e49"
+  "sha256": "1e24ee9c3fa9ac6447ff9f0c8096d80c4e2a98348d0e3b0277d406dfe8109e17"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.60.5",
-  "source_commit": "a49feea0a58695a606269a3e4ccd1f94afba7114",
-  "source_sha256": "173f7953ea95f0facc3230dc993d4b64aab54037d8a89dfdafe044ad66063bb7",
+  "release_version": "1.60.7",
+  "source_commit": "6299d1f0f325871a33f5aa28bff8dc8029e7350c",
+  "source_sha256": "ac9f92aeaec3cf0cb18de06f1e16b0ee2c44c413ec7c84866f949909611098f1",
   "target": "linux-x64",
-  "sha256": "58a715446ff176ec2b65d583e4d6a6bf3ce81ab48dc0c030da52c61a019523b4"
+  "sha256": "68dfb56ddf1b4647dcd00644d88489fe2022b4136d72443e33f83a86ecb270bb"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.60.5",
-  "source_commit": "a49feea0a58695a606269a3e4ccd1f94afba7114",
-  "source_sha256": "173f7953ea95f0facc3230dc993d4b64aab54037d8a89dfdafe044ad66063bb7",
+  "release_version": "1.60.7",
+  "source_commit": "6299d1f0f325871a33f5aa28bff8dc8029e7350c",
+  "source_sha256": "ac9f92aeaec3cf0cb18de06f1e16b0ee2c44c413ec7c84866f949909611098f1",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "a6b56a02eca424bcc5dc408b90f1d831456a241d04dcc59adc2210b071698e49",
+      "sha256": "1e24ee9c3fa9ac6447ff9f0c8096d80c4e2a98348d0e3b0277d406dfe8109e17",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "58a715446ff176ec2b65d583e4d6a6bf3ce81ab48dc0c030da52c61a019523b4",
+      "sha256": "68dfb56ddf1b4647dcd00644d88489fe2022b4136d72443e33f83a86ecb270bb",
       "mode": "0755"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.60.5",
+  "version": "1.60.7",
   "description": "BotBuddy \u2014 Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {
@@ -19,7 +19,9 @@
     "daemon/",
     "daemon-release/",
     "src/",
-    "!src/**/*.test.mjs"
+    "!src/**/*.test.mjs",
+    "!src/staging-pool/test-helpers/",
+    "!src/staging-pool/fixtures/"
   ],
   "keywords": [
     "mcp",

package/src/commands.mjs

@@ -25,6 +25,7 @@ import { VERSION } from "./version.mjs";
 import { setupMcpKey, revokeMcpKey, resolveMcpConfigKey, resolveEnvVarName, DEFAULT_MCP_ENV_VAR, McpKeyError, McpKeyStoreError } from "./mcp-key.mjs";
 import { readAgentBinding } from "./wait-profile.mjs";
 import { runPw } from "./pw/run.mjs";
+import { symptomHelp as stagingPoolSymptomHelp } from "./staging-pool/errors.mjs";
 import { maybeWarnStale, cmdUpdate } from "./update-check.mjs";
 import { createTelemetryOutbox } from "./telemetry-outbox.mjs";
 import { attestTelemetryCredential, loadTelemetryIdentity, loadTelemetryLocation } from "./telemetry-config.mjs";
@@ -123,6 +124,8 @@ export async function run(argv, {
     case "test-ingest": return cmdTestIngest(args);
     case "wait": return runWait(args);
     case "pw": return runPw(args);
+    // BOT-2084: the human-installed staging session pool broker.
+    case "staging-pool": return (await import("./staging-pool/cli.mjs")).runStagingPool(args);
     case "mcp": return cmdMcp(args);
     case "resources": return callTool("list_resources");
     case "agents": return callTool("list_agents");
@@ -269,6 +272,16 @@ ${bold("BROWSER LANES")}
                               with --environment <env> or BB_PW_ENV)
   pw --help                   Show lane usage
 
+${bold("STAGING SIGN-IN")} (BOT-2084)
+  pw --environment staging <lane> auth --persona <alias>
+                              Agents: sign a claimed lane in to staging as a seeded
+                              persona, no password (${cyan("bb pw auth --help")})
+  staging-pool status [--check]
+                              Pool health: one reason, who acts, the next command
+  staging-pool install|tick|mint-one|uninstall
+                              Human only, from Terminal.app (${cyan("bb staging-pool --help")})
+  help symptom staging-pool   Every refusal code with its cause and next command
+
 ${bold("OTHER")}
   locks -m [--host name]    Reserve typed local resources, including Playwright MCP lanes
   evidence publish <file>    Publish a local evidence statement → botbuddy/ready check-run
@@ -421,6 +434,13 @@ async function cmdToolHelp(args) {
       : `Discovery failed: ${res.status} ${res.statusText}`);
   }
   console.log(formatDiscovery(await res.json(), { tool }));
+  if (!tool) console.log(toolCatalogFooter());
+}
+
+// BOT-2084: local CLI commands are not MCP tools, so the catalog names where
+// their help lives (kept to a few lines: the discovery help has a size budget).
+export function toolCatalogFooter() {
+  return `\nLocal CLI commands (not MCP tools): ${cyan("bb pw auth --help")} staging sign-in for a lane · ${cyan("bb staging-pool --help")} the human-installed session pool · ${cyan("bb help symptom staging-pool")} their error codes.`;
 }
 
 // Keep the most common lifecycle recoveries local: an agent must be able to
@@ -451,6 +471,8 @@ ${bold("WAITING")}
 
   ${cyan("telemetry-unavailable")}  A test launch has no test-run ID or wait command.
   ${cyan("command-run-stuck")}     A local command receipt and remote lifecycle disagree.
+  ${cyan("staging-pool")}          Every bb staging-pool / bb pw auth error code (BOT-2084);
+                         ${cyan("bb help symptom <code>")} for one, e.g. pool_empty.
 
 Choose the symptom printed by the command. If neither applies, preserve the
 original command result and receipt, then report the exact error and command ID.`;
@@ -506,6 +528,12 @@ ${bold("Boundary")}
 Command-run status is agent-owned. A different agent may be denied access; that
 denial is not evidence that the run is missing or terminal.`;
 
+
+  // BOT-2084: the staging session pool's error codes (cli/src/staging-pool/errors.mjs).
+  if (topic.startsWith("symptom ")) {
+    const local = stagingPoolSymptomHelp(topic.slice("symptom ".length));
+    if (local) return local;
+  }
   return null;
 }
 

package/src/pw/args.mjs

@@ -61,6 +61,23 @@ export function planInvocation(argv, env = process.env) {
     if (argv.length !== 3 || !["pass", "fail"].includes(argv[2])) throw new Error("bb-pw: usage: bb-pw <lane> verdict pass|fail");
     return { scope: "lane", lane, session: `lane-${lane}`, verb, mode: "verdict", verdict: argv[2] };
   }
+  // BOT-2084: `auth --persona <slug>` is a LOCAL wrapper verb (never forwarded to
+  // Playwright). Wrapper flags stay before the lane; only --persona follows it.
+  if (verb === "auth") {
+    const authArgs = argv.slice(2);
+    const strayAuth = authArgs.find((value) => credentialFlagOf(value));
+    if (strayAuth) throw misplacedCredentialFlag(strayAuth);
+    const usage = "bb-pw: usage: bb pw --environment staging <lane> auth --persona <slug>";
+    let persona = null;
+    for (let i = 0; i < authArgs.length; i++) {
+      const token = String(authArgs[i]);
+      if (token === "--persona" && persona === null && authArgs[i + 1] !== undefined && !String(authArgs[i + 1]).startsWith("--")) { persona = String(authArgs[++i]); continue; }
+      if (token.startsWith("--persona=") && persona === null && token.length > "--persona=".length) { persona = token.slice("--persona=".length); continue; }
+      throw new Error(`${usage} (unexpected '${token}')`);
+    }
+    if (!persona) throw new Error(`${usage} (--persona is required)`);
+    return { scope: "lane", lane, session: `lane-${lane}`, verb, mode: "auth", persona };
+  }
   if (verb === "status") {
     // `status` has no workload, so — like the global verbs — there is no `--`
     // exemption: a credential flag in ANY position (incl. after `--`) is misplaced

package/src/pw/coordinator.mjs

@@ -18,7 +18,11 @@ function mcpCaller(authHeader, fetchImpl) {
 }
 
 function laneCoordinator(kind, call, agentId) {
-  return { kind, async status({ host, slot }) { const result = await call("list_resources", { host, subtype: "playwright_lane" }); const list = Array.isArray(result) ? result : result.resources ?? []; const resource = list.find((item) => item.name === `playwright_lane:${host}:${slot}` || String(item.slot) === String(slot)); /* BOT-1490: canonical_host is a TOP-LEVEL field the server echoes even on an empty page (not-held lane); owner_is_caller is per-row. Older servers send neither → null. */ const canonicalHost = (result && !Array.isArray(result) ? result.canonical_host : null) ?? null; return resource ? { held: resource.status !== "free", heldBy: resource.owner_agent_id ?? null, heldByName: resource.agents?.name ?? null, host: resource.host ?? null, name: resource.name ?? null, slot: resource.slot ?? null, canonicalHost, ownerIsCaller: resource.owner_is_caller ?? null } : { held: false, heldBy: null, heldByName: null, host: null, name: null, slot: null, canonicalHost, ownerIsCaller: null }; }, agentId };
+  return { kind,
+    // BOT-2084: the agent this credential authenticates as (whoami), for checks that
+    // need the exact holder when no local agent id is known (an exported session token).
+    async whoami() { const identity = await call("whoami", {}); return typeof identity?.agent?.id === "string" ? identity.agent.id : null; },
+    async status({ host, slot }) { const result = await call("list_resources", { host, subtype: "playwright_lane" }); const list = Array.isArray(result) ? result : result.resources ?? []; const resource = list.find((item) => item.name === `playwright_lane:${host}:${slot}` || String(item.slot) === String(slot)); /* BOT-1490: canonical_host is a TOP-LEVEL field the server echoes even on an empty page (not-held lane); owner_is_caller is per-row. Older servers send neither → null. */ const canonicalHost = (result && !Array.isArray(result) ? result.canonical_host : null) ?? null; return resource ? { held: resource.status !== "free", heldBy: resource.owner_agent_id ?? null, heldByName: resource.agents?.name ?? null, host: resource.host ?? null, name: resource.name ?? null, slot: resource.slot ?? null, canonicalHost, ownerIsCaller: resource.owner_is_caller ?? null } : { held: false, heldBy: null, heldByName: null, host: null, name: null, slot: null, canonicalHost, ownerIsCaller: null }; }, agentId };
 }
 
 // BOT-1572/1582: authenticate lock verification with a per-session `bb_agent_` token —

package/src/pw/run.mjs

@@ -10,11 +10,12 @@ import { loadConfig, getConfig } from "../config.mjs";
 import { VERSION } from "../version.mjs";
 import { readAgentSessionTokenEnv, AGENT_KEY_RE, legacyAgentAliasHint } from "../agent-key.mjs";
 import { clearAgentState, isRejectedCachedMcpSession, resolveAgentSessionCredential } from "../agent-session.mjs";
+import * as stagingAuth from "./staging-auth.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>] [--agent-session-token <token>] [--environment <env>] <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>    accepted before the lane but currently INERT — the tenant\n                   comes from your resolved credential, so bb pw does not act on\n                   this flag for session/lane auth yet (server-validated tenant\n                   selection is tracked in BOT-1732).\n\n--environment <local|preview|staging|production>  the environment a TRACKED\n                   browser session is exercising (env $BB_PW_ENV when absent; the\n                   flag wins). Required when a session starts in a repository\n                   with .botbuddy/config.json; persisted for the session, and a\n                   later disagreeing value is refused.\n\nBrowser-acceptance telemetry (BOT-1318): each lane browser session (open →\nclose) is reported once as a browser_acceptance execution with wall/active/\ncommand time, per-action results and a verdict. Every action's result is\nuploaded before the command returns; offline, events queue locally and drain\nlater. Values you type/fill, secrets, query strings and raw output are never\nrecorded. BB_PW_NO_LOCK=1 stays local and untracked.\n  bb-pw <lane> verdict pass|fail   record the acceptance verdict (local; never\n                                   sent to Playwright). Without it a session\n                                   closes as not_asserted.\n  bb-pw <lane> status              shows browser_session: source_run_id,\n                                   execution_id, delivery, environment, verdict.\n\nCredential flags (--tenant / --session-id / --agent-session-token) and\n--environment go BEFORE the lane. Placed after the lane they are refused with guidance (they are not\nPlaywright arguments, and a --tenant after the lane cannot be safely honored).\n\nFile upload (BOT-1702) — works on a hidden <input type=file>:\n  bb-pw <lane> upload <selector> <path...>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,size=<bytes>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,bytes=@base64:<b64>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,text=<str>\n     --inline repeats; builds synthetic files in memory (no workstation FS).\n     <selector> also accepts --testid/--role/--label/--text like click/fill.\n\nNetwork mocking (BOT-1702) — routes persist on the lane across invocations:\n  bb-pw <lane> route <url-glob> stall                 hold the request pending\n                                                      (screenshot the loading state)\n  bb-pw <lane> route <url-glob> abort [--error <code>] fail the request (default: failed)\n  bb-pw <lane> route <url-glob> fulfill --status <n> [--content-type <ct>]\n                                        [--body <str|@base64:..|@file:PATH>]\n  bb-pw <lane> unroute [<url-glob>]                    release one route, or all\n  bb-pw <lane> route-list                              list the routes owned on this lane\n  (offline mode already exists upstream: bb-pw <lane> network-state-set offline)\n"); }
+function help(out) { out.write("Usage: pw [--tenant <slug>] [--session-id <id>] [--agent-session-token <token>] [--environment <env>] <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>    accepted before the lane but currently INERT — the tenant\n                   comes from your resolved credential, so bb pw does not act on\n                   this flag for session/lane auth yet (server-validated tenant\n                   selection is tracked in BOT-1732).\n\n--environment <local|preview|staging|production>  the environment a TRACKED\n                   browser session is exercising (env $BB_PW_ENV when absent; the\n                   flag wins). Required when a session starts in a repository\n                   with .botbuddy/config.json; persisted for the session, and a\n                   later disagreeing value is refused.\n\nBrowser-acceptance telemetry (BOT-1318): each lane browser session (open →\nclose) is reported once as a browser_acceptance execution with wall/active/\ncommand time, per-action results and a verdict. Every action's result is\nuploaded before the command returns; offline, events queue locally and drain\nlater. Values you type/fill, secrets, query strings and raw output are never\nrecorded. BB_PW_NO_LOCK=1 stays local and untracked.\n  bb-pw <lane> verdict pass|fail   record the acceptance verdict (local; never\n                                   sent to Playwright). Without it a session\n                                   closes as not_asserted.\n  bb-pw <lane> status              shows browser_session: source_run_id,\n                                   execution_id, delivery, environment, verdict.\n\nCredential flags (--tenant / --session-id / --agent-session-token) and\n--environment go BEFORE the lane. Placed after the lane they are refused with guidance (they are not\nPlaywright arguments, and a --tenant after the lane cannot be safely honored).\n\nFile upload (BOT-1702) — works on a hidden <input type=file>:\n  bb-pw <lane> upload <selector> <path...>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,size=<bytes>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,bytes=@base64:<b64>\n  bb-pw <lane> upload <selector> --inline name=<n>,mime=<m>,text=<str>\n     --inline repeats; builds synthetic files in memory (no workstation FS).\n     <selector> also accepts --testid/--role/--label/--text like click/fill.\n\nNetwork mocking (BOT-1702) — routes persist on the lane across invocations:\n  bb-pw <lane> route <url-glob> stall                 hold the request pending\n                                                      (screenshot the loading state)\n  bb-pw <lane> route <url-glob> abort [--error <code>] fail the request (default: failed)\n  bb-pw <lane> route <url-glob> fulfill --status <n> [--content-type <ct>]\n                                        [--body <str|@base64:..|@file:PATH>]\n  bb-pw <lane> unroute [<url-glob>]                    release one route, or all\n  bb-pw <lane> route-list                              list the routes owned on this lane\n  (offline mode already exists upstream: bb-pw <lane> network-state-set offline)\n\nStaging sign-in (BOT-2084) — agents sign a lane in to staging without a password:\n  bb pw --environment staging <lane> auth --persona <alias>\n     Installs a session from the human-installed staging session pool into this lane only.\n     Prerequisites, example, output and every refusal: bb pw auth --help\n  bb setup / bb doctor restore YOUR BotBuddy agent session; they never sign in to the\n  application under test.\n\nSaved browser state (state-save / state-load) is forwarded to Playwright. State files are\nSECRET-BEARING and are not a staging sign-in path: use auth above.\n"); }
 // Redact LONGEST secrets first: replacing a short value that is a substring of a
 // longer secret (e.g. a filename that also appears inside the payload's base64)
 // would otherwise break the longer match and leave the remainder recoverable
@@ -67,7 +68,7 @@ async function gate({ env, host, lane, deps }) {
     coordinator = createSessionTokenCoordinator({ token, fetchImpl: deps.fetch });
   }
   if (coordinator.kind === "unverified") return { allowed: false, message: "bb-pw: BotBuddy credential is unusable. Re-register the agent, or set BB_PW_NO_LOCK=1 for local-only work." };
-  const selfAgentIds = new Set([sessionAgentId, registeredAgentId, coordinator.agentId].filter(Boolean));
+  const selfAgentIds = new Set([sessionAgentId, registeredAgentId, coordinator.agentId, deps.credentialAgentId].filter(Boolean));
   const callerId = coordinator.agentId ?? sessionAgentId ?? registeredAgentId ?? "botbuddy";
   const laneName = `playwright_lane:${host}:${lane}`;
   try {
@@ -85,15 +86,20 @@ async function gate({ env, host, lane, deps }) {
     // the holder to the caller's owner (BOT-1490 owner_is_caller — server-authoritative,
     // closing the shared-hostname gap without trusting a local file). The local paths
     // stay as fallbacks for older servers that do not send owner_is_caller.
-    if (status.held && (selfAgentIds.has(status.heldBy) || status.ownerIsCaller === true)) return { allowed: true, coordinator, canonicalHost };
+    // BOT-2084: report HOW the holder matched. `auth` (staging session issuance)
+    // requires the exact agent ("self"), never only a same-owner match ("owner").
+    // callerIds/holder let staging-auth cleanup touch only what this caller installed.
+    const callerIds = [...selfAgentIds];
+    if (status.held && selfAgentIds.has(status.heldBy)) return { allowed: true, coordinator, canonicalHost, holderMatch: "self", holder: status.heldBy, callerIds };
+    if (status.held && status.ownerIsCaller === true) return { allowed: true, coordinator, canonicalHost, holderMatch: "owner", holder: status.heldBy ?? null, callerIds };
     // Distinguish an expired/free lane from one another operator holds so the
     // operator knows whether to re-acquire vs. wait for a handover (BOT-660). Name it
     // by the server's canonical host so a not-held message matches the dashboard even
     // when local normalization cannot reach the alias-collapsed key (BOT-1490 AC-5).
-    if (!status.held) return { allowed: false, message: `bb-pw: lane lock ${foundLaneName} is not held (caller ${callerId}). Acquire it via BotBuddy first, or set BB_PW_NO_LOCK=1 for local-only work.` };
+    if (!status.held) return { allowed: false, reason: "not_held", canonicalHost, callerIds, coordinator, message: `bb-pw: lane lock ${foundLaneName} is not held (caller ${callerId}). Acquire it via BotBuddy first, or set BB_PW_NO_LOCK=1 for local-only work.` };
     const holder = status.heldBy ?? "unknown";
     const holderName = status.heldByName ? ` (${status.heldByName})` : "";
-    return { allowed: false, message: `bb-pw: lane lock ${foundLaneName} is held by ${holder}${holderName}, not you (caller ${callerId}). Acquire it first or set BB_PW_NO_LOCK=1 for local-only work.` };
+    return { allowed: false, reason: "held_by_other", canonicalHost, callerIds, coordinator, message: `bb-pw: lane lock ${foundLaneName} is held by ${holder}${holderName}, not you (caller ${callerId}). Acquire it first or set BB_PW_NO_LOCK=1 for local-only work.` };
   } catch (error) {
     return { allowed: false, errorCode: error?.code ?? null, message: `bb-pw: could not verify lane lock ${laneName} (${error.message}). Set BB_PW_NO_LOCK=1 for local-only work.` };
   }
@@ -183,8 +189,23 @@ function consumeWrapperFlags(list, deps, start = 0) {
   return { deps, rest };
 }
 
+// The non-secret values a staging-auth refusal names in its next command.
+const authVars = (plan, deps = {}) => {
+  const cwd = deps.cwd ?? process.cwd();
+  return { lane: plan.lane, persona: plan.persona, cwd, ticketFlag: stagingAuth.ticketFlagFor(cwd) };
+};
+
+// `bb pw auth --help` / `bb pw [flags] <lane> auth --help`: auth's own help, before
+// any credential, lock or daemon call.
+function wantsAuthHelp(args) {
+  const at = args.indexOf("auth");
+  if (at === -1 || !(at === 0 || /^[0-9]+$/.test(args[at - 1]))) return false;
+  return args.slice(at + 1).some((token) => token === "--help" || token === "-h");
+}
+
 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 (wantsAuthHelp(args)) { stdout.write(`${(await import("../staging-pool/help.mjs")).PW_AUTH_HELP}\n`); 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);
@@ -206,6 +227,14 @@ async function runPwInner(argv, deps = {}) {
   // `--tenant` lane fallback is BOT-1732.
   { const consumed = consumeWrapperFlags(args, deps, 0); if (consumed.error) { stderr.write(`bb-pw: ${consumed.error} needs a value\n`); return 2; } deps = consumed.deps; args = consumed.rest; }
   let plan; try { plan = planInvocation(args, env); } catch (error) { stderr.write(`${error.message}\n`); return 2; }
+  // BOT-2084 (#1068 run.mjs:110): auth only ever issues a STAGING session into a
+  // lock-gated lane, so refuse any other resolved environment — and the unlocked
+  // local mode — before any credential, lock or issuer call.
+  if (plan.mode === "auth") {
+    const authEnvironment = resolveEnvironment({ flag: deps.environment ?? null, env });
+    if (authEnvironment.error || authEnvironment.environment !== "staging") return stagingAuth.refuse({ stdout, stderr }, "auth_requires_staging_environment", 2, {}, authVars(plan, deps));
+    if (env.BB_PW_NO_LOCK === "1") return stagingAuth.refuse({ stdout, stderr }, "auth_requires_lane_lock", 3, {}, authVars(plan, deps));
+  }
   const { spawnExec, socketRun } = deps.daemon ?? await import("./daemon.mjs");
   if (plan.scope === "global") { if (plan.mode === "reap") { await (deps.reap ?? (await import("./reap.mjs")).reap)({ env, stdout }); return 0; } if (env.BB_PW_NO_LOCK !== "1") { stderr.write("bb-pw: close-all and kill-all require BB_PW_NO_LOCK=1 because they can affect lanes you do not own.\n"); return 3; } return spawnExec(plan, env); }
   // Local-only lanes explicitly opt out of lock ownership, so they also need no
@@ -215,7 +244,7 @@ async function runPwInner(argv, deps = {}) {
     try {
       const credential = await (deps.resolveCredential ?? resolveAgentSessionCredential)({ argv, env, cwd: deps.cwd ?? process.cwd(), sessionId: deps.sessionId ?? env.BOTBUDDY_SESSION_ID ?? null, flagToken: null });
       managedCredential = credential;
-      deps = { ...deps, sessionToken: credential.token, sessionId: deps.sessionId ?? credential.sessionId ?? null };
+      deps = { ...deps, sessionToken: credential.token, sessionId: deps.sessionId ?? credential.sessionId ?? null, credentialAgentId: credential.agentId ?? null };
     } catch (error) {
       stderr.write(selfHealErrorLine(error)); return 3;
     }
@@ -232,7 +261,7 @@ async function runPwInner(argv, deps = {}) {
       managedCredential = credential;
       // Keep an explicit --session-id holder authoritative over the freshly minted
       // one, same precedence as the initial resolution (Codex).
-      deps = { ...deps, sessionToken: credential.token, sessionId: deps.sessionId ?? credential.sessionId ?? null };
+      deps = { ...deps, sessionToken: credential.token, sessionId: deps.sessionId ?? credential.sessionId ?? null, credentialAgentId: credential.agentId ?? null };
     } catch (error) {
       // BOT-1682: the renewal after a revoked cache can also fail self-heal; fail
       // closed with a clear message rather than letting the error escape to exit 1.
@@ -240,7 +269,21 @@ async function runPwInner(argv, deps = {}) {
     }
     auth = await gate({ env, host, lane: plan.lane, deps });
   }
-  if (!auth.allowed) { stderr.write(`${auth.message}\n`); return 3; }
+  // BOT-2084 staging-auth hooks share the lane's daemon and the gate-verified
+  // credential; the trust bridge decides how that credential reaches Staging.
+  const daemonModule = deps.daemon?.resolveSession ? null : await import("./daemon.mjs");
+  const authCtx = { plan, host: auth.canonicalHost ?? host, env, deps, stdout, stderr, socketRun, resolveSession: deps.daemon?.resolveSession ?? daemonModule.resolveSession,
+    holder: auth.holder ?? null, callerIds: auth.callerIds ?? [],
+    // An exported session token carries no local agent id: ask the server who it is.
+    resolveCallerId: typeof auth.coordinator?.whoami === "function" ? () => auth.coordinator.whoami() : null,
+    credential: { token: deps.sessionToken ?? readAgentSessionTokenEnv(env) ?? null, agentId: deps.credentialAgentId ?? null, sessionId: deps.sessionId ?? null } };
+  if (!auth.allowed) {
+    // A lane that is provably no longer ours (not a transient verify error):
+    // clear the session we installed and revoke its custody (AC-3).
+    if (auth.reason === "not_held" || auth.reason === "held_by_other") await stagingAuth.onLaneAuthorityLost(authCtx).catch(() => {});
+    if (plan.mode === "auth" && (auth.reason === "not_held" || auth.reason === "held_by_other")) return stagingAuth.refuse({ stdout, stderr }, "lane_not_claimed", 3, { detail: auth.message }, authVars(plan, deps));
+    stderr.write(`${auth.message}\n`); return 3;
+  }
   // Report the host the lock service actually stored (alias-collapsed), so the
   // status view and lane telemetry match the server, not the local string (AC-4).
   const effHost = auth.canonicalHost ?? host;
@@ -259,6 +302,19 @@ async function runPwInner(argv, deps = {}) {
   const envResolution = resolveEnvironment({ flag: deps.environment ?? null, env });
   if (tracker && envResolution.error) { stderr.write(`${envResolution.error}\n`); return 2; }
   const environment = envResolution.environment ?? null;
+  if (plan.mode === "auth") {
+    let holderMatch = auth.holderMatch;
+    if (holderMatch === "owner" && auth.holder && authCtx.resolveCallerId) {
+      const me = await authCtx.resolveCallerId().catch(() => null);
+      if (me && me === auth.holder) { holderMatch = "self"; authCtx.callerIds = [...authCtx.callerIds, me]; }
+    }
+    if (holderMatch !== "self") return stagingAuth.refuse({ stdout, stderr }, "exact_lane_holder_required", 3, {}, authVars(plan, deps));
+    if (tracker) {
+      const browserSession = await tracker.status();
+      if (browserSession.active && browserSession.environment && browserSession.environment !== "staging") return stagingAuth.refuse({ stdout, stderr }, "browser_session_not_staging", 2, {}, authVars(plan, deps));
+    }
+    return stagingAuth.runStagingAuth(authCtx);
+  }
   if (plan.mode === "status") {
     const lock = auth.coordinator?.status ? await auth.coordinator.status({ host: effHost, slot: plan.lane }) : null;
     const browserSession = tracker ? await tracker.status() : { tracked: false, active: false };
@@ -275,6 +331,9 @@ async function runPwInner(argv, deps = {}) {
     if (result.error) { stderr.write(`${result.error}\n`); return 2; }
     reportDegradation(stderr, result.delivery); return 0;
   }
+  // BOT-2084: crash cleanup and renewal-before-sweep for a lane carrying a
+  // staging custody; a failed renewal stops the command (AC-3).
+  { const stop = await stagingAuth.beforeLaneCommand(authCtx); if (stop !== null) return stop; }
   // Translate verbs ALWAYS run via the socket (even a small, non-secret one), so
   // run.mjs — not an inherited-stdio spawnExec — owns their output and can strip
   // the internal code echo; socketRun falls back to execArgv.slice(1) as its args
@@ -291,10 +350,15 @@ async function runPwInner(argv, deps = {}) {
     if (inspect) { if (plan.fresh) await socketRun({ ...plan, socketArgs: ["snapshot"] }, env).catch(() => {}); const result = await socketRun({ ...plan, socketArgs: plan.socketArgs ?? plan.execArgv.slice(1) }, env); if (result.text) { const text = suppressEcho ? stripCodeEcho(result.text) : result.text; stdout.write(`${redact(text, plan.secretValues)}\n`); } if (!result.ok) { let errText = plan.targetKind === "ref" && isStaleRefError(result.error) ? staleRefRemediation(plan.target) : result.error; if (suppressEcho) errText = stripCodeEcho(errText); stderr.write(`${redact(errText, plan.secretValues)}\n`); } return { code: result.ok ? 0 : 1, errorText: result.ok ? null : String(result.error ?? "") }; }
     const code = await spawnExec(plan, env); return { code, errorText: code === 0 ? null : `exit ${code}` };
   };
-  if (!tracker) return (await execute()).code;
+  if (!tracker) {
+    const result = await execute();
+    if (plan.verb === "close") await stagingAuth.afterLaneClose(authCtx);
+    return result.code;
+  }
   const probe = async () => { const resolver = deps.daemon?.resolveSession ?? (await import("./daemon.mjs")).resolveSession; const { session } = await resolver(plan.session, env); return { alive: Boolean(session), generation: session?.socketPath ?? null }; };
   if (plan.verb === "close") {
     const closed = await tracker.close({ environment, probe, run: execute });
+    await stagingAuth.afterLaneClose(authCtx);
     if (closed.error) { stderr.write(`${closed.error}\n`); return 2; }
     reportDegradation(stderr, closed.delivery); return closed.code;
   }