@botbuddy/cli 1.14.0 → 1.17.0

package/package.json

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

package/src/auth.mjs

@@ -69,6 +69,12 @@ export async function doLogin(options = {}, deps = {}) {
   const noBrowser = Boolean(options.noBrowser);
   // BOT-1566: optional tenant preselection (validated by the argument parser).
   const tenant = typeof options.tenant === "string" && options.tenant ? options.tenant : null;
+  // BOT-1580: display-only caller identity hints. Forwarded to the authorization
+  // screen so the approver knows who requested the login; sanitized inside
+  // buildAuthorizeUrl. These never influence tenant, scope, or token minting.
+  const caller = typeof options.caller === "string" && options.caller ? options.caller : null;
+  const callerHarness = typeof options.callerHarness === "string" && options.callerHarness ? options.callerHarness : null;
+  const callerTicket = typeof options.callerTicket === "string" && options.callerTicket ? options.callerTicket : null;
 
   log(`${bold("BotBuddy OAuth Login")}\n`);
 
@@ -108,7 +114,7 @@ export async function doLogin(options = {}, deps = {}) {
 
     // AC-6/AC-7: build the authorization URL and always print it (headless users
     // open it themselves). The CLI never fetches /authorize.
-    const authUrl = buildAuthorizeUrl({ serverUrl, clientId, redirectUri, state, codeChallenge, tenant });
+    const authUrl = buildAuthorizeUrl({ serverUrl, clientId, redirectUri, state, codeChallenge, tenant, caller, callerHarness, callerTicket });
     log("");
     log(dim("→ Authorize BotBuddy in your browser:"));
     log(`  ${cyan(authUrl)}`);

package/src/commands.mjs

@@ -91,7 +91,7 @@ ${bold("OPTIONS")}
     --no-server              Don't auto-start codex app-server
 
 ${bold("AUTH")}
-  login [--no-browser] [--tenant <slug>]
+  login [--no-browser] [--tenant <slug>] [--caller <name>] [--caller-harness <h>] [--caller-ticket <ref>]
                              Authenticate via OAuth (opens browser + localhost callback)
   logout                     Remove saved credentials
   status                     Show current auth status (local metadata + server check)
@@ -176,7 +176,16 @@ export class LoginUsageError extends Error {
 // preselects the tenant on the OAuth picker; a malformed slug is a usage
 // error with exit code 2 (never sent to the server).
 export function parseLoginArgs(args) {
-  const out = { noBrowser: false, tenant: null, help: false };
+  const out = { noBrowser: false, tenant: null, help: false, caller: null, callerHarness: null, callerTicket: null };
+  // BOT-1580: display-only caller flags. Unlike --tenant they are free text (an
+  // unverified hint shown on the consent screen), so they are never validated
+  // into a usage error here — sanitization/length-capping happens when the URL is
+  // built. A value is taken verbatim from `--flag value` or `--flag=value`.
+  const CALLER_FLAGS = {
+    "--caller": "caller",
+    "--caller-harness": "callerHarness",
+    "--caller-ticket": "callerTicket",
+  };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--help" || arg === "-h") { out.help = true; continue; }
@@ -189,6 +198,31 @@ export function parseLoginArgs(args) {
       out.tenant = value;
       continue;
     }
+    let matchedCaller = false;
+    for (const [flag, key] of Object.entries(CALLER_FLAGS)) {
+      if (arg === flag || arg.startsWith(`${flag}=`)) {
+        let value;
+        if (arg.startsWith(`${flag}=`)) {
+          // `--flag=value` takes the value verbatim (an explicit leading dash is
+          // the user's own choice, e.g. --caller=--weird).
+          value = arg.slice(`${flag}=`.length);
+        } else {
+          // `--flag value`: the next token is the value only if it exists and is
+          // not itself an option. Otherwise it would silently swallow the next
+          // flag (e.g. `--caller --no-browser` would set caller="--no-browser"
+          // and drop --no-browser) — reject that as a usage error instead.
+          value = args[i + 1];
+          if (typeof value !== "string" || value.startsWith("-")) {
+            throw new LoginUsageError(`error: ${flag} requires a value`, { exitCode: 2 });
+          }
+          i++;
+        }
+        out[key] = value;
+        matchedCaller = true;
+        break;
+      }
+    }
+    if (matchedCaller) continue;
     if (arg.startsWith("-")) {
       throw new LoginUsageError(`Unknown login option: ${arg}. Run ${cyan("botbuddy login --help")}.`);
     }
@@ -196,6 +230,26 @@ export function parseLoginArgs(args) {
   return out;
 }
 
+// BOT-1580: resolve the caller identity from parsed flags, falling back to the
+// BOTBUDDY_CALLER* environment variables so an agent harness can advertise who it
+// is without every wrapper having to pass flags. A flag always wins over the env.
+// Returns only the three caller fields; empty values collapse to null.
+export function resolveCaller(parsed = {}, env = {}) {
+  const pick = (flagVal, envKey) => {
+    // A flag that was PROVIDED wins over the environment, even when it is an
+    // explicit empty `--caller=` — that is how a user clears a stale inherited
+    // identity, so it must NOT fall back to the env. `null` means the flag was
+    // omitted → fall back to the env var. Either way an empty result is null.
+    const raw = flagVal != null ? flagVal : env[envKey];
+    return typeof raw === "string" && raw !== "" ? raw : null;
+  };
+  return {
+    caller: pick(parsed.caller, "BOTBUDDY_CALLER"),
+    callerHarness: pick(parsed.callerHarness, "BOTBUDDY_CALLER_HARNESS"),
+    callerTicket: pick(parsed.callerTicket, "BOTBUDDY_CALLER_TICKET"),
+  };
+}
+
 // BOT-1383: login now runs the RFC 8252 loopback flow (opens the browser,
 // waits for the localhost callback). Parse --no-browser / --tenant and print
 // focused help.
@@ -209,8 +263,10 @@ async function cmdLogin(args, { errorLog = (line) => console.error(line) } = {})
     die(err.message);
   }
   if (options.help) return loginHelp();
+  // BOT-1580: merge caller flags with the BOTBUDDY_CALLER* env fallback.
+  const caller = resolveCaller(options, process.env);
   try {
-    await doLogin({ noBrowser: options.noBrowser, tenant: options.tenant });
+    await doLogin({ noBrowser: options.noBrowser, tenant: options.tenant, ...caller });
   } catch (err) {
     die(err.message);
   }
@@ -221,6 +277,7 @@ function loginHelp() {
 
 ${bold("USAGE")}
   botbuddy login [--no-browser] [--tenant <slug>]
+                 [--caller <name>] [--caller-harness <harness>] [--caller-ticket <ref>]
 
 ${bold("HOW IT WORKS")}
   Starts a localhost callback listener on an ephemeral 127.0.0.1 port, opens
@@ -238,6 +295,20 @@ ${bold("OPTIONS")}
                  Preselect a tenant (e.g. ${cyan("supply-guard")}) on the sign-in page when
                  your account belongs to more than one. Must be a lowercase slug;
                  membership is still enforced by the server.
+  --caller <name>
+                 Show WHO requested this login on the authorization screen, so
+                 the human approving it can confirm the request came from the
+                 agent/session they are actually running. Display-only and
+                 unverified — it never affects the tenant, scope, or token.
+  --caller-harness <harness>
+                 Optional harness label shown next to the caller (e.g.
+                 ${cyan("claude-code")}, ${cyan("codex")}).
+  --caller-ticket <ref>
+                 Optional ticket the caller is working on. A full
+                 ${dim("https://linear.app/…")} URL is shown as a link; anything else is
+                 shown as plain text.
+                 ${dim("Each --caller* value also falls back to $BOTBUDDY_CALLER,")}
+                 ${dim("$BOTBUDDY_CALLER_HARNESS and $BOTBUDDY_CALLER_TICKET.")}
 
 ${bold("NOTES")}
   • The authorization URL is always printed so you can open it manually.
@@ -264,14 +335,19 @@ async function cmdStart(args) {
   // (owner token from `login`, agent key from `profile setup`), so probe those
   // rather than a plaintext config secret.
   try {
+    // BOT-1580: the auto-login path has no --caller flags of its own, but a
+    // harness that exports BOTBUDDY_CALLER* should still be identified on the
+    // authorization screen. Resolve the caller from the environment and forward
+    // it, exactly as `botbuddy login` does.
+    const caller = resolveCaller({}, process.env);
     const owner = await resolveOwnerToken({ getConfig });
     const agentKey = owner ? null : await resolveAgentKey();
     if (!owner && !agentKey) {
       console.log(dim("→ No credentials found. Starting login...\n"));
-      await doLogin();
+      await doLogin({ ...caller });
     } else if (owner && owner.expiresAt && owner.expiresAt <= Date.now() && !(await resolveAgentKey())) {
       console.log(dim("→ Token expired. Re-authenticating...\n"));
-      await doLogin();
+      await doLogin({ ...caller });
     }
   } catch (err) {
     die(err.message);

package/src/oauth-loopback.mjs

@@ -44,9 +44,43 @@ export function generateState() {
   return randomBytes(16).toString("hex");
 }
 
+// BOT-1580: display-only caller identity is UNTRUSTED text. Sanitize it before
+// it ever enters the authorize URL: strip control characters (they can break the
+// consent-screen layout or smuggle terminal escapes into any log that echoes the
+// URL) and cap the length. Returns the cleaned string, or null when nothing
+// printable remains — so an absent/blank/garbage field is simply omitted rather
+// than rendered as an empty or fabricated identity. This is defense in depth; the
+// web consent screen sanitizes again at render time and never trusts this hint
+// for tenant selection, scope, or token minting.
+export function sanitizeCallerField(value, maxLen = 200) {
+  if (typeof value !== "string") return null;
+  // Strip Unicode control (C0/C1/DEL), format (bidi overrides, zero-width, BOM,
+  // soft hyphen), and line/paragraph separators — an untrusted caller must not be
+  // able to alter line breaking or visual ordering on the consent screen — while
+  // preserving legitimate visible non-ASCII in names.
+  const cleaned = value.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, "").trim();
+  if (!cleaned) return null;
+  return cleaned.slice(0, maxLen);
+}
+
+// BOT-1580: length caps per caller field. Names and harnesses are short labels;
+// a ticket may be a full Linear URL, so it gets more headroom.
+export const CALLER_FIELD_LIMITS = { name: 80, harness: 40, ticket: 200 };
+
 // AC-6/AC-7: build the complete /authorize URL. The browser follows it; the CLI
 // never fetches it. `redirectUri` must be the exact loopback callback we bound.
-export function buildAuthorizeUrl({ serverUrl, clientId, redirectUri, state, codeChallenge, scope = "read write lock", tenant = null }) {
+export function buildAuthorizeUrl({
+  serverUrl,
+  clientId,
+  redirectUri,
+  state,
+  codeChallenge,
+  scope = "read write lock",
+  tenant = null,
+  caller = null,
+  callerHarness = null,
+  callerTicket = null,
+}) {
   const url = new URL(`${serverUrl}/authorize`);
   url.searchParams.set("client_id", clientId);
   url.searchParams.set("redirect_uri", redirectUri);
@@ -59,6 +93,16 @@ export function buildAuthorizeUrl({ serverUrl, clientId, redirectUri, state, cod
   // it to the /mcp-auth picker as `requestedTenant`; membership is still
   // enforced server-side at authorize_complete — this only preselects.
   if (tenant) url.searchParams.set("tenant", tenant);
+  // BOT-1580: display-only caller identity, so the human approving the login can
+  // check it against the agent session they are actually running. These are
+  // UNVERIFIED hints — /authorize only forwards them to the consent screen; they
+  // never influence tenant, scope, or the minted token.
+  const callerName = sanitizeCallerField(caller, CALLER_FIELD_LIMITS.name);
+  const harness = sanitizeCallerField(callerHarness, CALLER_FIELD_LIMITS.harness);
+  const ticket = sanitizeCallerField(callerTicket, CALLER_FIELD_LIMITS.ticket);
+  if (callerName) url.searchParams.set("caller", callerName);
+  if (harness) url.searchParams.set("caller_harness", harness);
+  if (ticket) url.searchParams.set("caller_ticket", ticket);
   return url.toString();
 }
 

package/src/pw/coordinator.mjs

@@ -1,12 +1,30 @@
 import { SERVER_URL } from "../config.mjs";
-export function createProfileCoordinator({ profile, identity, fetchImpl = fetch } = {}) {
-  if (!profile?.token || !identity?.agentId || identity.tenant !== profile.tenant) return { kind: "unverified" };
+
+// Shared JSON-RPC caller — auth header differs (profile key vs. session token).
+function mcpCaller(authHeader, fetchImpl) {
   let id = 0;
-  async function call(name, args) {
-    const response = await fetchImpl(SERVER_URL, { method: "POST", headers: { "content-type": "application/json", "x-agent-api-key": profile.token }, body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method: "tools/call", params: { name, arguments: args } }) });
+  return async function call(name, args) {
+    const response = await fetchImpl(SERVER_URL, { method: "POST", headers: { "content-type": "application/json", ...authHeader }, body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method: "tools/call", params: { name, arguments: args } }) });
     if (!response.ok) throw new Error(`BotBuddy lock verification returned HTTP ${response.status}`);
     const json = await response.json(); if (json.error) throw new Error(json.error.message || "BotBuddy lock verification failed");
     const text = json.result?.content?.find((item) => item.type === "text")?.text; try { return text ? JSON.parse(text) : {}; } catch { throw new Error("BotBuddy lock verification returned invalid JSON"); }
-  }
-  return { kind: "profile", 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 }; }, async emit(event) { await call("record_lane_event", event); }, agentId: identity.agentId };
+  };
+}
+
+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 }; }, async emit(event) { await call("record_lane_event", event); }, agentId };
+}
+
+// BOT-1572: authenticate lock verification with a per-session `bb_sess_` token —
+// the server resolves it to the session agent (mcp-server authenticateAgent), so
+// `list_resources`/`record_lane_event` run AS the session, and holder matching
+// rides on the server's `owner_is_caller`. No machine profile is required.
+export function createSessionTokenCoordinator({ token, fetchImpl = fetch } = {}) {
+  if (!token) return { kind: "unverified" };
+  return laneCoordinator("session_token", mcpCaller({ "x-agent-api-key": token }, fetchImpl), null);
+}
+
+export function createProfileCoordinator({ profile, identity, fetchImpl = fetch } = {}) {
+  if (!profile?.token || !identity?.agentId || identity.tenant !== profile.tenant) return { kind: "unverified" };
+  return laneCoordinator("profile", mcpCaller({ "x-agent-api-key": profile.token }, fetchImpl), identity.agentId);
 }

