@botbuddy/cli 1.16.0 → 1.17.0

package/package.json

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

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);
     }