@botbuddy/cli 1.48.0 → 1.49.0

package/package.json

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

package/src/commands.mjs

@@ -30,6 +30,7 @@ import { attestTelemetryCredential, loadTelemetryIdentity, loadTelemetryLocation
 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 { runUsage, usageStatus } from "./usage/sync.mjs";
 import { installUsageAgent, usageAgentStatus } from "./usage/launchd.mjs";
@@ -83,6 +84,8 @@ export async function run(argv, {
     case "logout": return cmdLogout();
     case "status": return cmdStatus();
     case "doctor": return cmdDoctor(args);
+    // BOT-2367: this Mac's Helper host key, whatever the status file's age.
+    case "host": return cmdHost(args);
     case "update": return cmdUpdate();
     // Agent-only commands (used by MCP agents, not humans)
     case "heartbeat": return cmdHeartbeat(args);
@@ -188,7 +191,9 @@ ${bold("AUTH")}
   logout                     Remove saved credentials
   status                     Show current auth status (local metadata + server check)
   doctor [--fix] [--print-exports] [--json]
-                             Diagnose or repair the cached agent session
+                             Diagnose or repair the cached agent session; on macOS also
+                             reports duplicate Helper workers (--fix terminates them)
+  host key [--json]          This Mac's Helper host key, whatever the status file's age
 
 ${bold("MCP CONFIG KEY")}
   mcp setup [--env <NAME>] [--tenant <slug>] [--label <l>] [--expiry-days <n>]
@@ -257,6 +262,8 @@ export async function cmdDoctor(args, {
   log = (line) => console.log(line), errorLog = (line) => console.error(line),
   doctor = doctorAgentAuth, usageReport = doctorUsageSync, bootstrapReport = doctorBootstrapState,
   publishReport = () => probeEnginePublishIp(),
+  helperWorkersReport = async () => inspectHelperWorkers(),
+  helperWorkersFix = (report) => fixHelperWorkers(report),
 } = {}) {
   const parsed = parseDoctorArgs(args);
   if (parsed.help) { log(doctorHelp()); return 0; }
@@ -271,8 +278,18 @@ export async function cmdDoctor(args, {
   const usage = await usageReport().catch(() => null);
   // BOT-1945 (AC-3): informational, like usage sync — never changes the exit code.
   const bootstrap = await bootstrapReport().catch(() => null);
+  // BOT-2367: duplicate Helper workers / stale Helper locks (macOS). Reported on
+  // every run; `--fix` SIGTERMs a duplicate launchd is not running, then
+  // re-checks. Informational: never changes doctor's exit code.
+  let helperWorkers = await helperWorkersReport().catch(() => null);
+  let helperFix = null;
+  if (parsed.fix && helperWorkers?.status === "duplicate") {
+    helperFix = await helperWorkersFix(helperWorkers).catch(() => null);
+    const recheck = await helperWorkersReport().catch(() => null);
+    helperWorkers = recheck ? { ...recheck, fix: helperFix } : { ...helperWorkers, fix: helperFix };
+  }
   if (parsed.json) {
-    log(JSON.stringify({ ...result.report, ...(usage ? { usage_sync: usage } : {}), ...(bootstrap ? { bootstrap } : {}) }));
+    log(JSON.stringify({ ...result.report, ...(usage ? { usage_sync: usage } : {}), ...(bootstrap ? { bootstrap } : {}), ...(helperWorkers ? { helper_workers: helperWorkers } : {}) }));
   } else {
     log(`binding: ${result.report.binding.status}${result.report.binding.tenant ? ` (${result.report.binding.tenant})` : ""}`);
     log(`client key: ${result.report.client_key.status}`);
@@ -288,6 +305,7 @@ export async function cmdDoctor(args, {
     if (result.report.recovery) log(`recovery: ${result.report.recovery}`);
     if (bootstrap) log(formatBootstrapLine(bootstrap));
     if (usage) log(formatUsageSyncLine(usage));
+    for (const line of formatHelperWorkersLines(helperWorkers, helperFix)) log(line);
   }
   if (result.exports) log(result.exports);
   return result.exitCode;

package/src/helper-host.mjs

@@ -0,0 +1,223 @@
+// BOT-2367 — this Mac's BotBuddy Helper host key, and the `bb doctor` Helper
+// duplicate-worker / stale-lock check.
+//
+// The Helper writes `managed-container-host-status.json` with this machine's
+// `host_key` and `checked_at` (Apple-epoch seconds; there is no `updated_at`).
+// The host key is derived from the machine's P-256 identity and is static, so
+// it never depends on the file's age: `bb host key` returns it whatever the
+// age and reports freshness separately. On 2026-10-14 a 7-minute Helper job
+// tick aged the file past Supply Guard's 300 s limit on a healthy host and SG
+// refused to name the host (exit 4); Helper 0.2.37 refreshes the file on every
+// beacon, and this command gives wrappers a resolver that cannot fail that way.
+//
+// Read-only except `fixHelperWorkers`, which only SIGTERMs a
+// `botbuddyhelper-worker` process launchd is not running, and only when the
+// launchd PID was read twice and agreed (fail-closed otherwise).
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { basename, join } from "node:path";
+
+export const HELPER_WORKER_LABEL = "com.botbuddy.helper.worker";
+export const HELPER_WORKER_BINARY = "botbuddyhelper-worker";
+/** Supply Guard's freshness limit; Helper 0.2.37 refreshes every ~20 s. */
+export const HELPER_STATUS_FRESH_SECONDS = 300;
+const APPLE_REFERENCE_EPOCH_SECONDS = 978_307_200;
+const HOST_KEY_PATTERN = /^[A-Za-z0-9._:-]+$/;
+const HELPER_LOCK_FILES = [".worker.lock", ".beacon.lock", ".metrics.lock"];
+const START_REMEDY = "start the BotBuddy Helper (open \"BotBuddy Helper.app\") so it writes this file";
+
+export function helperSupportDir(home = homedir()) {
+  return join(home, "Library", "Application Support", "BotBuddyHelper");
+}
+
+export function helperStatusPath(home = homedir()) {
+  return join(helperSupportDir(home), "managed-container-host-status.json");
+}
+
+/**
+ * `{ ok: true, host_key, checked_at, age_seconds, fresh, path }`, or
+ * `{ ok: false, code, path, message }` when the file is missing or names no
+ * well-formed host key. Freshness never decides whether the key is returned.
+ */
+export function readHelperHostKey({ home = homedir(), nowMs = Date.now(), readFile = (p) => readFileSync(p, "utf8") } = {}) {
+  const path = helperStatusPath(home);
+  let contents;
+  try {
+    contents = readFile(path);
+  } catch (error) {
+    return { ok: false, code: "HELPER_STATUS_MISSING", path, message: `could not read ${path} (${error?.code ?? "unreadable"}); ${START_REMEDY}` };
+  }
+  let status;
+  try {
+    status = JSON.parse(contents);
+  } catch {
+    status = null;
+  }
+  const hostKey = status?.host_key;
+  if (typeof hostKey !== "string" || !HOST_KEY_PATTERN.test(hostKey)) {
+    return { ok: false, code: "HELPER_STATUS_MALFORMED", path, message: `${path} names no well-formed host_key; ${START_REMEDY}` };
+  }
+  const checkedAt = status.checked_at;
+  if (!Number.isFinite(checkedAt)) {
+    return { ok: true, host_key: hostKey, checked_at: null, age_seconds: null, fresh: false, path };
+  }
+  const checkedAtMs = (checkedAt + APPLE_REFERENCE_EPOCH_SECONDS) * 1000;
+  const ageSeconds = Math.round((nowMs - checkedAtMs) / 1000);
+  return {
+    ok: true,
+    host_key: hostKey,
+    checked_at: new Date(checkedAtMs).toISOString(),
+    age_seconds: ageSeconds,
+    fresh: ageSeconds >= -60 && ageSeconds <= HELPER_STATUS_FRESH_SECONDS,
+    path,
+  };
+}
+
+const HOST_USAGE = "Usage: bb host key [--json]";
+
+export function hostHelp() {
+  return `${HOST_USAGE}
+
+Prints this Mac's managed-container host key from the BotBuddy Helper's status
+file, whatever the file's age: the key is this machine's static identity. A file
+older than ${HELPER_STATUS_FRESH_SECONDS} s still prints the key (exit 0) with a freshness warning on
+stderr. Exit 4 when the file is missing or names no host key.
+--json prints {host_key, checked_at, age_seconds, fresh, path}.`;
+}
+
+/** `bb host key [--json]` → exit code. */
+export async function cmdHost(args, {
+  log = (line) => console.log(line), errorLog = (line) => console.error(line),
+  read = () => readHelperHostKey(),
+} = {}) {
+  const [sub, ...rest] = args;
+  if (sub === "help" || sub === "--help" || sub === "-h") { log(hostHelp()); return 0; }
+  const json = rest.includes("--json");
+  const unknown = rest.filter((a) => a !== "--json");
+  if (sub !== "key" || unknown.length) { errorLog(HOST_USAGE); return 4; }
+  const r = read();
+  if (!r.ok) {
+    errorLog(`bb host key: ${r.code}: ${r.message}`);
+    return 4;
+  }
+  if (json) {
+    log(JSON.stringify({ host_key: r.host_key, checked_at: r.checked_at, age_seconds: r.age_seconds, fresh: r.fresh, path: r.path }));
+  } else {
+    log(r.host_key);
+  }
+  if (!r.fresh) {
+    const age = r.age_seconds == null ? "has no checked_at" : `is ${r.age_seconds} s old`;
+    errorLog(`bb host key: warning: the Helper status file ${age} (fresh is ≤ ${HELPER_STATUS_FRESH_SECONDS} s); the key is still this Mac's. ` +
+      `If the Helper is not running, check \`launchctl print gui/$(id -u)/${HELPER_WORKER_LABEL}\` and the worker log.`);
+  }
+  return 0;
+}
+
+// ── bb doctor: duplicate Helper workers and stale Helper locks ───────────────
+
+function defaultRun(cmd, args) {
+  const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 5000 });
+  return { status: r.error ? null : r.status, stdout: r.stdout ?? "" };
+}
+
+/** `launchctl list <label>` → pid number, null (loaded, not running), or undefined (unreadable). */
+export function parseLaunchctlListPid(result) {
+  if (!result || result.status !== 0) return undefined;
+  const m = /"PID"\s*=\s*(\d+)\s*;/.exec(result.stdout);
+  return m ? Number(m[1]) : null;
+}
+
+/** `ps -axo pid=,comm=` → the pids of `botbuddyhelper-worker` processes. */
+export function parseWorkerPids(stdout) {
+  const pids = [];
+  for (const line of String(stdout).split("\n")) {
+    const m = /^\s*(\d+)\s+(.+?)\s*$/.exec(line);
+    if (m && basename(m[2]) === HELPER_WORKER_BINARY) pids.push(Number(m[1]));
+  }
+  return pids.sort((a, b) => a - b);
+}
+
+/** `lsof -F pcn` → Helper lock files held open by a process that is not a Helper process. */
+export function parseStaleLocks(stdout) {
+  const stale = [];
+  let pid = null; let command = null;
+  for (const line of String(stdout).split("\n")) {
+    const tag = line[0]; const value = line.slice(1);
+    if (tag === "p") { pid = Number(value); command = null; }
+    else if (tag === "c") command = value;
+    else if (tag === "n") {
+      const file = basename(value);
+      if (HELPER_LOCK_FILES.includes(file) && !/^botbuddyhelper/i.test(command ?? "")) {
+        stale.push({ file, pid, command });
+      }
+    }
+  }
+  return stale;
+}
+
+/**
+ * Read-only census of Helper worker processes against launchd's own job PID.
+ * A duplicate is a `botbuddyhelper-worker` launchd is not running. The launchd
+ * PID is read before and after `ps`; if launchd's answer is unreadable or
+ * changed (a tick started mid-check), nothing is called a duplicate.
+ */
+export function inspectHelperWorkers({ run = defaultRun, home = homedir(), platformFn = platform } = {}) {
+  if (platformFn() !== "darwin") return null;
+  const before = parseLaunchctlListPid(run("launchctl", ["list", HELPER_WORKER_LABEL]));
+  const workers = parseWorkerPids(run("ps", ["-axo", "pid=,comm="]).stdout);
+  const after = parseLaunchctlListPid(run("launchctl", ["list", HELPER_WORKER_LABEL]));
+  const lockPaths = HELPER_LOCK_FILES.map((f) => join(helperSupportDir(home), f));
+  const lsof = run("lsof", ["+c", "0", "-F", "pcn", ...lockPaths]);
+  const staleLocks = parseStaleLocks(lsof.stdout);
+  const base = { launchd_pid: after ?? null, workers, duplicates: [], stale_locks: staleLocks };
+  if (before === undefined || after === undefined) {
+    return { status: "unknown", ...base, reason: `launchd job ${HELPER_WORKER_LABEL} is not readable in this session` };
+  }
+  if (before !== after) return { status: "unsettled", ...base, reason: "launchd started a worker tick during the check" };
+  const duplicates = workers.filter((pid) => pid !== after);
+  return { status: duplicates.length ? "duplicate" : "ok", ...base, duplicates };
+}
+
+function defaultIsAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (error) { return error?.code === "EPERM"; }
+}
+
+/** SIGTERM each duplicate (never launchd's worker); wait up to ~3 s for exit. */
+export async function fixHelperWorkers(report, {
+  kill = (pid, signal) => process.kill(pid, signal), isAlive = defaultIsAlive,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+} = {}) {
+  const result = { terminated: [], failed: [] };
+  if (report?.status !== "duplicate") return result;
+  for (const pid of report.duplicates) {
+    if (pid === report.launchd_pid) continue;
+    try { kill(pid, "SIGTERM"); } catch { /* already gone or not ours; checked below */ }
+  }
+  for (let i = 0; i < 30 && report.duplicates.some((pid) => isAlive(pid)); i++) await sleep(100);
+  for (const pid of report.duplicates) (isAlive(pid) ? result.failed : result.terminated).push(pid);
+  return result;
+}
+
+/** Human lines for `bb doctor`. */
+export function formatHelperWorkersLines(report, fix = null) {
+  if (!report) return [];
+  const lines = [];
+  const launchd = report.launchd_pid ? `launchd ${HELPER_WORKER_LABEL} pid ${report.launchd_pid}` : `launchd ${HELPER_WORKER_LABEL} idle between ticks`;
+  if (fix && (fix.terminated.length || fix.failed.length)) {
+    // A re-checked report (cmdDoctor attaches `fix`) already lists the survivors.
+    const running = report.fix ? report.workers.length : report.workers.length - fix.terminated.length;
+    for (const pid of fix.terminated) lines.push(`helper workers: terminated duplicate pid ${pid}; ${running} running (${launchd})`);
+    for (const pid of fix.failed) lines.push(`helper workers: could not terminate duplicate pid ${pid}; stop it with \`kill ${pid}\``);
+  } else if (report.status === "ok") {
+    lines.push(`helper workers: ${report.workers.length} running (${launchd})`);
+  } else if (report.status === "duplicate") {
+    lines.push(`helper workers: ${report.workers.length} running — duplicate pid ${report.duplicates.join(", ")} (${launchd}); fix: \`bb doctor --fix\` terminates the duplicate`);
+  } else {
+    lines.push(`helper workers: ${report.workers.length} running — ${report.reason}; not checked for duplicates${report.status === "unsettled" ? " (re-run bb doctor)" : ""}`);
+  }
+  for (const s of report.stale_locks) {
+    lines.push(`helper lock: ${s.file} is held open by pid ${s.pid} (${s.command}), not a Helper process, so the Helper cannot take it; stop pid ${s.pid}`);
+  }
+  return lines;
+}