Summary

Expand vigilante status from a basic service-installation check into a compact operational dashboard in the terminal. The command should still report service health, but it should present live work in a grouped, compressed, high-signal UI that makes it obvious what Vigilante is actively executing, what is paused while monitoring PRs, what is paused while tracking issues, whether anything looks stale, and whether GitHub rate limits are slowing work down.

Problem

• vigilante status currently reports only the installed service state, manager, service name, path, and whether the service is running.
• That is not enough to understand whether Vigilante is healthy as an execution system.
• Operators currently lack one command that answers basic questions such as:
• what is actively executing right now
• what work is paused but still being tracked
• whether blocked sessions are waiting on PR maintenance or issue execution
• whether any sessions appear stale or abandoned
• whether GitHub rate limiting is likely to delay work
• A flat list of sessions or a raw sessions.json dump would also be insufficient because it forces the user to manually interpret the lifecycle of each session.

Context

• Repository: aliengiraffe/vigilante
• vigilante status already exists and currently calls App.Status(...), which prints only service-level information.
• Session state is persisted in sessions.json and includes status values such as running, blocked, resuming, success, and failed.
• Additional fields such as PR number/state and blocked stage already carry the information needed to derive more meaningful UI groupings than raw status counts alone.
• The user wants vigilante status to feel like a compact operational control panel, not just a diagnostic text dump.

Desired Outcome

• Running vigilante status prints a concise but expressive terminal summary of Vigilante.
• The output should preserve service/daemon state, but the session area should be grouped by operational meaning rather than only by raw status enum.
• At minimum, the UI should compress sessions into groups like:
• Actively working
• Paused, tracking PRs
• Paused, tracking issues
• Stale sessions
• Completed / failed summary
• GitHub rate limits
• The session display should be optimized for fast scanning. It should make the difference between “actively executing work” and “paused but being monitored” immediately obvious.
• Non-goals:
• turning vigilante status into a full TUI
• dumping the entire contents of sessions.json by default
• showing every field for every session on the default screen
• requiring GitHub access just to print local service/session information when rate-limit lookup is unavailable

Implementation Notes

• Treat this as a feature request that expands the existing vigilante status command into a summary-first terminal UI.
• Required behavior:
• preserve the current service state reporting, but make it one section of a richer status view
• load session data from the existing state store and derive higher-level groupings from status plus session metadata such as PullRequestNumber, PullRequestState, and BlockedStage
• distinguish active execution from passive monitoring/maintenance
• report stale sessions explicitly instead of leaving “stale” ambiguous
• query GitHub /rate_limit when available and include a bounded human-readable summary in the output
• degrade gracefully if GitHub rate-limit lookup fails, for example by reporting local status and showing that GitHub status could not be fetched
• Required UI direction:
• prefer sectioned, compressed output over a flat chronological or JSON-style dump
• show counts in section headers where useful
• keep each session row short and information-dense
• visually separate “doing work now” from “paused but tracked” states
• The UI should be able to represent information like this in a compressed form:

Actively working
- Issue 258 in aliengiraffe/vigilante: running
  Current state: actively executing work, not just tracking.

Paused, tracking PRs
- Issue 106 in aliengiraffe/vigilante: blocked, PR #138 OPEN, stage pr_maintenance
- Issue 58 in teros-dev/platform: blocked, PR #62 OPEN, stage pr_maintenance
- Issue 59 in teros-dev/platform: blocked, PR #63 OPEN, stage pr_maintenance
- Issue 68 in teros-dev/platform: blocked, PR #69 OPEN, stage pr_maintenance
- Issue 204 in aliengiraffe/vigilante: blocked, PR #205 OPEN, stage pr_maintenance
- Issue 117 in teros-dev/platform: blocked, PR #118 OPEN, stage pr_maintenance

Paused, tracking issues
- Issue 122 in aliengiraffe/vigilante: blocked, stage issue_execution
- Issue 67 in teros-dev/platform: blocked, stage issue_execution
- Issue 70 in teros-dev/platform: blocked, stage issue_execution

