Stop re-merging the Codex plan-utilization history with itself on every refresh

[olddonkey]

Summary

UsageStore.materializeCodexPlanUtilizationHistoryIfNeeded exists to fold legacy, opaque and unscoped Codex plan-utilization buckets into the canonical account bucket. Its scoped loop also appended the canonical bucket's own histories to historiesToMerge — matchesTargetContinuity is true for rawKey == canonicalKey (CodexHistoryOwnership.swift:58-61), and only the removal of the old key was guarded by if rawKey != canonicalKey. So guard !historiesToMerge.isEmpty never fired once the canonical bucket had any history, and the migration merge ran on every successful provider refresh and every menu open, merging the history with itself.

That merge is quadratic: updatedPlanUtilizationEntries copied the whole entry array per entry, scanned it linearly for the insertion point, and allocated the same-hour slice. Measured with an optimized standalone reproduction over a real three-month-old history (session 1909 entries, weekly 2239): 20.6 ms of MainActor time per call, scaling ~3.9× per doubling. planUtilizationMaxSamples is 17520 per series, so it keeps growing — at the retention cap this would be several hundred ms per series, on the main thread, while the menu is opening.

Reached from UsageStore+Refresh.swift (applyProviderRefreshSuccess → recordPlanUtilizationHistorySample → MainActor.run → resolvePlanUtilizationAccountKey → resolveCodexPlanUtilizationAccountKey) and from the synchronous planUtilizationHistorySelection(for:) used while building the menu. Codex-only; Claude short-circuits earlier.

Changes

• Only merge when a foreign source contributed. A flag is set in the three branches that add non-canonical data (legacy scoped key, opaque recovery, unscoped adoption) and required by the guard, so the canonical-only case returns without merging or rewriting anything. Every path where a legacy/opaque/unscoped bucket does contribute is untouched: legacyRawKeysToRemove is only ever populated in branches that also set the flag (so no removal is skipped), and providerBuckets.unscoped is cleared only inside the branch that sets it.
• Make the genuine migration near-linear. updatedPlanUtilizationEntries mutates the array in place and finds the insertion point with a binary search for the same strict upper bound (plus a fast path for the common append); mergedPlanUtilizationHistories accumulates per series and constructs each history once.
• Enforce the sortedness invariant the binary search relies on. Every in-app producer went through PlanUtilizationSeriesHistory's designated initializer, which sorts — except the synthesized Codable decoder, which assigned entries verbatim from JSON. An explicit init(from:) now routes decoding through that initializer, so a history file written by an older build (or edited by hand) cannot smuggle in an unsorted series. The JSON shape is unchanged.

The skipped self-merge was also an incidental normalizer — it re-ran per-hour peak canonicalization on read, which is not a fixpoint. Repairing legacy data belongs at load time, not on every refresh and menu open, so that is not reintroduced here; the visible effect is that at most one extra real observation per affected hour is kept. This is commented at the guard.

Measured on real data

Against this machine's real history/codex.json (4160 entries: session 1909, weekly 2251), driving the real UsageStore.planUtilizationHistory(for: .codex) read path (swift test debug builds, same machine; an optimized standalone reproduction of the same algorithm measured 20.6 ms per call for current main):

Path	current main	this PR
canonical-only (every refresh, every menu open)	243–274 ms	0.94–1.12 ms
genuine legacy migration	238–273 ms	13.8–16.8 ms

The migration result is unchanged: the legacy bucket is absorbed, one account bucket remains, all 4160 entries survive. Full terminal transcripts are in a comment below.

Tests

• Canonical-only history is returned untouched and enqueues no persistence write (planUtilizationHistoryRevision unchanged) — the property that actually matters for the menu path.
• A genuine foreign merge matches an explicit expected result across overlapping hours, out-of-order sources, distinct session/weekly series, and retention trimming.
• The binary search's upper-bound contract is pinned directly through the DEBUG shim over a 65-entry array containing a run of equal capturedAt (a lower bound would return a different index), plus the endIndex/startIndex edges.
• Decoding a series whose JSON entries are out of order yields a sorted series, and the shuffled payload produces the same forecast estimate as the sorted fixture.

The existing Codex-ownership migration suite (12 cases, all of which seed a foreign key) is unchanged and still green.

Process

Implemented by grok-4.6 (xhigh) via implementation-loop; reviewed hunk by hunk plus an independent deep review that confirmed both equivalence claims by differential fuzzing (200k sorted cases, zero mismatches; and an exhaustive path enumeration showing the foreign-source paths are byte-identical) and found the decoder gap, fixed in one iterate round. The line-anchored ProviderArchitectureGatekeeperTests entries for the touched file were re-verified independently after every edit. Full make check and make test (77/77 sharded groups, zero failures) pass locally on this head.

🤖 Generated with Claude Code

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 22, 2026, 3:09 PM ET / 19:09 UTC.

ClawSweeper review

What this changes

The PR skips canonical-only Codex plan-history rewrites, makes genuine legacy-bucket merging cheaper, and normalizes decoded history ordering.