package/src/pw/run.mjs

@@ -2,7 +2,7 @@ import os from "node:os";
 import { planInvocation } from "./args.mjs";
 import { actionTypeFromMethod, NAV } from "./readiness.mjs";
 import { isStaleRefError, staleRefRemediation } from "./targets.mjs";
-import { createProfileCoordinator } from "./coordinator.mjs";
+import { createProfileCoordinator, createSessionTokenCoordinator } from "./coordinator.mjs";
 import { canonicalizeHostString } from "./host.mjs";
 import { resolveAgentProfile } from "../wait-profile.mjs";
 import { readProfileIdentity } from "../agent-credential-store.mjs";
@@ -23,24 +23,38 @@ function redact(value, secretValues = []) { return secretValues.reduce((text, se
 async function readRegisteredAgentId() { try { await loadConfig(); const id = getConfig()?.agent_id; return typeof id === "string" && id ? id : null; } catch { return null; } }
 async function gate({ env, host, lane, deps }) {
   if (env.BB_PW_NO_LOCK === "1") return { allowed: true };
-  let profile, identity;
-  try {
-    profile = await (deps.resolveProfile ?? resolveAgentProfile)({ cwd: deps.cwd ?? process.cwd(), env, explicitProfile: deps.profile ?? null });
-    identity = await (deps.readIdentity ?? readProfileIdentity)(profile.name);
-  } catch (error) {
-    return { allowed: false, message: `bb-pw: profile verification failed (${error.message}). Run botbuddy profile setup or set BB_PW_NO_LOCK=1 for local-only work.` };
-  }
-  const coordinator = deps.coordinator ?? createProfileCoordinator({ profile, identity, fetchImpl: deps.fetch });
-  if (!profile.token || !identity || identity.tenant !== profile.tenant || coordinator.kind !== "profile") return { allowed: false, message: "bb-pw: profile identity is missing or tenant-mismatched. Run botbuddy profile setup or set BB_PW_NO_LOCK=1 for local-only work." };
-  const laneName = `playwright_lane:${host}:${lane}`;
-  // The operator's own holder identities: the tenant-bound profile agent (today's
-  // happy path) OR the arming session agent — named explicitly with --session-id /
-  // $BOTBUDDY_SESSION_ID (BOT-1467 precedent) or read from the local register_agent
-  // identity. A foreign operator's agent is in none of these, so the gate stays a
-  // real refusal (AC-3).
+  // BOT-1572: a per-session `bb_sess_` token authenticates lock verification AS
+  // the session agent — no machine profile needed. It takes precedence over the
+  // profile path; holder matching then rides on the server's owner_is_caller
+  // (plus any local session/registered agent id). The profile path stays intact
+  // for a session that has not adopted the token.
+  const sessionToken = deps.sessionToken ?? env.BOTBUDDY_SESSION_TOKEN ?? null;
   const sessionAgentId = deps.sessionId ?? env.BOTBUDDY_SESSION_ID ?? null;
   const registeredAgentId = await (deps.readSessionAgentId ?? readRegisteredAgentId)();
-  const selfAgentIds = new Set([identity.agentId, sessionAgentId, registeredAgentId].filter(Boolean));
+  let coordinator, selfAgentIds, callerId;
+  if (sessionToken) {
+    coordinator = deps.coordinator ?? createSessionTokenCoordinator({ token: sessionToken, fetchImpl: deps.fetch });
+    if (coordinator.kind === "unverified") return { allowed: false, message: "bb-pw: $BOTBUDDY_SESSION_TOKEN is malformed. Re-register the agent, or set BB_PW_NO_LOCK=1 for local-only work." };
+    selfAgentIds = new Set([sessionAgentId, registeredAgentId, coordinator.agentId].filter(Boolean));
+    callerId = coordinator.agentId ?? sessionAgentId ?? "session-token";
+  } else {
+    let profile, identity;
+    try {
+      profile = await (deps.resolveProfile ?? resolveAgentProfile)({ cwd: deps.cwd ?? process.cwd(), env, explicitProfile: deps.profile ?? null });
+      identity = await (deps.readIdentity ?? readProfileIdentity)(profile.name);
+    } catch (error) {
+      return { allowed: false, message: `bb-pw: profile verification failed (${error.message}). Run botbuddy profile setup or set BB_PW_NO_LOCK=1 for local-only work.` };
+    }
+    coordinator = deps.coordinator ?? createProfileCoordinator({ profile, identity, fetchImpl: deps.fetch });
+    if (!profile.token || !identity || identity.tenant !== profile.tenant || coordinator.kind !== "profile") return { allowed: false, message: "bb-pw: profile identity is missing or tenant-mismatched. Run botbuddy profile setup or set BB_PW_NO_LOCK=1 for local-only work." };
+    // The operator's own holder identities: the tenant-bound profile agent OR the
+    // arming session agent (--session-id / $BOTBUDDY_SESSION_ID / local register_agent
+    // id). A foreign operator's agent is in none of these, so the gate stays a real
+    // refusal (AC-3).
+    selfAgentIds = new Set([identity.agentId, sessionAgentId, registeredAgentId].filter(Boolean));
+    callerId = identity.agentId;
+  }
+  const laneName = `playwright_lane:${host}:${lane}`;
   try {
     const status = await coordinator.status({ host, slot: lane });
     // The server's alias map can collapse the locally-normalized host further
@@ -61,10 +75,10 @@ async function gate({ env, host, lane, deps }) {
     // 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 ${identity.agentId}). Acquire it via BotBuddy first, or set BB_PW_NO_LOCK=1 for local-only work.` };
+    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.` };
     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 ${identity.agentId}). Acquire it first or set BB_PW_NO_LOCK=1 for local-only work.` };
+    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.` };
   } catch (error) {
     return { allowed: false, message: `bb-pw: could not verify lane lock ${laneName} (${error.message}). Set BB_PW_NO_LOCK=1 for local-only work.` };
   }
@@ -85,7 +99,11 @@ export async function runPw(argv, deps = {}) {
 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; }
-  while (args[0] === "--profile" || args[0] === "--session-id") { const flag = args[0]; if (!args[1]) { stderr.write(`bb-pw: ${flag} needs a value\n`); return 2; } deps = flag === "--profile" ? { ...deps, profile: args[1] } : { ...deps, sessionId: args[1] }; args = args.slice(2); }
+  // BOT-1572 (AC-8): --session-token / $BOTBUDDY_SESSION_TOKEN is accepted as a
+  // session identity alongside --session-id, so a token-armed session need not
+  // pass an id. Holder matching still rides on the server's owner_is_caller and
+  // the resolved agent ids (gate()).
+  while (args[0] === "--profile" || args[0] === "--session-id" || args[0] === "--session-token") { const flag = args[0]; if (!args[1]) { stderr.write(`bb-pw: ${flag} needs a value\n`); return 2; } deps = flag === "--profile" ? { ...deps, profile: args[1] } : flag === "--session-token" ? { ...deps, sessionToken: args[1] } : { ...deps, sessionId: args[1] }; args = args.slice(2); }
   let plan; try { plan = planInvocation(args, env); } catch (error) { stderr.write(`${error.message}\n`); return 2; }
   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); }

package/src/run.mjs

@@ -24,8 +24,14 @@ const MAX_CAPTURE_BYTES = 8_192;
 // Well under AC-3's 5 s so a begin/verdict is visible within the window.
 const LANE_FLUSH_INTERVAL_MS = 2_500;
 
-export function parseRunArgs(argv) {
-  const opts = { sessionId: null, environment: null, category: "validation", kind: "other", expectedDuration: 0, timeout: DEFAULT_TIMEOUT_SECONDS, rerunReason: null, json: false };
+// BOT-1572: identical to the server's session-token shape check (bb_sess_ + 64 hex).
+const SESSION_TOKEN_RE = /^bb_sess_[0-9a-f]{64}$/;
+
+export function parseRunArgs(argv, env = process.env) {
+  // BOT-1572 (AC-8): $BOTBUDDY_SESSION_TOKEN authenticates the run and carries its
+  // session, so --session-id becomes optional (the relay derives it). $BOTBUDDY_SESSION_ID
+  // is the default when a plain id is used (parity with `botbuddy test`).
+  const opts = { sessionId: env.BOTBUDDY_SESSION_ID ?? null, sessionToken: env.BOTBUDDY_SESSION_TOKEN ?? null, environment: null, category: "validation", kind: "other", expectedDuration: 0, timeout: DEFAULT_TIMEOUT_SECONDS, rerunReason: null, json: false };
   const errors = [];
   const separator = argv.indexOf("--");
   const flags = separator === -1 ? argv : argv.slice(0, separator);
@@ -38,6 +44,7 @@ export function parseRunArgs(argv) {
     const flag = flags[i];
     switch (flag) {
       case "--session-id": opts.sessionId = value(flag, i); i++; break;
+      case "--session-token": opts.sessionToken = value(flag, i); i++; break;
       case "--environment": opts.environment = value(flag, i); i++; break;
       case "--category": opts.category = value(flag, i); i++; break;
       case "--kind": opts.kind = value(flag, i); i++; break;
@@ -56,7 +63,11 @@ export function parseRunArgs(argv) {
       default: errors.push(`unknown option: ${flag}`);
     }
   }
-  if (!opts.sessionId) errors.push("--session-id is required (from register_agent)");
+  // BOT-1572: a session token stands in for --session-id (the backend derives the
+  // session from the token). A malformed token, or a plain id AND a differing
+  // token, is a hard error.
+  if (opts.sessionToken && !SESSION_TOKEN_RE.test(opts.sessionToken)) errors.push("$BOTBUDDY_SESSION_TOKEN must match bb_sess_<64 hex>");
+  if (!opts.sessionId && !opts.sessionToken) errors.push("--session-id is required (from register_agent), or set $BOTBUDDY_SESSION_TOKEN");
   if (!opts.environment || !["local", "preview", "staging", "production", "none"].includes(opts.environment)) errors.push("--environment must be local, preview, staging, production, or none");
   if (!command.length) errors.push("a workload is required after --");
   if (!Number.isInteger(opts.expectedDuration) || opts.expectedDuration < 0) errors.push("--expected-duration must be a non-negative integer");
@@ -95,12 +106,21 @@ function workerInvocation(context) {
   return [process.execPath, [bin, "run", "--worker", context]];
 }
 
-export async function launchRun(argv, { cwd = process.cwd(), spawnImpl = spawn, call = callToolJson, childEnv = null, testRun = null } = {}) {
+export async function launchRun(argv, { cwd = process.cwd(), spawnImpl = spawn, call = null, childEnv = null, testRun = null } = {}) {
   const { opts, command, errors } = parseRunArgs(argv);
   if (errors.length) return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", errors, exit_code: EXIT.INVALID } };
+  // BOT-1572 (AC-8): when a session token is present it is the credential — pin it
+  // so register_command authenticates as the session's agent and derives session_id
+  // from the token. Tests inject `call` directly and bypass this.
+  const effectiveCall = call ?? (opts.sessionToken
+    ? (t, a) => callToolJson(t, a, { auth: { "x-agent-api-key": opts.sessionToken } })
+    : callToolJson);
   const runId = randomUUID();
-  const registration = await call("register_command", {
-    session_id: opts.sessionId, run_id: runId, tool_category: opts.category,
+  const registration = await effectiveCall("register_command", {
+    // Omit session_id entirely when only a token is present — the backend derives
+    // it. A plain id is still sent (and honoured) when supplied.
+    ...(opts.sessionId ? { session_id: opts.sessionId } : {}),
+    run_id: runId, tool_category: opts.category,
     command_hash: commandHash(command), environment_hash: environmentHash(cwd, opts.environment),
     environment: opts.environment, command_kind: opts.kind, expected_duration_seconds: opts.expectedDuration,
     rerun_reason: opts.rerunReason,
@@ -116,7 +136,9 @@ export async function launchRun(argv, { cwd = process.cwd(), spawnImpl = spawn,
     const worker = spawnImpl(file, args, { detached: true, stdio: "ignore", windowsHide: true });
     worker.unref();
   } catch (error) {
-    await call("update_command_run", { run_id: runId, run_credential: registration.data.run_credential, status: "owner_lost", invalidated_reason: `launcher_failed:${error instanceof Error ? error.message : String(error)}` });
+    // BOT-1572 (Codex P2): use effectiveCall — `call` may be null (the token-pinned
+    // default path), so calling it here would throw and strand the registered run.
+    await effectiveCall("update_command_run", { run_id: runId, run_credential: registration.data.run_credential, status: "owner_lost", invalidated_reason: `launcher_failed:${error instanceof Error ? error.message : String(error)}` });
     return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "owner_lost", run_id: runId, exit_code: EXIT.INTERNAL } };
   }
   return { exitCode: EXIT.OK, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "launched", run_id: runId, session_id: opts.sessionId, durable_owner: "detached_worker", receipt_path: receipt, reentry: "update_command_run publishes the terminal callback for this run_id", exit_code: EXIT.OK } };

package/src/test-lane.mjs

@@ -36,6 +36,9 @@ const LANE_KIND_SET = new Set(LANE_KINDS);
 export function parseTestArgs(argv, { env = process.env } = {}) {
   const opts = {
     sessionId: env.BOTBUDDY_SESSION_ID ?? null,
+    // BOT-1572 (AC-8): a session token stands in for --session-id; it flows to the
+    // sub-invoked `run`/`wait` which derive the session from it.
+    sessionToken: env.BOTBUDDY_SESSION_TOKEN ?? null,
     environment: "local",
     ticket: null, pr: null, repo: null,
     laneKind: null,
@@ -52,6 +55,7 @@ export function parseTestArgs(argv, { env = process.env } = {}) {
     const flag = flags[i];
     switch (flag) {
       case "--session-id": opts.sessionId = value(flag, i); i++; break;
+      case "--session-token": opts.sessionToken = value(flag, i); i++; break;
       case "--environment": opts.environment = value(flag, i); i++; break;
       case "--ticket": opts.ticket = value(flag, i); i++; break;
       case "--pr": { const raw = value(flag, i); i++; opts.pr = raw == null ? null : Number(raw); if (raw != null && !Number.isInteger(opts.pr)) errors.push("--pr must be an integer"); break; }
@@ -131,14 +135,24 @@ export function defaultGitInfo({ cwd = process.cwd(), ticket = null, pr = null,
 
 // The production lane launcher: run the lane through the durable `botbuddy run`
 // worker, carrying the telemetry env into its detached child.
-async function defaultLaunchLane({ command, sessionId, environment, expectedDurationSeconds, childEnv, testRun, cwd, call }) {
-  const argv = ["--session-id", sessionId, "--environment", environment, "--category", "validation", "--kind", "full_suite", "--expected-duration", String(expectedDurationSeconds ?? 0), "--", ...command];
-  const result = await launchRun(argv, { cwd, call, childEnv, testRun });
+async function defaultLaunchLane({ command, sessionId, sessionToken, environment, expectedDurationSeconds, childEnv, testRun, cwd, call }) {
+  // BOT-1572: pass --session-id only when a plain id is used; a token-only lane
+  // relies on the inherited $BOTBUDDY_SESSION_TOKEN (and an explicit --session-token
+  // so the child never falls back to a machine credential).
+  const argv = [
+    ...(sessionId ? ["--session-id", sessionId] : []),
+    ...(sessionToken ? ["--session-token", sessionToken] : []),
+    "--environment", environment, "--category", "validation", "--kind", "full_suite",
+    "--expected-duration", String(expectedDurationSeconds ?? 0), "--", ...command,
+  ];
+  const result = await launchRun(argv, { cwd, call: sessionToken ? null : call, childEnv, testRun });
   return { exitCode: result.exitCode, runId: result.receipt?.run_id ?? null };
 }
 
-function waitCommand(testRunId, sessionId) {
-  return `botbuddy wait 'test-run:id=${testRunId}' --session-id ${sessionId} --heartbeat`;
+function waitCommand(testRunId, sessionId, sessionToken) {
+  // BOT-1572: a token-armed session runs the wait with only $BOTBUDDY_SESSION_TOKEN.
+  const idFlag = sessionId && !sessionToken ? ` --session-id ${sessionId}` : "";
+  return `botbuddy wait 'test-run:id=${testRunId}'${idFlag} --heartbeat`;
 }
 
 export async function launchTestLane(argv, {
@@ -154,11 +168,20 @@ export async function launchTestLane(argv, {
     for (const e of errors) process.stderr.write(`botbuddy test: ${e}\n`);
     return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", errors }) };
   }
-  if (!opts.sessionId) {
-    process.stderr.write("botbuddy test: --session-id is required (or set $BOTBUDDY_SESSION_ID)\n");
+  if (!opts.sessionId && !opts.sessionToken) {
+    process.stderr.write("botbuddy test: --session-id is required (or set $BOTBUDDY_SESSION_ID or $BOTBUDDY_SESSION_TOKEN)\n");
     return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", errors: ["--session-id is required"] }) };
   }
 
+  // BOT-1572 (Codex P1): a token-only session has no owner/profile credential, so
+  // create_test_run / update_test_run must authenticate with the session token —
+  // otherwise both fail and the run launches with test_run_id=null, silently
+  // dropping the test-run record and case telemetry. Wrap the call so the token
+  // is pinned; an injected test `call` that ignores the 3rd arg is unaffected.
+  const apiCall = opts.sessionToken
+    ? (name, args) => call(name, args, { auth: { "x-agent-api-key": opts.sessionToken } })
+    : call;
+
   const resolved = resolveLane(laneName, { cwd });
   if (!resolved.ok) {
     if (resolved.error === "missing") process.stderr.write(`botbuddy test: no lane config — create ${resolved.path}\n`);
@@ -193,12 +216,12 @@ export async function launchTestLane(argv, {
     // BOT-1549: stamp the resolved lane kind on the run; absent ⇒ omitted (NULL).
     lane_kind: laneKind ?? undefined,
   };
-  const created = await call("create_test_run", createArgs);
+  const created = await apiCall("create_test_run", createArgs);
   const testRunId = created?.ok && !created.isError ? created.data?.id ?? null : null;
 
   if (testRunId) {
     // Step 2: attach the ticket + promote to active in one update.
-    await call("update_test_run", {
+    await apiCall("update_test_run", {
       test_run_id: testRunId,
       ticket_id: git.ticket ?? undefined,
       ticket_url: git.ticketUrl ?? undefined,
@@ -223,7 +246,7 @@ export async function launchTestLane(argv, {
     : null;
   const launch = await launchLane({
     command: [...resolved.lane.command, ...extra],
-    sessionId: opts.sessionId, environment: opts.environment,
+    sessionId: opts.sessionId, sessionToken: opts.sessionToken, environment: opts.environment,
     expectedDurationSeconds: resolved.lane.expected_duration_seconds ?? 0,
     childEnv, testRun, cwd, call, testRunId, lane: laneName, runner: resolved.lane.runner,
   });
@@ -232,7 +255,7 @@ export async function launchTestLane(argv, {
   const line = testRunId
     ? {
         outcome: "launched", test_run_id: testRunId, command_run_id: commandRunId, lane: laneName,
-        wait: waitCommand(testRunId, opts.sessionId),
+        wait: waitCommand(testRunId, opts.sessionId, opts.sessionToken),
         receipt_path: commandRunId ? receiptPath(commandRunId) : null, waits_url: WAITS_URL,
       }
     : {

package/src/wait-profile.mjs

@@ -72,7 +72,24 @@ export async function resolveAgentProfile({
 }
 
 export function withPrincipalReceipt(receipt, profile, registration = {}) {
-  if (!profile) return receipt;
+  if (!profile) {
+    // BOT-1572: a session-token wait has no profile, but the receipt must still
+    // carry principal.session_id / agent_id / tenant_id derived by the relay from
+    // the token. Only attach when the relay actually echoed a session identity.
+    if (registration.sessionId || registration.agentId || registration.sessionTenant != null) {
+      return {
+        ...receipt,
+        principal: {
+          profile: null,
+          tenant_id: registration.sessionTenant ?? null,
+          agent_id: registration.agentId ?? null,
+          session_id: registration.sessionId ?? null,
+          session_agent_id: registration.sessionAgentId ?? null,
+        },
+      };
+    }
+    return receipt;
+  }
   return {
     ...receipt,
     principal: {

package/src/wait.mjs

@@ -24,11 +24,17 @@ import { latestPublicCliCommand } from "./public-invocation.mjs";
 // implementation gets a typed, safe upgrade instruction.
 // BOT-1554: protocol 2 makes --session-id mandatory for every non-timer wait (the
 // server keeps MINIMUM_WAIT_PROTOCOL=1 so pre-2 installs are not 426'd).
-export const WAIT_PROTOCOL_VERSION = 2;
+// BOT-1572: protocol 3 — a $BOTBUDDY_SESSION_TOKEN (bb_sess_) authenticates the
+// wait on its own; no profile / --session-id / --token needed (the relay derives
+// agent, tenant, and session from the token). Falls back to protocol-2 behaviour
+// when no session token is present.
+export const WAIT_PROTOCOL_VERSION = 3;
 const CLI_UPGRADE_COMMAND = latestPublicCliCommand("wait");
 const MIN_RECEIPT_MAX_BYTES = 512;
 // BOT-1554: identical to the server's session-id shape check.
 const SESSION_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// BOT-1572: identical to the server's session-token shape check (bb_sess_ + 64 hex).
+const SESSION_TOKEN_RE = /^bb_sess_[0-9a-f]{64}$/;
 
 const HELP = `botbuddy wait — one wait command instead of a polling loop (BOT-989)
 
@@ -153,6 +159,10 @@ function parseArgv(argv) {
     // BOT-1467: attribute this wait to the arming session's agent (the id from
     // register_agent) instead of the tenant-bound profile agent. Env fallback.
     sessionId: process.env.BOTBUDDY_SESSION_ID || null,
+    // BOT-1572: the per-session token. When present it is the ONLY credential —
+    // profile, --session-id, and --token are unnecessary. Env is the norm; the
+    // flag is for tests/overrides.
+    sessionToken: process.env.BOTBUDDY_SESSION_TOKEN || null,
     help: false,
   };
   for (let i = 0; i < argv.length; i++) {
@@ -174,6 +184,7 @@ function parseArgv(argv) {
     else if (a === "--receipt-max-bytes") opts.receiptMaxBytes = Number(optionValue());
     else if (a === "--url") opts.url = optionValue();
     else if (a === "--token") opts.token = optionValue();
+    else if (a === "--session-token") opts.sessionToken = optionValue();
     else if (a === "--profile") opts.profile = optionValue();
     else if (a === "--session-id") opts.sessionId = optionValue();
     else if (a.startsWith("--")) opts.unknown = a;
@@ -186,14 +197,19 @@ function parseArgv(argv) {
 // {waitSessionId, cursorStart} on success. Profiled waits fail closed unless the
 // relay authenticates and attests their machine principal.
 async function registerWait(opts, conditions, deadlineIso) {
-  const res = await fetch(`${opts.url.replace(/\/$/, "")}/event-stream`, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${opts.token}`,
-      "x-agent-api-key": opts.token || "",
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify({
+  // BOT-1572: a session-token wait sends NO profile / expected_tenant /
+  // session_id — the relay derives all three from the token. Everything else
+  // (protocol-2 profile wait) is unchanged.
+  const registerBody = opts.useSessionToken
+    ? {
+      action: "register",
+      client_version: VERSION,
+      wait_protocol_version: WAIT_PROTOCOL_VERSION,
+      conditions,
+      deadline: deadlineIso,
+      mode: opts.mode,
+    }
+    : {
       action: "register",
       profile: opts.agentProfile.name,
       expected_tenant: opts.agentProfile.tenant,
@@ -205,7 +221,15 @@ async function registerWait(opts, conditions, deadlineIso) {
       conditions,
       deadline: deadlineIso,
       mode: opts.mode,
-    }),
+    };
+  const res = await fetch(`${opts.url.replace(/\/$/, "")}/event-stream`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${opts.token}`,
+      "x-agent-api-key": opts.token || "",
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(registerBody),
   });
   if (res.status === 429) {
     const body = await res.json().catch(() => ({}));
@@ -326,13 +350,23 @@ async function registerWait(opts, conditions, deadlineIso) {
     throw err;
   }
   const body = await res.json();
-  if (body.profile !== opts.agentProfile.name || typeof body.agent_id !== "string" || !body.agent_id) {
+  if (opts.useSessionToken) {
+    // BOT-1572: a session-token wait has no profile to attest; the relay instead
+    // returns the derived session_id + agent_id. Their absence means the relay
+    // did not honour the token as a session credential — fail closed.
+    if (typeof body.agent_id !== "string" || !body.agent_id ||
+        typeof body.session_id !== "string" || !body.session_id) {
+      const err = new Error("relay did not attest the session token");
+      err.auth = true;
+      err.errorCode = "session_token_not_enforced";
+      throw err;
+    }
+  } else if (body.profile !== opts.agentProfile.name || typeof body.agent_id !== "string" || !body.agent_id) {
     const err = new Error("relay did not attest the tenant-bound agent profile");
     err.auth = true;
     err.errorCode = "profile_not_enforced";
     throw err;
-  }
-  if (body.session_tenant !== opts.agentProfile.tenant) {
+  } else if (body.session_tenant !== opts.agentProfile.tenant) {
     const err = new Error(
       `profile expects ${opts.agentProfile.tenant} but registration resolved ${body.session_tenant ?? "no tenant"}`,
     );
@@ -655,7 +689,25 @@ export async function runWait(argv) {
   const deadlineMs = Date.now() + timeoutSec * 1000;
 
   const needsRelay = conditions.some((c) => c.type !== "timer");
-  if (needsRelay) {
+  // BOT-1572: a $BOTBUDDY_SESSION_TOKEN authenticates the wait on its own. When
+  // present it supersedes the profile + --session-id path entirely: the relay
+  // derives agent, tenant, and session from the token. --profile / --session-id
+  // are simply ignored; a conflicting explicit --token (a DIFFERENT credential)
+  // is a contradiction and is rejected.
+  if (needsRelay && opts.sessionToken) {
+    if (!SESSION_TOKEN_RE.test(opts.sessionToken)) {
+      process.stderr.write("botbuddy wait: $BOTBUDDY_SESSION_TOKEN must match bb_sess_<64 hex>\n");
+      emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_token" });
+      process.exit(EXIT.INVALID);
+    }
+    if (opts.token && opts.token !== opts.sessionToken) {
+      process.stderr.write("botbuddy wait: --token conflicts with $BOTBUDDY_SESSION_TOKEN; pass only one\n");
+      emitReceipt({ schema_version: 1, outcome: "error", error: "session_token_conflict" });
+      process.exit(EXIT.INVALID);
+    }
+    opts.useSessionToken = true;
+    opts.token = opts.sessionToken;
+  } else if (needsRelay) {
     // BOT-1554: a relay wait MUST name its arming work-graph session. Fail fast —
     // before any profile resolution or network call — so a wait can never be filed
     // under whatever credential the machine holds (the "/waits all Megan" bug). A
@@ -799,6 +851,24 @@ export async function runWait(argv) {
         process.exit(EXIT.INVALID);
       }
       if (err && err.auth) {
+        // BOT-1572: a session-token failure (revoked/expired/rotated, or the relay
+        // refusing to honour the token) is fixed by RE-REGISTERING, not by profile
+        // setup. Lead with that, and never touch the (absent) agentProfile.
+        const SESSION_TOKEN_ERRORS = new Set([
+          "session_token_revoked", "session_token_expired", "session_token_not_enforced",
+        ]);
+        if (opts.useSessionToken || SESSION_TOKEN_ERRORS.has(err.errorCode)) {
+          process.stderr.write(
+            `botbuddy wait: session token rejected (${err.errorCode || "unauthorized"}) — re-register the agent and export the new $BOTBUDDY_SESSION_TOKEN\n`,
+          );
+          emitReceipt(withPrincipalReceipt({
+            schema_version: 1,
+            outcome: "error",
+            error: err.errorCode || "unauthorized",
+            recovery: "register_agent → export BOTBUDDY_SESSION_TOKEN=<session_token>",
+          }, opts.agentProfile, { sessionTenant, agentId: registeredAgentId, sessionId: registeredSessionId }));
+          process.exit(EXIT.AUTH);
+        }
         // BOT-1554: these are all SESSION-IDENTITY failures — the supplied session id
         // (or the credential behind it) is a shared service carrier, an
         // ended/foreign session, or a wrong-tenant session. Re-running profile setup
@@ -823,7 +893,7 @@ export async function runWait(argv) {
             error: err.errorCode,
             ...(err.carrierAgentId ? { carrier_agent_id: err.carrierAgentId } : {}),
             recovery: "register_agent → export BOTBUDDY_SESSION_ID=<new session_id>",
-          }, opts.agentProfile, { sessionTenant: opts.agentProfile.tenant, agentId: null }));
+          }, opts.agentProfile, { sessionTenant: opts.agentProfile?.tenant ?? sessionTenant ?? null, agentId: null }));
           process.exit(EXIT.AUTH);
         }
         const error = typedProfileError(err.errorCode);
@@ -890,7 +960,7 @@ export async function runWait(argv) {
       emitReceipt(withPrincipalReceipt(
         { schema_version: 1, outcome: "error", error: "register_failed", detail: String(err && err.message || err) },
         opts.agentProfile,
-        { sessionTenant: opts.agentProfile.tenant, agentId: null },
+        { sessionTenant: opts.agentProfile?.tenant ?? sessionTenant ?? null, agentId: null },
       ));
       process.exit(EXIT.INTERNAL);
     }