Problem
A supervisor can get machine-readable session state through zelma sessions list --live --json and the implemented zelma status --json backend, but there is no human-friendly live monitor for quickly seeing which zelma sessions are actually running now.
The first screen should answer the operational question: which sessions are live and worth attention right now? Stale, missing, or historical records should be available, but must not crowd out currently running work.
Proposed TUI Surface
Add a read-only TUI command, for example:
Open naming can be decided during design (zelma tui, zelma sessions monitor, or zelma monitor), but the feature should provide one canonical command and document it in CLI help.
Scope
- Render a terminal UI over the existing status/list contracts instead of reading
.zelma/sessions.json directly from the UI layer.
- Prioritize live/active sessions in the default view.
- Show enough session identity to choose the right work item: repo-local numeric id, state/live status, opened path, zellij session/pane, and Codex session ref when available.
- Keep stale/non-active sessions visible through a secondary section, filter, or toggle, without making them the primary view.
- Support refresh/polling with a bounded interval and a manual refresh key.
- Provide keyboard navigation over visible sessions.
- Provide an action to focus the selected live session using the existing
zelma sessions focus <id> behavior.
- Surface degraded states and recovery hints from the status backend when zellij is unavailable or a pane cannot be revalidated.
Acceptance Criteria
- Running the TUI with live sessions shows live/active sessions first without requiring extra flags.
- With mixed active and stale records, active/live sessions remain visually and navigationally primary; stale records do not appear above live work by default.
- With no live sessions, the TUI shows an empty-live state plus any known stale/non-active records or recovery hints.
- The UI does not parse registry internals directly; it consumes
zelma status --json, zelma sessions list --live --json, or an internal service behind those same contracts.
- Selecting a live session and invoking focus switches to the stored zellij tab/pane or reports a structured, user-readable failure.
- Refresh does not mutate registry state except through already-defined status/list reconciliation behavior.
- Tests cover rendering/order logic with active plus stale sessions and command/action behavior with a fake status provider/focus adapter.
Non-Scope
References
UC-001: zelma sessions list --live --json inventory contract.
UC-010 / FT-042: implemented dashboard/status backend (zelma status --json).
README.md: sessions list defaults to active sessions for the current repository, while --all adds stale/non-active records.
#102: related future observation commands, explicitly not dashboard UI.
Problem
A supervisor can get machine-readable session state through
zelma sessions list --live --jsonand the implementedzelma status --jsonbackend, but there is no human-friendly live monitor for quickly seeing whichzelmasessions are actually running now.The first screen should answer the operational question: which sessions are live and worth attention right now? Stale, missing, or historical records should be available, but must not crowd out currently running work.
Proposed TUI Surface
Add a read-only TUI command, for example:
Open naming can be decided during design (
zelma tui,zelma sessions monitor, orzelma monitor), but the feature should provide one canonical command and document it in CLI help.Scope
.zelma/sessions.jsondirectly from the UI layer.zelma sessions focus <id>behavior.Acceptance Criteria
zelma status --json,zelma sessions list --live --json, or an internal service behind those same contracts.Non-Scope
References
UC-001:zelma sessions list --live --jsoninventory contract.UC-010/FT-042: implemented dashboard/status backend (zelma status --json).README.md:sessions listdefaults to active sessions for the current repository, while--alladds stale/non-active records.#102: related future observation commands, explicitly not dashboard UI.