Skip to content

Add TUI monitor for live zelma sessions #103

Description

@dapi

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:

zelma monitor

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions