Feature/Fix: Classify shadow lineage residuals

[iam-brain]

Stack dependency

This is slice 6 of 15. It follows Feature/Fix: Run lineage accounting in shadow mode; review and merge that PR first.

Summary

• add a conservative classifier for differences between legacy, lineage, and finalized UTC usage totals
• keep provisional reference days out of acceptance math and require explicit evidence before assigning unavailable history
• validate the July 9–11 sanitized replay, where aggregate absolute error drops from 810.3M to 103.4M tokens, while preserving ordinary-day parity checks
• reject invalid evidence and keep aggregate/tolerance arithmetic overflow-safe

This is the residual-classification slice of the planned scanner rearchitecture. It does not change production accounting totals.

Validation

• swift test --filter CodexLineageResidualClassifierTests
• make check
• env SDKROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX26.5.sdk make test (642 selections passed)

Related investigation: steipete/CodexBar#2037.

[clawsweeper]

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

Summary
Adds experimental Codex lineage discovery, ledger and shadow accounting, residual classification, parser evidence extraction, cache-hash invalidation, and focused tests while retaining legacy totals as authoritative.

Reproducibility: yes. at the source and sanitized-test level: the linked investigation and classifier fixture define the fork-heavy accounting discrepancy. A high-confidence live current-head reproduction is still absent because no redacted real-corpus execution is shown.

Review metrics: 3 noteworthy metrics.

• Stacked diff: 6 commits, 10 files. The branch includes predecessor lineage work in addition to the classifier slice, so review should be refreshed after rebasing onto the merged dependency.
• Code surface: 1,538 added, 11 removed. The change introduces substantial experimental accounting code despite intentionally preserving existing production totals.
• New coverage: 4 production modules, 4 test suites. The implementation is paired with focused coverage across discovery, ledger, shadow comparison, and residual classification.

Root-cause cluster
Relationship: partial_overlap
Canonical: #2037
Summary: The issue is the canonical user-visible accounting investigation; this PR and its adjacent stack slices implement parts of a proposed lineage-based solution without yet changing authoritative totals.

Members:

• canonical: Ultra-mode Terra and Sol sessions can overcount forked context #2037 - Tracks the observable fork-related Codex cost-accounting discrepancy that motivates the lineage scanner work.
• same_root_cause: Feature/Fix: Run lineage accounting in shadow mode #2144 - This PR explicitly depends on that preceding shadow-accounting slice and currently includes its implementation commits.
• same_root_cause: Feature/Fix: Contain ambiguous lineage families #2146 - The successor slice builds containment behavior on the lineage evidence and classification introduced here.

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: 🐚 platinum hermit
Result: blocked until real behavior proof from a real setup is added.

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

Rank-up moves:

• Merge Feature/Fix: Run lineage accounting in shadow mode #2144 first and rebase this branch so the classifier slice can be reviewed independently.
• [P1] Add redacted real-corpus CLI output or logs showing before/after legacy totals, shadow classifications, elapsed time, and any relevant memory observation.

Proof guidance:

• [P1] Needs real behavior proof before merge: Validation consists of tests and checks only; before merge, add a redacted real CLI or runtime transcript showing the shadow result, unchanged legacy totals, and representative scan timing, then update the PR body to trigger review or ask a maintainer for @clawsweeper re-review.

Risk before merge

• [P1] The current branch is not an isolated sixth slice: merging or reviewing it before Feature/Fix: Run lineage accounting in shadow mode #2144 lands would conflate predecessor code with the residual-classification change and make stack provenance harder to verify.
• [P1] Shadow execution adds lineage construction and transitive parent discovery alongside the production scan; without a representative real-corpus run, wall-clock, memory, cancellation, and large-archive behavior remain uncertain.
• [P1] The sanitized numeric replay proves classifier arithmetic but does not prove that live rollout parsing and discovery produce the same evidence classifications on the contributor's affected setup.

Maintainer options:

1. Require representative shadow-run proof (recommended)
   After the predecessor merges and this branch is rebased, require redacted live output showing unchanged legacy totals plus acceptable elapsed time and memory on a representative large rollout corpus.
2. Accept temporary shadow overhead
   Merge after stack cleanup while explicitly accepting that production scans may perform additional experimental work until the later containment and rollout slices land.
3. Pause the scanner stack
   Keep the draft stack paused if maintainers do not want experimental lineage traversal running in the production scan path before the complete architecture is reviewable.

Next step before merge

• [P1] Review should resume after the predecessor lands and the contributor supplies real-corpus proof for output and scan overhead; there is no narrow code defect for an automated repair worker.

Security
Cleared: The diff adds local parsing and accounting logic without new dependencies, workflow permissions, secret access, downloads, or other concrete security or supply-chain concerns.

