PRD: Manifest Process State grammar

[csfh]

Problem Statement

The Workspace Manifest panel currently reads like raw process output. Direct Managed Processes repeat long all-caps lifecycle states, healthy rows expose low-signal metadata such as empty exit codes and zero restart counts, and the selected row uses a > marker that feels like a prompt rather than a dashboard selection state.

Developers need the Manifest panel to communicate Process State at a glance while preserving enough density for local development orchestration. The panel should use the same canonical Process State vocabulary for Direct Managed Processes and External Managed Processes, and should not force developers to decode separate internal and external state languages.

Solution

Introduce a compact Workspace Process State grammar based on the canonical RuntimeStatus model. The Manifest panel should render the stored canonical runtime status directly, using three-character Title-case codes: Run, Rty, Err, Blk, Str, Stp, Off, Pau, and Unk.

The Manifest panel should prioritize Managed Process identity over repeated state text, reserve health color for the state code and selected rail, hide healthy metadata by default, and summarize visible Process State using the same status codes. Empty Manifest states should be actionable and point developers toward Manifest Editing or Discovery.

User Stories

1. As a developer, I want each Direct Managed Process row to use compact Process State codes, so that I can scan the Development Stack quickly.
2. As a developer, I want healthy Direct Managed Processes to show Run instead of RUNNING, so that the Manifest panel feels calm and readable.
3. As a developer, I want retrying Direct Managed Processes to show Rty, so that I can see that Stasium is actively recovering them.
4. As a developer, I want errored Direct Managed Processes to show Err, so that I can distinguish final errors from retrying recovery.
5. As a developer, I want blocked Direct Managed Processes to show Blk, so that I know the process itself may not be the root cause.
6. As a developer, I want stopped Direct Managed Processes to show Off, so that inactive processes are distinct from processes that are actively stopping.
7. As a developer, I want starting and stopping states to show Str and Stp, so that transitional states are visible without taking over the row.
8. As a developer, I want paused and unknown External Managed Processes to use canonical codes, so that External Runtime Visibility uses the same Process State language.
9. As a developer, I want the Manifest summary to use the same Process State codes as rows, so that I do not have to learn two vocabularies.
10. As a developer, I want the Manifest summary to omit zero-count states, so that the header stays compact.
11. As a developer, I want errored states to appear first in summaries, so that the most important operational condition is visible first.
12. As a developer, I want retrying states to count as Rty rather than Err, so that the summary matches the visible row state.
13. As a developer, I want the selected row marker to use ┃ instead of >, so that selection feels like navigation rather than a command prompt.
14. As a developer, I want unselected rows to reserve the same rail width, so that status codes and process names stay aligned.
15. As a developer, I want the selected rail to use the selected process state color, so that selection carries operational context without extra text.
16. As a developer, I want selected row text to keep normal status coloring, so that selection does not erase Process State meaning.
17. As a developer, I want process names to use normal foreground text, so that identity remains distinct from Process State.
18. As a developer, I want Rty rows to show only the countdown metadata, so that retry timing is clear and compact.
19. As a developer, I want Err rows to show non-zero exit metadata as Ext n, so that the failure signal is visible.
20. As a developer, I want Run rows to show Rst n only when restart count is non-zero, so that healthy rows remain quiet unless there is instability history.
21. As a developer, I want Rst 0, Ext 0, and absent exit values hidden in Manifest rows, so that no-signal metadata does not clutter the overview.
22. As a developer, I want metadata right-aligned in a fixed metadata column, so that countdowns and lifecycle facts do not cause visual jitter.
23. As a developer, I want metadata hidden below narrow width thresholds, so that process identity and Process State remain readable in compact layouts.
24. As a developer, I want empty Manifest headers to show Add a service, so that an empty Project has an obvious next step.
25. As a developer, I want the empty Manifest body to explain a add and i discover shortcuts, so that I can create Process Definitions without hunting through help.
26. As a developer, I want the empty-state guidance to disappear after the first Process Definition exists, so that normal list usage is not cluttered.
27. As a keyboard user, I want the selected row to remain visible when the Process Output panel is focused, so that I know which process scope is active.
28. As a pointer user, I want hover background to be weaker than selected background, so that temporary hover does not obscure selection.
29. As an AFK agent, I want the UI to render from canonical runtimeStatus, so that I do not duplicate lifecycle mapping inside row rendering.
30. As a maintainer, I want Direct Managed Process and External Managed Process status presentation to share one canonical vocabulary, so that future Workspace panels remain consistent.

Implementation Decisions

• Treat RuntimeStatus as the canonical user-facing Process State model.
• Keep raw direct lifecycle state for supervision mechanics, but render Workspace rows and summaries from stored runtimeStatus.
• Use three-character Title-case Process State codes: Run, Rty, Err, Blk, Str, Stp, Off, Pau, Unk.
• Use this summary order: Err, Rty, Blk, Str, Stp, Off, Pau, Unk, Run.
• Store canonical runtime status on Direct Managed Process views and External Managed Process snapshots before the UI renders them.
• Rty is a visible runtime status when a Direct Managed Process has a pending restart countdown.
• Replace selected row > with ┃.
• Keep process names in normal foreground and use Process State color only for the state code and selected rail where supported.
• Hide healthy row metadata by default.
• Show row metadata only when it carries signal: retry countdown, non-zero exit code, or non-zero restart count.
• Preserve compact density and existing panel layout boundaries.
• Use Add a service as the empty Manifest header and add a muted empty-state body line that teaches the add and Discovery shortcuts.

Testing Decisions

• Test the canonical runtime status model at the status-helper seam, not by snapshotting terminal pixels.
• Test Direct Managed Process view status changes through Service Manager behavior where possible.
• Test External Managed Process snapshot status through External Runtime Visibility or Docker snapshot behavior where possible.
• Test row formatting behavior through formatter-level tests if the formatter is exported or through a high-level UI seam if already available.
• Prefer external behavior assertions: visible codes, summary text, metadata omission, and selection marker output.
• Prior art exists in Service Manager tests for lifecycle transitions and Docker tests for external snapshots.
• Add tests that distinguish Err from Rty when a Restart Rule schedules a retry.
• Add tests that empty manifests report no selection and present the empty state.

Out of Scope

• Live CPU or memory metrics.
• Selected Process detail strip above Process Output.
• Process Output panel layout rework.
• Dedicated service column for aggregate Process Output.
• Renaming raw lifecycle state throughout the process supervision internals.
• Changing Manifest file schema.
• Adding new External Runtime providers.

Further Notes

The current implementation already introduced the canonical RuntimeStatus type, runtimeStatus fields, aggregate Process Output scope, and space selection toggling during design exploration. This PRD should finish and harden the visual Manifest grammar around those decisions.

[csfh]

Completed by merged PR #195.