Best possible solution:

Land a lineage fix that records family metadata on every logical session rotation path, preserves instance-mode compatibility, and keeps the new UI controls backed by green protocol, Gateway, and Control UI validation.

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

Yes. Source inspection gives a high-confidence reproduction for the main gap: trigger a normal /new or /reset through src/auto-reply/reply/session.ts, then request family usage for that logical key; the PR's new family fields are not populated by that path.

Is this the best way to solve the issue?

No. The direction is maintainable, but this patch is incomplete until the primary session reset path records lineage and the UI compatibility retry accounts for the new sessions.usage params.

Full review comments:

• [P2] Propagate lineage through explicit resets — src/auto-reply/reply/agent-runner-session-reset.ts:65-68
  The new family metadata is only written in the agent-runner reset helper and compaction updates. Normal /new and /reset go through src/auto-reply/reply/session.ts, which already captures the previous entry, mints a new sessionId, and builds a fresh entry without usageFamilyKey or usageFamilySessionIds. That leaves one of the linked issue's main acceptance paths showing only the new current instance in lineage mode.
  Confidence: 0.86
• [P3] Keep legacy usage fallback working — ui/src/ui/controllers/usage.ts:190-191
loadUsage now sends groupBy and includeHistorical on every sessions.usage request, but the existing retry only recognizes older gateways rejecting mode or utcOffset. A cached/newer Control UI pointed at an older gateway will fail with unexpected groupBy/includeHistorical instead of retrying with instance-only parameters.
  Confidence: 0.75

Overall correctness: patch is incorrect
Overall confidence: 0.87

Acceptance criteria:

• pnpm test src/gateway/server-methods/usage.sessions-usage.test.ts src/auto-reply/reply/session.test.ts ui/src/ui/controllers/usage.node.test.ts ui/src/ui/views/usage-render-details.test.ts ui/src/ui/views/usage-metrics.test.ts
• pnpm exec oxfmt --check --threads=1 src/auto-reply/reply/session.ts src/gateway/server-methods/usage.ts src/gateway/server-methods/usage.sessions-usage.test.ts ui/src/ui/controllers/usage.ts ui/src/ui/controllers/usage.node.test.ts
• OPENCLAW_TESTBOX=1 pnpm check:changed

What I checked:

• protected_pr_metadata: The GitHub context and public PR API show author association MEMBER and label maintainer, so this PR needs maintainer handling rather than cleanup closure. (360558512632)
• pr_diff_scope: The PR diff modifies 18 files across session metadata, Gateway usage protocol/handler, Control UI usage state/rendering, tests, and changelog. (360558512632)
• linked_issue_context: The linked issue asks for usage history continuity across updates, restarts, /new, /reset, and logical session re-binding; comments support transcript-backed lineage rollups as the long-term direction.
• main_reset_path_gap: Current main captures previousSessionEntry for explicit /new and /reset plus stale rotations, then creates a fresh sessionEntry with baseEntry undefined for new sessions; the PR does not patch this path to carry usage-family metadata. (src/auto-reply/reply/session.ts:469, 10ebcbdb9986)
• partial_lineage_persistence: The PR persists usageFamilyKey and usageFamilySessionIds in resetReplyRunSession and compaction updates, which covers some rotations but not the primary reply session reset path above. (src/auto-reply/reply/agent-runner-session-reset.ts:65, 360558512632)
• legacy_usage_fallback_gap: Current UI compatibility handling retries only when older gateways reject mode or utcOffset; the PR adds unconditional groupBy and includeHistorical params without extending that fallback. (ui/src/ui/controllers/usage.ts:190, 360558512632)

Likely related people:

• BunsDev: Local changelog history credits this handle for several Control UI and usage-view changes, including usage overview styling and usage detail-panel cleanup; the current PR also comes from the same maintainer account. (role: adjacent Control UI usage maintainer; confidence: medium; commits: 360558512632; files: ui/src/ui/views/usage.ts, ui/src/ui/views/usage-render-details.ts, ui/src/ui/controllers/usage.ts)
• Takhoffman: Changelog history credits this handle for adding the Web UI token usage dashboard and fixing multi-agent sessions.usage discovery, both central to this lineage surface. (role: introduced related usage dashboard behavior; confidence: medium; files: src/gateway/server-methods/usage.ts, ui/src/ui/views/usage.ts, CHANGELOG.md)
• konanok: Changelog history and prior ClawSweeper context identify recent Usage Mosaic work touching transcript usage aggregation and Control UI usage buckets. (role: recent usage aggregation maintainer; confidence: medium; commits: 0eb8f34000b8; files: src/infra/session-cost-usage.ts, ui/src/ui/views/usage.ts, CHANGELOG.md)
• mcaxtr: Changelog history and prior review context connect this handle to /new and /reset transcript archive behavior, which is the retained transcript layer the lineage rollup depends on. (role: related reset/archive behavior owner; confidence: medium; commits: 4724df7dea24; files: src/auto-reply/reply/session.ts, src/gateway/session-reset-service.ts, src/gateway/session-transcript-files.fs.ts)
• Val Alexander: The local checkout's available blame points central usage and reset files to this display name, but the checkout history is compact, so this is weaker than the changelog/PR-history routing above. (role: available current-main line history; confidence: low; commits: d919281fa8; files: src/gateway/server-methods/usage.ts, ui/src/ui/controllers/usage.ts, src/auto-reply/reply/session.ts)

Remaining risk / open question:

• Exact PR head has failing public check-runs, including protocol/build-related jobs that should be resolved before merge.
• The new lineage metadata is forward-looking and may not backfill preexisting split logical sessions unless the reset/restart discovery semantics are expanded.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 10ebcbdb9986.