Watching the fleet
Every surface is a projection of one record - and the fleet health runbook.
All views are projections of the one record; none of them holds state of its own.
| Surface | What it gives you |
|---|---|
saphan fleet show | The resolved fleet: one row per stream — state, last gate, executor liveness, what is pending — plus the machine roster and the one current notification. |
saphan fleet next | Per stream: everything it still owes and the ready command for each legal next act. |
saphan fleet health | Terminal run status counts over a lookback window. The headline counts work only; probe runs and historical rows without a recorded purpose are excluded and shown separately. |
saphan wave show | Branch → base → gate → merge across the wave: what is mergeable, what is blocked, what waits on you. |
saphan board export | The persisted record rendered as an artifact — delivery report (Markdown), flat data lanes (CSV), a paginated document (PDF), a styled report (HTML). This is the export you hand to someone who was not in the room. |
| The dashboard | A self-contained HTML view served by saphan server — fleet state at a glance in a browser, eight screens over the same record. |
| The MCP server | The same projections over the Model Context Protocol, so any MCP client — including an AI assistant — can read your fleet's state and answer questions from the record. Read-only without exception; documented fully in the MCP server. |
| The VS Code extension | The fleet as a tree in your editor, with paste-ready gate acts — section 11. |
The metering daemon (saphan serverd) | The background component that meters running sessions, watches owner-declared standing conditions (zero rules = zero dispatch, always), and delivers owner directives to running work through an insert-only mailbox. |
Fleet health runbook
- Run
saphan fleet health --workspace <canonical workspace root> --window 2h. Increase--windowwhen investigating a longer incident; the window is a duration ending now. - Read
work failuresas the health headline. It includes terminal failures from real work and excludes rows whose persistedrun_record.purposeisprobe. - Read the status table before diagnosing.
refused,child-failed,permission-blocked,lane-exhausted,auth-failed,error, andvendor-errorname different failure classes and remain separate rows. - Check both excluded columns.
PROBE(excluded)proves the instrument traffic was removed from the headline.UNCLASSIFIED(excluded)names historical rows written before purpose existed; do not silently add them to work or probes. - Use
--jsonfor automation. The payload carries the same three populations plus anexclusion_notice; a consumer that drops that notice presents a filtered number as an unfiltered one.
The command is read-only and runs no probe. A zero probe count means no recorded probe failure occurred in that window; it does not claim that a probe was executed.
The dashboard, concretely
saphan server start serves, beside the MCP endpoint, a dashboard — one
self-contained, server-rendered HTML document embedded in the binary: inline styles, no
external assets, no build step, no JavaScript framework. It binds to loopback by default
and re-reads the record on every request, so what you see is never a cached opinion. Eight
screens: the overview ("one window"), streams, runners and machines, the cost ledger, the
inbox, the sparks wall, and two placeholder screens for roles that are still growing into
the surface.
Two honesty notes, because a claim you can check is worth ten you cannot. The dashboard is pre-auth today — it binds to loopback and is deliberately served before the OAuth surface; fronting it with OAuth is named, planned work (the MCP server §6). And it is read-only with one exception: a "spark" note can be filed from the overview, through the same signed capture path the CLI uses, with the actor resolved server-side. Everything else is a read.
The design consequence worth noting: because every view is computed from the record, the answer you get from the dashboard, the CLI, the exported report, the VS Code tree, and an AI assistant reading over MCP is the same answer. There is no privileged screen.