@botbuddy/cli 1.25.0 → 1.27.0

package/src/run.mjs

@@ -6,15 +6,19 @@
 // allowed to call update_command_run.  A bb-wait is therefore a notification
 // mechanism, never the owner of a child process.
 
-import { createHash, randomUUID } from "crypto";
-import { mkdir, readFile, writeFile, chmod, unlink, stat, rename } from "fs/promises";
-import { dirname, join } from "path";
-import { homedir } from "os";
-import { spawn } from "child_process";
-import { fileURLToPath } from "url";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile, chmod, unlink, stat, rename } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import { callToolJson } from "./api.mjs";
 import { parseLaneEvents, laneCaseCounts, flushLaneCases, buildLaneSummary, laneSummaryFilename } from "./test-lane-events.mjs";
 import { AGENT_KEY_RE, readAgentKeyEnv } from "./agent-key.mjs";
+import { createTelemetryOutbox } from "./telemetry-outbox.mjs";
+import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
+import { attestTelemetryCredential, loadTelemetryIdentity } from "./telemetry-config.mjs";
+import { VERSION } from "./version.mjs";
 
 export const RUN_SCHEMA_VERSION = 1;
 export const EXIT = Object.freeze({ OK: 0, INVALID: 4, BACKEND: 5, INTERNAL: 7 });
@@ -24,6 +28,7 @@ const MAX_CAPTURE_BYTES = 8_192;
 // BOT-1510: how often the worker flushes lane case verdicts to the backend.
 // Well under AC-3's 5 s so a begin/verdict is visible within the window.
 const LANE_FLUSH_INTERVAL_MS = 2_500;
+const FOREGROUND_KINDS = new Set(["test", "wait", "browser", "ci", "hook", "stack"]);
 
 // BOT-1582: the server's session-token shape (bb_agent_ + 64 hex) plus the
 // BOT-1572 bb_sess_ legacy alias, both accepted for one release.
@@ -34,7 +39,7 @@ export function parseRunArgs(argv, env = process.env) {
   // session, so --session-id becomes optional (the relay derives it). The old
   // $BOTBUDDY_SESSION_TOKEN is still accepted for one release. $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: readAgentKeyEnv(env), environment: null, category: "validation", kind: "other", expectedDuration: 0, timeout: DEFAULT_TIMEOUT_SECONDS, rerunReason: null, json: false };
+  const opts = { sessionId: env.BOTBUDDY_SESSION_ID ?? null, sessionToken: readAgentKeyEnv(env), environment: null, category: "validation", kind: "other", expectedDuration: 0, timeout: DEFAULT_TIMEOUT_SECONDS, rerunReason: null, foreground: false, json: false };
   const errors = [];
   const separator = argv.indexOf("--");
   const flags = separator === -1 ? argv : argv.slice(0, separator);
@@ -62,6 +67,7 @@ export function parseRunArgs(argv, env = process.env) {
         } catch (error) { errors.push(`--rerun-reason must be a JSON object (${error instanceof Error ? error.message : String(error)})`); }
         break;
       }
+      case "--foreground": opts.foreground = true; break;
       case "--json": opts.json = true; break;
       default: errors.push(`unknown option: ${flag}`);
     }
