@botbuddy/cli 1.55.0 → 1.56.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.55.0",
+  "version": "1.56.1",
   "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

@@ -31,7 +31,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";
@@ -931,6 +931,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 +973,7 @@ export async function cmdBootstrap(args, {
     type,
     harnessSessionId,
     codexThreadId,
+    claudeDesktopSessionId,
     branch,
     ticketId,
     ticketUrl,
@@ -1163,8 +1168,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/fixtures/bot-2403-docker-desktop-mounts-2026-10-16.json

@@ -0,0 +1,29 @@
+{
+  "ticket": "BOT-2403",
+  "captured_at": "2026-10-16T20:43:49Z",
+  "provenance": "Actual Docker Desktop container inspect .Mounts and context inspect on owned MacBook lease 0c68ff71-3a1a-4d3c-b7d2-d06617609772; requester and container destination both contained43 entries; actual MCP readyz HTTP200/version2.97.1. No environment/credentials captured.",
+  "project_id": "bbbot240305b549",
+  "host_functions_dir": "/Users/jono/Developer/botbuddy-web/.claude/worktrees/bot-2402/.botbuddy/stacks/bbbot240305b549/supabase/functions",
+  "docker_context": "desktop-linux",
+  "docker_endpoint": "unix:///Users/jono/.docker/run/docker.sock",
+  "mounts": [
+    {
+      "Type": "volume",
+      "Name": "supabase_edge_runtime_bbbot240305b549",
+      "Source": "/var/lib/docker/volumes/supabase_edge_runtime_bbbot240305b549/_data",
+      "Destination": "/root/.cache/deno",
+      "Driver": "local",
+      "Mode": "rw",
+      "RW": true,
+      "Propagation": ""
+    },
+    {
+      "Type": "bind",
+      "Source": "/host_mnt/Users/jono/Developer/botbuddy-web/.claude/worktrees/bot-2402/.botbuddy/stacks/bbbot240305b549/supabase/functions",
+      "Destination": "/Users/jono/Developer/botbuddy-web/.claude/worktrees/bot-2402/.botbuddy/stacks/bbbot240305b549/supabase/functions",
+      "Mode": "ro",
+      "RW": false,
+      "Propagation": "rprivate"
+    }
+  ]
+}

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,

package/src/stack-mount-health.mjs

@@ -38,20 +38,41 @@ export function runDocker(args, { timeoutMs = MOUNT_CHECK_TIMEOUT_MS } = {}) {
 }
 
 /** The container path the functions directory is mounted at, or null (from `docker inspect … .Mounts`). */
-export function functionsMountDestination(mountsJson, hostFunctionsDir) {
+export function functionsMountDestination(mountsJson, hostFunctionsDir, { dockerDesktop = false } = {}) {
   let mounts;
   try { mounts = JSON.parse(String(mountsJson ?? "").trim()); } catch { return null; }
   if (!Array.isArray(mounts)) return null;
-  const mount = mounts.find((m) => m?.Type === "bind" && m?.Source === hostFunctionsDir);
+  const mount = mounts.find((m) => m?.Type === "bind" && (
+    m?.Source === hostFunctionsDir || (
+      dockerDesktop === true && hostFunctionsDir.startsWith("/Users/") &&
+      m?.Source === `/host_mnt${hostFunctionsDir}`
+    )
+  ));
   return typeof mount?.Destination === "string" && mount.Destination ? mount.Destination : null;
 }
 
+// Docker Desktop exposes a macOS bind through its VM's /host_mnt alias.
+// Authorize that alias only for the selected engine, never an arbitrary remote
+// daemon or another VM. Explicit context selection wins over endpoint metadata,
+// exactly as dockerSelectorArgs does. A failed probe keeps the gate closed.
+async function isSelectedDockerDesktop(target, run, platform) {
+  if (platform !== "darwin") return false;
+  const context = typeof target?.context === "string" && target.context ? target.context : null;
+  let endpoint = context ? null : target?.resolved_endpoint ?? target?.endpoint;
+  if (!endpoint) {
+    const result = await run(["context", "inspect", ...(context ? [context] : []), "--format", "{{.Endpoints.docker.Host}}"]);
+    if (result.code !== 0 || result.timedOut) return false;
+    endpoint = String(result.stdout ?? "").trim();
+  }
+  return typeof endpoint === "string" && /^unix:\/\/\/Users\/[^/]+\/\.docker\/run\/docker\.sock$/.test(endpoint);
+}
+
 /**
  * Check (and once repair) the functions mount of a re-adopted idle lease.
  * `lease` is the re-adoption answer: `{ execution_mode, connection: { project_id, botbuddy_docker_target? } }`.
  * Returns `{ ok: true, skipped? , restarted? }` or `{ ok: false, restarted, reason }`. Never throws.
  */
-export async function checkReadoptedStackMounts(lease, stackDir, { run = runDocker, listHost = (dir) => readdirSync(dir), log = () => {} } = {}) {
+export async function checkReadoptedStackMounts(lease, stackDir, { run = runDocker, listHost = (dir) => readdirSync(dir), log = () => {}, platform = process.platform } = {}) {
   if (!CO_LOCATED_MODES.has(lease?.execution_mode)) return { ok: true, skipped: "remote" };
   const projectId = lease?.connection?.project_id;
   if (typeof projectId !== "string" || !PROJECT_ID_RE.test(projectId)) return { ok: true, skipped: "no_project_id" };
@@ -72,7 +93,13 @@ export async function checkReadoptedStackMounts(lease, stackDir, { run = runDock
     if (!inspect.timedOut && /No such (container|object)/i.test(inspect.stderr ?? "")) return { ok: true, skipped: "no_edge_runtime" };
     return { ok: false, restarted: false, reason: `could not inspect ${container} (exit ${inspect.code}${inspect.timedOut ? ", timed out" : ""})` };
   }
-  const destination = functionsMountDestination(inspect.stdout, hostFunctions);
+  let destination = functionsMountDestination(inspect.stdout, hostFunctions);
+  if (!destination) {
+    const desktopDestination = functionsMountDestination(inspect.stdout, hostFunctions, { dockerDesktop: true });
+    if (desktopDestination && await isSelectedDockerDesktop(lease.connection.botbuddy_docker_target, run, platform)) {
+      destination = desktopDestination;
+    }
+  }
   if (!destination) return { ok: false, restarted: false, reason: `${container} does not bind-mount ${hostFunctions}` };
 
   const mountedEntries = async () => {