@botbuddy/cli 1.34.0 → 1.34.2

package/src/usage/sync.mjs

@@ -0,0 +1,725 @@
+// BOT-803 / BOT-1021 / BOT-1023 — `bb usage sync`: enumerate local Claude Code
+// and Codex transcripts, parse only what changed since each file's cursor into
+// allowlisted envelopes, and POST them to `usage-ingest` in batches of ≤500.
+//
+// One code path serves every trigger (daily launchd sweep, lefthook pre-push,
+// the cloud Stop hook, manual backfill). The server's idempotency key makes any
+// overlap between triggers a no-op, and the local cursor makes a repeat run cheap.
+//
+// Output contract: exactly one JSON receipt line (suppressed by --quiet on
+// success). It carries row COUNTS only — never paths, never prompt text, never
+// token totals. Fail-open: any failure exits 0 unless --strict.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { homedir, hostname as systemHostname } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import { AGENT_BINDING_FILE, parseAgentBinding } from "../wait-profile.mjs";
+import { createClaudeAdapter } from "./claude.mjs";
+import { createCodexAdapter } from "./codex.mjs";
+import { envelopeRefusal, hmac as hmacWith, loadHmacKey, normalizeRepo, privacySelfCheck } from "./envelope.mjs";
+import { cursorPath, loadCursorState, readCompleteLines, saveCursorState } from "./cursor.mjs";
+
+export const BATCH_SIZE = 500;
+export const PROVIDERS = Object.freeze(["claude", "codex"]);
+// The server's `ingestion_runs.trigger` values (BOT-1019).
+export const TRIGGERS = Object.freeze(["manual", "pre_push", "daily", "cloud_stop", "cloud_session_start"]);
+// A live file whose trailing message has no final record yet is held back until
+// it has been quiet this long (or the trigger is the end-of-turn cloud Stop).
+export const QUIESCENT_MS = 5 * 60 * 1000;
+const DEFAULT_SINCE = "2d";
+const DEFAULT_MAX_SECONDS = 60;
+// Stop reading new data at this fraction of the budget, leaving the rest for the POST.
+const PARSE_BUDGET_FRACTION = 0.7;
+// flush() sentinel: the deadline passed before a batch could start (not an error).
+const OUT_OF_TIME = Symbol("out_of_time");
+const DEFAULT_SERVER_URL = "https://api.bot-buddy.ai/functions/v1/mcp-server";
+
+export class UsageUsageError extends Error {}
+
+export function parseDuration(text) {
+  const match = /^(\d+)\s*([smhdw])$/i.exec(String(text ?? "").trim());
+  if (!match) return null;
+  const unit = { s: 1, m: 60, h: 3600, d: 86400, w: 604800 }[match[2].toLowerCase()];
+  return Number(match[1]) * unit * 1000;
+}
+
+export function parseSyncArgs(argv = []) {
+  const opts = {
+    since: DEFAULT_SINCE, sinceMs: parseDuration(DEFAULT_SINCE), provider: "all", dryRun: false, quiet: false,
+    file: null, maxSeconds: DEFAULT_MAX_SECONDS, strict: false, trigger: "manual", rescan: false, allTenants: false, help: false,
+  };
+  const value = (i, flag) => {
+    const v = argv[i + 1];
+    if (v === undefined || v.startsWith("--")) throw new UsageUsageError(`${flag} requires a value`);
+    return v;
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--since") { opts.since = value(i, arg); opts.sinceMs = parseDuration(opts.since); i += 1; if (opts.sinceMs === null) throw new UsageUsageError("--since must look like 2d, 12h, 30m, 1w"); }
+    else if (arg === "--provider") { opts.provider = value(i, arg); i += 1; if (![...PROVIDERS, "all"].includes(opts.provider)) throw new UsageUsageError("--provider must be claude, codex, or all"); }
+    else if (arg === "--file") { opts.file = value(i, arg); i += 1; }
+    else if (arg === "--max-seconds") { opts.maxSeconds = Number(value(i, arg)); i += 1; if (!Number.isFinite(opts.maxSeconds) || opts.maxSeconds <= 0) throw new UsageUsageError("--max-seconds must be a positive number"); }
+    else if (arg === "--trigger") { opts.trigger = value(i, arg); i += 1; if (!TRIGGERS.includes(opts.trigger)) throw new UsageUsageError(`--trigger must be one of ${TRIGGERS.join(", ")}`); }
+    else if (arg === "--dry-run") opts.dryRun = true;
+    else if (arg === "--quiet") opts.quiet = true;
+    else if (arg === "--strict") opts.strict = true;
+    else if (arg === "--rescan") opts.rescan = true;
+    else if (arg === "--all-tenants") opts.allTenants = true;
+    else if (arg === "--help" || arg === "-h") opts.help = true;
+    else throw new UsageUsageError(`unknown option: ${arg}`);
+  }
+  return opts;
+}
+
+export function usageIngestEndpoint(serverUrl = DEFAULT_SERVER_URL) {
+  const url = new URL(serverUrl);
+  url.pathname = url.pathname.replace(/\/mcp-server\/?$/, "/usage-ingest");
+  return url.toString();
+}
+
+export function transcriptRoots(env = process.env, home = homedir()) {
+  return {
+    claude: join(env.CLAUDE_CONFIG_DIR || join(home, ".claude"), "projects"),
+    codex: join(env.CODEX_HOME || join(home, ".codex"), "sessions"),
+  };
+}
+
+/**
+ * Every *.jsonl under `root` (recursively — subagent transcripts live in
+ * subdirectories) modified since `cutoffMs`. `shouldStop` is checked before
+ * every directory read and stat, so a huge history or a slow filesystem cannot
+ * outlive the run's time budget (the pre-push lane runs with 5 s).
+ * @returns {Promise<{ files: string[], stopped: boolean }>}
+ */
+export async function listTranscripts(root, cutoffMs, { shouldStop = () => false, keep = () => false } = {}) {
+  const out = [];
+  let stopped = false;
+  const halt = () => (stopped = stopped || shouldStop());
+  async function walk(dir) {
+    if (halt()) return;
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (halt()) return;
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) await walk(path);
+      else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+        try {
+          const info = await stat(path);
+          if (info.mtimeMs >= cutoffMs || keep(path, info)) out.push(path);
+        } catch { /* vanished between readdir and stat */ }
+      }
+    }
+  }
+  await walk(root);
+  return { files: out, stopped };
+}
+
+/** Which adapter owns a single `--file`: under a Codex root, or a rollout whose first record is session_meta. */
+/** The adapter a path's location names (under a known root), else null. */
+export function providerByPath(path, roots) {
+  const abs = resolve(path);
+  if (abs.startsWith(resolve(roots.codex) + sep)) return "codex";
+  if (abs.startsWith(resolve(roots.claude) + sep)) return "claude";
+  return null;
+}
+
+export function detectProvider(path, roots, firstLine = "") {
+  const abs = resolve(path);
+  if (abs.startsWith(resolve(roots.codex) + sep)) return "codex";
+  if (abs.startsWith(resolve(roots.claude) + sep)) return "claude";
+  try {
+    const record = JSON.parse(firstLine);
+    if (record?.type === "session_meta" && record.payload) return "codex";
+  } catch { /* fall through */ }
+  return "claude";
+}
+
+// Variables that relocate git away from `-C <cwd>` (mirrors scripts/lib/git-env.mjs,
+// BOT-1802). A git hook — the pre-push lane runs inside lefthook — exports them
+// for the pushing repo, which would otherwise answer for every transcript.
+const GIT_REPOSITORY_ENV = Object.freeze([
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_COMMON_DIR", "GIT_DIR", "GIT_INDEX_FILE",
+  "GIT_OBJECT_DIRECTORY", "GIT_PREFIX", "GIT_WORK_TREE",
+]);
+
+/** cwd → GitHub owner/name via the checkout's origin remote; cached, 1 s bounded, null on any failure. */
+export function createRepoResolver({ exec = execFileSync, env = process.env } = {}) {
+  const gitEnv = { ...env };
+  for (const name of GIT_REPOSITORY_ENV) delete gitEnv[name];
+  const cache = new Map();
+  return (cwd) => {
+    if (cache.has(cwd)) return cache.get(cwd);
+    let repo = null;
+    try {
+      const url = exec("git", ["-C", cwd, "config", "--get", "remote.origin.url"], {
+        encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"], env: gitEnv,
+      });
+      repo = normalizeRepo(String(url).trim());
+    } catch { repo = null; }
+    cache.set(cwd, repo);
+    return repo;
+  };
+}
+
+/**
+ * cwd → the tenant bound to its checkout (BOT-1902 tenant routing), or null
+ * when unbound. The binding is the checkout's committed `.botbuddy-agent.json`:
+ * the working-tree file at the git toplevel, else (a missing or retired
+ * `{ profile }` file, e.g. a stale main checkout) the copy committed at
+ * origin/HEAD or origin/main. A deleted worktree resolves through its nearest
+ * existing ancestor. Synchronous and cached per cwd and per toplevel; every
+ * git child runs with the repository-location variables stripped.
+ */
+export function createTenantResolver({ exec = execFileSync, env = process.env, exists = existsSync, read = readFileSync } = {}) {
+  const gitEnv = { ...env };
+  for (const name of GIT_REPOSITORY_ENV) delete gitEnv[name];
+  // `-c core.fsmonitor=false`: these checkouts are read, never trusted to run a
+  // configured fsmonitor hook (none of these commands needs the index anyway).
+  const git = (cwd, args) => String(exec("git", ["-c", "core.fsmonitor=false", "-C", cwd, ...args], {
+    encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"], env: gitEnv,
+  })).trim();
+  const tenantOf = (raw) => { try { return parseAgentBinding(raw).tenant; } catch { return null; } };
+  const byCwd = new Map();
+  const byTop = new Map();
+  const forTop = (top) => {
+    if (byTop.has(top)) return byTop.get(top);
+    let tenant = null;
+    try { tenant = tenantOf(read(join(top, AGENT_BINDING_FILE), "utf8")); } catch { tenant = null; }
+    for (const ref of ["origin/HEAD", "origin/main"]) {
+      if (tenant) break;
+      // cat-file: raw blob bytes — never a textconv/filter program the checkout configured.
+      try { tenant = tenantOf(git(top, ["cat-file", "blob", `${ref}:${AGENT_BINDING_FILE}`])); } catch { tenant = null; }
+    }
+    byTop.set(top, tenant);
+    return tenant;
+  };
+  return (cwd) => {
+    if (typeof cwd !== "string" || !cwd) return null;
+    if (byCwd.has(cwd)) return byCwd.get(cwd);
+    let dir = cwd;
+    while (dir && !exists(dir)) { const up = dirname(dir); dir = up === dir ? null : up; }
+    let tenant = null;
+    if (dir) {
+      let top = null;
+      try { top = git(dir, ["rev-parse", "--show-toplevel"]) || null; } catch { top = null; }
+      if (top) tenant = forTop(top);
+    }
+    byCwd.set(cwd, tenant);
+    return tenant;
+  };
+}
+
+const TENANT_SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/**
+ * The tenant this run posts for: an explicit BOTBUDDY_TENANT, else the binding
+ * of the checkout the command runs in, else the login's sole tenant. null →
+ * the run fails closed (tenant_unresolved).
+ */
+export async function defaultResolveTarget({ cwd, env, tenantFor }) {
+  const explicit = typeof env.BOTBUDDY_TENANT === "string" ? env.BOTBUDDY_TENANT.trim() : "";
+  if (explicit) return TENANT_SLUG_RE.test(explicit) ? explicit : null;
+  const bound = tenantFor(cwd);
+  if (bound) return bound;
+  try {
+    const { loadConfig, getConfig } = await import("../config.mjs");
+    await loadConfig({ warn: () => {} });
+    const tenants = Array.isArray(getConfig()?.token_tenants) ? getConfig().token_tenants.filter((t) => typeof t === "string" && t) : [];
+    return tenants.length === 1 ? tenants[0] : null;
+  } catch {
+    return null;
+  }
+}
+
+export function usageEnvironment(env = process.env) {
+  return env.CLAUDE_CODE_REMOTE === "true" ? "cloud" : "local";
+}
+
+/**
+ * The same credential `bb wait` uses: an exported/cached tier-3 session token,
+ * self-healed from the durable client key when the cache is stale; otherwise
+ * the durable owner key (pinned to a tenant) or MCP key.
+ */
+export async function defaultResolveAuth({ cwd, env, target, preferOwner = false }, impl = {}) {
+  const resolveSession = impl.resolveSession ?? (async (args) => (await import("../agent-session.mjs")).resolveAgentSessionCredential(args));
+  const resolveCall = impl.resolveCall ?? (async (args) => (await import("../api.mjs")).resolveCallAuth(args));
+  // The durable client key's scope (BOT-1571): `user` reaches any member tenant
+  // by pin; `tenant` is SEALED to token_tenant_id and must never be re-pinned.
+  const ownerScope = impl.ownerScope ?? (async () => {
+    const { getConfig } = await import("../config.mjs");
+    const cfg = getConfig() ?? {};
+    return { tenantMode: cfg.token_tenant_mode === "tenant" ? "tenant" : "user", tenantId: typeof cfg.token_tenant_id === "string" ? cfg.token_tenant_id : null };
+  });
+  // usage-ingest reads every credential kind from `Authorization: Bearer` (BOT-1019).
+  const bearer = (token) => ({ Authorization: `Bearer ${token}` });
+  // --all-tenants pins each pass to its tenant with the multi-tenant client key;
+  // a worktree session belongs to one tenant, so it is not consulted then.
+  if (!preferOwner) try {
+    const session = await resolveSession({ argv: [], env, cwd, warn: () => {} });
+    if (session?.token) {
+      // A session token writes to ITS session's tenant. Only a cached or freshly
+      // minted worktree session has a known tenant; an exported/flag token does
+      // not, so it is reported unknown and the run refuses it (fail closed).
+      let credentialTenant = null;
+      if (session.source === "cache" || session.source === "minted") {
+        const { readAgentState } = await import("../agent-state.mjs");
+        credentialTenant = (await readAgentState(cwd).catch(() => null))?.tenant ?? null;
+      }
+      return { headers: bearer(session.token), tenant: null, credentialTenant, source: session.source };
+    }
+  } catch { /* no binding / no client key: try the durable credential */ }
+  const resolved = await resolveCall({ env, cwd });
+  if (resolved.error) return { error: resolved.error.error ?? "not_authenticated" };
+  // An MCP key's tenant is not knowable client-side: refused (fail closed).
+  if (resolved.auth["x-agent-api-key"]) return { headers: bearer(resolved.auth["x-agent-api-key"]), tenant: null, credentialTenant: null, source: resolved.source };
+  const scope = await ownerScope();
+  if (scope.tenantMode === "tenant") {
+    // Sealed: report ITS tenant, so a run for any other tenant refuses it.
+    return { headers: resolved.auth, tenant: null, credentialTenant: scope.tenantId, source: resolved.source };
+  }
+  // A user (client) key reaches several tenants: it names the run's tenant as
+  // the body `tenant` scope request; the server still verifies membership.
+  return { headers: resolved.auth, tenant: target, credentialTenant: target, source: resolved.source };
+}
+
+async function postBatch({ endpoint, headers, tenant, run, envelopes, fetchImpl, timeoutMs }) {
+  const sent = envelopes.length;
+  let response;
+  try {
+    response = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...headers },
+      body: JSON.stringify({ ...(tenant ? { tenant } : {}), run, records: envelopes }),
+      // Only the time actually left in the run (the caller never starts past the deadline).
+      signal: AbortSignal.timeout(Math.max(1, Math.trunc(timeoutMs))),
+    });
+  } catch (error) {
+    return { ok: false, error: error?.name === "TimeoutError" || error?.name === "AbortError" ? "timeout" : "transport" };
+  }
+  let body = null;
+  try { body = await response.json(); } catch { body = null; }
+  if (response.status < 200 || response.status >= 300) {
+    const code = typeof body?.error === "string" && /^[a-z0-9_.:-]{1,64}$/i.test(body.error) ? body.error : null;
+    return { ok: false, error: code ? `http_${response.status}:${code}` : `http_${response.status}` };
+  }
+  // A 2xx is a delivery only with a well-formed receipt: a truncated/non-JSON
+  // body or missing counters is a retryable protocol error, so the batch stays
+  // queued and no cursor advances past it.
+  const counted = (v) => Number.isFinite(v) && v >= 0;
+  if (!body || typeof body !== "object" || !["seen", "inserted", "deduped", "refused"].every((k) => counted(body[k]))) {
+    return { ok: false, error: "ack_malformed" };
+  }
+  // …and it must account for exactly this batch (BOT-1019: seen = records sent,
+  // inserted + superseded + deduped + refused = seen), or nothing is acknowledged.
+  const superseded = body.superseded === undefined ? 0 : body.superseded;
+  if (!counted(superseded) || body.seen !== sent || body.inserted + superseded + body.deduped + body.refused !== sent) {
+    return { ok: false, error: "ack_malformed" };
+  }
+  const n = (v) => (Number.isFinite(v) && v >= 0 ? Math.trunc(v) : 0);
+  // Per-row refusals (BOT-1019): only the reason CODE is kept, and only when it
+  // is a well-formed code — never an index-aligned value or free text.
+  const refusalReasons = {};
+  if (Array.isArray(body.refusals)) {
+    for (const r of body.refusals) {
+      const reason = typeof r?.reason === "string" && /^[a-z0-9_]{1,64}$/.test(r.reason) ? r.reason : null;
+      // Bounded: at most 16 distinct codes per batch, however the server answers.
+      if (reason && (reason in refusalReasons || Object.keys(refusalReasons).length < 16)) {
+        refusalReasons[reason] = (refusalReasons[reason] ?? 0) + 1;
+      }
+    }
+  }
+  return {
+    ok: true, allRefused: body.status === "failed", refusalReasons,
+    seen: n(body.seen), inserted: n(body.inserted), superseded: n(body.superseded), deduped: n(body.deduped), refused: n(body.refused),
+    run_id: typeof body.run_id === "string" && /^[A-Za-z0-9-]{1,64}$/.test(body.run_id) ? body.run_id : null,
+  };
+}
+
+/**
+ * Run one sync. Pure over its dependencies; the CLI wrapper handles printing,
+ * exit codes, and fail-open.
+ */
+export async function syncUsage(opts, deps = {}) {
+  const {
+    env = process.env, home = homedir(), cwd = process.cwd(), now = () => Date.now(),
+    fetchImpl = fetch, resolveAuth = defaultResolveAuth, hostname = systemHostname,
+    roots = transcriptRoots(env, home), repoFor = createRepoResolver(), cliVersion = "0.0.0",
+    tenantFor = createTenantResolver({ env }), resolveTarget = defaultResolveTarget, readLines = readCompleteLines,
+    serverUrl = env.BOTBUDDY_SERVER_URL || DEFAULT_SERVER_URL, statePath = cursorPath(home),
+  } = deps;
+  const startedMs = now();
+  const deadlineMs = startedMs + opts.maxSeconds * 1000;
+  const parseDeadlineMs = startedMs + opts.maxSeconds * 1000 * PARSE_BUDGET_FRACTION;
+  const startedAt = new Date(startedMs).toISOString();
+  const receipt = {
+    schema_version: 1, command: "usage sync", outcome: "ok", trigger: opts.trigger, dry_run: opts.dryRun,
+    providers: [], files_scanned: 0, files_read: 0, envelopes: 0, batches: 0,
+    tenant: null, skipped_other_tenant: 0, skipped_unbound: 0,
+    seen: 0, inserted: 0, superseded: 0, deduped: 0, refused: 0, refusal_reasons: {}, batches_all_refused: 0,
+    refused_local: 0, parse_errors: 0,
+    held_open_messages: 0, cost_state_withheld: 0,
+    privacy: "pass", budget_exhausted: false, run_ids: [], started_at: startedAt, duration_ms: 0,
+  };
+  const finish = (outcome, error) => {
+    receipt.outcome = outcome;
+    if (error) receipt.error = error;
+    receipt.duration_ms = Math.max(0, now() - startedMs);
+    return receipt;
+  };
+
+  // Tenant routing (BOT-1902): the run posts only transcripts whose checkout is
+  // bound to ITS tenant; with no resolvable tenant it reads nothing (fail closed).
+  const target = await resolveTarget({ cwd, env, tenantFor });
+  if (!target) return finish("error", "tenant_unresolved");
+  receipt.tenant = target;
+
+  const key = await loadHmacKey({ home, create: !opts.dryRun });
+  const hmac = (value) => hmacWith(key, value);
+  const cursorKeyFor = (path) => hmac(`${target}\u0000${resolve(path)}`);
+  const environment = usageEnvironment(env);
+  const state = await loadCursorState(statePath);
+  const cursorUpdates = {};
+
+  // Resolve the work list: one --file, or every provider root.
+  let plan;
+  if (opts.file) {
+    const path = resolve(cwd, opts.file);
+    let firstLine = "";
+    // Only a regular file: opening a FIFO/device would block the run forever.
+    try { if (!(await stat(path)).isFile()) return finish("error", "file_unreadable"); } catch { return finish("error", "file_unreadable"); }
+    // Sniff the first record ONLY when neither --provider nor the path (under a
+    // known transcript root) names the adapter, and never past the run deadline.
+    const byPath = opts.provider === "all" ? providerByPath(path, roots) : opts.provider;
+    if (!byPath) {
+      try {
+        await readLines(path, 0, (line) => { if (!firstLine && line.trim()) firstLine = line; }, {
+          shouldStop: () => firstLine !== "" || now() >= parseDeadlineMs,
+        });
+      } catch { return finish("error", "file_unreadable"); }
+    }
+    const provider = byPath ?? detectProvider(path, roots, firstLine);
+    plan = [{ provider, files: [path] }];
+  } else {
+    const cutoff = startedMs - opts.sinceMs;
+    const wanted = opts.provider === "all" ? PROVIDERS : [opts.provider];
+    plan = [];
+    for (const provider of wanted) {
+      const listed = await listTranscripts(roots[provider], cutoff, {
+        shouldStop: () => now() >= parseDeadlineMs,
+        // A file this tenant has only partly read stays in scope whatever its
+        // mtime: its unread tail would otherwise be lost once it ages out.
+        keep: (path, info) => {
+          const tracked = state.files[cursorKeyFor(path)];
+          return Boolean(tracked && Number.isFinite(tracked.offset) && tracked.offset < info.size);
+        },
+      });
+      if (listed.stopped) receipt.budget_exhausted = true;
+      plan.push({ provider, files: listed.stopped ? [] : listed.files });
+    }
+  }
+
+  let auth = null;
+  const ensureAuth = async () => {
+    if (auth) return auth;
+    const remaining = Math.max(1, deadlineMs - now());
+    auth = await Promise.race([
+      resolveAuth({ cwd, env, target }),
+      new Promise((done) => setTimeout(() => done({ error: "auth_timeout" }), remaining).unref?.()),
+    ]);
+    if (!auth.error && auth.credentialTenant !== target) auth = { error: "credential_tenant_mismatch" };
+    return auth;
+  };
+
+  for (const { provider, files } of plan) {
+    if (!files.length) continue;
+    receipt.providers.push(provider);
+    receipt.files_scanned += files.length;
+    const adapter = provider === "codex"
+      ? createCodexAdapter({ hmac, environment, tenantFor, repoFor })
+      : createClaudeAdapter({ hmac, environment, repoFor, tenantFor });
+    const run = {
+      host: hostname(), trigger: opts.trigger, provider, cli_version: cliVersion,
+      parser_version: adapter.parserVersion, started_at: startedAt,
+    };
+
+    // Envelopes are queued with a global sequence; a file's cursor commits only
+    // once every envelope it produced has been accepted by the server.
+    let queue = [];
+    let postedSeq = 0;
+    let enqueuedSeq = 0;
+    const parsedFiles = []; // { cursorKey, entry, endSeq }
+
+    const commitDelivered = () => {
+      while (parsedFiles.length && parsedFiles[0].endSeq <= postedSeq) {
+        const done = parsedFiles.shift();
+        cursorUpdates[done.cursorKey] = done.entry;
+      }
+    };
+    const flush = async (count) => {
+      const batch = queue.slice(0, count);
+      const privacy = privacySelfCheck(batch);
+      if (!privacy.pass) {
+        receipt.privacy = "fail";
+        receipt.privacy_fields = privacy.violations.map((v) => v.field);
+        return "privacy_check_failed";
+      }
+      if (opts.dryRun) {
+        receipt.batches += 1;
+      } else {
+        // Never START a request once the run's deadline has passed: the rest is
+        // left for the next run (cursors only advance past delivered envelopes).
+        if (now() >= deadlineMs) {
+          receipt.budget_exhausted = true;
+          return OUT_OF_TIME;
+        }
+        const resolved = await ensureAuth();
+        if (resolved.error) return resolved.error;
+        // Credential resolution can itself take a while: re-check before the POST.
+        if (now() >= deadlineMs) {
+          receipt.budget_exhausted = true;
+          return OUT_OF_TIME;
+        }
+        const result = await postBatch({
+          endpoint: usageIngestEndpoint(serverUrl), tenant: resolved.tenant,
+          headers: resolved.headers, run, envelopes: batch, fetchImpl, timeoutMs: deadlineMs - now(),
+        });
+        if (!result.ok) return result.error;
+        receipt.batches += 1;
+        receipt.seen += result.seen;
+        receipt.inserted += result.inserted;
+        receipt.superseded += result.superseded;
+        receipt.deduped += result.deduped;
+        receipt.refused += result.refused;
+        // A refused row is final (the server will refuse it again): the cursor
+        // still advances past it, and the receipt names why.
+        if (result.allRefused) receipt.batches_all_refused += 1;
+        for (const [reason, count] of Object.entries(result.refusalReasons)) {
+          if (!(reason in receipt.refusal_reasons) && Object.keys(receipt.refusal_reasons).length >= 16) continue;
+          receipt.refusal_reasons[reason] = (receipt.refusal_reasons[reason] ?? 0) + count;
+        }
+        if (result.run_id && !receipt.run_ids.includes(result.run_id)) receipt.run_ids.push(result.run_id);
+      }
+      queue = queue.slice(count);
+      postedSeq += count;
+      commitDelivered();
+      return null;
+    };
+
+    for (const path of files) {
+      if (now() >= parseDeadlineMs) { receipt.budget_exhausted = true; break; }
+      let info;
+      try { info = await stat(path); } catch { continue; }
+      const sourceHmac = hmac(resolve(path));
+      // Cursors are per (tenant, file): a run skips other tenants' records, so a
+      // shared per-file cursor would consume them for every later tenant's run.
+      const cursorKey = cursorKeyFor(path);
+      const previous = state.files[cursorKey];
+      let fromOffset = 0;
+      let ctx = {};
+      let reset = false;
+      if (previous && !opts.rescan) {
+        if (info.size < previous.offset) reset = true; // rewritten/truncated: start over
+        else { fromOffset = previous.offset; ctx = { ...(previous.ctx ?? {}) }; }
+        if (!reset && info.size === previous.offset) continue; // nothing new
+      }
+      receipt.files_read += 1;
+      const parser = adapter.beginFile({ sourceHmac, ctx });
+      let result;
+      try {
+        result = await readLines(path, fromOffset, (line, offset) => {
+          if (!line.trim()) return;
+          let record;
+          try { record = JSON.parse(line); } catch { receipt.parse_errors += 1; return; }
+          parser.parseRecord(record, offset);
+        }, { shouldStop: () => now() >= parseDeadlineMs });
+      } catch {
+        continue; // unreadable file: skip, cursor unchanged
+      }
+      if (result.stopped) receipt.budget_exhausted = true;
+      receipt.parse_errors += result.oversized ?? 0;
+      const quiescent = !result.stopped && (opts.trigger === "cloud_stop" || now() - info.mtimeMs >= QUIESCENT_MS);
+      const { envelopes: parsed, holdOffset } = parser.finish({ quiescent });
+      // Never post another tenant's (or an unbound checkout's) usage under this
+      // credential: skip and count it; the cursor still advances past it.
+      const produced = [];
+      for (const envelope of parsed) {
+        // The server's allowlist, applied BEFORE anything leaves the machine: a
+        // row it would refuse (bad id / timestamp) is refused here instead.
+        if (envelopeRefusal(envelope)) { receipt.refused_local += 1; continue; }
+        if (envelope.route_tenant === target) produced.push(envelope);
+        else if (envelope.route_tenant) receipt.skipped_other_tenant += 1;
+        else receipt.skipped_unbound += 1;
+      }
+      receipt.refused_local += parser.stats.refused;
+      receipt.cost_state_withheld += parser.stats.withheld;
+      if (holdOffset !== null) receipt.held_open_messages += 1;
+      queue.push(...produced);
+      enqueuedSeq += produced.length;
+      receipt.envelopes += produced.length;
+      parsedFiles.push({
+        cursorKey,
+        endSeq: enqueuedSeq,
+        entry: {
+          provider, offset: holdOffset ?? result.endOffset, size: info.size, mtime_ms: Math.trunc(info.mtimeMs),
+          ctx, updated_at: new Date(now()).toISOString(), ...(reset || opts.rescan ? { reset: true } : {}),
+        },
+      });
+      while (queue.length >= BATCH_SIZE) {
+        const error = await flush(BATCH_SIZE);
+        if (error === OUT_OF_TIME) return finalize(null);
+        if (error) return finalize(error);
+      }
+      commitDelivered();
+      if (result.stopped) break;
+    }
+    while (queue.length > 0) {
+      const error = await flush(Math.min(BATCH_SIZE, queue.length));
+      if (error === OUT_OF_TIME) return finalize(null);
+      if (error) return finalize(error);
+    }
+    commitDelivered();
+  }
+  return finalize(null);
+
+  async function finalize(error) {
+    const outcome = error ? "error" : opts.dryRun ? "dry_run" : receipt.budget_exhausted ? "partial" : "ok";
+    finish(outcome, error);
+    if (!opts.dryRun) {
+      const runSummary = {
+        at: startedAt, trigger: receipt.trigger, outcome: receipt.outcome, providers: receipt.providers,
+        files_read: receipt.files_read, envelopes: receipt.envelopes, inserted: receipt.inserted, superseded: receipt.superseded,
+        deduped: receipt.deduped, refused: receipt.refused, duration_ms: receipt.duration_ms,
+        ...(receipt.error ? { error: receipt.error } : {}),
+      };
+      try {
+        await saveCursorState(statePath, { files: cursorUpdates, runs: [runSummary] });
+      } catch {
+        receipt.cursor_write = "failed";
+      }
+    }
+    return receipt;
+  }
+}
+
+/** The tenants a user-mode (multi-tenant) client key reaches, from `bb login`; [] otherwise. */
+export async function defaultListTenants() {
+  try {
+    const { loadConfig, getConfig } = await import("../config.mjs");
+    await loadConfig({ warn: () => {} });
+    const cfg = getConfig() ?? {};
+    if (cfg.token_tenant_mode !== "user" || !Array.isArray(cfg.token_tenants)) return [];
+    return [...new Set(cfg.token_tenants.filter((t) => typeof t === "string" && TENANT_SLUG_RE.test(t)))];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * `--all-tenants` (the daily LaunchAgent): one routed pass per tenant the login
+ * reaches, each with the client key pinned to that tenant and its own cursors,
+ * so every workspace's transcripts are swept however many repos the machine
+ * holds (Codex #982 R6). Without a multi-tenant login it is a normal run.
+ */
+export async function syncAllTenants(opts, deps = {}) {
+  const tenants = await (deps.listTenants ?? defaultListTenants)();
+  if (!tenants.length) return syncUsage(opts, deps);
+  const resolveAuth = deps.resolveAuth ?? defaultResolveAuth;
+  const now = deps.now ?? (() => Date.now());
+  // ONE budget for all passes: each gets only what is left, and a tenant whose
+  // turn comes after the budget is spent is reported, not started.
+  const deadlineMs = now() + opts.maxSeconds * 1000;
+  const perTenant = [];
+  for (const tenant of tenants) {
+    const left = (deadlineMs - now()) / 1000;
+    if (left < 1) {
+      perTenant.push({ tenant, outcome: "not_started", envelopes: 0, inserted: 0, deduped: 0, skipped_other_tenant: 0, skipped_unbound: 0 });
+      continue;
+    }
+    const passOpts = { ...opts, maxSeconds: Math.min(opts.maxSeconds, left) };
+    deps.onPass?.(passOpts);
+    perTenant.push(await syncUsage(passOpts, {
+      ...deps,
+      resolveTarget: async () => tenant,
+      resolveAuth: (args) => resolveAuth({ ...args, preferOwner: true }),
+    }));
+  }
+  const sum = (k) => perTenant.reduce((t, r) => t + (Number.isFinite(r[k]) ? r[k] : 0), 0);
+  const outcome = perTenant.some((r) => r.outcome === "error") ? "error"
+    : opts.dryRun ? "dry_run"
+    : perTenant.some((r) => r.outcome === "partial" || r.outcome === "not_started") ? "partial" : "ok";
+  return {
+    schema_version: 1, command: "usage sync", outcome, trigger: opts.trigger, dry_run: opts.dryRun, all_tenants: true,
+    envelopes: sum("envelopes"), inserted: sum("inserted"), deduped: sum("deduped"), superseded: sum("superseded"),
+    refused: sum("refused"), refused_local: sum("refused_local"), skipped_unbound: sum("skipped_unbound"),
+    per_tenant: perTenant.map((r) => ({
+      tenant: r.tenant, outcome: r.outcome, ...(r.error ? { error: r.error } : {}), envelopes: r.envelopes,
+      inserted: r.inserted, deduped: r.deduped, skipped_other_tenant: r.skipped_other_tenant, skipped_unbound: r.skipped_unbound,
+    })),
+    ...(outcome === "error" ? { error: perTenant.find((r) => r.outcome === "error")?.error ?? "sync_failed" } : {}),
+  };
+}
+
+/** `bb usage status` — the local view: how many files are tracked and the last runs. */
+export async function usageStatus({ home = homedir(), statePath = cursorPath(home), limit = 5 } = {}) {
+  const state = await loadCursorState(statePath);
+  const byProvider = {};
+  for (const entry of Object.values(state.files)) {
+    const p = entry?.provider ?? "unknown";
+    byProvider[p] = (byProvider[p] ?? 0) + 1;
+  }
+  return {
+    schema_version: 1, command: "usage status",
+    files_tracked: Object.keys(state.files).length, files_by_provider: byProvider,
+    last_runs: state.runs.slice(-limit).reverse(),
+  };
+}
+
+export function usageHelp() {
+  return `bb usage sync [--since <dur>] [--provider claude|codex|all] [--file <transcript>]
+              [--trigger manual|pre_push|daily|cloud_stop|cloud_session_start] [--max-seconds <n>]
+              [--dry-run] [--quiet] [--rescan] [--strict] [--all-tenants]
+    Ingest local Claude Code / Codex token usage into BotBuddy. Reads only what
+    changed since the last run (per-file cursors in ~/.botbuddy), sends only
+    allowlisted counters and ids (no prompts, no paths), prints one JSON receipt.
+    Fails open (exit 0) unless --strict. Defaults: --since 2d, --max-seconds 60.
+bb usage status
+    Show locally tracked transcripts and the last sync runs.`;
+}
+
+/**
+ * CLI entry: `bb usage <sync|status|help>`. Fail-open — every error becomes a
+ * receipt and exit 0, unless --strict (exit 1). Usage errors exit 2.
+ */
+export async function runUsage(argv, {
+  log = (line) => console.log(line), errorLog = (line) => console.error(line), deps = {},
+} = {}) {
+  const [sub, ...rest] = argv;
+  if (!sub || sub === "help" || sub === "--help" || sub === "-h") { log(usageHelp()); return 0; }
+  if (sub === "status") {
+    try { log(JSON.stringify(await usageStatus(deps))); } catch { log(JSON.stringify({ schema_version: 1, command: "usage status", outcome: "error", error: "status_unreadable" })); }
+    return 0;
+  }
+  if (sub !== "sync") { errorLog(`bb usage: unknown subcommand ${sub}. ${usageHelp().split("\n")[0]}`); return 2; }
+  let opts;
+  try {
+    opts = parseSyncArgs(rest);
+  } catch (error) {
+    if (!(error instanceof UsageUsageError)) throw error;
+    errorLog(`bb usage sync: ${error.message}`);
+    return 2;
+  }
+  if (opts.help) { log(usageHelp()); return 0; }
+  let receipt;
+  try {
+    receipt = opts.allTenants ? await syncAllTenants(opts, deps) : await syncUsage(opts, deps);
+  } catch (error) {
+    const code = typeof error?.code === "string" && /^[a-z0-9_]{1,64}$/i.test(error.code) ? error.code : "sync_failed";
+    receipt = { schema_version: 1, command: "usage sync", outcome: "error", trigger: opts.trigger, error: code };
+  }
+  const failed = receipt.outcome === "error";
+  if (!opts.quiet || failed) (failed && opts.quiet ? errorLog : log)(JSON.stringify(receipt));
+  return failed && opts.strict ? 1 : 0;
+}