Feature/Fix: Add a shadow lineage ledger for Codex token accounting

[iam-brain]

Stack position

This is slice 1 of 15 and the first isolated component of the planned scanner rearchitecture.

Summary

Adds a shadow lineage ledger that treats Codex rollout files as overlapping physical views of transitive session families. It admits each complete (last_token_usage, total_token_usage) state once per lineage, keeps identical observations from unrelated lineages additive, and provides separate UTC and local-day projections.

This is the first isolated component of a planned scanner rearchitecture tracked in Map: rearchitect Codex rollout token accounting around lineages. It deliberately does not change production scanner totals yet.

Why

Forked, sibling, archived, and long-lived Codex sessions can copy or re-emit token history across physical rollout files. A small lineage-focused component gives later PRs a testable accounting boundary before discovery, parsing, pricing, shadow comparison, and production promotion are migrated piecemeal.

An independent privacy-safe replay over active and archived local rollout data reproduced the investigated July 9–11 UTC lineage totals and collapsed 1.535 million physical snapshots to 204,547 admitted observations. The remaining gap to OpenAI totals is intentionally not hidden or guessed away; later mapped slices will classify it through shadow diagnostics.

Validation

• swift test --filter CodexLineageLedgerTests
• make check
• SDKROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX26.5.sdk make test
• 639 full-suite selections passed across 54 groups with no retries or timeouts
• Repository review gate completed with no implementation defects; fingerprint-dimension coverage was added during review

Known limits

• No rollout-file adapter or discovery integration yet
• No production totals or pricing paths use the ledger
• Missing or malformed evidence policy remains a later isolated slice

Tracks Land the shadow lineage ledger foundation.

Related investigation: steipete/CodexBar#2037.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 13, 2026, 9:19 PM ET / July 14, 2026, 01:19 UTC.

Summary
Adds a standalone shadow ledger and focused tests for lineage-based Codex token accounting without changing production totals.

Reproducibility: yes. at source level: distinct observations in one lineage with the same complete token-counter tuple are treated as one admitted observation under the proposed identity contract. The PR head has not changed since this case was previously raised.

Review metrics: 2 noteworthy metrics.

• Patch surface: 2 files, +358/-0. The change is isolated to a new accounting component and focused tests.
• Production integration: 0 production total paths changed. The ledger is shadow-only, so its identity contract should be settled before later slices depend on it.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #2037
Summary: This PR is an early candidate component for the remaining cross-file lineage-accounting work tracked by the canonical issue.

Members:

• canonical: Ultra-mode Terra and Sol sessions can overcount forked context #2037 - The issue tracks the observable fork/interleaving overcount and the remaining exact cross-file lineage behavior.
• partial_overlap: Contain Codex interleaved overcount and add fork provenance fixtures (#2037) #2082 - The merged PR supplies file-local containment and explicitly defers stronger cross-file provenance and collision handling.
• adjacent_distinct: Feature/Fix: Adapt rollout snapshots for lineage accounting #2141 - The open stacked adapter depends on this ledger but changes parser-to-document adaptation rather than the ledger identity itself.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🦪 silver shellfish
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Replace tuple-only deduplication with a copy-stable identity or conservative ambiguous-event handling.
• [P1] Add redacted initial and repeat replay output showing accepted, duplicate, UTC-day, and local-day results; redact private paths, identifiers, endpoints, and credentials.

Proof guidance:

• [P1] Needs real behavior proof before merge: The body reports private replay aggregates but provides no inspectable redacted terminal output, logs, or artifact showing after-change admissions and collision handling; after adding proof, update the PR body to trigger review or ask a maintainer to comment @clawsweeper re-review.

Risk before merge

• [P1] If later stack slices promote this ledger, legitimate distinct events with identical complete counter states can be silently undercounted.
• [P1] The dependent adapter PR builds on this identity contract, so merging the foundation unchanged can propagate the ambiguity through the planned stack.
• [P1] The private replay aggregates are not independently inspectable, leaving real collision and repeat-scan behavior unproven.

Maintainer options:

1. Decide the mitigation before merge
   Define a copy-stable event identity or a conservative fail-open collision policy that preserves ambiguous equal-counter events, then attach redacted initial and repeat replay output before integrating the ledger into production totals.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P1] The contributor must revise the accounting identity and provide real replay proof; automation cannot safely infer event identity or validate the contributor's private rollout corpus.

