From c118020b29ab463aff5f8fbb5bde111ebaebccbc Mon Sep 17 00:00:00 2001 From: Miguel Palhas Date: Tue, 25 Aug 2026 12:24:56 +0100 Subject: [PATCH] docs(maestro): make sidebar card line 2 unconditional Line 2 was rendered only past a 30s activity hold, blocked work, exit, or reported Error, and was gated behind a metadata.name comparison and TUI-optional. Both worked against scanability: cards changed height as sessions aged, and fresh sessions hid their command. Card is now always two lines. The 30s hold rule survives, demoted to gating only the fragment. is unconditional in both clients. Closes #116 --- docs/SIDEBAR.md | 51 +++++++++++++++++++++++++------------------------ 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/docs/SIDEBAR.md b/docs/SIDEBAR.md index 82b0522..2a3d658 100644 --- a/docs/SIDEBAR.md +++ b/docs/SIDEBAR.md @@ -5,8 +5,7 @@ sidebar (#107) and the TUI sidebar (#108) describe a session the same way. Read this before changing either. Both clients implement exactly what is written here; if it needs to change, change it here first. -A card has **line 1** always and **line 2** only when line 2 has something to -say. +A card is always two lines: **line 1** and **line 2**. ## Line 1 — name + actions @@ -25,32 +24,32 @@ badge move off this row into line 2. ## Line 2 — meta line (adaptive) -Rendered only when at least one of these holds: +Line 2 always renders — never an empty placeholder row either, since its +unconditional fragments (see below) always have something to show. Its +*fragments* are adaptive: some show only when their trigger holds. The line +itself is not. -1. The session has been held in its current activity state longer than - **30 seconds** (`activity_since` from #102). A freshly-active session - stays one line. -2. Its worktree holds blocked work: `blocked_work` is `Some` and not clear - (`InTheWay::is_clear()`), rendered in `formatInTheWay`'s phrasing on web - and as `⚠ ` on the TUI. -3. It has exited: `status == Dead`. -4. An agent-reported state (#105) of `Error` is in force (see Precedence). - -Otherwise line 2 is absent — never an empty placeholder row. - -When present, line 2 reads left to right: +Line 2 reads left to right: ``` - [] [ | exited] [] + [] [] [ | exited] ``` +Its minimum content is therefore the dot and the command. + `` is a single filled glyph (`●` on both clients) carrying the activity -state's colour, and `` follows in the same colour. There is no state -word and no second badge: the dot exists so the state is still legible when a -row is dimmed or the terminal renders the duration in the default fg. The dot -and duration are unconditional parts of line 2; the bracketed fragments appear -only when their trigger holds. A payload that predates #102 (no usable -`activity_since`) contributes no duration — the dot still renders. +state's colour, and `` follows in the same colour when shown. There +is no state word and no second badge: the dot exists so the state is still +legible when a row is dimmed or the terminal renders the duration in the +default fg. The dot is an unconditional part of line 2; the bracketed +fragments appear only when their trigger holds. + +`` renders only once the session has been held in its current +activity state longer than **30 seconds** (`activity_since` from #102) — under +that threshold the duration is absent and the dot renders alone. A payload +that predates #102 (no usable `activity_since`) likewise contributes no +duration — the dot still renders. This rule now governs only the duration +fragment; it no longer decides whether line 2 exists. `` is an agent-reported string (#105) — e.g. why a session is in `Error`. It sits right after the duration, in the muted style, and shows only @@ -60,9 +59,11 @@ truncates with `…` ahead of the trailing fragments — a long detail never pushes ``, `exited`, or `` off the line, and neither client ever lets it wrap. -`` is optional and muted: the session's command line, shown only when -the rendered name came from `metadata.name` and differs from the command (the -web has always surfaced this; the TUI may omit it). +`` is unconditional and muted: the session's command line, shown on +every card in both clients — no omission in the TUI, no name-vs-command +comparison gating it. A session named by its command line then shows the same +string on both lines; that is accepted, the price of a row that never changes +height. ## Colour per activity state