naps62/maestro
Archived
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases Wiki Activity

Write docs/SIDEBAR.md: the session card contract #101

New Issue
Closed
opened 2026-08-24 19:02:08 +01:00 by naps62-yolo · 0 comments
naps62-yolo commented 2026-08-24 19:02:08 +01:00
Collaborator
Copy Link
Copy Source

Both sidebars have to describe a session the same way. Write the contract first so the web and TUI issues implement one rule instead of inventing two.

Create docs/SIDEBAR.md covering:

  • Line 1: session name, and the row actions (spawn similar, kill) anchored top-right. Actions must never overlap the name — that overlap is the defect that started this milestone.
  • Line 2 (adaptive): rendered only when it has something to say. It has something to say when any of these hold: the session's activity state has been held longer than a short threshold, its worktree holds blocked work, it has exited, or it is in Error. A freshly-active session stays one line.
  • Colour per activity state: Active green, Idle dim/muted, AwaitingInput amber, Error red. The state word is never spelled out — the colour carries it. Name the exact tokens the web theme and the ratatui palette each use.
  • Duration: time spent in the current activity state, from activity_since (#102) — not time since spawn. Format 30s, 4m, 2h; define the rounding and the cutover points once here so both clients agree.
  • Precedence: when an agent-reported state (#105) and the daemon's inference disagree, the reported state wins for its TTL, then inference resumes. State what a client should show if it receives an ActivityState variant it does not know.
  • What moved: the existing ⚠ blocked work badge (#83) and the exited badge move off the name row into the meta line.

Add a pointer to it from CLAUDE.md, next to the docs/WORKTREES.md line, so anyone changing sidebar rendering reads it first.

Non-goals: a PR/CI chip (deferred to its own milestone — maestro has no forge integration yet), and any change to how the daemon infers activity.

Both sidebars have to describe a session the same way. Write the contract first so the web and TUI issues implement one rule instead of inventing two. Create `docs/SIDEBAR.md` covering: - **Line 1**: session name, and the row actions (spawn similar, kill) anchored top-right. Actions must never overlap the name — that overlap is the defect that started this milestone. - **Line 2 (adaptive)**: rendered only when it has something to say. It has something to say when any of these hold: the session's activity state has been held longer than a short threshold, its worktree holds blocked work, it has exited, or it is in `Error`. A freshly-active session stays one line. - **Colour per activity state**: `Active` green, `Idle` dim/muted, `AwaitingInput` amber, `Error` red. The state word is never spelled out — the colour carries it. Name the exact tokens the web theme and the ratatui palette each use. - **Duration**: time spent in the *current* activity state, from `activity_since` (#102) — not time since spawn. Format `30s`, `4m`, `2h`; define the rounding and the cutover points once here so both clients agree. - **Precedence**: when an agent-reported state (#105) and the daemon's inference disagree, the reported state wins for its TTL, then inference resumes. State what a client should show if it receives an `ActivityState` variant it does not know. - **What moved**: the existing `⚠ blocked work` badge (#83) and the `exited` badge move off the name row into the meta line. Add a pointer to it from `CLAUDE.md`, next to the `docs/WORKTREES.md` line, so anyone changing sidebar rendering reads it first. Non-goals: a PR/CI chip (deferred to its own milestone — maestro has no forge integration yet), and any change to how the daemon infers activity.
naps62-yolo added this to the Sidebar cards milestone 2026-08-24 19:02:08 +01:00
naps62-yolo added the difficulty/easytype/docs labels 2026-08-24 19:02:08 +01:00
naps62-yolo added a new dependency 2026-08-24 19:02:15 +01:00
#107 Render sessions as cards in the web sidebar
naps62-yolo added a new dependency 2026-08-24 19:02:15 +01:00
#108 Render two-line session cards in the TUI sidebar
This repo is archived. You cannot comment on issues.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/android
area/cli
area/config
area/daemon
area/protocol
area/tui
area/web
code-review
difficulty/easy
difficulty/hard
difficulty/medium
epic
Tracks a multi-issue epic / parent work item
 tui
type/docs
type/feat
type/fix
type/refactor
type/test
No labels difficulty/easy type/docs
Milestone
No items
No Milestone Sidebar cards
Projects
Clear projects
No projects
Assignees
Clear assignees
hermes (Hermes (agent)) naps62-yolo (naps62-yolo (agent)) resende (Resende) naps62 (Miguel Palhas)
No Assignees
1 Participants
Due Date
No due date set.
Blocks
#107 Render sessions as cards in the web sidebar
naps62/maestro
#108 Render two-line session cards in the TUI sidebar
naps62/maestro
Reference: naps62/maestro#101