@botbuddy/cli 1.21.0 → 1.22.0

package/package.json

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

package/src/stack.mjs

@@ -31,6 +31,7 @@ import { callToolJson } from "./api.mjs";
 import { SERVER_URL, getConfig } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
 import { runDockerCommand, runDockerWorkflow } from "./docker-hygiene.mjs";
+import { machineUuid } from "./machine-id.mjs";
 import { bold, dim, yellow } from "./utils.mjs";
 
 export const STACK_SCHEMA_VERSION = 1;
@@ -667,6 +668,7 @@ export async function cmdUp(opts, {
   localProvisionFn = localProvision,
   waitFn = waitForLease,
   emitResult = emit,
+  machineUuidFn = machineUuid,
 } = {}) {
   let slot;
   try { slot = deriveSlot(opts); } catch (e) {
@@ -696,6 +698,13 @@ export async function cmdUp(opts, {
   const auth = await authProvider();
   if (!auth) return emitResult(buildReceipt({ command: "up", outcome: "error", error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
 
+  // BOT-1585: co-location dispatches the lease to the Helper enrolled for THIS
+  // physical machine (hardware id), since a hostname is not machine-unique. The
+  // server requires it; fail fast with an actionable message if it can't be read.
+  const hardwareUuid = machineUuidFn();
+  if (!hardwareUuid) {
+    return emitResult(buildReceipt({ command: "up", outcome: "error", code: "MACHINE_UUID_REQUIRED", error: "could not determine this machine's hardware id (needed to dispatch the stack lease to the right machine)" }), opts, EXIT.BACKEND);
+  }
   const req = await callTool("request_stack_lease", {
     slot, host_key: opts.host || undefined, repo: opts.repo || undefined,
     ticket_id: opts.ticket || undefined, ticket_url: opts.ticketUrl || undefined,
@@ -703,6 +712,7 @@ export async function cmdUp(opts, {
     purpose: opts.purpose || undefined, idle_ttl_secs: opts.idleTtl ?? undefined,
     stack_path: execution.stackPath,
     worktree_root: execution.worktreeRoot,
+    machine_uuid: hardwareUuid,
   });
   if (!req.ok) {
     return req.auth
@@ -1046,6 +1056,7 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
     release: (leaseId, signal) => callToolJson("release_stack_lease", { lease_id: leaseId, disposition: "destroy" }, { signal }),
   };
   const auth = adapters.auth ?? await stackAuthHeader();
+  const machineUuidFn = adapters.machineUuidFn ?? machineUuid;
   const wait = adapters.wait ?? ((leaseId, done, failed, options) => waitForLease(leaseId, done, failed, options));
   // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- validated executable + argv only; shell is never used.
   const startChild = adapters.startChild ?? ((argv, env, cwd) => spawn(argv[0], argv.slice(1), { cwd, env, stdio: "inherit", detached: true }));
@@ -1122,6 +1133,13 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
 
   try {
     if (!auth) return { exitCode: EXIT.AUTH, outcome: "error", error: "not authenticated — run botbuddy profile setup botbuddy-dev" };
+    // BOT-1585: request_stack_lease requires this machine's hardware id so the lease
+    // dispatches to the machine the worktree was registered on. `stack run` builds its
+    // own payload (separate from `cmdUp`), so it must send it too.
+    const hardwareUuid = machineUuidFn();
+    if (!hardwareUuid) {
+      return { exitCode: EXIT.BACKEND, outcome: "error", error: "could not determine this machine's hardware id (needed to dispatch the stack lease to the right machine)" };
+    }
     const slot = deriveSlot(opts);
     const execution = resolveStackPath(process.cwd(), opts.stackPath);
     const request = await api.request({
@@ -1129,6 +1147,7 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
       ticket_url: opts.ticketUrl || undefined, pr_id: opts.prId || undefined, pr_url: opts.prUrl || undefined,
       purpose: opts.purpose || "stack run", idle_ttl_secs: opts.idleTtl ?? undefined,
       stack_path: execution.stackPath, worktree_root: execution.worktreeRoot,
+      machine_uuid: hardwareUuid,
     });
     if (!request?.ok) return { exitCode: request?.auth ? EXIT.AUTH : EXIT.BACKEND, outcome: "error", error: request?.error || "lease request failed" };
     if (!request.data?.success) return { exitCode: EXIT.BACKEND, outcome: "error", error: request.data?.message || request.data?.code || "lease request refused" };

package/src/wait-profile.mjs

@@ -20,6 +20,19 @@ export function getAgentProfile(name) {
   return PROFILES[name] ?? null;
 }
 
+// BOT-1593: when no profile is named (no --profile, no .botbuddy-agent.json) but
+// EXACTLY ONE supported profile's credential env var is populated, that slot is the
+// unambiguous profile. Used only by best-effort setup-error telemetry to attribute a
+// `profile_required` failure that still has a usable env bearer — never for the wait
+// itself. Returns the profile name, or null when zero or more than one slot is set
+// (ambiguous → no attribution). Reads env only; never touches the Keychain.
+export function findEnvProfile(env = process.env) {
+  const populated = Object.entries(PROFILES).filter(
+    ([, { tokenEnv }]) => typeof env[tokenEnv] === "string" && env[tokenEnv].length > 0,
+  );
+  return populated.length === 1 ? populated[0][0] : null;
+}
+
 export async function findProfileName(cwd) {
   let dir = cwd;
   const root = parse(dir).root;

package/src/wait.mjs

@@ -14,7 +14,7 @@
 // Run     botbuddy wait --help for the condition grammar.
 
 import { EXIT, parseConditions, parseSseFrames, runWaitLoop, normalizeSince, truncateReceipt, formatPrReviewSnapshotWarnings } from "./wait-core.mjs";
-import { resolveAgentProfile, withPrincipalReceipt, PROFILE_FILE } from "./wait-profile.mjs";
+import { resolveAgentProfile, getAgentProfile, findProfileName, findEnvProfile, withPrincipalReceipt, PROFILE_FILE } from "./wait-profile.mjs";
 import { VERSION } from "./version.mjs";
 import { fileURLToPath } from "node:url";
 import { latestPublicCliCommand } from "./public-invocation.mjs";
@@ -701,6 +701,131 @@ function profileCredentialRecovery(profile) {
   return `${profileRecovery(profile)} (stores $${profile.tokenEnv} in the macOS Keychain; on a non-Keychain host export $${profile.tokenEnv} directly); ${HUMAN_PAT_NOTE}`;
 }
 
+// BOT-1593: emit ONE secret-free sensor event per setup/auth/parameter failure,
+// so the maintainer can see which onboarding gap agents hit most (and whether the
+// BOT-1590 recovery copy is reducing repeats). Best-effort AND time-bounded — the
+// same stance as docker-hygiene's reportReliability: the receipt has already been
+// written to stdout by the time this runs, so a slow/failing POST must never delay
+// the agent's wake or change the exit path. A 2 s AbortController caps the fetch;
+// timeout / network error / non-2xx are all a silent drop (we never read the body).
+//
+// Never posts without a usable bearer, and never on the session-token path: the
+// ingest endpoint authenticates only allowed_users PATs or agent keys
+// (edgeAuth.ts) — a bb_sess_ session token 401s, so we don't spend the round-trip.
+// The event carries NO secret by construction: no token (only the bearer header,
+// never the body), no session id, no condition params/values, no hostnames/paths —
+// only error code, exit code, condition TYPES, auth path, profile name, cli version.
+const SENSOR_TELEMETRY_TIMEOUT_MS = 2000;
+
+async function reportSetupError(opts, { error, exitCode, conditions }) {
+  // Never on the session-token path. A bb_agent_/bb_sess_ SESSION token cannot
+  // authenticate at sensor-ingest (edgeAuth resolves only PATs / agent keys), so it
+  // would only 401. Discriminate by the credential's SOURCE, not its shape: a
+  // session token arrives only via $BOTBUDDY_AGENT_KEY / --session-token
+  // (opts.sessionToken), whereas a resolved PROFILE credential may legitimately be a
+  // legacy bb_agent_ CARRIER key that ingest CAN authenticate — the two share a shape
+  // (BOT-1582), so a shape check would wrongly drop the carrier case (Codex P1).
+  if (opts.sessionToken) return;
+
+  // Time-box the WHOLE operation — the implicit-profile file lookup AND the fetch —
+  // against one 2 s abort, the reportReliability idiom. findProfileName walks up the
+  // directory tree with async readFile; on a slow/unresponsive network or FUSE mount
+  // that read can hang, and it runs on fail-fast paths right before process.exit, so
+  // starting the timer FIRST and racing the whole worker keeps a nominally fail-fast
+  // error inside the advertised bound (Codex P2). On expiry the race resolves and we
+  // return; the orphaned lookup is reaped by the imminent process.exit.
+  const ac = new AbortController();
+  let timer;
+  const TIMED_OUT = Symbol("sensor-telemetry-timeout");
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => { ac.abort(); resolve(TIMED_OUT); }, SENSOR_TELEMETRY_TIMEOUT_MS);
+  });
+  try {
+    await Promise.race([sendSetupErrorEvent(opts, { error, exitCode, conditions }, ac.signal), timeout]);
+  } catch {
+    // Best-effort: an AbortError (2 s timeout) or any transport/lookup error drops.
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function sendSetupErrorEvent(opts, { error, exitCode, conditions }, signal) {
+  // Resolve a bearer WITHOUT ever touching the Keychain. This telemetry is
+  // best-effort and runs on fail-fast paths right before process.exit; a Keychain
+  // read (readProfileCredential → `security find-generic-password`) can block/prompt
+  // on a locked or non--A item AND takes no abort signal, so it would leave an
+  // orphaned `security` child or an auth dialog behind after the wait exits (Codex
+  // P2). So only ever REUSE a token the main flow already resolved (opts.token) or
+  // read the profile's env var directly — never a fresh Keychain lookup.
+  //
+  // Discover the caller's profile — flag or .botbuddy-agent.json — INDEPENDENTLY of
+  // whether --token was supplied, so profile/tenant are attached for attribution and
+  // dual-member disambiguation even on the documented --token override (without it a
+  // multi-tenant bearer is rejected tenant_ambiguous and the event is lost) (Codex P2).
+  // The env-slot inference (findEnvProfile) applies ONLY when there is no explicit
+  // token — inferring a tenant for an explicit --token bearer could attach one it is
+  // not a member of (→ tenant_forbidden drop).
+  let profileName = opts.agentProfile?.name ?? opts.profile ?? null;
+  if (!profileName) {
+    try {
+      profileName = await findProfileName(process.cwd());
+    } catch {
+      profileName = null; // a malformed .botbuddy-agent.json → no profile
+    }
+    if (!profileName && !opts.token) profileName = findEnvProfile(process.env);
+  }
+  // Only a KNOWN profile contributes a name/tenant/env-var — an unknown/oversized/
+  // sensitive raw --profile value (which the token path never validates) must not
+  // ride the secret-free event, matching the wait path's getAgentProfile rejection
+  // (Codex P2).
+  const known = profileName ? getAgentProfile(profileName) : null;
+  let token = opts.token;
+  if (!token && known) token = process.env[known.tokenEnv] || null;
+  // The only unusable bearer is none at all. A credential the RELAY just rejected
+  // (revoked/unauthorized) will 401 at ingest too and drop silently — best-effort, by
+  // design; a valid-key failure (session_id_required, wait_actor_required, wrong-tenant)
+  // authenticates and records (Codex P1: this is an accepted limitation, see docs).
+  if (!token) return;
+  // "profile" auth path whenever a profile was discovered (flag/file/env slot), even
+  // with a --token override; "explicit_token" only for a bare --token, no profile.
+  const explicit = !!opts.token && !profileName;
+  const tenant = opts.agentProfile?.tenant ?? known?.tenant ?? null;
+  const safeProfile = known ? profileName : null;
+  // Omit the explicit tenant for a wrong-tenant credential: the profile's expected
+  // tenant is NOT one the bearer belongs to, and sensor-ingest's resolveWriteTenant
+  // rejects an unauthorized explicit tenant (tenant_forbidden) → the event would drop.
+  // Without it the server resolves the bearer's ACTUAL tenant and the row records
+  // there instead (Codex P1). Every other error's tenant equals the credential's own.
+  const includeTenant = tenant && error !== "profile_credential_wrong_tenant";
+  const conditionTypes = Array.isArray(conditions)
+    ? [...new Set(conditions.map((c) => c.type))].sort()
+    : [];
+  const event = {
+    ...(includeTenant ? { tenant } : {}),
+    source: "bb-wait",
+    kind: "wait_setup_error",
+    dedupe_key: `bb-wait:${error}:${crypto.randomUUID()}`,
+    occurred_at: new Date().toISOString(),
+    payload: {
+      error,
+      exit_code: exitCode,
+      condition_types: conditionTypes,
+      auth_path: explicit ? "explicit_token" : "profile",
+      profile: safeProfile,
+      cli_version: VERSION,
+    },
+  };
+  await fetch(`${opts.url.replace(/\/$/, "")}/sensor-ingest`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(event),
+    signal,
+  });
+}
+
 export async function runWait(argv) {
   const opts = parseArgv(argv);
   const emitReceipt = (receipt, options = {}) => emit(receipt, {
@@ -727,6 +852,9 @@ export async function runWait(argv) {
     for (const e of errors) process.stderr.write(`bb-wait: invalid condition '${e.spec}': ${e.message}\n`);
     process.stderr.write(`bb-wait: ${RECOVERY.conditions}\n`);
     emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_conditions", errors, recovery: RECOVERY.conditions });
+    // BOT-1593: condition_types is [] on a grammar failure (the parsed set is
+    // partial/empty and is caller data regardless).
+    await reportSetupError(opts, { error: "invalid_conditions", exitCode: EXIT.INVALID, conditions: [] });
     process.exit(EXIT.INVALID);
   }
 
@@ -753,11 +881,13 @@ export async function runWait(argv) {
     if (!SESSION_TOKEN_RE.test(opts.sessionToken)) {
       process.stderr.write(`botbuddy wait: $BOTBUDDY_AGENT_KEY must match bb_agent_<64 hex>; ${RECOVERY.sessionToken}\n`);
       emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_token", recovery: RECOVERY.sessionToken });
+      await reportSetupError(opts, { error: "invalid_session_token", exitCode: EXIT.INVALID, conditions });
       process.exit(EXIT.INVALID);
     }
     if (opts.token && opts.token !== opts.sessionToken) {
       process.stderr.write(`botbuddy wait: --token conflicts with $BOTBUDDY_AGENT_KEY; ${RECOVERY.sessionTokenConflict}\n`);
       emitReceipt({ schema_version: 1, outcome: "error", error: "session_token_conflict", recovery: RECOVERY.sessionTokenConflict });
+      await reportSetupError(opts, { error: "session_token_conflict", exitCode: EXIT.INVALID, conditions });
       process.exit(EXIT.INVALID);
     }
     opts.useSessionToken = true;
@@ -777,11 +907,13 @@ export async function runWait(argv) {
         error: "session_id_required",
         recovery: RECOVERY.sessionId,
       });
+      await reportSetupError(opts, { error: "session_id_required", exitCode: EXIT.INVALID, conditions });
       process.exit(EXIT.INVALID);
     }
     if (!SESSION_UUID.test(opts.sessionId)) {
       process.stderr.write(`botbuddy wait: --session-id must be a uuid (got '${opts.sessionId}'); ${RECOVERY.sessionId}\n`);
       emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_agent", detail: "session_id must be a uuid", recovery: RECOVERY.sessionId });
+      await reportSetupError(opts, { error: "invalid_session_agent", exitCode: EXIT.INVALID, conditions });
       process.exit(EXIT.INVALID);
     }
     try {
@@ -794,6 +926,7 @@ export async function runWait(argv) {
       const recovery = profileResolutionRecovery(code);
       process.stderr.write(`bb-wait: ${err.message}; ${recovery}\n`);
       emitReceipt({ schema_version: 1, outcome: "error", error: code, recovery });
+      await reportSetupError(opts, { error: code, exitCode: EXIT.INVALID, conditions });
       process.exit(EXIT.INVALID);
     }
     opts.token = opts.agentProfile.token;
@@ -802,6 +935,10 @@ export async function runWait(argv) {
         `botbuddy wait: profile '${opts.agentProfile.name}' has no tenant-bound agent credential; run ${profileCredentialRecovery(opts.agentProfile)}\n`,
       );
       emitReceipt(profileErrorReceipt(opts.agentProfile, "profile_required"));
+      // No credential resolved (opts.token is null here), so reportSetupError has
+      // no bearer to authenticate with and self-skips — call it for allowlist
+      // symmetry; it is a no-op until a token exists.
+      await reportSetupError(opts, { error: "profile_required", exitCode: EXIT.AUTH, conditions });
       process.exit(EXIT.AUTH);
     }
   }
@@ -924,6 +1061,9 @@ export async function runWait(argv) {
             error: err.errorCode || "unauthorized",
             recovery: "register_agent → export BOTBUDDY_AGENT_KEY=<session_token>",
           }, opts.agentProfile, { sessionTenant, agentId: registeredAgentId, sessionId: registeredSessionId }));
+          // Session-token path → reportSetupError self-skips (a bb_sess_ bearer
+          // ingest cannot authenticate); called for allowlist symmetry.
+          await reportSetupError(opts, { error: err.errorCode || "unauthorized", exitCode: EXIT.AUTH, conditions });
           process.exit(EXIT.AUTH);
         }
         // BOT-1554: these are all SESSION-IDENTITY failures — the supplied session id
@@ -951,11 +1091,13 @@ export async function runWait(argv) {
             ...(err.carrierAgentId ? { carrier_agent_id: err.carrierAgentId } : {}),
             recovery: "register_agent → export BOTBUDDY_SESSION_ID=<new session_id>",
           }, opts.agentProfile, { sessionTenant: opts.agentProfile?.tenant ?? sessionTenant ?? null, agentId: null }));
+          await reportSetupError(opts, { error: err.errorCode, exitCode: EXIT.AUTH, conditions });
           process.exit(EXIT.AUTH);
         }
         const error = typedProfileError(err.errorCode);
         process.stderr.write(`botbuddy wait: profile authentication failed (${error}); run ${profileCredentialRecovery(opts.agentProfile)}\n`);
         emitReceipt(profileErrorReceipt(opts.agentProfile, error));
+        await reportSetupError(opts, { error, exitCode: EXIT.AUTH, conditions });
         process.exit(EXIT.AUTH);
       }
       if (err && err.cap) {