Regression provenance

Possible regression — probable (reviewed change; reproduction). No predecessor PR is attributed.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

Keep open: this is a focused, source-supported fix for an active main-thread history rewrite, with sufficient real-path terminal proof and no blocking correctness or security finding.

Priority: P2
Reviewed head: d45b9617c7c4d6d9e2e8d18c891242bd2ce199eb

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Strong real-path terminal proof and focused regression coverage support a narrow repair with no identified correctness blocker.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (terminal): The contributor supplied before-and-after terminal output from the real Codex persisted-history read path, showing both the improved result and preserved legacy migration outcome; private data should remain redacted in any future proof updates.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (terminal): The contributor supplied before-and-after terminal output from the real Codex persisted-history read path, showing both the improved result and preserved legacy migration outcome; private data should remain redacted in any future proof updates.
Evidence reviewed	5 items	Current-main defect and narrow guard: Current main merges whenever any matching bucket is present; the PR makes the merge contingent on a non-canonical scoped, opaque, or unscoped contributor, leaving canonical-only reads unchanged. Migration preservation: The foreign-source branches retain the canonical history in the merge input while removing only old scoped keys or clearing unscoped history after it contributes. Sorted persisted input: The explicit decoder routes persisted entries through the existing sorting initializer, establishing the captured-time ordering required by binary-search insertion without changing the encoded fields.
Findings	None	None.
Security	None	None.

Live Verification

Command: swift test --filter UsageStorePlanUtilizationCodexMergeTests

Result: FAIL (failed) — execution before step 1 run: sh -lc pnpm install --ignore-scripts --frozen-lockfile failed: ! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-11.22.0.tgz

sh -lc pnpm install --ignore-scripts --frozen-lockfile failed: ! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-11.22.0.tgz

Assertions:

• FAIL expect_output: Test run with

How this fits together

CodexBar stores provider utilization samples in account-keyed persisted history buckets. Codex account resolution runs during refreshes and menu history reads, optionally migrating legacy or unscoped data before menu and forecast consumers receive the selected history.

flowchart LR
A[Provider refresh] --> B[History buckets]
C[Menu history read] --> D[Codex account resolution]
B --> D
D --> E{Foreign history found?}
E -->|yes| F[Merge and persist canonical history]
E -->|no| G[Return canonical history unchanged]
F --> H[Menu and forecast]
G --> H

Loading

Before merge

• Complete next step (P2) - No repair is requested; this PR can proceed through normal merge checks on its reviewed head.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production versus test delta	6 files; production +107/-28, tests +301/-9	The implementation change is accompanied by focused coverage for canonical-only reads, legacy merging, retention, binary-search edges, and decode normalization.

Technical review

Best possible solution:

Keep canonical-only reads as no-ops while preserving the existing guarded migration paths for legacy, opaque, and unscoped Codex history.

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

Yes: current-main source directly permits the canonical bucket to satisfy the old non-empty merge guard, and the contributor provided before-and-after real-history terminal measurements for the read path.

Is this the best way to solve the issue?

Yes: the foreign-source guard fixes the unnecessary rewrite at the existing migration boundary, while the merge optimization and sorted decode invariant preserve the required migration path.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 27c7f334e3c4.

Labels

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The contributor supplied before-and-after terminal output from the real Codex persisted-history read path, showing both the improved result and preserved legacy migration outcome; private data should remain redacted in any future proof updates.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The contributor supplied before-and-after terminal output from the real Codex persisted-history read path, showing both the improved result and preserved legacy migration outcome; private data should remain redacted in any future proof updates.
• remove status: 📣 needs proof: Current PR status label is status: 👀 ready for maintainer look.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P2: The PR fixes normal Codex menu and refresh responsiveness without evidence of data loss, security impact, or a service outage.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The contributor supplied before-and-after terminal output from the real Codex persisted-history read path, showing both the improved result and preserved legacy migration outcome; private data should remain redacted in any future proof updates.
• proof: sufficient: Contributor real behavior proof is sufficient. The contributor supplied before-and-after terminal output from the real Codex persisted-history read path, showing both the improved result and preserved legacy migration outcome; private data should remain redacted in any future proof updates.

Evidence

What I checked:

• Current-main defect and narrow guard: Current main merges whenever any matching bucket is present; the PR makes the merge contingent on a non-canonical scoped, opaque, or unscoped contributor, leaving canonical-only reads unchanged. (Sources/CodexBar/UsageStore+PlanUtilization.swift:1262, d45b9617c7c4)
• Migration preservation: The foreign-source branches retain the canonical history in the merge input while removing only old scoped keys or clearing unscoped history after it contributes. (Sources/CodexBar/UsageStore+PlanUtilization.swift:1277, d45b9617c7c4)
• Sorted persisted input: The explicit decoder routes persisted entries through the existing sorting initializer, establishing the captured-time ordering required by binary-search insertion without changing the encoded fields. (Sources/CodexBar/PlanUtilizationHistoryStore.swift:65, d45b9617c7c4)
• After-fix real behavior proof: The contributor's terminal transcript uses an actual on-disk Codex history through the real read path, reporting canonical-only reads from 243–274 ms to 0.94–1.12 ms while preserving the tested legacy migration result. (d45b9617c7c4)
• Area provenance: Recent history shows Peter Steinberger’s provider-architecture refactor on this path; the current PR is not contained in the latest release tag. (Sources/CodexBar/UsageStore+PlanUtilization.swift:1153, 7deae2acc44e)

