docs(maestro): add SIDEBAR.md session card contract

CLAUDE.md

@@ -66,6 +66,10 @@ See `docs/INSTALL.md` for end-user install instructions.
 collisions, what blocks a kill, what `--force` retains, and what reclaim
 touches. Read it before changing anything that creates or removes one.
 
+`docs/SIDEBAR.md` is the contract for session cards in the web and TUI
+sidebars — line layout, activity colours, duration format, state precedence.
+Read it before changing sidebar rendering.
+
 `nix run .#dev` (or `just dev`) brings up the whole local stack under
 process-compose: a debug daemon on 127.0.0.1:7071, then Vite on :5173 once the
 daemon answers `/api/info`. The SPA proxies `/api/*` back to the daemon, so only

crates/maestro-cli/src/sessions.rs

@@ -108,7 +108,6 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
             ActivityState::Active => "active",
             ActivityState::Idle => "idle",
             ActivityState::AwaitingInput => "awaiting",
-            ActivityState::Error => "error",
         };
         // Show the live foreground command alongside the spawn command when
         // the daemon has observed one that differs (NAP-340).
@@ -177,7 +176,6 @@ mod tests {
             foreground: None,
             activity: Default::default(),
             last_activity_at: chrono::Utc::now(),
-            activity_since: chrono::Utc::now(),
             current_cwd: None,
             blocked_work: None,
         }

crates/maestro-daemon/src/session.rs

