@botbuddy/cli 1.34.3 → 1.35.0

package/src/pw/telemetry.mjs

@@ -1,14 +1,115 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
-import { homedir } from "node:os";
+// BOT-1318 — production wiring for bb pw browser-acceptance telemetry.
+//
+// Replaces the pre-BOT-1318 lane-number spool + close-only record_lane_event
+// rollup. A repository opts in by committing `.botbuddy/config.json` (BOT-1316);
+// once opted in every rule fails closed: the checked-in repository must match
+// origin, the local credential binding must belong to the expected tenant, and
+// that credential is attested once against the server (cached by fingerprint).
+// A repository without the checked-in config stays untracked, exactly as before.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { deriveSession } from "./readiness.mjs";
-const spoolDir = (env) => env.BB_PW_SPOOL_DIR || join(homedir(), ".botbuddy", "pw-spool");
-export function makeTelemetry({ env = process.env } = {}) {
-  const path = (lane) => join(spoolDir(env), `lane-${lane}.jsonl`);
-  const readEvents = (lane) => existsSync(path(lane)) ? readFileSync(path(lane), "utf8").split("\n").filter(Boolean).flatMap((line) => { try { return [JSON.parse(line)]; } catch { return []; } }) : [];
+import { fileURLToPath } from "node:url";
+import { VERSION } from "../version.mjs";
+import { createTelemetryOutbox } from "../telemetry-outbox.mjs";
+import { deliverExecutionEvent } from "../telemetry-delivery.mjs";
+import { attestTelemetryCredential, loadTelemetryIdentity, loadTelemetryLocation } from "../telemetry-config.mjs";
+import { defaultGitInfo, findGitRoot } from "../test-lane.mjs";
+import { createBrowserTelemetryResolver } from "./session.mjs";
+import { resolveAgentSessionCredential } from "../agent-session.mjs";
+import { homedir } from "node:os";
+
+const HEARTBEAT_ENTRY = fileURLToPath(new URL("./heartbeat.mjs", import.meta.url));
+
+export function telemetryRoot(env = process.env) {
+  return env.BB_PW_TELEMETRY_ROOT || join(homedir(), ".botbuddy");
+}
+
+// Ticket/PR/branch attribution reuses the `botbuddy test` helper (BOT-1510):
+// explicit BB_PW_TICKET_ID / BB_PW_PR_ID win, else the branch's `bot-<n>` segment
+// and `gh pr view`; anything unresolved stays null — never a guess.
+export function gitInfoFor({ cwd, env }) {
+  let cached = null;
+  return () => {
+    if (!cached) {
+      const prOverride = env.BB_PW_PR_ID ? Number.parseInt(env.BB_PW_PR_ID, 10) : null;
+      cached = defaultGitInfo({ cwd, ticket: env.BB_PW_TICKET_ID || null, pr: Number.isInteger(prOverride) ? prOverride : null });
+    }
+    return cached;
+  };
+}
+
+// The session credential the foreground authenticated with (e.g. an explicit
+// --agent-session-token that is neither exported nor cached) is handed to the
+// detached heartbeat through its environment — readable only by the same user,
+// never on the command line — so the heartbeat re-resolves the same principal.
+export function spawnHeartbeatProcess({ cwd, env, sessionCredential = null, spawnImpl = spawn }) {
+  return (info) => {
+    const childEnv = { ...env, BB_PW_TELEMETRY_ROOT: info.root, ...(sessionCredential ? { BOTBUDDY_AGENT_SESSION_TOKEN: sessionCredential } : {}) };
+    const child = spawnImpl(process.execPath, [HEARTBEAT_ENTRY, JSON.stringify({ ...info, cwd })], {
+      cwd, detached: true, stdio: "ignore", env: childEnv,
+    });
+    child.on("error", () => {});
+    child.unref();
+    return child.pid ?? null;
+  };
+}
+
+// The worktree's already-resolved session credential (exported or the fresh `bb setup`
+// cache). Never self-heals: the detached heartbeat must not mint a session.
+async function cachedSessionCredential({ env, cwd }) {
+  try {
+    const credential = await resolveAgentSessionCredential({ argv: [], env, cwd, sessionId: null, flagToken: null, selfHeal: async () => null, warn: () => {} });
+    return credential?.token ?? null;
+  } catch { return null; }
+}
+
+/**
+ * Resolve the verified telemetry identity for this worktree and return a
+ * lane-tracker resolver, `{ tracked:false }` when the repository has not opted
+ * in, or `{ error }` (fail closed) when the opted-in identity is invalid. The
+ * durable mcp_env key is preferred; without one, the session credential the lane
+ * gate authenticated with (`sessionCredential`), else the cached session, is used.
+ */
+export async function resolveBrowserTelemetry({
+  env = process.env, cwd = process.cwd(), sessionCredential = null,
+  identityOptions = {}, resolveSession = cachedSessionCredential, attest = attestTelemetryCredential,
+} = {}) {
+  const gitRoot = findGitRoot(cwd);
+  if (!gitRoot || !existsSync(join(gitRoot, ".botbuddy", "config.json"))) return { tracked: false };
+  let identity;
+  try {
+    await loadTelemetryLocation(cwd, identityOptions);
+    identity = await loadTelemetryIdentity(cwd, { ...identityOptions, fallbackCredential: async () => sessionCredential || (await resolveSession({ env, cwd })) });
+  } catch (error) {
+    return { error: `bb-pw: browser telemetry identity rejected (${error?.message ?? "invalid"}); nothing was run. Fix .botbuddy/config.json or the worktree credential binding.` };
+  }
+  const root = telemetryRoot(env);
+  try {
+    const outbox = await createTelemetryOutbox({ root: join(root, "telemetry"), tenant: identity.tenant, repository: identity.repository, producerVersion: VERSION });
+    await attest(identity, outbox);
+  } catch (error) {
+    return { error: `bb-pw: browser telemetry credential rejected (${error?.message ?? "unattested"}); nothing was run.` };
+  }
+  return {
+    tracked: true,
+    resolver: createBrowserTelemetryResolver({
+      root, tenant: identity.tenant, repository: identity.repository, producerVersion: VERSION,
+      deliver: (event) => deliverExecutionEvent(event, { credential: identity.credential }),
+      gitInfo: gitInfoFor({ cwd, env }),
+      spawnHeartbeat: spawnHeartbeatProcess({ cwd, env, sessionCredential }),
+    }),
+  };
+}
+
+/** The runPw `deps.telemetry` default: `{ resolve({host, lane}) }`. */
+export function makeTelemetry({ env = process.env, cwd = process.cwd(), sessionCredential = null } = {}) {
+  let resolved = null;
   return {
-    append(lane, event) { mkdirSync(spoolDir(env), { recursive: true }); appendFileSync(path(lane), JSON.stringify({ ts: event.ts, method: event.method, url: event.url ?? null }) + "\n"); },
-    count(lane) { return readEvents(lane).length; },
-    async rollup({ lane, coordinator, host }) { const events = readEvents(lane); if (!events.length) return { emitted: false, count: 0 }; const session = deriveSession(events, { meta: { host, slot: String(lane), ticket_id: env.BB_PW_TICKET_ID, ticket_url: env.BB_PW_TICKET_URL, pr_id: env.BB_PW_PR_ID, pr_url: env.BB_PW_PR_URL, branch: env.BB_PW_BRANCH, commit_sha: env.BB_PW_COMMIT, environment: env.BB_PW_ENV } }); const event = { ...session, started_at: new Date(session.started_at).toISOString(), ended_at: new Date(session.ended_at).toISOString(), ended_reason: "close" }; try { if (!coordinator?.emit) return { emitted: false, count: events.length, session: event }; await coordinator.emit(event); rmSync(path(lane), { force: true }); return { emitted: true, count: events.length, session: event }; } catch { return { emitted: false, count: events.length, session: event }; } },
+    async resolve({ host, lane }) {
+      resolved ??= await resolveBrowserTelemetry({ env, cwd, sessionCredential });
+      if (!resolved.tracked) return resolved;
+      return resolved.resolver.resolve({ host, lane });
+    },
   };
 }

package/src/session-bootstrap.mjs

@@ -153,6 +153,55 @@ export async function heartbeatHarnessSession({
   return response.data;
 }
 
+// BOT-1945: a worktree cache that this bootstrap path did not create — written by
+// the self-heal / `bb setup` / MCP registration path (no `harness_origin` marker),
+// or a legacy bootstrap cache with no stored generation — is not a harness
+// principal this bootstrap owns and cannot be retired through the fenced durable
+// close (the server refuses a generated row without its generation:
+// `session_generation_required`). Retire it best-effort and NEVER fail the
+// bootstrap because of it:
+//   1. its own scoped bearer self-closes with if_stale (the server derives the
+//      generation from the token, and still refuses a live holder);
+//   2. the durable credential confirms (with the generation when cached): an
+//      ended row answers already_closed, an active generated row stays refused;
+//   3. otherwise leave it: a session that is never closed simply ages out of the
+//      server's holder-liveness window and its short-lived token expires.
+// Returns a non-secret receipt `{ session_id, retired }`.
+export function cacheOwnedByBootstrap(cached) {
+  return cached?.harness_origin === "bootstrap_agent_session" && !!cached.session_token_generation;
+}
+
+async function retireUnownedCachedSession({ cached, call, callOptions, resolveCleanupOptions }) {
+  const receipt = { session_id: cached.session_id, retired: false };
+  const ok = (response) => !!response?.ok && !response.isError;
+  try {
+    if (cached.session_token) {
+      const self = await call("close_session", { session_id: cached.session_id, if_stale: true }, {
+        auth: { "x-agent-api-key": cached.session_token },
+      }).catch(() => null);
+      if (ok(self)) return { ...receipt, retired: true };
+      // A live holder is refused by if_stale; the durable credential would be
+      // refused the same way, so do not widen to it.
+      if ((self?.data?.error || self?.error) === "session_still_active") return receipt;
+    }
+    // Codex #986 P2: confirm with the durable credential even without a cached
+    // generation. A bearer that fails auth often means the row was already ended
+    // (e.g. superseded by registration reconciliation) — the durable close then
+    // answers idempotent `already_closed`; an ACTIVE generated row is still
+    // refused (`session_generation_required`) and `if_stale` protects a live one.
+    const durable = callOptions ?? await resolveCleanupOptions().catch(() => null);
+    if (!durable) return receipt;
+    const confirmed = await call("close_session", {
+      session_id: cached.session_id,
+      ...(cached.session_token_generation ? { session_token_generation: cached.session_token_generation } : {}),
+      if_stale: true,
+    }, durable).catch(() => null);
+    return { ...receipt, retired: ok(confirmed) };
+  } catch {
+    return receipt;
+  }
+}
+
 export async function bootstrapHarnessSession({
   name,
   type = "codex",
@@ -231,7 +280,10 @@ export async function bootstrapHarnessSession({
     // to retire the cached session *only if its authoritative holder-liveness
     // window elapsed*. The file's timestamp is intentionally not authority:
     // relay heartbeats can extend it after the snapshot was written.
-    if (cached && cached.session_id !== session.session_id) {
+    let replacedCachedSession = null;
+    if (cached && cached.session_id !== session.session_id && !cacheOwnedByBootstrap(cached)) {
+      replacedCachedSession = await retireUnownedCachedSession({ cached, call, callOptions, resolveCleanupOptions });
+    } else if (cached && cached.session_id !== session.session_id) {
       const cleanupOptions = callOptions ?? await resolveCleanupOptions();
       if (!cleanupOptions) {
         // BOT-1650 (Codex round-27): the new session was admitted but there is no
@@ -370,6 +422,29 @@ export async function bootstrapHarnessSession({
       }
       throw error;
     }
-    return { ...state, ...(displayName ? { display_name: displayName } : {}), ...(ticketSignals ? { ticket_signals: ticketSignals } : {}), ...(linkage ? { linkage } : {}) };
+    return { ...state, ...(replacedCachedSession ? { replaced_cached_session: replacedCachedSession } : {}), ...(displayName ? { display_name: displayName } : {}), ...(ticketSignals ? { ticket_signals: ticketSignals } : {}), ...(linkage ? { linkage } : {}) };
   });
 }
+
+/** BOT-1945 (AC-3): non-secret `bb doctor` view of whether this worktree's cache
+ * is a harness session linked by `bb bootstrap` (the SessionStart hook's job).
+ * Only ids and presence flags — never the bearer. */
+export async function doctorBootstrapState({ cwd = process.cwd(), readState = readAgentState } = {}) {
+  let root;
+  try { root = await worktreeRoot(cwd); } catch { root = cwd; }
+  const state = await readState(root).catch(() => null);
+  if (!state) return { status: "not_linked", cache: "none" };
+  const bootstrap = state.harness_origin === "bootstrap_agent_session";
+  return {
+    status: bootstrap ? "linked" : "not_linked",
+    cache: bootstrap ? "bootstrap" : "self_heal",
+    session_id: state.session_id ?? null,
+    generation: state.session_token_generation ? "cached" : "missing",
+  };
+}
+
+export function formatBootstrapLine(report) {
+  if (report?.status === "linked") return `bootstrap: linked (session ${report.session_id}, generation ${report.generation})`;
+  if (!report || report.cache === "none") return "bootstrap: not linked — no session cache in this worktree (the SessionStart hook runs bb bootstrap)";
+  return `bootstrap: not linked — cache is a self-heal session ${report.session_id} (generation ${report.generation}); the SessionStart hook's bb bootstrap replaces it`;
+}

package/src/telemetry-config.mjs

@@ -36,18 +36,23 @@ export async function repositoryFromRemote(cwd = process.cwd()) {
 
 export async function verifyTelemetryIdentity(config, {
   cwd = process.cwd(), repositoryFromRemote: remote = repositoryFromRemote, resolveBinding = resolveAgentBinding, call = callToolJson, verifyCredential = false,
+  // BOT-1318: a `bb setup`-only worktree holds no mcp_env key, only its cached
+  // session token. The durable key still wins; the fallback is used only without it,
+  // and is attested against the expected tenant like any other credential.
+  fallbackCredential = async () => null,
 } = {}) {
   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");
+  if (binding?.tenant !== config.expectedTenant) throw new Error("telemetry tenant mismatch with checked-in config");
+  const credential = binding.token || (await fallbackCredential()) || null;
+  if (!credential) throw new Error("telemetry requires a locally stored tenant-bound credential");
   // 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 },
+      auth: { "x-agent-api-key": credential },
       tenant: config.expectedTenant,
       signal: AbortSignal.timeout(2_000),
     });
@@ -55,7 +60,7 @@ export async function verifyTelemetryIdentity(config, {
       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 };
+  return { repository: config.repository, tenant: config.expectedTenant, appSlug: config.appSlug, profile: config.profile, credential };
 }
 
 export async function loadTelemetryLocation(cwd = process.cwd(), {

package/src/telemetry-delivery.mjs

@@ -21,11 +21,29 @@ export async function deliverExecutionEvent(event, {
     });
     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" };
+    // BOT-1318 (Codex R1 P2): carry the canonical execution UUID from the real
+    // execution-ingest receipt so producers can report it (never source_run_id).
+    if (response.status === 200 || response.status === 202) {
+      return {
+        accepted: true, receipt: body.receipt ?? "accepted",
+        ...(typeof body.execution_id === "string" && body.execution_id ? { execution_id: body.execution_id } : {}),
+        // BOT-1318 (Codex R13): a terminal outcome on a non-terminal event means the
+        // server already ended the run (e.g. reaped as abandoned) — producers reconcile.
+        ...(typeof body.outcome === "string" && body.outcome ? { outcome: body.outcome } : {}),
+      };
+    }
     // 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 409 carries the canonical outcome and execution id; keep them so the producer
+    // reconciles its local terminal to the server's (Codex R27).
+    if (response.status === 409 && body.error === "terminal_conflict") {
+      return {
+        accepted: true, receipt: "terminal_conflict_retired",
+        ...(typeof body.outcome === "string" && body.outcome ? { outcome: body.outcome } : {}),
+        ...(typeof body.execution_id === "string" && body.execution_id ? { execution_id: body.execution_id } : {}),
+      };
+    }
     // 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

package/src/telemetry-outbox.mjs

@@ -3,7 +3,7 @@
 // append a small, allowlisted lifecycle event before spawning a child; delivery
 // is a separate, idempotent step against execution-ingest.
 
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { chmod, link, mkdir, open, readFile, readdir, rename, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -24,10 +24,26 @@ const CORRELATION_KEYS = new Set([
 ]);
 const PROGRESS_KEYS = new Set(["completed", "total", "phase", "current_item", "worker", "shard"]);
 const DIAGNOSTIC_KEYS = new Set(["code", "message", "category", "signal", "retryable"]);
+// BOT-1318: the optional, bounded browser-acceptance object. Mirrors the
+// execution-ingest contract; anything else (typed values, raw output, invented
+// metrics) is stripped here rather than shipped for the server to reject.
+const BROWSER_KEYS = new Set(["lane", "host", "action", "summary"]);
+const BROWSER_ACTION_KEYS = new Set(["action_id", "verb", "category", "phase", "started_at", "finished_at", "command_ms", "result", "error_class", "route"]);
+const BROWSER_SUMMARY_KEYS = new Set([
+  "actions_total", "actions_succeeded", "actions_failed", "actions_interrupted", "command_ms", "active_ms", "action_span_ms",
+  "first_action_at", "last_action_at", "navigations", "screenshots", "snapshots", "interactions", "distinct_routes", "acceptance_verdict",
+]);
+const pick = (value, keys) => Object.fromEntries(Object.entries(value).filter(([key]) => keys.has(key)));
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const hash = (value) => createHash("sha256").update(value).digest("hex");
 
+/** True when a string carries a credential the outbox would redact. */
+export function containsSensitive(value) {
+  SENSITIVE.lastIndex = 0;
+  return typeof value === "string" && SENSITIVE.test(value);
+}
+
 function redactString(value) {
   SENSITIVE.lastIndex = 0;
   return value.replace(SENSITIVE, "[REDACTED]");
@@ -55,7 +71,7 @@ function eventPayload(event) {
   if (!clean || typeof clean !== "object" || Array.isArray(clean)) throw new Error("telemetry event must be an object");
   // execution-ingest is intentionally strict. Keep this client-side allowlist so
   // a reporter cannot accidentally turn arbitrary process state into telemetry.
-  const allowed = new Set(["schema_version", "action", "producer_kind", "source_run_id", "attempt", "producer_event_id", "producer_sequence", "occurred_at", "context", "progress", "outcome", "diagnostic", "evidence_refs"]);
+  const allowed = new Set(["schema_version", "action", "producer_kind", "source_run_id", "attempt", "producer_event_id", "producer_sequence", "occurred_at", "context", "progress", "outcome", "diagnostic", "evidence_refs", "browser"]);
   for (const key of Object.keys(clean)) if (!allowed.has(key)) delete clean[key];
   // Mirror the server contract at the producer boundary. A malformed reporter
   // must not create a permanently retrying record merely because it included
@@ -69,6 +85,11 @@ function eventPayload(event) {
   if (clean.progress && typeof clean.progress === "object" && !Array.isArray(clean.progress)) {
     clean.progress = Object.fromEntries(Object.entries(clean.progress).filter(([key]) => PROGRESS_KEYS.has(key)));
   }
+  if (clean.browser && typeof clean.browser === "object" && !Array.isArray(clean.browser)) {
+    clean.browser = pick(clean.browser, BROWSER_KEYS);
+    if (clean.browser.action && typeof clean.browser.action === "object" && !Array.isArray(clean.browser.action)) clean.browser.action = pick(clean.browser.action, BROWSER_ACTION_KEYS);
+    if (clean.browser.summary && typeof clean.browser.summary === "object" && !Array.isArray(clean.browser.summary)) clean.browser.summary = pick(clean.browser.summary, BROWSER_SUMMARY_KEYS);
+  }
   if (clean.diagnostic && typeof clean.diagnostic === "object" && !Array.isArray(clean.diagnostic)) {
     clean.diagnostic = Object.fromEntries(Object.entries(clean.diagnostic).filter(([key]) => DIAGNOSTIC_KEYS.has(key)));
   }
@@ -88,7 +109,7 @@ async function durableWrite(path, value, { append = false } = {}) {
 }
 
 async function atomicJson(path, value) {
-  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
   await durableWrite(temp, `${JSON.stringify(value)}\n`);
   await rename(temp, path);
   // Persist the directory entry, not just the file data, before reporting the
@@ -137,7 +158,7 @@ export async function createTelemetryOutbox({
         // Write a complete, fsynced owner record first, then atomically publish
         // it with link(2). A crash can leave an unreferenced temp file but can
         // never strand the shared lock name with missing PID metadata.
-        const candidate = `${lockPath}.${process.pid}.${Date.now()}.tmp`;
+        const candidate = `${lockPath}.${process.pid}.${randomUUID()}.tmp`;
         await durableWrite(candidate, JSON.stringify({ pid: process.pid, created_at: now().toISOString() }));
         try { await link(candidate, lockPath); } finally { await unlink(candidate).catch(() => {}); }
         return async () => { try { await unlink(lockPath); } catch { /* a process may have cleaned its own stale lock */ } };
@@ -257,7 +278,7 @@ export async function createTelemetryOutbox({
         }
         offset += Buffer.byteLength(line) + 1;
       }
-      const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+      const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
       await durableWrite(tmp, remaining.map((record) => `${JSON.stringify(record)}\n`).join(""));
       await rename(tmp, path);
       let dir;
@@ -266,20 +287,25 @@ export async function createTelemetryOutbox({
     } finally { await release(); }
   }
 
-  async function status() {
+  /** `ownerOf(event)` (optional) also counts the queue per owner key, e.g. a browser lane. */
+  async function status({ ownerOf = null } = {}) {
     const lines = await readLines();
     let oldest = null;
     let queued = 0;
+    const byOwner = {};
     for (const line of lines) {
       try {
         const record = parseRecord(line);
         queued += 1;
+        const owner = ownerOf ? ownerOf(record.event) : null;
+        if (owner) byOwner[owner] = (byOwner[owner] ?? 0) + 1;
         if (!oldest || record.created_at < oldest) oldest = record.created_at;
       } catch { queued += 1; }
     }
     const persisted = await readStatus();
     return {
       queued_count: queued,
+      ...(ownerOf ? { queued_by_owner: byOwner } : {}),
       oldest_queued_at: oldest,
       last_successful_delivery_at: persisted.last_successful_delivery_at ?? null,
       last_error_class: persisted.last_error_class ?? null,