Summary

deepseek-tui already has a strong internal context-management system, but users cannot clearly see what is happening. We should surface Coherence as a simple, plain-language signal for how stable and focused the current session is.

Important wording rule:

• User-facing label can be Coherence
• Helper copy should explain it as something like how stable and focused this session is right now
• Do not show internal formulas, variable names, or math-heavy terms in normal UI

Scope

• Add a coherence status area in the TUI (footer, sidebar, status rows, or another clearly visible location)
• Show understandable state changes such as:
  • healthy
  • getting crowded
  • refreshing context
  • verifying recent work
  • resetting plan
• Expose machine-readable coherence state through the runtime API and thread metadata/events
• Keep deeper technical detail available only in debug views or logs

Acceptance Criteria

• Normal UI never shows internal score names or raw equations
• A user can tell when the session is healthy, strained, refreshing, or being reset
• Runtime API exposes a stable coherence state that other clients can consume
• Docs explain the user-facing meaning of coherence in plain language

Starting Points

• docs/capacity_controller.md
• crates/tui/src/core/capacity.rs
• crates/tui/src/core/capacity_memory.rs
• crates/tui/src/tui/
• docs/RUNTIME_API.md