@@ -353,7 +353,6 @@ impl SessionManager {
             foreground: None,
             activity: ActivityState::Active,
             last_activity_at: Utc::now(),
-            activity_since: chrono::Utc::now(),
 
             current_cwd: None,
             // The watcher fills this in on its first blocked-work pass; a
@@ -573,7 +572,6 @@ impl SessionManager {
                     foreground: None,
                     activity: ActivityState::Idle,
                     last_activity_at: Utc::now(),
-                    activity_since: chrono::Utc::now(),
 
                     current_cwd: None,
                     blocked_work: None,

crates/maestro-daemon/tests/sidecar.rs

@@ -27,7 +27,6 @@ fn sample(id: Uuid) -> Session {
         foreground: None,
         activity: Default::default(),
         last_activity_at: chrono::Utc::now(),
-        activity_since: chrono::Utc::now(),
         current_cwd: Some(PathBuf::from("/tmp/work/crates")),
         blocked_work: None,
     }

crates/maestro-protocol/src/lib.rs

@@ -80,13 +80,6 @@ pub struct Session {
     /// from daemons that predate the field.
     #[serde(default = "epoch")]
     pub last_activity_at: DateTime<Utc>,
-    /// Wall-clock time at which the session entered its current
-    /// [`ActivityState`] (#102) — how long it has been `Active`, `Idle` or
-    /// `AwaitingInput`. Distinct from [`Self::last_activity_at`], which only
-    /// tracks the last observed PTY output. Populated by #104; defaults to the
-    /// Unix epoch on payloads from daemons that predate the field.
-    #[serde(default = "epoch")]
-    pub activity_since: DateTime<Utc>,
     /// The pane's *current* working directory (`#{pane_current_path}`) — distinct
     /// from [`Session::cwd`], the directory it was spawned in. The activity
     /// watcher refreshes it as the user `cd`s around; it drives the web UI's
@@ -126,9 +119,6 @@ pub enum ActivityState {
     Idle,
     /// Blocked on a `read()` from the pty — waiting on the user.
     AwaitingInput,
-    /// The agent running in the session reported a failure (#102). Never
-    /// inferred by the daemon; only set when an agent reports it (#105).
-    Error,
 }
 
 /// Optional worktree request attached to a `CreateSessionRequest`.
@@ -547,9 +537,6 @@ mod tests {
             last_activity_at: DateTime::parse_from_rfc3339("2026-05-24T12:05:00Z")
                 .unwrap()
                 .with_timezone(&Utc),
-            activity_since: DateTime::parse_from_rfc3339("2026-05-24T12:04:30Z")
-                .unwrap()
-                .with_timezone(&Utc),
             current_cwd: Some(PathBuf::from("/home/naps62/projects/maestro/crates")),
             blocked_work: None,
         }
@@ -601,35 +588,6 @@ mod tests {
         );
     }
 
-    #[test]
-    fn activity_since_defaults_to_epoch_on_legacy_payload() {
-        // A daemon predating #102 omits `activity_since`; it must deserialize
-        // to the forward-compat default rather than failing, and a present
-        // value round-trips.
-        let json = serde_json::json!({
-            "id": Uuid::from_u128(1),
-            "cwd": "/tmp",
-            "command": "bash",
-            "status": "Running",
-            "created_at": "2026-05-24T12:00:00Z"
-        });
-        let s: Session = serde_json::from_value(json).unwrap();
-        assert_eq!(s.activity_since, epoch());
-
-        let full = sample_session();
-        assert_eq!(full, round_trip(&full));
-    }
-
-    // #102: nothing infers `Error`; only #105's agent-reported failure sets it.
-    #[test]
-    fn error_activity_state_serializes_pascal_case_and_idle_stays_default() {
-        assert_eq!(
-            serde_json::to_value(ActivityState::Error).unwrap(),
-            serde_json::json!("Error")
-        );
-        assert_eq!(ActivityState::default(), ActivityState::Idle);
-    }
-
     #[test]
     fn activity_state_serializes_pascal_case_and_defaults_idle() {
         assert_eq!(

crates/maestro-testing/src/lib.rs

@@ -42,7 +42,6 @@ pub fn session(id: Uuid, cwd: &str, command: &str) -> Session {
         foreground: None,
         activity: Default::default(),
         last_activity_at: Utc::now(),
-        activity_since: chrono::Utc::now(),
         current_cwd: None,
         blocked_work: None,
     }

crates/maestro-tui/src/app.rs

@@ -1127,7 +1127,6 @@ mod tests {
                 foreground: None,
                 activity: Default::default(),
                 last_activity_at: Utc::now(),
-                activity_since: chrono::Utc::now(),
                 current_cwd: None,
                 blocked_work: None,
             }],
@@ -1645,7 +1644,6 @@ mod tests {
                 foreground: None,
                 activity: Default::default(),
                 last_activity_at: chrono::Utc::now(),
-                activity_since: chrono::Utc::now(),
 
                 current_cwd: None,
                 blocked_work: None,

crates/maestro-tui/src/catalog.rs

@@ -194,7 +194,6 @@ mod tests {
             foreground: None,
             activity: Default::default(),
             last_activity_at: chrono::Utc::now(),
-            activity_since: chrono::Utc::now(),
             current_cwd: None,
             blocked_work: None,
         }

crates/maestro-tui/src/sidebar.rs

@@ -105,7 +105,6 @@ mod tests {
             foreground: None,
             activity: Default::default(),
             last_activity_at: chrono::Utc::now(),
-            activity_since: chrono::Utc::now(),
             current_cwd: None,
             blocked_work: None,
         }
@@ -229,7 +228,6 @@ mod tests {
             foreground: None,
             activity: Default::default(),
             last_activity_at: chrono::Utc::now(),
-            activity_since: chrono::Utc::now(),
 
             current_cwd: None,
             blocked_work: None,

docs/SIDEBAR.md

@@ -0,0 +1,92 @@
+# SIDEBAR.md — the session card contract
+
+One rule for how a session is rendered as a card in the sidebar, so the web
+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.
+
+## Line 1 — name + actions
+
+- Left: the session name — `metadata.name` if present, else the command line
+  (same fallback both clients already use).
+- Right: two actions anchored to the top-right corner: **spawn similar**
+  (`⧉`) and **kill** (`✕`). In the TUI these are keyboard affordances shown on
+  the highlighted row; in the web they are buttons. The glyphs are shared so
+  muscle memory transfers.
+- Actions reserve their fixed width; the name truncates with `…` before it can
+  ever reach them. **Overlap between the name and the actions is a defect** —
+  that overlap is what started this milestone.
+
+Line 1 carries no badges. The `⚠ blocked work` badge (#83) and the `exited`
+badge move off this row into line 2.
+
+## Line 2 — meta line (adaptive)
+
+Rendered only when at least one of these holds:
+
+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 `⚠ <summary>` 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:
+
+```
+<duration> [<state badge>] [<blocked work> | exited]
+```
+
+## Colour per activity state
+
+The state word is never spelled out — the colour carries it.
+
+| Activity state   | Web token | ratatui colour    |
+| ---------------- | --------- | ----------------- |
+| `Active`         | `--live`  | `Color::Green`    |
+| `Idle`           | `--muted` | `Color::DarkGray` |
+| `AwaitingInput`  | `--warn`  | `Color::Yellow`   |
+| `Error`          | `--danger`| `Color::Red`      |
+
+Web tokens resolve per theme automatically (`styles.css` defines dark, light,
+and `prefers-color-scheme` variants for each). The TUI uses the plain ratatui
+named colours above; do not introduce RGB values or a new palette module for
+this.
+
+The duration text inherits its state's colour; the blocked-work and exited
+fragments use the muted colour (`--faint` / default style), since the ⚠ glyph
+already signals severity.
+
+## Duration format
+
+Time spent in the **current activity state**, sourced from `activity_since`
+(#102) — *not* time since spawn, and *not* time since last PTY output
+(`last_activity_at`). Both clients compute it identically:
+
+- `< 60s` → whole seconds, floored: `30s`
+- `< 60m` → whole minutes, floored: `4m`
+- `≥ 60m` → whole hours, floored: `2h`
+
+No days unit, no seconds inside minutes, no rounding up. Floor everywhere so
+the counter never shows a duration the state hasn't actually reached yet.
+Clock granularity: re-render at least once every 30s while visible so the
+cutover points land within one tick.
+
+## Precedence
+
+An agent-reported `ActivityState` (#105) overrides the daemon's inference for
+the TTL the report carries; when the TTL expires, inference resumes. Clients
+never blend the two: whichever source is in force supplies both the colour and
+the clock for `activity_since`.
+
+If a client receives an `ActivityState` variant it does not know, it must not
+fail rendering: treat it as `Idle` (neutral/dim, line-2 rules apply as usual)
+until the daemon sends a variant it does know. Rust clients deserialize
+activity leniently for the same reason.

web/src/types.ts

@@ -9,9 +9,8 @@ export type IsoTimestamp = string;
 export type SessionStatus = "Running" | "Dead";
 
 /** Daemon-inferred activity dimension, orthogonal to `SessionStatus` (NAP-340).
- * Absent on payloads from daemons that predate the field. `Error` is only set
- * when an agent reports failure (#105); the daemon never infers it. */
-export type ActivityState = "Active" | "Idle" | "AwaitingInput" | "Error";
+ * Absent on payloads from daemons that predate the field. */
+export type ActivityState = "Active" | "Idle" | "AwaitingInput";
 
 export interface Session {
   id: Uuid;
@@ -28,11 +27,6 @@ export interface Session {
   activity?: ActivityState;
   /** Wall-clock of the most recent observed PTY output (NAP-340). */
   last_activity_at?: IsoTimestamp;
-  /** Wall-clock of when the session entered its current `activity` state
-   * (#102) — distinct from `last_activity_at`, which only tracks PTY output.
-   * Defaults to the Unix epoch on payloads from daemons that predate the
-   * field. */
-  activity_since?: IsoTimestamp;
   /** The pane's *current* working directory, as the daemon's activity watcher
    * observed it (`#{pane_current_path}`) — distinct from `cwd` (the spawn dir).
    * Drives the directory-based session tree. Absent until first observed. */