feat(tui): opt-in status line for plan usage, cache hit rate, and session metrics

Summary

Add an opt-in, configurable status line (HUD) to the TUI footer so users can continuously monitor plan usage limits (weekly / rolling 5-hour), cache hit rate, and other session metrics without running /usage repeatedly.

This is inspired by the Claude Code ecosystem (e.g. claude-hud), where a persistent status line surfaces rate-limit and context data at a glance. Kimi Code already collects all the required data internally; it is just not rendered in the footer.

Motivation

As a heavy Kimi Code user, I want to see at a glance:

• How much of my weekly quota is left
• How much of the current rolling 5-hour window is consumed
• Cache hit rate for the current session (affects both cost and latency)
• Current context window usage (already shown)

Right now I have to interrupt my flow and run /usage to check quota, or open the Kimi Code Console in a browser. A persistent, low-noise status line would make these limits visible without breaking concentration.

Proposed Design

1. Configuration (tui.toml)

Add a new [footer] section. All new fields are optional and default to a conservative, non-intrusive layout.

[footer]
# Show plan usage (weekly + 5h limits) fetched from /usages
show_plan_usage = true
# Show cache hit rate for the current session
show_cache_hit_rate = true
# How often to poll managed usage from the network (seconds)
plan_usage_refresh_seconds = 60
# Compact layout: merge usage info into existing lines instead of adding a 3rd line
compact = true

Defaults: show_plan_usage = false, show_cache_hit_rate = false, plan_usage_refresh_seconds = 60, compact = true.

Rationale for opt-in defaults: the feature adds network polling and visual noise; users who do not need it should see zero change.

2. Data Sources

Metric	Source	Notes
Weekly limit	harness.auth.getManagedUsage() → summary	Already used by /usage
5-hour rolling limit	harness.auth.getManagedUsage() → limits[]	Label is auto-generated from window duration
Cache hit rate	session.getUsage() → TokenUsage.inputCacheRead / (inputCacheRead + inputCacheCreation)	Local computation, no extra network request
Context usage	AppState.contextTokens / maxContextTokens	Already rendered in footer line 2

3. UI Layout

Keep the footer at two lines by default. When compact = false, allow a third line for usage details.

Line 1 (existing, unchanged):

[yolo] [plan] kimi-for-coding thinking: high  ~/project  main  [2 tasks running]        hint...

Line 2 (existing + compact additions, right-aligned):

weekly: ████░░░░ 40%  5h: ██░░░░ 8%  cache: 73%  context: 42% (110k/256k)

If the terminal is too narrow, fall back to the existing context: ... only.

Line 3 (optional, compact = false):

plan: weekly ████░░░░ 40% (resets in 2d 3h) · 5h ██░░░░ 8% (resets in 4h 12m) · cache 73% · extra ¥12.34

4. Refresh Strategy

• Plan usage: poll getManagedUsage() every plan_usage_refresh_seconds. Cache the last successful result; on error keep showing stale data (grayed out) and retry on next tick.
• Cache hit rate: recalculate on every setState() from session.getUsage() (no network).
• Context: unchanged, driven by existing AppState updates.

5. Error & Edge-Case Handling

• Not logged in / non-managed provider: hide plan usage section entirely.
• Network failure: show last known values with a muted stale indicator; do not flash error banners.
• Zero cache tokens: show cache: -- instead of NaN%.
• Very narrow terminal (< 80 cols): truncate from the leftmost optional segment (plan usage first, then cache rate), preserving context percentage.

6. Implementation Sketch (files to touch)

1. apps/kimi-code/src/tui/config.ts — extend TuiConfigFileSchema and TuiConfigSchema with [footer] fields.
2. apps/kimi-code/src/tui/types.ts — add managedUsage?: ManagedUsageReport | null to AppState.
3. apps/kimi-code/src/tui/components/chrome/footer.ts — add polling timer, render new segments, respect width fallbacks.
4. apps/kimi-code/src/tui/kimi-tui.ts — start/stop the plan-usage poller; pass harness reference to footer.
5. apps/kimi-code/src/tui/components/messages/usage-panel.ts — reuse ManagedUsageReport types and formatting helpers.

No changes are needed in agent-core, oauth, or the network layer; getManagedUsage() already exists and is battle-tested by /usage.

Alternatives Considered

1. Plugin/Hook-based HUD — Not feasible. Hooks only run on tool-call lifecycle events and have no access to the TUI render tree or session state. There is no statusLine stdin/stdout contract like Claude Code.
2. Always-on third line — Rejected. Adds visual clutter for users who do not care about quotas; terminal height is precious.
3. Push-based updates — The /usages endpoint is REST-only; WebSocket/SSE push would require server-side changes. Polling is the only viable client-side approach today.

Additional Context

I am willing to implement this and open a PR if the design is accepted. I have already reviewed the relevant code paths (footer.ts, usage-panel.ts, managed-usage.ts, tui.toml schema) and can keep the diff focused (~150–200 lines plus tests).

Start with apps/kimi-code/src/tui/components/chrome/footer.ts and apps/kimi-code/src/tui/components/messages/usage-panel.ts, then trace configuration in apps/kimi-code/src/tui/config.ts and state in apps/kimi-code/src/tui/types.ts. Use the existing /usage path and getManagedUsage() behavior as the reference. Done means opt-in footer metrics, refresh and error handling, width fallbacks, and compact or third-line layouts work without changing default users’ displays.