• That exact formatting is not mandatory, but the same information hierarchy is required.
• The default view should summarize before it expands. For example:
• section headers may include counts such as Paused, tracking PRs (6)
• per-session rows should compress repo, issue number, raw state, and the most important lifecycle detail into one line where possible
• a short explanatory subline is acceptable for active work or stale/problem sessions when it adds clarity
• Plausible grouping heuristics:
• Actively working: sessions whose effective state means code is currently executing, such as running and possibly resuming
• Paused, tracking PRs: blocked sessions with an open PR and maintenance-oriented stage such as pr_maintenance or CI-follow-up states
• Paused, tracking issues: blocked sessions still associated with issue execution rather than PR maintenance
• Stale sessions: sessions whose timestamps, inactivity windows, missing artifacts, or cleanup drift indicate operator attention may be needed
• Completed / failed summary: compact totals instead of long per-session lists by default unless there are anomalies worth surfacing
• Required constraints:
• do not make the command unusable offline just because GitHub rate-limit data is unavailable
• stale-session detection must be based on explicit, documented heuristics rather than an undocumented guess
• keep the default output concise enough to scan in a terminal with many sessions
• avoid raw field names or internal implementation jargon unless they are useful to operators
• Flexible details:
• whether stale sessions are defined by age thresholds, blocked inactivity thresholds, missing worktree state, cleanup drift, or a combination
• whether the command gains flags later such as --json, --verbose, or --all, as long as the base human-readable output is useful
• whether completed and failed sessions are shown as counts only or expanded conditionally when they need attention
• Likely implementation areas:
• internal/app/app.go for expanding App.Status(...)
• state/session helpers for loading, grouping, and summarizing sessions
• existing stale/inactivity logic if it can be reused for status classification
• GitHub helper code for /rate_limit retrieval and formatting
• Tradeoffs to consider:
• GitHub lookups improve observability but should not make the command slow or brittle
• reporting too much per-session detail by default will make the command noisy, so summary-first output is preferable
• grouping by operator meaning is more useful than grouping only by raw session enum, but the mapping must be consistent and explainable

Acceptance Criteria

• vigilante status continues to report whether the service is installed and running.
• vigilante status reports the total number of sessions currently tracked.
• vigilante status groups sessions into operator-meaningful sections rather than only printing raw status totals.
• The default output clearly distinguishes sessions that are actively executing work from sessions that are paused while monitoring open PRs.
• The default output clearly distinguishes sessions that are paused while tracking issue execution without an active PR-maintenance loop.
• Session rows are compressed enough that multiple sessions can be scanned quickly without reading raw JSON-like dumps.
• vigilante status reports whether any sessions are stale and includes enough identifying information for affected sessions to inspect them quickly.
• vigilante status includes GitHub rate-limit information, including the REST core remaining quota and reset time, when that information can be retrieved.
• If GitHub rate-limit lookup fails, vigilante status still returns local service/session status and clearly indicates that GitHub rate-limit data is unavailable.
• The default output remains readable in a terminal even when many sessions are present.

Testing Expectations

• Add tests for the expanded vigilante status output covering service state plus grouped session summaries.
• Add tests for mixed session populations to verify grouping into active work, paused PR tracking, paused issue tracking, and stale/problem buckets.
• Add tests proving that PR-related blocked sessions are rendered differently from issue-execution blocked sessions.
• Add tests for stale-session detection and output formatting based on the chosen heuristic.
• Add tests for successful GitHub /rate_limit retrieval and rendering.
• Add tests for GitHub lookup failure to verify the command still succeeds with local-only status information.
• Add regression coverage so future changes to session fields or status values do not silently break the grouping or compressed output.

Operational / UX Considerations

• This command should become the first place an operator looks when they want to know whether Vigilante is healthy or why work is delayed.
• The UI should feel intentional and high-signal, not like a debug dump.
• Summary-first presentation matters more than exhaustiveness on the default screen.
• Prefer stable labels and consistent section ordering so frequent users can build muscle memory.
• Document what qualifies as a stale session and how the grouped sections are derived so operators can trust the output.
• If the command later grows machine-readable output, keep the human-readable default optimized for quick diagnosis from a terminal.