@botbuddy/cli 1.34.0 → 1.34.1

package/package.json

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

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/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);
+      }
+    },
+  };
+}

package/src/usage/codex.mjs

@@ -0,0 +1,236 @@
+// BOT-803 — Codex rollout adapter (`~/.codex/sessions/**/*.jsonl`, or
+// `$CODEX_HOME/sessions`).
+//
+// VERIFIED SHAPE (parser_version 'codex-2'): checked on 2026-09-28 against real
+// Codex Desktop rollouts (0.117 → 0.155.0-alpha.9.2, ~/.codex/sessions). The
+// fixtures in cli/test-fixtures/usage/ are synthetic copies of that shape.
+// Every record is {"timestamp","type","ordinal"?,"payload"}:
+//   session_meta     {id, session_id, cli_version, thread_source, parent_thread_id?, cwd,
+//                     git:{commit_hash, branch, repository_url}, …}
+//                    A subagent rollout is its own file: id = the subagent thread,
+//                    session_id = the ROOT session, thread_source 'subagent'.
+//   turn_context     {model, cwd, turn_id, …}
+//   response_item    {type:'function_call'|'custom_tool_call'|'local_shell_call'|…} —
+//                    written BEFORE the usage record of the response that made it
+//   token_usage_record (≥0.151) {response_id, session_id, thread_id, turn_id,
+//                    usage:{input_tokens, cached_input_tokens, cache_write_input_tokens,
+//                    output_tokens, reasoning_output_tokens, total_tokens},
+//                    turn_token_usage, thread_token_usage} — ONE per model response,
+//                    including a compaction's own response (which has no token_count)
+//   event_msg/token_count {info:{total_token_usage, last_token_usage, model_context_window}|null,
+//                    rate_limits} — follows each usage record with the same numbers,
+//                    is re-emitted with unchanged totals, and is null-info for a
+//                    rate-limit-only update
+// Identity: a usage record keys on its provider `response_id`. Rollouts written
+// before token_usage_record existed (and the pre-upgrade head of a session
+// resumed on a newer Codex) fall back to token_count keyed on the cumulative
+// total; once a file shows a usage record, token_count is ignored (it would
+// double count). `cache_write_input_tokens` has no BOT-1019 column and was 0 in
+// every real rollout checked; it is not sent.
+// Codex classes stay provider-faithful (codex_* columns); Claude's four classes
+// are null on Codex rows. Codex `input_tokens` INCLUDES `cached_input_tokens`.
+import {
+  commitSha, finalizeEnvelope, inferTicketKey, modelLabel, normalizeRepo, safeLabel, str, tok, usageQuality, uuid, withRoute,
+} from "./envelope.mjs";
+
+export const CODEX_PROVIDER = "codex";
+export const CODEX_PARSER_VERSION = "codex-2";
+
+// Mirrors the server's PROVIDER_ID_RE (usageEnvelope.ts): resp_… ids, no '/' or '@'.
+const RESPONSE_ID_RE = /^[A-Za-z0-9_.:-]{1,200}$/;
+const responseId = (value) => (typeof value === "string" && RESPONSE_ID_RE.test(value) ? value : null);
+
+function totalOf(usage) {
+  if (!usage || typeof usage !== "object") return null;
+  const explicit = tok(usage.total_tokens);
+  if (explicit !== null) return explicit;
+  const input = tok(usage.input_tokens);
+  const output = tok(usage.output_tokens);
+  return input === null && output === null ? null : (input ?? 0) + (output ?? 0);
+}
+
+function deltaUsage(total, previous) {
+  const keys = ["input_tokens", "cached_input_tokens", "output_tokens", "reasoning_output_tokens"];
+  const out = {};
+  for (const key of keys) {
+    const now = tok(total?.[key]);
+    const before = tok(previous?.[key]) ?? 0;
+    out[key] = now === null ? null : Math.max(0, now - before);
+  }
+  return out;
+}
+
+// Only derived values are kept in ctx (it is persisted in the cursor file):
+// the cwd's HMAC and the ticket key its last segment names — never the path.
+function setCwd(ctx, cwd, hmac, tenantFor, repoFor = () => null) {
+  const value = str(cwd);
+  if (!value) return;
+  const cwdHmac = hmac(value);
+  // A later turn in ANOTHER checkout: the session_meta git metadata described
+  // the old one. Drop it (the ticket then falls back to the new cwd) and
+  // re-derive the repo from the new checkout.
+  if (ctx.cwd_hmac && ctx.cwd_hmac !== cwdHmac) {
+    ctx.git_branch = null;
+    ctx.commit_sha = null;
+    ctx.repo = repoFor(value) ?? null;
+  }
+  ctx.cwd_hmac = cwdHmac;
+  ctx.cwd_ticket = inferTicketKey(null, value);
+  ctx.cwd_tenant = tenantFor(value); // a tenant slug (or null), never the path
+}
+
+const NONE = Object.freeze({ envelopes: [], refused: 0 });
+
+/**
+ * @param {object} opts
+ * @param {(value: string) => string} opts.hmac
+ * @param {string} opts.environment
+ */
+export function createCodexAdapter({ hmac, environment, tenantFor = () => null, repoFor = () => null }) {
+  function parseCodexRecord(record, { offset, sourceHmac, ctx }) {
+    if (!record || typeof record !== "object") return NONE;
+    const payload = record.payload && typeof record.payload === "object" ? record.payload : null;
+    if (!payload) return NONE;
+
+    if (record.type === "session_meta") {
+      // The harness session is the ROOT thread (`session_id`); a subagent's own
+      // thread id (`id`) only keeps its legacy token_count keys apart.
+      const root = uuid(payload.session_id) ?? uuid(payload.id);
+      if (root) ctx.session_id = root;
+      const thread = uuid(payload.id);
+      ctx.subagent_thread = thread && root && thread !== root ? thread
+        : payload.thread_source === "subagent" && thread ? thread : null;
+      if (safeLabel(payload.cli_version)) ctx.cli_version = safeLabel(payload.cli_version);
+      setCwd(ctx, payload.cwd, hmac, tenantFor, repoFor);
+      const git = payload.git && typeof payload.git === "object" ? payload.git : {};
+      ctx.git_branch = safeLabel(git.branch) ?? ctx.git_branch ?? null;
+      ctx.commit_sha = commitSha(git.commit_hash) ?? ctx.commit_sha ?? null;
+      ctx.repo = normalizeRepo(git.repository_url) ?? ctx.repo ?? null;
+      return NONE;
+    }
+    if (record.type === "turn_context") {
+      if (modelLabel(payload.model)) ctx.model = modelLabel(payload.model);
+      setCwd(ctx, payload.cwd, hmac, tenantFor, repoFor);
+      return NONE;
+    }
+    if (record.type === "response_item") {
+      if (["function_call", "local_shell_call", "custom_tool_call"].includes(payload.type)) {
+        ctx.pending_tool_calls = (ctx.pending_tool_calls ?? 0) + 1;
+      }
+      return NONE;
+    }
+    if (record.type === "token_usage_record") {
+      ctx.has_usage_records = true;
+      const id = responseId(payload.response_id);
+      const session = uuid(payload.session_id) ?? ctx.session_id ?? null;
+      const usage = payload.usage && typeof payload.usage === "object" ? payload.usage : null;
+      if (!id || !session || !usage) return { envelopes: [], refused: 1 };
+      const toolCalls = ctx.pending_tool_calls ?? 0;
+      ctx.pending_tool_calls = 0;
+      return { envelopes: [envelopeFor({ record, usage, usageFinal: true, messageId: id, session, toolCalls, offset, sourceHmac, ctx })], refused: 0 };
+    }
+    if (record.type !== "event_msg" || payload.type !== "token_count") return NONE;
+    // Each usage record is followed by a token_count carrying the same numbers.
+    if (ctx.has_usage_records) return NONE;
+
+    const info = payload.info && typeof payload.info === "object" ? payload.info : null;
+    const total = info?.total_token_usage;
+    const cumulative = totalOf(total);
+    // A token_count without cumulative usage (e.g. a rate-limit-only update)
+    // has no stable identity: refuse it rather than invent one.
+    if (!info || cumulative === null || !ctx.session_id) return info ? { envelopes: [], refused: 1 } : NONE;
+    // Codex re-emits token_count with unchanged totals; within one accounting
+    // epoch the cumulative total strictly increases per real response, so it is
+    // the message identity. Older rollouts reset the total (after compaction):
+    // a drop starts a new epoch so a later equal total is never read as a repeat.
+    if (ctx.last_total_tokens === cumulative) return NONE;
+    if (typeof ctx.last_total_tokens === "number" && cumulative < ctx.last_total_tokens) {
+      ctx.total_epoch = (ctx.total_epoch ?? 0) + 1;
+      ctx.last_total_usage = null; // a delta across the reset would be meaningless
+    }
+
+    let usage = info.last_token_usage && typeof info.last_token_usage === "object" ? info.last_token_usage : null;
+    let usageFinal = true;
+    if (!usage) {
+      // No per-response usage: derive it from the previous cumulative total;
+      // without one the row cannot be split from earlier turns → not final.
+      usage = deltaUsage(total, ctx.last_total_usage);
+      usageFinal = Boolean(ctx.last_total_usage);
+    }
+    ctx.last_total_tokens = cumulative;
+    ctx.last_total_usage = {
+      input_tokens: tok(total.input_tokens),
+      cached_input_tokens: tok(total.cached_input_tokens),
+      output_tokens: tok(total.output_tokens),
+      reasoning_output_tokens: tok(total.reasoning_output_tokens),
+    };
+    const toolCalls = ctx.pending_tool_calls ?? 0;
+    ctx.pending_tool_calls = 0;
+
+    // A legacy subagent's cumulative totals restart at zero: keep its keys
+    // apart from the parent's under the shared root session.
+    const epoch = ctx.total_epoch ? `r${ctx.total_epoch}:` : "";
+    const messageId = ctx.subagent_thread
+      ? `token_count:${ctx.subagent_thread}:${epoch}${cumulative}`
+      : `token_count:${epoch}${cumulative}`;
+    return {
+      envelopes: [envelopeFor({ record, usage, usageFinal, messageId, session: ctx.session_id, toolCalls, offset, sourceHmac, ctx })],
+      refused: 0,
+    };
+  }
+
+  function envelopeFor({ record, usage, usageFinal, messageId, session, toolCalls, offset, sourceHmac, ctx }) {
+    const classes = {
+      codex_input_tokens: tok(usage.input_tokens),
+      codex_cached_input_tokens: tok(usage.cached_input_tokens),
+      codex_output_tokens: tok(usage.output_tokens),
+      codex_reasoning_output_tokens: tok(usage.reasoning_output_tokens),
+    };
+    const ticket = inferTicketKey(ctx.git_branch, null) ?? ctx.cwd_ticket ?? null;
+    return withRoute(finalizeEnvelope({
+      provider: CODEX_PROVIDER,
+      provider_schema_version: ctx.cli_version ?? null,
+      harness_session_id: session,
+      message_id: messageId,
+      occurred_at: str(record.timestamp),
+      model: ctx.model ?? null,
+      ...classes,
+      tool_call_count: toolCalls,
+      is_sidechain: Boolean(ctx.subagent_thread),
+      usage_final: usageFinal,
+      // The server's rule: Codex is 'measured' when input/cached/output are present.
+      usage_quality: usageQuality({
+        usageFinal, classes: [classes.codex_input_tokens, classes.codex_cached_input_tokens, classes.codex_output_tokens],
+      }),
+      git_branch: ctx.git_branch ?? null,
+      repo: ctx.repo ?? null,
+      commit_sha: ctx.commit_sha ?? null,
+      ticket_key_inferred: ticket,
+      attribution_confidence: ticket ? "inferred" : null,
+      environment,
+      cwd_hmac: ctx.cwd_hmac ?? null,
+      source_hmac: sourceHmac,
+      source_offset: offset,
+      parser_version: CODEX_PARSER_VERSION,
+    }), ctx.cwd_tenant ?? null);
+  }
+
+  return {
+    provider: CODEX_PROVIDER,
+    parserVersion: CODEX_PARSER_VERSION,
+    /** One file's parser; token_count rows are complete when written, so nothing is ever held back. */
+    beginFile({ sourceHmac, ctx }) {
+      const envelopes = [];
+      const stats = { refused: 0, withheld: 0 };
+      return {
+        stats,
+        parseRecord(record, offset) {
+          const result = parseCodexRecord(record, { offset, sourceHmac, ctx });
+          stats.refused += result.refused;
+          envelopes.push(...result.envelopes);
+        },
+        finish() { return { envelopes, holdOffset: null }; },
+      };
+    },
+  };
+}