Review details

Best possible solution:

Land the classifier as a rebased, isolated stack slice after its predecessor, with legacy totals still authoritative and with redacted real-corpus output demonstrating unchanged production totals, bounded scan overhead, and the expected residual classifications.

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

Yes at the source and sanitized-test level: the linked investigation and classifier fixture define the fork-heavy accounting discrepancy. A high-confidence live current-head reproduction is still absent because no redacted real-corpus execution is shown.

Is this the best way to solve the issue?

Unclear. Conservative shadow classification is a maintainable intermediate seam, but this stacked draft is not yet the production fix and needs isolated review plus live performance and output proof before it is the best landing form.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add P2: This is a bounded accounting-correctness improvement with meaningful user impact, but the current slice remains experimental and does not yet replace production totals.
• add merge-risk: 🚨 availability: The stacked branch runs additional lineage discovery and accounting work during scans, and tests alone do not settle latency or resource behavior on large real archives.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Validation consists of tests and checks only; before merge, add a redacted real CLI or runtime transcript showing the shadow result, unchanged legacy totals, and representative scan timing, then update the PR body to trigger review or ask a maintainer for @clawsweeper re-review.

Label justifications:

• P2: This is a bounded accounting-correctness improvement with meaningful user impact, but the current slice remains experimental and does not yet replace production totals.
• merge-risk: 🚨 availability: The stacked branch runs additional lineage discovery and accounting work during scans, and tests alone do not settle latency or resource behavior on large real archives.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Validation consists of tests and checks only; before merge, add a redacted real CLI or runtime transcript showing the shadow result, unchanged legacy totals, and representative scan timing, then update the PR body to trigger review or ask a maintainer for @clawsweeper re-review.

Evidence reviewed

What I checked:

• Stack dependency: The PR describes itself as slice 6 of 15 and explicitly requires Feature/Fix: Run lineage accounting in shadow mode #2144 to be reviewed and merged first; its current six-commit branch includes the preceding lineage implementation rather than an isolated classifier-only diff. (a140e7df7e88)
• Production boundary: The new ledger and shadow types are documented as experimental and the PR states that legacy accounting remains authoritative, so this slice analyzes differences rather than completing the production correction. (Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift:3, a140e7df7e88)
• Residual coverage: The classifier tests cover the sanitized July 9–11 totals, provisional days, unavailable-history evidence, ordinary-day regressions, invalid samples, tolerance behavior, and overflow-safe arithmetic. (Tests/CodexBarTests/CodexLineageResidualClassifierTests.swift:1, a140e7df7e88)
• Real behavior proof: The PR body lists focused tests, repository checks, and the full test suite, but contains no live CLI output, redacted runtime log, recording, or artifact demonstrating the shadow pass on a real rollout corpus. (a140e7df7e88)
• Canonical investigation: The linked investigation reports inaccurate local Codex cost metrics after forked-context usage and remains the appropriate canonical problem record. citeturn865079search0turn865079search1. (Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, 0437067deaa8)
• Existing scanner history: Earlier merged work by Ifan24 corrected first-entry accounting spikes, while jskoiz contributed fork-accounting logic in the same scanner surface, making both relevant routing candidates. citeturn865079search2turn706016view0. (Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, 60f4a4e)

Likely related people:

• iam-brain: Authored this lineage stack and previously contributed merged Codex usage and pricing work, so they have the strongest context for the proposed accounting model. citeturn865079search5. (role: recent area contributor; confidence: high; commits: 6170f5c8c745, 547567d51686, 5c2b75e5871a; files: Sources/CodexBarCore/Providers/Codex/CodexLineageDiscovery.swift, Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift, Sources/CodexBarCore/Providers/Codex/CodexLineageResidualClassifier.swift)
• Ifan24: Authored the merged first-entry accounting correction in the same Codex scanner and test surface, providing useful historical context for snapshot interpretation. citeturn865079search2. (role: introduced related behavior; confidence: high; commits: 60f4a4e; files: Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, Tests/CodexBarTests/CostUsageScannerBreakdownTests.swift)
• jskoiz: Contributed the nearby fork-accounting implementation and associated regression tests, directly overlapping the lineage and inherited-baseline problem space. citeturn706016view0. (role: feature owner; confidence: high; commits: 7c321e05c0; files: Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, Tests/CodexBarTests/CostUsageScannerBreakdownTests.swift)
• steipete: Merged earlier Codex scanner corrections and owns release integration for this repository, making them a likely reviewer for sequencing and acceptable runtime overhead. citeturn865079search2. (role: merger and adjacent owner; confidence: medium; commits: 60f4a4e; files: Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.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.

[iam-brain]

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