Feature/Fix: Contain ambiguous lineage families

[iam-brain]

Stack dependency

This is slice 7 of 15. It follows Feature/Fix: Classify shadow lineage residuals; review and merge that PR first.

Summary

• scope lineage identities and exceptional parent discovery to one normalized Codex home
• preserve incomplete, truncated, and malformed evidence instead of silently dropping it
• route every family exclusively through primary accounting or conservative containment
• retain deterministic descendant usage when ancestry is missing and expose privacy-safe diagnostics

This is another isolated component of the planned Codex scanner rearchitecture. It keeps the production legacy total authoritative while making shadow accounting safer around malformed and ambiguous rollout histories.

Validation

• swift test --filter 'CodexLineage(Shadow|Ledger|Discovery)Tests' (28 passed)
• make check
• env SDKROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX26.5.sdk make test (642 selections, 54 groups, no failures or retries)

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
The PR adds shadow Codex lineage discovery, accounting, containment, and residual classification with focused tests while keeping legacy production totals authoritative.

Reproducibility: yes. at source level: the canonical issue and merged sanitized fixtures establish interleaved and fork-family accounting failures with hand oracles, but this branch's new ledger behavior has not been demonstrated on the affected private corpus.

Review metrics: 3 noteworthy metrics.

• Patch surface: 10 files, +2,126/-12. This is a large internal accounting slice despite preserving legacy totals.
• New lineage components: 4 added, 1 scanner integrated. Discovery, ledger, shadow comparison, and residual classification create a substantial new runtime subsystem.
• Reported validation: 28 focused tests; 642 full-suite selections. The branch has strong automated coverage, but those runs do not establish real archive performance or after-change behavior.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #2037
Summary: This PR is a staged candidate for the exact cross-file lineage work intentionally left open after the merged file-local containment fix.

Members:

