Skip to content

fix(insights): stop recounting a Codex fork's copied parent history - #131

Merged
GaganSD merged 4 commits into
GaganSD:mainfrom
ktwu1997:fix/codex-fork-replay
Nov 16, 2026
Merged

GaganSD merged 4 commits into
GaganSD:mainfrom
ktwu1997:fix/codex-fork-replay

Conversation

@ktwu1997

Copy link
Copy Markdown
Contributor

Summary

Codex usage was overcounted for every subagent (forked thread). A forked rollout file starts with a copy of the parent's history, and Insights counted that copy again in each fork. On one real machine this inflated lifetime Codex usage from about 42 B to 628 B tokens, and put 275 B of it under model "unknown".

What

  • core/adapters.mjs (Codex parser): in a forked session, records before the child's first own turn only set the cumulative baseline; they no longer add usage. Applies to token_count and token_usage_record.
  • The child's first own turn is the first UUIDv7 turn id created at or after the forked thread id. Copied history can contain turns with other id versions (goal continuations use UUIDv4), so those never end the copy.
  • A fork whose own thread id is not UUIDv7 keeps the previous behavior, so its usage is never dropped.
  • core/scan.mjs: Codex parser version 5 to 7, so stored scans are recomputed.
  • Four fixtures and tests: copied parent turn_context before the copied counters, copied counters with no turn_context, a copied UUIDv4 turn inside the copy, and a non-fork session.

Why

Subagent rollouts (session_meta.payload.forked_from_id, thread_source: "subagent") replay the parent's records with timestamps at the fork moment. The first copied token_count had no previous total, so the parent's cumulative usage was counted once per fork, and copied records before any turn_context had no model. The parent's usage is already counted from its own file.

A simpler boundary does not hold on real data. "Until the first turn_context" fails because the copy often includes the parent's turn_context before its counters. A timestamp window fails because a large copy can take seconds to write. UUIDv7 turn ids carry their creation time, which separates the two cleanly.

Related issues

None

Testing

  • npm run test:insights: 251 pass, 0 fail, 3 skipped (247 before; 4 new tests). The fork tests failed before the fix.
  • npx eslint herdr-insights tests/herdr-insights --max-warnings=0: clean.
  • Real data, Linux machine with 117 forked rollouts: copied records sat within 2 ms of the fork and the child's own records started 6 s or later. Codex total fell by 1,623,172 tokens, exactly the sum of the copied parent totals; "unknown" went from 821,065 to 0.
  • Real data, Linux machine with 109 forks of one parent on 2026-09-02: that day went from 543.4 B to 0.999 B tokens, lifetime total from 628.0 B to 42.05 B, and Codex "unknown" from 274.8 B to 0. An independent count of the forks' own usage with the same boundary agreed.

Compatibility

None. Existing stores are recomputed once on the next scan because the Codex parser version changed.

Risk

  • If a future Codex version stops using UUIDv7 turn ids inside a fork whose thread id is UUIDv7, that fork's own usage would be treated as copied and not counted. Current rollouts use UUIDv7 for every own turn (all 117 + 109 forks checked).
  • Non-fork sessions take the unchanged path.

Checklist

  • The change is focused; unrelated changes are excluded.
  • Tests cover behavior changes, or the testing section explains why not.
  • Relevant documentation is updated, or no documentation changes are needed.

🤖 Generated with Claude Code

ktwu1997 and others added 2 commits November 16, 2026 14:30
A forked Codex thread (a subagent) starts its rollout file with a copy of
the parent's records. The first copied token_count had no previous total,
so the parent's whole cumulative usage was counted again in every fork,
and copied records before any turn_context landed under model "unknown".

In a forked session, records before the child's first own turn now only
set the cumulative baseline. Codex turn ids are UUIDv7, so a turn older
than the forked thread id is copied history; copied turn_context records
can precede the copied counters, so the first turn_context alone is not
a safe boundary. Non-fork sessions are unchanged. The Codex parser
version is bumped so stored scans are recomputed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The fork boundary treated any turn id that was not UUIDv7 as the child's
own turn. Copied parent history can contain goal-continuation turns with
UUIDv4 ids, so the copy ended early and most of the parent's usage was
still counted in every fork. Only a UUIDv7 turn created after the forked
thread now ends the copy; a fork whose own thread id is not UUIDv7 keeps
the previous behavior. The Codex parser version is bumped again so scans
made with the earlier boundary are recomputed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@GaganSD

GaganSD commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Codex Review

  • P2 — Preserve copied modern usage baselines (core/adapters.mjs:722–724). The replay early return skips modern cumulative/pending accounting. If copied history has only modern records, followed by child modern usage and a legacy cumulative counter, parent usage can be recounted: parent 2500 → child 100 → cumulative 2600 can attribute 2600 instead of 100 to the child. This is source-traced, not runtime-verified; confirm that supported Codex formats permit this sequence, then preserve a compatible baseline and add a regression.
  • P3 — Harden fork-boundary handling. Missing/non-v7 child markers can leave replay suppression active; equal-millisecond IDs can end it early. Add an unresolved-boundary diagnostic and malformed/equal-timestamp cases.
  • P3 — Broaden release coverage. Add modern/mixed/last-only fixtures and verify full versus incremental scan equivalence, repeat-scan idempotence, token-category accounting, and parser-version migration before shipping.

Update: Addressed in 2918146 and 174aa91. Replay baselines and copied-carrier reconciliation are fixed, ambiguous formats are diagnosed, and full/incremental/migration regressions were added. Local concurrent and serial suites pass 305/305; CI passes on Node 22.15.0, 22, and 24. UUID-time and identity-poor compatibility limitations remain documented.

@GaganSD
GaganSD merged commit 4032102 into GaganSD:main Nov 16, 2026
9 checks passed
@GaganSD

GaganSD commented Nov 16, 2026

Copy link
Copy Markdown
Owner

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants