fix(server): exclude inherited Codex child usage

[imMxts]

Closes #5793.

Problem

Codex child usage events contain a cumulative total counter. A fork can copy prior cumulative history into that counter. CodexAdapter sent the raw total through the provider-neutral task-usage interface. The Agents panel then summed task snapshots that already contained parent history.

The client fold and Agents panel did not create the inflation. They correctly max-merge and sum the task totals supplied by the adapter.

Change

• Normalize Codex child counters in CodexAdapter before runtime storage and UI consumption.
• Calculate one fixed baseline per child from its first valid total - last frame.
• Subtract that baseline from later cumulative totals.
• Keep total, input, cached input, output, and reasoning output values non-negative and non-decreasing.
• Leave parent usage and transcript-based usage analytics unchanged.

This keeps Codex counter rules inside the existing Codex adapter. It needs no contract, storage, or UI change.

Regression coverage

The provider-free adapter regression covers:

• a nonzero parent baseline;
• two children with independent baselines;
• zero child usage;
• resume and retry frames;
• duplicate cumulative frames;
• every token breakdown field;
• unchanged parent usage;
• public task.progress.typedUsage output.

The test failed before the fix with inherited totals such as 5,800,000,100 instead of 100.

Verification

• pnpm exec vp test run apps/server/src/provider/Layers/CodexAdapter.test.ts — 27 passed
• adjacent runtime tests — 60 passed
• Codex collaboration integration tests — 3 passed
• server and client-runtime typechecks — passed
• touched-file lint and format checks — passed
• server bundle build — passed
• git diff --check — passed

Repo-wide checks were not run, as repository guidance assigns the full suite to CI.

Compatibility

No public contract or stored shape changes. Existing inflated stored rows cannot be repaired from their stored shape alone. A later corrected snapshot replaces the active stable task-usage row.

Prepared with Codex. Luna Max subagents performed independent design and review checks.

Note

Fix Codex collab agent token usage to exclude inherited parent baseline

• mapCollabAgentEvent in CodexAdapter.ts now subtracts a per-agent baseline from cumulative token totals, so task.progress events reflect only child-generated usage rather than raw inherited totals.
• On first observation of a child agent, the baseline is computed as cumulative - current-turn counts (clamped to zero); subsequent events normalize against this stored baseline and clamp to the previously emitted maximum.
• A per-session collabUsageByAgent map is introduced in adapter.startSession to maintain baseline and latest state across events for each child agent.
• Events are suppressed when either total.totalTokens or last.totalTokens is absent.
• Behavioral Change: collab agent token usage events previously forwarded raw cumulative totals; they now emit baseline-subtracted values, which will be lower for agents that inherit parent thread history.

^{Macroscope summarized f9b6ed4.}

---

Note

Medium Risk
Changes only Codex collab usage math in the server adapter; wrong baselines would skew agent token display/sums, but parent usage and public contracts are untouched and coverage is targeted.

Overview
Fixes inflated token totals in the Agents panel when Codex collab children inherit cumulative usage from a forked parent thread.

CodexAdapter now normalizes collabAgent/tokenUsage before emitting task.progress typedUsage. It keeps per-child CodexCollabUsageState (baseline + latest) for the session event stream. The first valid frame sets baseline from total − last so copied history is stripped; later frames subtract that fixed baseline from cumulative total while clamping each breakdown field to stay non-negative and non-decreasing. Events missing total.totalTokens or last.totalTokens are dropped. Parent thread/tokenUsage/updated mapping is unchanged.

A lifecycle regression test drives parent baseline, two children, zero usage, resume/retry, duplicate frames, and asserts child typedUsage stays turn-scoped (e.g. ~100 tokens, not billions).

^{Reviewed by Cursor Bugbot for commit f9b6ed4. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 86b3ac94-7a90-457d-9879-a886d611dd82

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR changes how token usage is calculated and reported for Codex child agents by introducing baseline subtraction logic. Changes to metering/usage calculation have potential billing implications and warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}