feat(tui): add configurable session token header

[XhesicaFrost]

Summary

Refs #4520.

Add an opt-in session token breakdown to the active underwater TUI header:

• Introduce the extensible tui.header_items configuration contract.
• Support header_items = ["tokens"] for cumulative input, cache-hit, and output token counts.
• Preserve the existing compact header when the option is not configured.
• Elide the optional token breakdown deterministically at narrow terminal widths.
• Keep the built-in context-utilization meter ahead of optional header content under width pressure.
• Reuse the existing compact token-count formatter.
• Avoid adding another cache-rate or total-token presentation to the footer.

Example configuration:

[tui]
header_items = ["tokens"]

The active underwater header continues to use its existing App data path and reads the three cumulative session counters from app.session.
This avoids introducing a second data-access pattern within the same renderer.

Unknown header_items values are ignored so that the configuration can be extended without breaking older clients.

Provider-specific missing-usage semantics are intentionally outside the scope of this change; the header treats the counters consistently
with the existing session token totals.

Testing

• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets --all-features
• cargo test --workspace --all-features

  • PR head: codewhale-tui reported 7,639 passed, 15 failed, and 3 ignored.

  • Direct parent baseline: codewhale-tui reported 7,636 passed, 12 failed, and
    3 ignored under the same environment.

  • Eleven failures reproduced on the direct parent commit.

  • Four additional terminal-session failures appeared only during the parallel PR
    run; the complete terminal-session test group passed 8/8 when run single-
    threaded on both the PR head and its direct parent.

  • All six tests added by this PR passed.

  • commands::tests::execute_links_and_aliases_return_links_message fails on
    both revisions because it expects https://codewhale.net/en/docs.

  • Focused header rendering tests at 40, 60, 80, and 100 columns

  • Default opt-in behavior test

  • Header configuration parsing and round-trip tests

  • cargo build -p codewhale-tui --bin codewhale-tui --locked

The width tests verify deterministic rendering at the requested terminal widths:

• At 40 columns, both the optional token breakdown and the built-in context meter
  are hidden by the existing compact layout.
• At 60 columns, the optional token breakdown is elided while the built-in context
  meter remains visible.
• At 80 columns, both the token breakdown and context meter are visible.
• At 100 columns, both the token breakdown and context meter are visible.

At every tested width, the mode and effective-permission indicators remain
visible. When the optional token breakdown does not fit, only that configured item
is removed; the existing context and version chrome retain their original
behavior.

Checklist

• Updated docs or comments as needed
• Added or updated tests where relevant
• Verified TUI behavior manually if UI changes
• Harvested/co-authored credit uses a GitHub numeric noreply address
  • N/A — this is an original contribution and contains no harvested code.

[github-actions]

Thanks @XhesicaFrost for taking the time to contribute.

This repository is observing a maintainer-managed PR intake gate in dry-run mode, so this pull request is staying open. This note helps maintainers prepare the allowlist before any enforcement is considered.

Please read CONTRIBUTING.md for the expected contribution shape. A maintainer can grant recurring PR access by commenting /lgtm on a pull request.

[Hmbown]

Thank you for picking up the header token-breakdown request and for documenting the width matrix and baseline failures carefully. The linked issue was explicitly held for v0.9.2 so we do not expand the frozen v0.9.1 candidate; I have applied that label to the PR and am leaving the source branch intact. This is a deferral, not a rejection. After the 0.9.1 cut, the maintainer pass should rebase onto current main, run the strict locked workspace gate, resolve the full-suite delta, and review the provider missing-usage semantics called out in the issue before merge.