@botbuddy/cli 1.56.0 → 1.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.56.0",
+  "version": "1.57.0",
   "description": "BotBuddy \u2014 Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/agent-session.mjs

@@ -158,7 +158,7 @@ export async function hasAgentSessionRuntime({
 /** Resolve without touching the network when an explicit source or fresh cache exists. */
 export async function resolveAgentSessionCredential({
   argv = [], env = process.env, cwd = process.cwd(), readState = readAgentState,
-  isFresh = isAgentStateFresh, selfHeal = selfHealAgentSession,
+  isFresh = isAgentStateFresh, selfHeal = selfHealAgentSession, allowSelfHeal = true,
   // BOT-1682 (Codex R13): callers that have ALREADY parsed the session id from
   // their own LEADING options (bb pw's runPwInner) pass it here, so this resolver
   // never re-scans raw argv — where a target-flag VALUE such as
@@ -190,6 +190,7 @@ export async function resolveAgentSessionCredential({
     warnLegacyResolvedToken(cached.agent_session_token, warn);
     return withIdentity({ token: cached.agent_session_token, sessionId: explicitSessionId ?? cached.session_id, agentId: cached.agent_id, source: "cache" }, cached);
   }
+  if (!allowSelfHeal) return null;
   const healed = await selfHeal({ cwd, env, sessionId: explicitSessionId });
   warnLegacyResolvedToken(healed?.token, warn);
   return healed;

package/src/commands.mjs

@@ -17,6 +17,7 @@ import { cmdManagedAllocation } from "./managed-allocation.mjs";
 import { cmdDocker } from "./docker-hygiene.mjs";
 import { cmdRun } from "./run.mjs";
 import { cmdTest } from "./test-lane.mjs";
+import { cmdEvidence } from "./evidence.mjs";
 import { runWait } from "./wait.mjs";
 import { SETUP_BLOCK } from "./setup-block.mjs";
 import { green, red, cyan, dim, bold, die } from "./utils.mjs";
@@ -31,7 +32,7 @@ import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
 import { doctorAgentAuth, doctorHelp, parseDoctorArgs, readClientKeyStrict, repairFailureRecovery } from "./agent-doctor.mjs";
 import { formatPublishIp, isLoopbackIp, probeEnginePublishIp, publishIpFix } from "./docker-publish-ip.mjs";
 import { cmdHost, fixHelperWorkers, formatHelperWorkersLines, inspectHelperWorkers } from "./helper-host.mjs";
-import { clearAgentState, selfHealAgentSession } from "./agent-session.mjs";
+import { clearAgentState, resolveAgentSessionCredential, selfHealAgentSession } from "./agent-session.mjs";
 import { readAgentState } from "./agent-state.mjs";
 import { runUsage, usageStatus } from "./usage/sync.mjs";
 import { cmdTestIngest, doctorTestIngest, formatTestIngestLine } from "./test-ingest.mjs";
@@ -112,6 +113,7 @@ export async function run(argv, {
       return code;
     }
     case "test": return cmdTest(args);
+    case "evidence": return cmdEvidence(args);
     case "test-ingest": return cmdTestIngest(args);
     case "wait": return runWait(args);
     case "pw": return runPw(args);
@@ -257,6 +259,7 @@ ${bold("BROWSER LANES")}
 
 ${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
   update                     Install the latest @botbuddy/cli in the background via npm
   help                       Show this help
   version                    Show version
@@ -931,6 +934,10 @@ export async function cmdBootstrap(args, {
   let harnessSessionId = null;
   let type = "custom";
   let codexThreadId = null;
+  // Claude Desktop injects this only for a desktop-hosted agent session. The
+  // CLI deliberately treats every other environment as absent, so terminal and
+  // cloud Claude sessions never manufacture a deep link.
+  const claudeDesktopSessionId = process.env.CLAUDE_CODE_HOST_SESSION_ID || null;
   let branch = null;
   let ticketId = null;
   let ticketUrl = null;
@@ -969,6 +976,7 @@ export async function cmdBootstrap(args, {
     type,
     harnessSessionId,
     codexThreadId,
+    claudeDesktopSessionId,
     branch,
     ticketId,
     ticketUrl,
@@ -1163,8 +1171,24 @@ export async function cmdLogout({ cwd = process.cwd(), clearState = clearAgentSt
   console.log(`${green("✓")} Logged out. Credentials removed.`);
 }
 
-function cmdHeartbeat(args) {
-  return args[0] ? callTool("heartbeat", { current_task: args[0] }) : callTool("heartbeat");
+export async function cmdHeartbeat(args, {
+  resolveSession = resolveAgentSessionCredential,
+  callTool: call = callTool,
+} = {}) {
+  // A Desktop identity belongs to the work-graph session that is currently
+  // running. Supply the cached session id with the host-provided value so the
+  // server refreshes that exact session rather than only mutable agent state.
+  const session = await resolveSession({
+    sessionId: process.env.BOTBUDDY_SESSION_ID || null,
+    allowSelfHeal: false,
+  });
+  const claudeDesktopSessionId = process.env.CLAUDE_CODE_HOST_SESSION_ID || null;
+  const heartbeat = {
+    ...(args[0] ? { current_task: args[0] } : {}),
+    ...(typeof session?.sessionId === "string" && session.sessionId ? { session_id: session.sessionId } : {}),
+    ...(claudeDesktopSessionId ? { claude_desktop_session_id: claudeDesktopSessionId } : {}),
+  };
+  return call("heartbeat", heartbeat, session?.token ? { auth: { "x-agent-api-key": session.token } } : undefined);
 }
 
 // ─── BOT-1607: `botbuddy mcp` — the tier-2 bb_mcp_ config key ────────────────

package/src/evidence.mjs

@@ -0,0 +1,85 @@
+// BOT-2341: `bb evidence publish <statement.json>` — post a local-E2E evidence
+// statement to the control plane (MCP `publish_evidence`), which stores it and
+// creates/updates the advisory `botbuddy/ready` check-run on the PR head.
+//
+// Auth prefers this worktree's agent session (the tenant the repo is bound to),
+// falling back to the owner/MCP-key ladder like every other `bb` call. Prints
+// the tool's JSON result on stdout; a refusal exits non-zero.
+
+import { readFileSync } from "node:fs";
+import { CALL_EXIT, callToolJson as defaultCallToolJson, resolveCallAuth } from "./api.mjs";
+
+export const EVIDENCE_EXIT = Object.freeze({ ...CALL_EXIT, USAGE: 2, REFUSED: 4 });
+
+const USAGE = `Usage: bb evidence publish <statement.json>
+
+Publish a local evidence statement for a PR head. BotBuddy stores it and posts
+the advisory botbuddy/ready check-run. The statement is a JSON object with:
+  repo, pr, headSha, mainSha, base, fingerprint, requirement, runs[],
+  verdict ("pass" | "fail"), fixCommand
+
+Exit codes: 0 published · 2 usage · 3 auth · 4 refused · 5 unreachable`;
+
+export async function cmdEvidence(args, {
+  resolveAuth = resolveCallAuth,
+  callToolJson = defaultCallToolJson,
+  log = (line) => console.log(line),
+  errorLog = (line) => console.error(line),
+} = {}) {
+  const [sub, file, ...rest] = args;
+  if (sub === undefined || sub === "help" || sub === "--help" || sub === "-h") {
+    log(USAGE);
+    return sub === undefined ? EVIDENCE_EXIT.USAGE : EVIDENCE_EXIT.OK;
+  }
+  if (sub !== "publish") {
+    errorLog(`Unknown evidence subcommand: ${sub}\n\n${USAGE}`);
+    return EVIDENCE_EXIT.USAGE;
+  }
+  if (!file || rest.length > 0) {
+    errorLog(USAGE);
+    return EVIDENCE_EXIT.USAGE;
+  }
+
+  let statement;
+  try {
+    statement = JSON.parse(readFileSync(file, "utf8"));
+  } catch (error) {
+    errorLog(`✗ Could not read ${file} as JSON: ${error?.message ?? error}`);
+    return EVIDENCE_EXIT.USAGE;
+  }
+
+  const resolved = await resolveAuth({ toolName: "publish_evidence", preferSession: true });
+  if (resolved?.error || !resolved?.auth) {
+    log(JSON.stringify(resolved?.error ?? { ok: false, auth: true, error: "not_authenticated" }, null, 2));
+    errorLog("✗ Not authenticated — run `bb doctor --fix` in this worktree.");
+    return EVIDENCE_EXIT.AUTH;
+  }
+
+  const res = await callToolJson("publish_evidence", { statement }, { auth: resolved.auth });
+  if (!res.ok) {
+    log(JSON.stringify(res, null, 2));
+    if (res.auth) {
+      errorLog(`✗ BotBuddy rejected the credential (${res.error_code ?? res.code ?? res.error}).`);
+      return EVIDENCE_EXIT.AUTH;
+    }
+    if (res.status === null || String(res.error ?? "").startsWith("transport")) {
+      errorLog(`✗ BotBuddy unreachable: ${res.error}`);
+      return EVIDENCE_EXIT.TRANSPORT;
+    }
+    errorLog(`✗ publish_evidence failed: ${res.error}`);
+    return EVIDENCE_EXIT.ERROR;
+  }
+
+  log(JSON.stringify(res.data, null, 2));
+  if (res.isError || res.data?.ok === false) {
+    errorLog(`✗ ${res.data?.error ?? "publish_evidence refused"}: ${res.data?.message ?? ""}`.trimEnd());
+    return EVIDENCE_EXIT.REFUSED;
+  }
+  // Codex #1169 R4: success means a receipt came back — an outage body that
+  // normalises to an empty result is never "published".
+  if (res.data?.ok !== true || typeof res.data?.receipt_id !== "string") {
+    errorLog("✗ BotBuddy returned no receipt — nothing is known to be published; retry.");
+    return EVIDENCE_EXIT.ERROR;
+  }
+  return EVIDENCE_EXIT.OK;
+}

package/src/session-bootstrap.mjs

@@ -130,6 +130,7 @@ async function recordOrphanAndFail({ session, cwd, retirementError, primaryError
 export async function heartbeatHarnessSession({
   session,
   codexThreadId = null,
+  claudeDesktopSessionId = null,
   model = null,
   call = callToolJson,
   cwd = process.cwd(),
@@ -141,6 +142,7 @@ export async function heartbeatHarnessSession({
   const response = await call("heartbeat", {
     session_id: session.session_id,
     ...(codexThreadId ? { codex_thread_id: codexThreadId } : {}),
+    ...(claudeDesktopSessionId ? { claude_desktop_session_id: claudeDesktopSessionId } : {}),
     ...(model ? { model } : {}),
   }, { auth: { "x-agent-api-key": session.session_token } });
   if (!response?.ok || response.isError) {
@@ -212,6 +214,7 @@ export async function bootstrapHarnessSession({
   type = "codex",
   harnessSessionId,
   codexThreadId = null,
+  claudeDesktopSessionId = null,
   cwd = process.cwd(),
   branch = null,
   ticketId = null,
@@ -273,6 +276,7 @@ export async function bootstrapHarnessSession({
       ...(prNumber != null ? { pr_number: prNumber } : {}),
       ...(prUrl ? { pr_url: prUrl } : {}),
       ...(codexThreadId ? { codex_thread_id: codexThreadId } : {}),
+      ...(claudeDesktopSessionId ? { claude_desktop_session_id: claudeDesktopSessionId } : {}),
       ...(model ? { model } : {}),
       ...(effort ? { effort } : {}),
       harness,