Likely related people:

• Peter Steinberger: Recent provider-architecture and plan-history work dominates the central file's history, including the current Codex account-resolution structure. (role: recent area contributor; confidence: high; commits: 7deae2acc44e, 01076474bab4; files: Sources/CodexBar/UsageStore+PlanUtilization.swift, Sources/CodexBar/PlanUtilizationHistoryStore.swift)
• Yuxin Qiao: History loading and persistence work in this subsystem includes their prior changes, making them a useful secondary routing contact. (role: adjacent history contributor; confidence: medium; commits: 04e4898a92f8; files: Sources/CodexBar/UsageStore+PlanUtilization.swift, Sources/CodexBar/PlanUtilizationHistoryStore.swift)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.

History

Review history (1 earlier review cycle)

• reviewed 2026-08-22T09:34:54.546Z sha 331bd44 :: needs real behavior proof before merge. :: none

[olddonkey]

Real-behavior proof (requested before merge)

Measured against this machine's actual on-disk Codex plan-utilization history — history/codex.json, 4160 entries across 2 series (session window 300: 1909 entries, weekly window 10080: 2251 entries), roughly three months of normal use. The harness loads that real file, installs it under the canonical account key, and drives the real read path UsageStore.planUtilizationHistory(for: .codex) — the same call the menu build and recordPlanUtilizationHistorySample go through — printing wall-clock per call. It is a measurement harness, not an assertion suite: the numbers below are its stdout.

Both sides are swift test debug builds of the same package on the same machine, so the absolute numbers are roughly an order of magnitude above release; the ratio is the point. (An optimized standalone reproduction of the same algorithm over the same history measured 20.6 ms per call for the current-main behaviour.)

Before — 27c7f334e (current main)

MEASURE: loaded 2 series / 4160 entries from the real history file
MEASURE:   series session window=300 entries=1909
MEASURE:   series weekly window=10080 entries=2251
MEASURE: [canonical-only] 5 read-path calls: 249.11, 250.00, 242.93, 274.46, 243.06 ms
MEASURE: [legacy migration] 5 calls: 264.51, 257.88, 272.79, 262.58, 238.06 ms
MEASURE: [legacy migration] account buckets now: 1 (legacy key removed: true)
MEASURE: [legacy migration] merged series: 2, entries: 4160

After — this PR

MEASURE: loaded 2 series / 4160 entries from the real history file
MEASURE:   series session window=300 entries=1909
MEASURE:   series weekly window=10080 entries=2251
MEASURE: [canonical-only] 5 read-path calls: 1.12, 0.96, 0.96, 0.94, 0.94 ms
MEASURE: [legacy migration] 5 calls: 16.01, 13.83, 16.79, 13.78, 14.16 ms
MEASURE: [legacy migration] account buckets now: 1 (legacy key removed: true)
MEASURE: [legacy migration] merged series: 2, entries: 4160

Canonical-only refresh behaviour (the state every normal single-account user is in, on every provider refresh and every menu open): 243–274 ms → 0.94–1.12 ms. The remaining work is reading the bucket; the merge no longer runs.

A real migration outcome is unchanged in result and faster: the legacy bucket is still absorbed (legacy key removed: true, one account bucket remains) and the merged series still carry all 4160 entries — at 238–273 ms → 13.8–16.8 ms, which is the in-place insert plus binary search doing what it was meant to do.

One fix this measurement produced

The first version of this branch put the DEBUG sortedness assertion inside updatedPlanUtilizationEntries, i.e. an O(n) scan per inserted entry — which reintroduced, in debug and test builds only, exactly the quadratic scan this insertion path exists to remove (the legacy migration measured ~1000 ms with it, ~15 ms without). It is now checked once per merged series. Release builds were never affected, but the assertion as written would have slowed every developer's test run; thanks to whatever prompted the "show real behaviour" ask, since a release-only benchmark would have hidden it.

Also in this push

The CHANGELOG.md entry has been removed from this branch — docs/RELEASING.md reserves the changelog for the release flow. For whoever writes the release notes:

• Codex: the plan-utilization history is no longer re-merged with itself on every refresh. The legacy-bucket migration also folded the canonical bucket into its own merge, so a quadratic merge ran on the main thread on every provider refresh and every menu open (~20 ms on a three-month-old history, growing with the square of its size); it now runs only when a legacy, opaque or unscoped bucket actually needs migrating, and the merge inserts in place with a binary search instead of copying the whole array per entry (Stop re-merging the Codex plan-utilization history with itself on every refresh #3141).

make check and the full make test (77/77 sharded groups, zero failures) pass on the pushed head.