Security
Cleared: The two-file Swift implementation and tests add no dependency, credential, permission, workflow, download, or supply-chain surface.

Review findings

• [P1] Preserve ambiguous equal-counter events within a lineage — Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift:83

Review details

Best possible solution:

Define a copy-stable event identity or a conservative fail-open collision policy that preserves ambiguous equal-counter events, then attach redacted initial and repeat replay output before integrating the ledger into production totals.

Do we have a high-confidence way to reproduce the issue?

Yes, at source level: distinct observations in one lineage with the same complete token-counter tuple are treated as one admitted observation under the proposed identity contract. The PR head has not changed since this case was previously raised.

Is this the best way to solve the issue?

No in its current form. Lineage grouping is a plausible boundary, but deduplication must use stronger identity or preserve ambiguous events rather than treating matching token counters as proof of duplication.

Full review comments:

• [P1] Preserve ambiguous equal-counter events within a lineage — Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift:83
  The ledger treats a complete (last, total) counter tuple as unique within the connected lineage, but current-main provenance records that distinct sibling events can have identical counter vectors. Those events are collapsed as duplicates and silently undercounted; use a copy-stable event identity, or fail open and admit ambiguous matches until one exists. This remains unresolved because the head is unchanged from the prior review.
  Confidence: 0.98

Overall correctness: patch is incorrect
Overall confidence: 0.97

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 0437067deaa8.

Label changes

Label justifications:

• P2: This is a bounded accounting-foundation change for a real usage-inflation problem, but it does not yet affect production totals.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦪 silver shellfish.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The body reports private replay aggregates but provides no inspectable redacted terminal output, logs, or artifact showing after-change admissions and collision handling; after adding proof, update the PR body to trigger review or ask a maintainer to comment @clawsweeper re-review.

Evidence reviewed

What I checked:

• Prior finding remains unresolved: The current head SHA is identical to the previously reviewed SHA, so the earlier ambiguous equal-counter finding has not been addressed. (Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift:83, 6170f5c8c745)
• Current-main accounting invariant: The merged provenance work records that distinct sibling events can share identical token-counter vectors and therefore ambiguous rows must remain billable unless a stronger copy-stable event identity exists. (Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, c852c135e10c)
• No production behavior change: The PR adds only the experimental ledger and its focused tests; the PR body confirms that discovery, production totals, and pricing do not use it yet. (Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift:3, 6170f5c8c745)
• Real replay proof is not inspectable: The PR body reports aggregate replay counts but includes no redacted terminal output, logs, recording, or linked artifact showing after-change admission and collision behavior. (6170f5c8c745)

Likely related people:

• steipete: Merged the current interleaved-accounting work and authored its final replay-state, cache, and fail-open refinements. (role: recent area contributor and merger; confidence: high; commits: c852c135e10c, cb6538b18d09, ab65dd331faf; files: Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner+CacheHelpers.swift, Tests/CodexBarTests/CostUsageScannerBreakdownTests.swift)
• xx205: Authored the merged parent-baseline and replay-accounting path that the lineage proposal must preserve. (role: introduced adjacent fork accounting behavior; confidence: high; commits: 45b68c34ec48; files: Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, Tests/CodexBarTests/CostUsageScannerBreakdownTests.swift)
• Zihao-Qi: Authored the merged provenance and containment branch that documented the unsafe equal-counter collision case and deferred a stronger lineage identity. (role: recent area contributor; confidence: high; commits: be56cc9aff5e, 5441ff75; files: Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, Tests/CodexBarTests/Issue2037ScannerIntegrationTests.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (1 earlier review cycle)

• reviewed 2026-07-14T01:01:47.384Z sha 6170f5c :: needs real behavior proof before merge. :: [P1] Preserve ambiguous equal-counter events within a lineage

[iam-brain]

Superseded by the consolidated four-PR review stack. This slice is now included in #2155; closing this draft to keep the upstream review surface manageable.