• canonical: Ultra-mode Terra and Sol sessions can overcount forked context #2037 - The issue remains open for exact cross-file provenance and smaller-lineage accounting.
• partial_overlap: Contain Codex interleaved overcount and add fork provenance fixtures (#2037) #2082 - The merged PR provides bounded file-local containment and explicitly defers the family-ledger work attempted here.
• partial_overlap: Feature/Fix: Classify shadow lineage residuals #2145 - This open predecessor supplies the residual-classification slice included in this stacked branch.
• partial_overlap: Feature/Fix: Bound lineage reconciliation work #2147 - This open successor depends on the current branch and adds reconciliation bounds relevant to safe landing.

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:

• [P1] Add redacted initial and cached repeat-scan CLI output or runtime logs from an affected fork-heavy Codex home.
• Rebase after Feature/Fix: Classify shadow lineage residuals #2145 lands and include the bounds from Feature/Fix: Bound lineage reconciliation work #2147 or keep shadow execution gated off.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR reports focused and full automated tests but no after-fix redacted live scanner output from an affected setup; add initial and cached repeat-scan CLI or runtime logs, redact private paths and identifiers, then update the PR body for re-review.

Risk before merge

• [P1] The shadow path adds ancestor discovery and family-ledger work to production scanning before the next stack slice supplies reconciliation bounds, so large Codex archives may see unproven CPU, memory, or refresh-latency growth even though legacy totals remain authoritative.
• [P1] No after-change real-corpus output demonstrates that malformed, missing-parent, and ambiguous families are contained as intended across both initial and cached repeat scans.
• [P1] The exact merge result depends on the still-open predecessor; changes made while landing that slice could invalidate assumptions or tests in this head.

Maintainer options:

1. Bound and prove before merge (recommended)
   Rebase after the prerequisite, land the reconciliation bounds in the same safe unit or keep the shadow path disabled, and add redacted live initial and repeat-scan evidence.
2. Own the interim resource risk
   Merge this isolated slice while explicitly accepting that real large archives may pay unmeasured extra scan cost until the next stack slice lands.
3. Pause the lineage stack
   Leave the current bounded containment in place and close or redesign this stack if a safe independently mergeable unit cannot be produced.

Next step before merge

• [P1] A maintainer should decide stack landing and runtime-risk acceptance after the contributor supplies real affected-corpus proof; there is no narrow mechanical repair to queue.

Maintainer decision needed

• Question: Should this production-wired shadow lineage slice land before its reconciliation-bounds follow-up and live affected-corpus proof are present?
• Rationale: Tests establish internal policy behavior, but they cannot determine whether the added ancestry and family work is operationally safe for real large archives; the next stacked PR explicitly owns those bounds.
• Likely owner: steipete — He merged and runtime-proved the current containment behavior and documented the deferred exact-provenance boundary this PR implements.
• Options:
  • Land bounds and proof together (recommended): Keep this draft open, rebase after the predecessor lands, include or gate on the bounding follow-up, and require redacted initial plus cached repeat-scan output before merge.
  • Accept temporary scan overhead: Merge this slice alone while knowingly accepting unmeasured shadow-scan CPU, memory, and latency until the next stack slice lands.
  • Pause the rearchitecture: Keep the merged file-local containment authoritative and defer the family ledger until a smaller independently landable design is available.

Security
Cleared: The supplied diff adds no dependency, workflow, permission, secret-handling, downloaded-code, package-resolution, or external execution change.

Review details

Best possible solution:

Land the lineage ledger as a bounded, cancellation-safe shadow pipeline rebased onto its prerequisite, with reconciliation bounds included or shadow execution gated off, plus redacted initial and cached repeat-scan proof from an affected corpus before any future promotion into authoritative totals.

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

Yes at source level: the canonical issue and merged sanitized fixtures establish interleaved and fork-family accounting failures with hand oracles, but this branch's new ledger behavior has not been demonstrated on the affected private corpus.

Is this the best way to solve the issue?

Unclear as an isolated merge unit. The architecture matches the deferred cross-file provenance direction, but it should be bounded, cancellation-safe, and live-proven before production shadow execution lands.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add P2: The PR advances a real local cost-accounting bug with limited provider-scanner blast radius, but it is a draft shadow implementation rather than an urgent production fix.
• add merge-risk: 🚨 availability: Merging can add unmeasured ancestry discovery and family-reconciliation cost to real Codex scans before the following stack slice supplies explicit bounds.
• 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: The PR reports focused and full automated tests but no after-fix redacted live scanner output from an affected setup; add initial and cached repeat-scan CLI or runtime logs, redact private paths and identifiers, then update the PR body for re-review.

Label justifications:

• P2: The PR advances a real local cost-accounting bug with limited provider-scanner blast radius, but it is a draft shadow implementation rather than an urgent production fix.
• merge-risk: 🚨 availability: Merging can add unmeasured ancestry discovery and family-reconciliation cost to real Codex scans before the following stack slice supplies explicit bounds.
• 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: The PR reports focused and full automated tests but no after-fix redacted live scanner output from an affected setup; add initial and cached repeat-scan CLI or runtime logs, redact private paths and identifiers, then update the PR body for re-review.

Evidence reviewed

What I checked:

• Canonical remaining work: The merged containment work explicitly left cross-window family closure, collision handling, ownership migration, and incomplete or contained accounting for a later lineage ledger, which is the central work attempted here. (Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, c852c13)
• Current main boundary: Current main contains the bounded file-local containment from the merged partial fix, while the canonical issue remains open for exact cross-file provenance and smaller-lineage accounting. (Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, 0437067deaa8)
• Branch implementation: The branch adds four lineage components, adapts scanner parsing, updates the parser hash, and adds focused discovery, ledger, shadow, and residual-classifier coverage. (Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift:1, 5bf1836bb625)
• Proof gap: The PR reports focused tests, make check, and the full suite, but provides no redacted initial and cached repeat-scan output from an affected real Codex setup. (5bf1836bb625)
• Stack and resource boundary: This is slice 7 of 15, depends on the still-open predecessor Feature/Fix: Classify shadow lineage residuals #2145, and the next slice Feature/Fix: Bound lineage reconciliation work #2147 explicitly adds reconciliation bounds, so this head is not yet a safe standalone landing unit. (Sources/CodexBarCore/Providers/Codex/CodexLineageShadow.swift:39, 5bf1836bb625)
• Scanner ownership history: Merged fork-accounting work in Harden Codex cost scanner fork and refresh handling #698 and recent containment work in Contain Codex interleaved overcount and add fork provenance fixtures (#2037) #2082 identify the current implementation and review trail for this area. (Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, fd19445)

Likely related people:

• steipete: Authored the final containment refinements and runtime proof for the merged partial fix, then merged that scanner work into main. (role: recent area contributor, reviewer, and merger; confidence: high; commits: cb6538b18d09, ab65dd331faf, 6a7c577acf58; files: Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner+CacheHelpers.swift, Tests/CodexBarTests/CostUsageScannerBreakdownTests.swift)
• xx205: Authored merged parent-baseline and replay-accounting work preserved by the current scanner and extended by the lineage design. (role: introduced adjacent fork accounting behavior; confidence: high; commits: 45b68c34ec48, d058431; files: Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, Tests/CodexBarTests/CostUsageScannerBreakdownTests.swift)
• ratulsarna: Carried merged work covering fork inheritance, cache reuse, sessions-root changes, and refresh behavior in the same scanner path. (role: recent scanner refactor and merger; confidence: high; commits: 7abea24, fd19445; files: Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, Tests/CodexBarTests/CostUsageScannerTests.swift)
• iam-brain: Prior cost-history and pricing work shows relevant history beyond proposing this PR, and this branch develops the deferred lineage-accounting design. (role: recent cost-accounting contributor; confidence: medium; commits: 78300d8, 6170f5c8c745, 5bf1836bb625; files: Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift, Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.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.