@botbuddy/cli 1.33.11 → 1.34.1

package/package.json

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

package/src/api.mjs

@@ -5,7 +5,7 @@ import { AGENT_KEY_RE } from "./agent-key.mjs";
 // BOT-1864: api.mjs ↔ agent-session.mjs is a deliberate import cycle — each side
 // only CALLS the other's functions at request time, never at module evaluation.
 import { resolveAgentSessionCredential } from "./agent-session.mjs";
-import { die, cyan, dim, yellow, prettyJson } from "./utils.mjs";
+import { die, red, cyan, dim, yellow, prettyJson } from "./utils.mjs";
 
 // Same slug shape the server accepts on `?tenant=`.
 const TENANT_PIN_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
@@ -57,7 +57,7 @@ async function genericEndpoint({ tenant = null, resolvePin = resolveDefaultTenan
 // tenant-bound agent key (from `botbuddy profile setup`) is the fallback.
 // BOT-1864: the generic commands (`bb call`, resources, heartbeat/locks/tasks)
 // first honour this worktree's tier-3 session — see resolveCallAuth.
-async function authHeader(toolName = null, { resolveAuth = resolveCallAuth } = {}) {
+async function authHeader(toolName = null, { resolveAuth = resolveCallAuth, exitCode = 1 } = {}) {
   const resolved = await resolveAuth({ toolName, preferSession: true });
   if (resolved.auth) {
     const expiresAt = resolved.ownerExpiresAt ?? null;
@@ -66,12 +66,15 @@ async function authHeader(toolName = null, { resolveAuth = resolveCallAuth } = {
     }
     return resolved;
   }
+  // BOT-1896: a missing/expired local credential is auth-class — callTool passes
+  // CALL_EXIT.AUTH so it never collapses into the generic exit 1.
+  const fail = (msg) => { console.error(`${red("✗")} ${msg}`); process.exit(exitCode); };
   const code = resolved.error?.error;
-  if (code === "token_expired") die(`Token expired. Run: ${cyan("botbuddy login")} to re-authenticate.`);
+  if (code === "token_expired") fail(`Token expired. Run: ${cyan("botbuddy login")} to re-authenticate.`);
   if (code === "session_token_malformed") {
-    die(`The agent session token has an unexpected shape (source: ${resolved.error.source ?? "unknown"}). Run: ${cyan("bb doctor --fix")} in this checkout.`);
+    fail(`The agent session token has an unexpected shape (source: ${resolved.error.source ?? "unknown"}). Run: ${cyan("bb doctor --fix")} in this checkout.`);
   }
-  die(`Not authenticated. Run: ${cyan("botbuddy login")}`);
+  fail(`Not authenticated. Run: ${cyan("botbuddy login")}`);
 }
 
 // BOT-1864: a cached session the server rejects (revoked by a concurrent
@@ -96,39 +99,200 @@ async function requestEndpoint(resolved, { tenant, resolvePin }) {
   return SESSION_SOURCES.has(resolved?.source) ? toolEndpoint(tenant) : genericEndpoint({ tenant, resolvePin });
 }
 
-export async function callTool(toolName, args = {}, { fetchImpl = fetch, auth = null, tenant = null, resolvePin = resolveDefaultTenantPin, resolveAuth = resolveCallAuth, log = (line) => console.log(line) } = {}) {
+// BOT-1896: `botbuddy call` (and every command riding callTool) exits with a
+// code that tells a tenant gate WHY it failed: AUTH when BotBuddy refused the
+// credential (fail closed), TRANSPORT when BotBuddy could not be reached or
+// answered with a gateway/5xx failure (the only case that may degrade to a
+// local-only lock). The values reuse `botbuddy stack`'s EXIT table (stack.mjs:
+// AUTH 3, BACKEND 5) — restated rather than imported because stack.mjs imports
+// this module; bot1896-call-auth-exit.test.mjs pins them equal.
+// ERROR (1) is the generic failure: a reachable server said something other than
+// "ok" or "auth" (a proxy 404, a 429 page, …). A gate must fail closed on it —
+// only TRANSPORT licenses a local-only fallback.
+export const CALL_EXIT = Object.freeze({ OK: 0, ERROR: 1, AUTH: 3, TRANSPORT: 5 });
+
+// BOT-1896: mirror of the server's AUTH_CLASS_ERROR_CODES
+// (supabase/functions/_shared/lib/authDenial.ts), used when an older server
+// sends a typed code without `error_class`. Pinned equal by the same test.
+export const CALL_AUTH_ERROR_CODES = new Set([
+  "scope_denied",
+  "session_token_revoked",
+  "session_token_expired",
+  "session_token_scope",
+  "credential_unknown",
+  "credential_missing",
+  "MCP_REAUTH_TENANT_REQUIRED",
+  "MCP_TENANT_PIN_REQUIRED",
+  "MCP_TENANT_SESSION_MISMATCH",
+  "MCP_TENANT_MEMBERSHIP_REQUIRED",
+  "MCP_TENANT_PIN_UNSUPPORTED",
+]);
+
+// BOT-1896: the codes the server's 401 gates emit when a request authenticated
+// as nothing — a dead/absent credential, never a tenant refusal.
+const UNAUTHENTICATED_CODES = new Set(["credential_unknown", "credential_missing", "session_token_revoked", "session_token_expired"]);
+
+function typedCodeOf(fields) {
+  if (!fields || typeof fields !== "object") return null;
+  const raw = fields.error_code ?? fields.code;
+  return typeof raw === "string" && raw ? raw : null;
+}
+
+function isAuthClass(fields) {
+  return Boolean(fields && typeof fields === "object" &&
+    (fields.error_class === "auth" || CALL_AUTH_ERROR_CODES.has(typedCodeOf(fields))));
+}
+
+/**
+ * BOT-1896: classify one tools/call exchange. Pure — no I/O.
+ *   kind "ok"           — a normal result (printed as before, exit 0)
+ *   kind "tool_error"   — a non-auth isError result (printed as before, exit 0)
+ *   kind "server_error" — a non-auth JSON-RPC error (die as before, exit 1)
+ *   kind "auth"         — BotBuddy refused the credential → receipt, CALL_EXIT.AUTH
+ *   kind "transport"    — no HTTP response, or a 5xx → receipt, CALL_EXIT.TRANSPORT
+ *   kind "http_error"   — any other HTTP failure (non-JSON or error-less 4xx,
+ *                         a non-JSON 2xx) → receipt, CALL_EXIT.ERROR (fail closed)
+ * The receipt carries the server's `error_code` and typed fields UNCHANGED. A
+ * 401/403 is auth even with no typed code (an older server), never transport.
+ */
+export function classifyCallResponse({ status = null, data = null, transportError = null, parseError = null } = {}) {
+  if (transportError) {
+    return {
+      kind: "transport",
+      receipt: { ok: false, error_class: "transport", error_code: "transport_error", http_status: null, message: String(transportError?.message ?? transportError) },
+    };
+  }
+  const authStatus = status === 401 || status === 403;
+  if (parseError || !data || typeof data !== "object") {
+    if (authStatus) {
+      return { kind: "auth", receipt: { ok: false, error_class: "auth", error_code: "unauthorized", http_status: status, message: "BotBuddy refused the credential (no typed body)." } };
+    }
+    // Codex P1 (PR #970): only a 5xx gateway page reads as transport. A reachable
+    // endpoint answering non-JSON with anything else (a proxy 404 from a wrong
+    // URL, a 429 rate-limit page) must fail closed, never license a fallback.
+    return typeof status === "number" && status >= 500
+      ? { kind: "transport", receipt: { ok: false, error_class: "transport", error_code: "invalid_response", http_status: status, message: `BotBuddy returned a non-JSON response (HTTP ${status}).` } }
+      : httpError(status, `BotBuddy returned a non-JSON response (HTTP ${status ?? "?"}).`);
+  }
+  const rpcError = data.error && typeof data.error === "object" ? data.error : null;
+  if (rpcError) {
+    const detail = rpcError.data && typeof rpcError.data === "object" ? rpcError.data : {};
+    if (isAuthClass(detail) || authStatus || rpcError.code === -32001) {
+      return {
+        kind: "auth",
+        receipt: { ok: false, ...detail, error_class: "auth", error_code: typedCodeOf(detail) ?? "unauthorized", http_status: status, message: rpcError.message ?? null },
+      };
+    }
+    if (typeof status === "number" && status >= 500) {
+      return { kind: "transport", receipt: { ok: false, error_class: "transport", error_code: "server_unavailable", http_status: status, message: rpcError.message ?? null } };
+    }
+    return { kind: "server_error", receipt: null };
+  }
+  // A bare REST-style `{ error }` body (not JSON-RPC).
+  if (typeof data.error === "string") {
+    if (isAuthClass(data) || authStatus) {
+      return { kind: "auth", receipt: { ok: false, ...data, error_class: "auth", error_code: typedCodeOf(data) ?? "unauthorized", http_status: status, message: data.error } };
+    }
+    if (typeof status === "number" && status >= 500) {
+      return { kind: "transport", receipt: { ok: false, error_class: "transport", error_code: "server_unavailable", http_status: status, message: data.error } };
+    }
+    return { kind: "server_error", receipt: null };
+  }
+  if (authStatus) {
+    return { kind: "auth", receipt: { ok: false, error_class: "auth", error_code: "unauthorized", http_status: status, message: null } };
+  }
+  if (typeof status === "number" && status >= 500) {
+    return { kind: "transport", receipt: { ok: false, error_class: "transport", error_code: "server_unavailable", http_status: status, message: null } };
+  }
+  if (typeof status === "number" && status >= 400) {
+    return httpError(status, null);
+  }
+  if (data.result?.isError === true) {
+    const first = data.result?.content?.[0]?.text;
+    let envelope = null;
+    try { envelope = typeof first === "string" ? JSON.parse(first) : null; } catch { envelope = null; }
+    if (isAuthClass(envelope)) {
+      const { success: _success, ...fields } = envelope;
+      return { kind: "auth", receipt: { ok: false, ...fields, error_class: "auth", error_code: typedCodeOf(envelope), http_status: status } };
+    }
+    return { kind: "tool_error", receipt: null };
+  }
+  return { kind: "ok", receipt: null };
+}
+
+function httpError(status, message) {
+  return { kind: "http_error", receipt: { ok: false, error_class: "http", error_code: `http_${status ?? "unknown"}`, http_status: status, message } };
+}
+
+function authFailureLine(receipt) {
+  const what = receipt.error_code === "scope_denied" && receipt.tool && receipt.required_scope
+    ? `scope_denied: \`${receipt.tool}\` requires the \`${receipt.required_scope}\` scope${receipt.key_prefix ? ` (presented a ${receipt.key_prefix} key)` : ""}`
+    : receipt.error_code;
+  return `BotBuddy refused the credential (${what}).${receipt.remedy ? ` ${receipt.remedy}` : ""}`;
+}
+
+export async function callTool(toolName, args = {}, { fetchImpl = fetch, auth = null, tenant = null, resolvePin = resolveDefaultTenantPin, resolveAuth = resolveCallAuth, log = (line) => console.log(line), errorLog = (line) => console.error(line) } = {}) {
   const body = {
     jsonrpc: "2.0",
     id: 1,
     method: "tools/call",
     params: { name: toolName, arguments: args },
   };
+  // BOT-1896: never throw on the wire — a fetch rejection or a non-JSON body is
+  // returned as a classified transport failure instead of an uncaught exit 1.
   const send = async (resolved) => {
     const headers = { "Content-Type": "application/json", ...resolved.auth };
-    const res = await fetchImpl(await requestEndpoint(resolved, { tenant, resolvePin }), { method: "POST", headers, body: JSON.stringify(body) });
-    return { status: res.status, data: await res.json() };
+    let res;
+    try {
+      res = await fetchImpl(await requestEndpoint(resolved, { tenant, resolvePin }), { method: "POST", headers, body: JSON.stringify(body) });
+    } catch (transportError) {
+      return { status: null, data: null, transportError };
+    }
+    try {
+      return { status: res.status, data: await res.json() };
+    } catch (parseError) {
+      return { status: res.status, data: null, parseError };
+    }
   };
 
-  const first = auth ? { auth, source: null } : await authHeader(toolName, { resolveAuth });
-  let { status, data } = await send(first);
+  const first = auth ? { auth, source: null } : await authHeader(toolName, { resolveAuth, exitCode: CALL_EXIT.AUTH });
+  let exchange = await send(first);
   let staleSession = false;
-  if (!auth && isRejectedCachedSessionResponse(first, status, data)) {
+  if (!auth && isRejectedCachedSessionResponse(first, exchange.status, exchange.data)) {
     const durable = await resolveAuth({ toolName, preferSession: false });
-    if (durable.auth) ({ status, data } = await send(durable));
+    if (durable.auth) exchange = await send(durable);
     else staleSession = true;
   }
+  const { status, data } = exchange;
   const exportedRejected = !auth && (first.source === "env" || first.source === "flag")
     && (status === 401 || status === 403 || data?.error?.code === -32001);
 
+  const code = data?.error?.data?.code;
+  const hint = code === "MCP_TENANT_PIN_REQUIRED"
+    ? ` Pin a tenant: ${cyan("botbuddy call <tool> --pin <slug>")}, ${cyan("BOTBUDDY_TENANT=<slug>")}, or run from a repo with ${dim(".botbuddy-agent.json")}.`
+    : staleSession
+      ? ` The cached agent session in this checkout was rejected; run ${cyan("bb doctor --fix")} here.`
+      : exportedRejected
+        ? ` The exported agent session token was rejected; unset ${cyan("BOTBUDDY_AGENT_SESSION_TOKEN")} (and its legacy aliases) to use this checkout's session or your login.`
+        : "";
+
+  const outcome = classifyCallResponse(exchange);
+  if (outcome.kind === "auth") {
+    log(JSON.stringify(outcome.receipt, null, 2));
+    errorLog(`${red("✗")} ${authFailureLine(outcome.receipt)}${hint}`);
+    return CALL_EXIT.AUTH;
+  }
+  if (outcome.kind === "transport") {
+    log(JSON.stringify(outcome.receipt, null, 2));
+    errorLog(`${red("✗")} BotBuddy unreachable (${outcome.receipt.error_code}${outcome.receipt.http_status ? `, HTTP ${outcome.receipt.http_status}` : ""}): ${outcome.receipt.message ?? ""}`);
+    return CALL_EXIT.TRANSPORT;
+  }
+  if (outcome.kind === "http_error") {
+    log(JSON.stringify(outcome.receipt, null, 2));
+    errorLog(`${red("✗")} BotBuddy answered HTTP ${outcome.receipt.http_status ?? "?"} (${outcome.receipt.error_code}); not treating this as unreachable.${hint}`);
+    return CALL_EXIT.ERROR;
+  }
   if (data.error?.message) {
-    const code = data.error?.data?.code;
-    const hint = code === "MCP_TENANT_PIN_REQUIRED"
-      ? ` Pin a tenant: ${cyan("botbuddy call <tool> --pin <slug>")}, ${cyan("BOTBUDDY_TENANT=<slug>")}, or run from a repo with ${dim(".botbuddy-agent.json")}.`
-      : staleSession
-        ? ` The cached agent session in this checkout was rejected; run ${cyan("bb doctor --fix")} here.`
-        : exportedRejected
-          ? ` The exported agent session token was rejected; unset ${cyan("BOTBUDDY_AGENT_SESSION_TOKEN")} (and its legacy aliases) to use this checkout's session or your login.`
-          : "";
     die(`Server error: ${data.error.message}${hint}`);
   }
 
@@ -260,13 +424,21 @@ export async function callToolJson(toolName, args = {}, { fetchImpl = fetch, sig
     // { error: { code: -32002, data: { code } } }). Surface that `code` so a
     // caller can tell a tenant refusal apart from a plain credential failure.
     // Best-effort: an opaque/bodyless 401/403 keeps the generic shape.
+    // BOT-1896: the unauthenticated 401 now carries a typed code too
+    // (credential_unknown / session_token_revoked / …). Those are exposed as
+    // `error_code` but NOT lifted into `code`, which callers (mcp-key,
+    // isRejectedCachedMcpSession) read as "a structured refusal other than a dead
+    // credential" — so a bad key keeps its not-authenticated / self-heal path.
     let code = null;
+    let errorCode = null;
     try {
       const body = await res.json();
       const raw = body?.error?.data?.code ?? body?.error?.code ?? body?.code ?? null;
-      if (typeof raw === "string" && raw) code = raw;
+      if (typeof raw === "string" && raw && !UNAUTHENTICATED_CODES.has(raw)) code = raw;
+      const typed = body?.error?.data?.error_code ?? body?.error_code ?? null;
+      if (typeof typed === "string" && typed) errorCode = typed;
     } catch { /* opaque body */ }
-    return { ok: false, auth: true, status: res.status, error: "unauthorized", ...(code ? { code } : {}) };
+    return { ok: false, auth: true, status: res.status, error: "unauthorized", ...(code ? { code } : {}), ...(errorCode ? { error_code: errorCode } : {}) };
   }
   let payload;
   try { payload = await res.json(); } catch { return { ok: false, status: res.status, error: "invalid_json" }; }

package/src/commands.mjs

@@ -28,13 +28,16 @@ import { attestTelemetryCredential, loadTelemetryIdentity, loadTelemetryLocation
 import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
 import { doctorAgentAuth, doctorHelp, parseDoctorArgs } from "./agent-doctor.mjs";
 import { clearAgentState, selfHealAgentSession } from "./agent-session.mjs";
+import { runUsage, usageStatus } from "./usage/sync.mjs";
+import { installUsageAgent, usageAgentStatus } from "./usage/launchd.mjs";
 
 // BOT-1566 D2: the stale-CLI check runs for every command EXCEPT `wait` and any
 // invocation carrying `--json` — those are hot paths whose receipts (BOT-1229)
-// must not pay for a registry round-trip.
+// must not pay for a registry round-trip. BOT-1023: nor may `usage`, which
+// runs inside every `git push` under a 5 s budget.
 export function shouldCheckForUpdates(argv) {
   const [command] = argv;
-  if (command === "wait" || command === "telemetry") return false;
+  if (command === "wait" || command === "telemetry" || command === "usage") return false;
   if (argv.includes("--json")) return false;
   return true;
 }
@@ -77,6 +80,16 @@ export async function run(argv, {
     case "docker": return cmdDocker(args);
     case "run": return cmdRun(args);
     case "telemetry": return cmdTelemetry(args);
+    // BOT-803: local Claude/Codex token usage → usage-ingest (fail-open).
+    case "usage": {
+      const code = await runUsage(args, { deps: { cliVersion: VERSION } });
+      // The run is bounded by --max-seconds, but a credential or socket call it
+      // abandoned at the deadline can keep the event loop alive for minutes
+      // (a pre-push lane would stall). An unref'd timer only fires when
+      // something is still lingering; a clean run exits on its own first.
+      setTimeout(() => process.exit(code), 250).unref();
+      return code;
+    }
     case "test": return cmdTest(args);
     case "wait": return runWait(args);
     case "pw": return runPw(args);
@@ -198,6 +211,11 @@ ${bold("DURABLE WORKLOADS")}
   telemetry <status|replay|doctor>
                               Inspect, replay, or gate durable lifecycle delivery
 
+${bold("USAGE INGEST")}
+  usage sync [--since 2d] [--provider claude|codex|all] [--file <transcript>] [--dry-run] [--quiet]
+                              Send local Claude/Codex token usage (counters only, no prompts)
+  usage status                Last sync runs and tracked transcripts
+
 ${bold("AGENT WAITS")}
   wait [--any] <condition>... [options]
                               Wait once for a pushed BotBuddy signal
@@ -216,13 +234,18 @@ ${bold("OTHER")}
 ${SETUP_BLOCK}`);
 }
 
-export async function cmdDoctor(args, { log = (line) => console.log(line), errorLog = (line) => console.error(line) } = {}) {
+export async function cmdDoctor(args, {
+  log = (line) => console.log(line), errorLog = (line) => console.error(line),
+  doctor = doctorAgentAuth, usageReport = doctorUsageSync,
+} = {}) {
   const parsed = parseDoctorArgs(args);
   if (parsed.help) { log(doctorHelp()); return 0; }
   if (parsed.errors.length) { errorLog(`bb doctor: ${parsed.errors.join("; ")}`); return 4; }
-  const result = await doctorAgentAuth({ fix: parsed.fix, printExports: parsed.printExports });
+  const result = await doctor({ fix: parsed.fix, printExports: parsed.printExports });
+  // BOT-1021: informational only — never changes doctor's exit code.
+  const usage = await usageReport().catch(() => null);
   if (parsed.json) {
-    log(JSON.stringify(result.report));
+    log(JSON.stringify(usage ? { ...result.report, usage_sync: usage } : result.report));
   } else {
     log(`binding: ${result.report.binding.status}${result.report.binding.tenant ? ` (${result.report.binding.tenant})` : ""}`);
     log(`client key: ${result.report.client_key.status}`);
@@ -233,11 +256,33 @@ export async function cmdDoctor(args, { log = (line) => console.log(line), error
       log(`stack lease: ${sl.capability} (host ${sl.host}, machine id ${sl.machine_id_readable ? "readable" : "unavailable"})${sl.reason ? ` — ${sl.reason}` : ""}`);
     }
     if (result.report.recovery) log(`recovery: ${result.report.recovery}`);
+    if (usage) log(formatUsageSyncLine(usage));
   }
   if (result.exports) log(result.exports);
   return result.exitCode;
 }
 
+/** BOT-1021: is the daily sweep installed, and how did the last sync runs go? */
+export async function doctorUsageSync({ agentStatus = usageAgentStatus, status = usageStatus } = {}) {
+  const agent = await agentStatus();
+  const { last_runs: runs = [] } = await status({ limit: 20 });
+  const pick = (run) => (run ? { at: run.at, outcome: run.outcome, ...(run.error ? { error: run.error } : {}) } : null);
+  return {
+    daily_agent: agent.supported ? (agent.installed ? "installed" : "not_installed") : "unsupported",
+    last_daily_run: pick(runs.find((run) => run.trigger === "daily")),
+    last_run: pick(runs[0]),
+  };
+}
+
+export function formatUsageSyncLine(usage) {
+  const last = usage.last_daily_run ?? usage.last_run;
+  const lastText = last ? `last ${usage.last_daily_run ? "daily " : ""}run ${last.outcome}${last.error ? ` (${last.error})` : ""} at ${last.at}` : "no runs yet";
+  const agentText = usage.daily_agent === "installed" ? "daily agent installed"
+    : usage.daily_agent === "unsupported" ? "daily agent n/a (launchd is macOS-only)"
+      : "daily agent NOT installed — run bb setup";
+  return `usage sync: ${agentText}; ${lastText}`;
+}
+
 // ─── BOT-876: generic tool access ───────────────────────────────
 
 async function cmdCall(args) {
@@ -425,6 +470,7 @@ export async function cmdSetup(args, {
   clearState = clearAgentState,
   selfHeal = selfHealAgentSession,
   callerResolver = resolveCaller,
+  usageAgent = installUsageAgent,
   cwd = process.cwd(),
   env = process.env,
   log = (line) => console.log(line),
@@ -485,6 +531,7 @@ export async function cmdSetup(args, {
       return 5;
     }
     log(`bb setup: ${tenant} is ready (${session.source} worktree session). Run bb wait '<condition>'.`);
+    await reportUsageAgent(usageAgent, { cwd, log });
     return 0;
   } catch (error) {
     errorLog(`bb setup: could not prepare this worktree (${error?.code ?? "setup_failed"}). Retry bb setup after completing sign-in.`);
@@ -492,6 +539,17 @@ export async function cmdSetup(args, {
   }
 }
 
+// BOT-1021: setup also (re)installs the daily usage sweep. Never fails setup —
+// the worktree session is ready either way; the line says what happened.
+async function reportUsageAgent(usageAgent, { cwd, log }) {
+  let result;
+  try { result = await usageAgent({ cwd }); } catch (error) { result = { status: "failed", error: error?.code ?? "install_failed" }; }
+  if (result?.status === "installed") log("bb setup: daily usage sync installed (ai.botbuddy.usage-sync, 03:10 local).");
+  else if (result?.status === "unchanged") log("bb setup: daily usage sync already installed (ai.botbuddy.usage-sync).");
+  else if (result?.status === "unsupported") log(`bb setup: daily usage sync skipped — ${result.notice}.`);
+  else log(`bb setup: daily usage sync could not be installed (${result?.error ?? "unknown"}); run bb setup again to retry.`);
+}
+
 export function loginHelp(log = console.log) {
   log(`${bold("botbuddy login")} — authenticate via OAuth (browser + loopback callback)
 

package/src/stack.mjs

@@ -27,7 +27,7 @@ import { open, unlink, readFile } from "fs/promises";
 import { tmpdir } from "os";
 import { basename, dirname, join, relative, isAbsolute } from "path";
 import { randomUUID } from "crypto";
-import { callToolJson } from "./api.mjs";
+import { callToolJson, CALL_AUTH_ERROR_CODES } from "./api.mjs";
 import { SERVER_URL, getConfig } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
 import { AGENT_KEY_RE, readAgentSessionTokenEnv } from "./agent-key.mjs";
@@ -696,6 +696,9 @@ export function stackPathRootRefusalNotice(code, message) {
  * reads as "the control plane is unhealthy, retry". Every other refusal keeps BACKEND (5).
  */
 export function leaseRefusalExit(code) {
+  // BOT-1896: an auth-class refusal (scope_denied, a tenant mismatch, …) is the
+  // server refusing the credential — never BACKEND, which a gate reads as "down".
+  if (CALL_AUTH_ERROR_CODES.has(code)) return EXIT.AUTH;
   return code === STACK_PATH_ROOT_REFUSED_CODE ? EXIT.INVALID : EXIT.BACKEND;
 }
 

package/src/usage/claude.mjs

@@ -0,0 +1,157 @@
+// BOT-803 — Claude Code transcript adapter (`~/.claude/projects/**/*.jsonl`).
+//
+// Verified on real transcripts (PoC report, 2026-09-28):
+//   * one API message fans out into several JSONL records that share
+//     `message.id` + `requestId` with identical usage. The server keys tokens on
+//     (provider, harness_session_id, message_id), first record wins — this
+//     matches the harness's own `cost-state` counters exactly;
+//   * `tool_use` blocks are split across those records, so the adapter emits ONE
+//     envelope per message whose tool_call_count is summed over the message's
+//     DISTINCT record uuids (the server stores, never sums, it — BOT-1019);
+//   * subagent transcripts live in `<session>/subagents/agent-*.jsonl`, reuse
+//     the parent sessionId, carry `isSidechain: true` and `stop_reason: null`
+//     with a stream-start output_tokens placeholder → usage_final false, partial;
+//   * `gitBranch` can be the literal "HEAD" and `cwd` can change mid-session, so
+//     the ticket key is inferred per message;
+//   * `cost-state` carries per-model cumulative `modelUsage` and no timestamp.
+//     BOT-1019's table has no row kind to hold it, and as a plain row it would
+//     double-count, so those records are counted and WITHHELD (never sent) until
+//     the server grows a reconciliation surface.
+//
+// Because the first record to reach the server wins, a message whose records
+// are still being written must not be sent early: the trailing message of a
+// live file is held back (the cursor stops at its first record) until it gains
+// a final record, a later message starts, or the file goes quiet.
+import {
+  finalizeEnvelope, inferTicketKey, modelLabel, safeLabel, str, tok, usageQuality, uuid, withRoute,
+} from "./envelope.mjs";
+
+export const CLAUDE_PROVIDER = "claude";
+export const CLAUDE_PARSER_VERSION = "claude-1";
+
+function countToolUses(content) {
+  if (!Array.isArray(content)) return 0;
+  let n = 0;
+  for (const block of content) if (block && block.type === "tool_use") n += 1;
+  return n;
+}
+
+const classesOf = (usage) => ({
+  input_tokens: tok(usage?.input_tokens),
+  output_tokens: tok(usage?.output_tokens),
+  cache_creation_input_tokens: tok(usage?.cache_creation_input_tokens),
+  cache_read_input_tokens: tok(usage?.cache_read_input_tokens),
+});
+
+/**
+ * @param {object} opts
+ * @param {(value: string) => string} opts.hmac   keyed HMAC of a local path
+ * @param {string} opts.environment                 'local' | 'cloud'
+ * @param {(cwd: string) => string|null} [opts.repoFor]  cwd → GitHub owner/name
+ * @param {(cwd: string|null) => string|null} [opts.tenantFor]  cwd → tenant bound to its checkout
+ */
+export function createClaudeAdapter({ hmac, environment, repoFor = () => null, tenantFor = () => null }) {
+  return {
+    provider: CLAUDE_PROVIDER,
+    parserVersion: CLAUDE_PARSER_VERSION,
+    /**
+     * One file's parser. `ctx` is per-file state persisted in the cursor (only
+     * derived, privacy-safe values).
+     */
+    beginFile({ sourceHmac, ctx }) {
+      const groups = new Map();
+      let lastKey = null;
+      const stats = { refused: 0, withheld: 0 };
+      return {
+        stats,
+        parseRecord(record, offset) {
+          if (!record || typeof record !== "object") return;
+          if (typeof record.timestamp === "string") ctx.last_ts = record.timestamp;
+          if (uuid(record.sessionId)) ctx.session_id = record.sessionId;
+
+          if (record.type === "cost-state" && record.modelUsage && typeof record.modelUsage === "object") {
+            stats.withheld += Object.keys(record.modelUsage).length;
+            return;
+          }
+          const msg = record.message;
+          if (record.type !== "assistant" || !msg || typeof msg !== "object" || !msg.usage || typeof msg.usage !== "object") return;
+          const messageId = str(msg.id);
+          // A record without a sessionId inherits the file's; a malformed one is refused.
+          const sessionId = record.sessionId === undefined ? ctx.session_id ?? null : uuid(record.sessionId);
+          // NULLs never conflict in a unique index — refuse rather than duplicate.
+          if (!messageId || !sessionId) { stats.refused += 1; return; }
+
+          const key = `${sessionId}\u0000${messageId}`;
+          let group = groups.get(key);
+          if (!group) {
+            if (lastKey && groups.has(lastKey)) groups.get(lastKey).closed = true; // a new API response began
+            const cwd = str(record.cwd);
+            const gitBranch = safeLabel(record.gitBranch);
+            group = {
+              offset, closed: false, final: false, toolCalls: 0, uuids: new Set(),
+              sessionId, messageId,
+              requestId: str(record.requestId), recordUuid: uuid(record.uuid), occurredAt: str(record.timestamp),
+              model: modelLabel(msg.model), version: safeLabel(record.version), isSidechain: record.isSidechain === true,
+              gitBranch, cwd, usage: classesOf(msg.usage),
+            };
+            groups.set(key, group);
+          }
+          const recordId = str(record.uuid);
+          if (!recordId || !group.uuids.has(recordId)) {
+            if (recordId) group.uuids.add(recordId);
+            group.toolCalls += countToolUses(msg.content);
+          }
+          if (msg.stop_reason !== null && msg.stop_reason !== undefined) {
+            group.final = true;
+            group.closed = true;
+            group.usage = classesOf(msg.usage); // the final record's usage is authoritative
+          }
+          lastKey = key;
+        },
+        /** @returns {{ envelopes: object[], holdOffset: number|null }} */
+        finish({ quiescent }) {
+          const envelopes = [];
+          let holdOffset = null;
+          for (const group of groups.values()) {
+            if (!group.closed && !quiescent) {
+              holdOffset = holdOffset === null ? group.offset : Math.min(holdOffset, group.offset);
+              continue;
+            }
+            envelopes.push(envelopeFor(group));
+          }
+          // Anything after a held message is re-read with it next time.
+          return { envelopes: holdOffset === null ? envelopes : envelopes.filter((e) => e.source_offset < holdOffset), holdOffset };
+        },
+      };
+
+      function envelopeFor(group) {
+        const ticket = inferTicketKey(group.gitBranch, group.cwd);
+        const usage = group.usage;
+        return withRoute(finalizeEnvelope({
+          provider: CLAUDE_PROVIDER,
+          provider_schema_version: group.version,
+          harness_session_id: group.sessionId,
+          request_id: group.requestId,
+          message_id: group.messageId,
+          record_uuid: group.recordUuid,
+          occurred_at: group.occurredAt,
+          model: group.model,
+          ...usage,
+          tool_call_count: group.toolCalls,
+          is_sidechain: group.isSidechain,
+          usage_final: group.final,
+          usage_quality: usageQuality({ usageFinal: group.final, classes: Object.values(usage) }),
+          git_branch: group.gitBranch,
+          repo: group.cwd ? repoFor(group.cwd) : null,
+          ticket_key_inferred: ticket,
+          attribution_confidence: ticket ? "inferred" : null,
+          environment,
+          cwd_hmac: group.cwd ? hmac(group.cwd) : null,
+          source_hmac: sourceHmac,
+          source_offset: group.offset,
+          parser_version: CLAUDE_PARSER_VERSION,
+        }), group.cwd ? tenantFor(group.cwd) : null);
+      }
+    },
+  };
+}