@@ -70,7 +76,8 @@ export function parseRunArgs(argv, env = process.env) {
   // 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_AGENT_KEY must match bb_agent_<64 hex>");
-  if (!opts.sessionId && !opts.sessionToken) errors.push("--session-id is required (from register_agent), or set $BOTBUDDY_AGENT_KEY");
+  if (!opts.foreground && !opts.sessionId && !opts.sessionToken) errors.push("--session-id is required (from register_agent), or set $BOTBUDDY_AGENT_KEY");
+  if (opts.foreground && !FOREGROUND_KINDS.has(opts.kind)) errors.push("--kind must be test, wait, browser, ci, hook, or stack with --foreground");
   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");
@@ -78,6 +85,118 @@ export function parseRunArgs(argv, env = process.env) {
   return { opts, command, errors };
 }
 
+function foregroundOutcome({ exitCode, signal, timedOut }) {
+  if (timedOut) return "timed_out";
+  if (signal) return "canceled";
+  return exitCode === 0 ? "passed" : "failed";
+}
+
+function signalExitCode(signal) {
+  const codes = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129, SIGKILL: 137 };
+  return codes[signal] ?? EXIT.INTERNAL;
+}
+
+// Foreground deliberately shares no ownership code with BOT-1350's detached
+// runner. It has exactly one durable pre-spawn boundary (the outbox start
+// event), then returns the child verdict even when terminal delivery degrades.
+export async function launchForegroundRun(argv, {
+  cwd = process.cwd(), spawnImpl = spawn, identity = null, outbox = null, signalEmitter = process,
+} = {}) {
+  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 } };
+  if (!opts.foreground) return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", error: "foreground_flag_required", exit_code: EXIT.INVALID } };
+  if (!identity?.repository || !identity?.tenant || !identity?.appSlug) {
+    return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", error: "telemetry_identity_required", exit_code: EXIT.INVALID } };
+  }
+  const telemetry = outbox ?? await createTelemetryOutbox({
+    tenant: identity.tenant,
+    repository: identity.repository,
+    producerVersion: identity.producerVersion ?? VERSION,
+  });
+  // An authenticated invocation is also the bounded recovery opportunity for
+  // prior offline records. Failure remains durable and never alters the child
+  // verdict below.
+  if (!outbox) {
+    // A cached proof keeps offline hooks fast; a new or rotated credential must
+    // be authenticated once before it may scope a BotBuddy lifecycle event.
+    try {
+      await attestTelemetryCredential(identity, telemetry);
+    } catch (error) {
+      return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", error: error?.message ?? "telemetry_credential_unattested", exit_code: EXIT.INVALID } };
+    }
+    await telemetry.importLegacyTestRunReceipts(join(cwd, ".botbuddy", "test-runs"), { maxReceipts: 8, deadline: Date.now() + 2_250 }).catch(() => {});
+    await telemetry.replay(
+      (event) => deliverExecutionEvent(event, { credential: identity.credential }),
+      // Recovery is opportunistic: a large offline backlog must never turn the
+      // next hook invocation into an unbounded pre-spawn upload job.
+      { maxEvents: 8, deadline: Date.now() + 2_250 },
+    ).catch(() => {});
+  }
+  const runId = randomUUID();
+  const context = {
+    repo: identity.repository,
+    environment: opts.environment,
+    runner: identity.appSlug,
+    phase: opts.kind === "wait" ? "waiting" : "testing",
+    health: "uninstrumented",
+  };
+  const base = {
+    schema_version: 1,
+    producer_kind: opts.kind,
+    source_run_id: runId,
+    attempt: 1,
+    occurred_at: new Date().toISOString(),
+    context,
+  };
+  try {
+    await telemetry.append({ ...base, action: "start", producer_event_id: `${runId}:start`, producer_sequence: 0 });
+  } catch (error) {
+    return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", error: error?.code ?? "telemetry_start_not_durable", exit_code: EXIT.INTERNAL } };
+  }
+  let child;
+  try {
+    // A foreground command still needs its own process group: hooks commonly
+    // launch package managers or test runners, whose descendants otherwise
+    // survive a timeout after their immediate parent exits.
+    child = spawnImpl(command[0], command.slice(1), { cwd, detached: process.platform !== "win32", stdio: "inherit", windowsHide: true });
+  } catch (error) {
+    await telemetry.append({ ...base, action: "terminal", producer_event_id: `${runId}:terminal`, producer_sequence: 1, outcome: "crashed", diagnostic: { code: "spawn_failed", category: "spawn" } }).catch(() => {});
+    return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "crashed", run_id: runId, telemetry: "degraded", exit_code: EXIT.INTERNAL } };
+  }
+  let timedOut = false;
+  let killTimer;
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    terminateProcessGroup(child, "SIGTERM");
+    killTimer = setTimeout(() => terminateProcessGroup(child, "SIGKILL"), TIMEOUT_GRACE_MS);
+  }, opts.timeout * 1000);
+  const forwarded = forwardTerminationSignals(child, signalEmitter);
+  const result = await waitForChild(child);
+  forwarded.cleanup();
+  clearTimeout(timeout);
+  clearTimeout(killTimer);
+  const terminalSignal = forwarded.signal ?? result.signal;
+  const outcome = result.error ? "crashed" : foregroundOutcome({ ...result, signal: terminalSignal, timedOut });
+  let telemetryState = "durable";
+  try {
+    await telemetry.append({
+      ...base,
+      action: "terminal",
+      producer_event_id: `${runId}:terminal`,
+      producer_sequence: 1,
+      // BOT-1317 derives duration from the two lifecycle timestamps. `base`
+      // intentionally represents pre-spawn time, so terminal needs a fresh
+      // timestamp after the child has actually completed.
+      occurred_at: new Date().toISOString(),
+      context: { ...context, phase: outcome === "passed" ? "complete" : "failed" },
+      outcome,
+      ...(terminalSignal ? { diagnostic: { code: "child_signaled", category: "signal", signal: terminalSignal } } : {}),
+    });
+  } catch { telemetryState = "degraded"; }
+  const exitCode = result.error ? EXIT.INTERNAL : timedOut ? signalExitCode("SIGTERM") : terminalSignal ? signalExitCode(terminalSignal) : result.exitCode ?? EXIT.INTERNAL;
+  return { exitCode, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome, run_id: runId, telemetry: telemetryState, exit_code: exitCode } };
+}
+
 export function terminalStatus({ exitCode, signal, timedOut = false, ownerLost = false }) {
   if (ownerLost) return "owner_lost";
   if (timedOut) return "timed_out";
@@ -280,7 +399,30 @@ function boundedCapture() {
 }
 
 function terminateProcessGroup(child, signal) {
-  try { process.kill(-child.pid, signal); } catch { try { child.kill?.(signal); } catch { /* already exited */ } }
+  if (process.platform !== "win32" && Number.isInteger(child?.pid) && child.pid > 0) {
+    try { process.kill(-child.pid, signal); return; } catch { /* fall back to the immediate child */ }
+  }
+  try { child.kill?.(signal); } catch { /* already exited */ }
+}
+
+function forwardTerminationSignals(child, signalEmitter) {
+  let signal = null;
+  let escalation = null;
+  const handlers = new Map();
+  for (const candidate of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    const handler = () => {
+      if (signal) { terminateProcessGroup(child, "SIGKILL"); return; }
+      signal = candidate;
+      terminateProcessGroup(child, candidate);
+      escalation = setTimeout(() => terminateProcessGroup(child, "SIGKILL"), TIMEOUT_GRACE_MS);
+    };
+    handlers.set(candidate, handler);
+    signalEmitter.on(candidate, handler);
+  }
+  return {
+    get signal() { return signal; },
+    cleanup() { clearTimeout(escalation); for (const [candidate, handler] of handlers) signalEmitter.removeListener(candidate, handler); },
+  };
 }
 
 function waitForChild(child) {
@@ -343,7 +485,20 @@ export async function cmdRun(args) {
     return;
   }
   if (args[0] === "help" || args[0] === "--help") {
-    console.log("botbuddy run --session-id <id> --environment <local|preview|staging|production|none> [--timeout <sec>] [--rerun-reason <json>] -- <command> [args...]\nbotbuddy run cancel <run_id>");
+    console.log("botbuddy run --session-id <id> --environment <local|preview|staging|production|none> [--timeout <sec>] [--rerun-reason <json>] -- <command> [args...]\nbotbuddy run --foreground --kind <test|wait|browser|ci|hook|stack> --environment <local|preview|staging|production|none> -- <command> [args...]\nbotbuddy run cancel <run_id>");
+    return;
+  }
+  if (args.includes("--foreground")) {
+    let identity;
+    try { identity = await loadTelemetryIdentity(); }
+    catch (error) {
+      oneLine({ schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", error: error?.message ?? "telemetry_identity_invalid", exit_code: EXIT.INVALID }, false);
+      process.exitCode = EXIT.INVALID;
+      return;
+    }
+    const result = await launchForegroundRun(args, { identity: { ...identity, producerVersion: VERSION } });
+    oneLine(result.receipt, Boolean(parseRunArgs(args).opts.json));
+    process.exitCode = result.exitCode;
     return;
   }
   const result = await launchRun(args);

package/src/stack.mjs

@@ -353,8 +353,8 @@ export function parseSupabaseStatus(text) {
 // ── runtime (network / process) ──────────────────────────────────────────────
 
 // BOT-1520: source both auth headers from the Keychain — the owner OAuth token
-// (`botbuddy login`) is preferred, the tenant-bound agent key
-// (`botbuddy profile setup`) is the fallback. No plaintext config.json secret.
+// (`botbuddy login`) is preferred, the tenant-bound MCP key
+// (`botbuddy mcp setup`, BOT-1608) is the fallback. No plaintext config.json secret.
 export async function stackAuthHeader() {
   const agentKey = await resolveAgentKey();
   const owner = await resolveOwnerToken({ getConfig });
@@ -1132,7 +1132,7 @@ 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" };
+    if (!auth) return { exitCode: EXIT.AUTH, outcome: "error", error: "not authenticated — run botbuddy login (agents: botbuddy mcp setup)" };
     // 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.

package/src/telemetry-config.mjs

@@ -0,0 +1,109 @@
+// BOT-1316 — checked-in repo identity, separate from local credentials.
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { resolveAgentBinding } from "./wait-profile.mjs";
+import { callToolJson } from "./api.mjs";
+
+const execFileAsync = promisify(execFile);
+const REQUIRED_KEYS = ["schema_version", "repository", "app_slug", "profile", "expected_tenant"];
+const REPOSITORY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+export function parseTelemetryConfig(raw) {
+  let value;
+  try { value = JSON.parse(raw); } catch { throw new Error(".botbuddy/config.json is not valid JSON"); }
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(".botbuddy/config.json must be an object");
+  const keys = Object.keys(value).sort();
+  if (keys.length !== REQUIRED_KEYS.length || keys.some((key, index) => key !== [...REQUIRED_KEYS].sort()[index])) {
+    throw new Error(".botbuddy/config.json must contain exactly schema_version, repository, app_slug, profile, expected_tenant");
+  }
+  if (value.schema_version !== 1 || !REPOSITORY.test(value.repository) || !SLUG.test(value.app_slug) || !SLUG.test(value.profile) || !SLUG.test(value.expected_tenant)) {
+    throw new Error(".botbuddy/config.json has an invalid schema_version or identity value");
+  }
+  return { schemaVersion: 1, repository: value.repository, appSlug: value.app_slug, profile: value.profile, expectedTenant: value.expected_tenant };
+}
+
+export async function repositoryFromRemote(cwd = process.cwd()) {
+  const { stdout } = await execFileAsync("git", ["config", "--get", "remote.origin.url"], { cwd });
+  const raw = stdout.trim().replace(/\.git$/, "");
+  const match = raw.match(/(?:github\.com[/:])([^/]+\/[^/]+)$/i);
+  if (!match) throw new Error("origin remote is not a canonical GitHub repository");
+  return match[1];
+}
+
+export async function verifyTelemetryIdentity(config, {
+  cwd = process.cwd(), repositoryFromRemote: remote = repositoryFromRemote, resolveBinding = resolveAgentBinding, call = callToolJson, verifyCredential = false,
+} = {}) {
+  const repository = await remote(cwd);
+  if (repository.toLowerCase() !== config.repository.toLowerCase()) throw new Error("telemetry repository mismatch with origin remote");
+  const binding = await resolveBinding({ cwd });
+  if (!binding?.token) throw new Error("telemetry requires a locally stored tenant-bound credential");
+  if (binding.tenant !== config.expectedTenant) throw new Error("telemetry tenant mismatch with checked-in config");
+  // A binding file names the intended tenant; it is not proof that a rotated
+  // environment credential still belongs there. Ask the server's read-only
+  // identity endpoint before allowing a foreground child to run.
+  if (verifyCredential) {
+    const verified = await call("whoami", {}, {
+      auth: { "x-agent-api-key": binding.token },
+      tenant: config.expectedTenant,
+      signal: AbortSignal.timeout(2_000),
+    });
+    if (!verified?.ok || verified.isError || verified.data?.tenant_id !== config.expectedTenant) {
+      throw new Error("telemetry credential is not attested to the expected tenant");
+    }
+  }
+  return { repository: config.repository, tenant: config.expectedTenant, appSlug: config.appSlug, profile: config.profile, credential: binding.token };
+}
+
+export async function loadTelemetryLocation(cwd = process.cwd(), {
+  repositoryFromRemote: remote = repositoryFromRemote,
+} = {}) {
+  const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd });
+  const root = stdout.trim();
+  const raw = await readFile(join(root, ".botbuddy", "config.json"), "utf8");
+  const config = parseTelemetryConfig(raw);
+  const repository = await remote(root);
+  if (repository.toLowerCase() !== config.repository.toLowerCase()) throw new Error("telemetry repository mismatch with origin remote");
+  return { root, repository: config.repository, tenant: config.expectedTenant, appSlug: config.appSlug, profile: config.profile };
+}
+
+export async function loadTelemetryIdentity(cwd = process.cwd(), options = {}) {
+  const location = await loadTelemetryLocation(cwd, options);
+  const config = {
+    schemaVersion: 1,
+    repository: location.repository,
+    appSlug: location.appSlug,
+    profile: location.profile,
+    expectedTenant: location.tenant,
+  };
+  return verifyTelemetryIdentity(config, { cwd: location.root, ...options });
+}
+
+function credentialFingerprint(credential) {
+  return createHash("sha256").update(credential).digest("hex");
+}
+
+// A tenant-bound key must be proven once before foreground execution can trust
+// it. The proof is keyed to a non-reversible fingerprint in the 0600 outbox
+// status file, so a later rotation or cross-tenant environment value cannot
+// reuse a prior attestation. Once cached, the check remains fully offline.
+export async function attestTelemetryCredential(identity, outbox, { call = callToolJson } = {}) {
+  const fingerprint = credentialFingerprint(identity?.credential ?? "");
+  if (!identity?.credential || !identity?.tenant || !outbox?.hasCredentialAttestation || !outbox?.recordCredentialAttestation) {
+    throw new Error("telemetry credential attestation is unavailable");
+  }
+  if (await outbox.hasCredentialAttestation({ tenant: identity.tenant, fingerprint })) return { cached: true };
+  const verified = await call("whoami", {}, {
+    auth: { "x-agent-api-key": identity.credential },
+    tenant: identity.tenant,
+    signal: AbortSignal.timeout(2_000),
+  });
+  if (!verified?.ok || verified.isError || verified.data?.tenant_id !== identity.tenant) {
+    throw new Error("telemetry credential is not attested to the expected tenant");
+  }
+  await outbox.recordCredentialAttestation({ tenant: identity.tenant, fingerprint });
+  return { cached: false };
+}

package/src/telemetry-delivery.mjs

@@ -0,0 +1,40 @@
+// BOT-1316 — direct HTTP delivery to BOT-1317. This intentionally bypasses the
+// MCP tool surface: agents never need to call telemetry MCP tools.
+export function executionIngestEndpoint(serverUrl = process.env.BOTBUDDY_SERVER_URL || "https://api.bot-buddy.ai/functions/v1/mcp-server") {
+  const url = new URL(serverUrl);
+  url.pathname = url.pathname.replace(/\/mcp-server\/?$/, "/execution-ingest");
+  return url.toString();
+}
+
+export async function deliverExecutionEvent(event, {
+  credential, endpoint = executionIngestEndpoint(), fetchImpl = fetch, timeoutMs = 2_000,
+} = {}) {
+  if (typeof credential !== "string" || !credential) return { accepted: false, error: "credential_missing" };
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "x-agent-api-key": credential },
+      body: JSON.stringify(event),
+      signal: controller.signal,
+    });
+    let body = {};
+    try { body = await response.json(); } catch { /* typed HTTP status still controls retry */ }
+    if (response.status === 200 || response.status === 202) return { accepted: true, receipt: body.receipt ?? "accepted" };
+    // A reaper may have terminalized a run after a successful upload whose
+    // response was lost. BOT-1317 correctly refuses a contradictory terminal;
+    // retaining that record would otherwise block every later local event.
+    if (response.status === 409 && body.error === "terminal_conflict") return { accepted: true, receipt: "terminal_conflict_retired" };
+    // The queue cannot repair an event rejected by the server's contract.
+    // Quarantine these client errors so one malformed historical line does not
+    // starve later valid lifecycle events. Authentication is deliberately left
+    // retryable: a key can be restored or rotated without discarding evidence.
+    if ([400, 404, 409, 413, 422].includes(response.status)) {
+      return { accepted: false, permanent: true, error: body.error ?? `http_${response.status}` };
+    }
+    return { accepted: false, error: body.error ?? `http_${response.status}` };
+  } catch (error) {
+    return { accepted: false, error: controller.signal.aborted ? "timeout" : error?.code ?? "transport" };
+  } finally { clearTimeout(timeout); }
+}